debian-mirror-gitlab/doc/topics/autodevops/quick_start_guide.md

300 lines
14 KiB
Markdown
Raw Normal View History

2018-11-08 19:23:39 +05:30
# Getting started with Auto DevOps
2018-03-17 18:26:18 +05:30
2020-04-22 19:07:51 +05:30
This step-by-step guide will help you use [Auto DevOps](index.md) to
2018-11-08 19:23:39 +05:30
deploy a project hosted on GitLab.com to Google Kubernetes Engine.
2018-03-17 18:26:18 +05:30
2020-04-22 19:07:51 +05:30
You will use GitLab's native Kubernetes integration, so you won't need
2018-11-08 19:23:39 +05:30
to create a Kubernetes cluster manually using the Google Cloud Platform console.
2020-04-22 19:07:51 +05:30
You will create and deploy a simple application that you create from a GitLab template.
2018-03-17 18:26:18 +05:30
2020-04-08 14:13:33 +05:30
These instructions will also work for a self-managed GitLab instance; you'll just
2020-11-24 15:15:51 +05:30
need to ensure your own [runners are configured](../../ci/runners/README.md) and
2018-11-08 19:23:39 +05:30
[Google OAuth is enabled](../../integration/google.md).
2018-03-17 18:26:18 +05:30
2020-04-22 19:07:51 +05:30
## Configure your Google account
2018-03-17 18:26:18 +05:30
2018-11-08 19:23:39 +05:30
Before creating and connecting your Kubernetes cluster to your GitLab project,
2020-04-22 19:07:51 +05:30
you need a [Google Cloud Platform account](https://console.cloud.google.com).
Sign in with an existing Google account, such as the one you use to access Gmail
or Google Drive, or create a new one.
2018-03-17 18:26:18 +05:30
2020-04-22 19:07:51 +05:30
1. Follow the steps described in the ["Before you begin" section](https://cloud.google.com/kubernetes-engine/docs/quickstart#before-you-begin)
of the Kubernetes Engine docs to enable the required APIs and related services.
1. Ensure you've created a [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account)
with Google Cloud Platform.
2018-03-17 18:26:18 +05:30
2018-11-08 19:23:39 +05:30
TIP: **Tip:**
Every new Google Cloud Platform (GCP) account receives [$300 in credit](https://console.cloud.google.com/freetrial),
2020-04-22 19:07:51 +05:30
and in partnership with Google, GitLab is able to offer an additional $200 for new
GCP accounts to get started with GitLab's Google Kubernetes Engine Integration.
[Follow this link](https://cloud.google.com/partners/partnercredit/?pcn_code=0014M00001h35gDQAQ#contact-form)
and apply for credit.
2018-03-17 18:26:18 +05:30
2020-04-22 19:07:51 +05:30
## Create a new project from a template
2018-10-15 14:42:47 +05:30
2018-11-08 19:23:39 +05:30
We will use one of GitLab's project templates to get started. As the name suggests,
2020-03-13 15:44:24 +05:30
those projects provide a bare-bones application built on some well-known frameworks.
2018-03-17 18:26:18 +05:30
2020-04-22 19:07:51 +05:30
1. In GitLab, click the plus icon (**{plus-square}**) at the top of the navigation bar, and select
2018-11-08 19:23:39 +05:30
**New project**.
2020-04-22 19:07:51 +05:30
1. Go to the **Create from template** tab, where you can choose among a Ruby on
2019-12-21 20:55:43 +05:30
Rails, Spring, or NodeJS Express project.
2020-04-22 19:07:51 +05:30
For this tutorial, use the Ruby on Rails template.
2018-03-17 18:26:18 +05:30
2019-12-21 20:55:43 +05:30
![Select project template](img/guide_project_template_v12_3.png)
2018-03-17 18:26:18 +05:30
2018-11-08 19:23:39 +05:30
1. Give your project a name, optionally a description, and make it public so that
you can take advantage of the features available in the
[GitLab Gold plan](https://about.gitlab.com/pricing/#gitlab-com).
2018-03-17 18:26:18 +05:30
2019-12-21 20:55:43 +05:30
![Create project](img/guide_create_project_v12_3.png)
2018-03-17 18:26:18 +05:30
2018-11-08 19:23:39 +05:30
1. Click **Create project**.
2018-03-17 18:26:18 +05:30
2020-04-22 19:07:51 +05:30
Now that you've created a project, you'll next create the Kubernetes cluster
to deploy this project to.
2018-03-17 18:26:18 +05:30
2020-04-22 19:07:51 +05:30
## Create a Kubernetes cluster from within GitLab
2018-03-17 18:26:18 +05:30
2020-04-22 19:07:51 +05:30
1. On your project's landing page, click **Add Kubernetes cluster**
2020-10-24 23:57:45 +05:30
(note that this option is also available when you navigate to **Operations > Kubernetes**).
2018-03-17 18:26:18 +05:30
2020-04-22 19:07:51 +05:30
![Project landing page](img/guide_project_landing_page_v12_10.png)
2018-03-17 18:26:18 +05:30
2020-04-22 19:07:51 +05:30
1. On the **Add a Kubernetes cluster integration** page, click the **Create new cluster** tab,
then click **Google GKE**.
2018-03-17 18:26:18 +05:30
2020-04-22 19:07:51 +05:30
1. Connect with your Google account, and click **Allow** to allow access to your
Google account. (This authorization request is only displayed the first time
you connect GitLab with your Google account.)
2018-03-17 18:26:18 +05:30
2020-04-22 19:07:51 +05:30
After authorizing access, the **Add a Kubernetes cluster integration** page
is displayed.
2018-03-17 18:26:18 +05:30
2020-04-22 19:07:51 +05:30
1. In the **Enter the details for your Kubernetes cluster** section, provide
details about your cluster:
2018-03-17 18:26:18 +05:30
2020-04-22 19:07:51 +05:30
- **Kubernetes cluster name**
- **Environment scope** - Leave this field unchanged.
- **Google Cloud Platform project** - Select a project. When you
[configured your Google account](#configure-your-google-account), a project
should have already been created for you.
- **Zone** - The [region/zone](https://cloud.google.com/compute/docs/regions-zones/) to
create the cluster in.
- **Number of nodes**
- **Machine type** - For more information about
[machine types](https://cloud.google.com/compute/docs/machine-types), see Google's documentation.
- **Enable Cloud Run for Anthos** - Select this checkbox to use the
[Cloud Run](../../user/project/clusters/add_gke_clusters.md#cloud-run-for-anthos),
Istio, and HTTP Load Balancing add-ons for this cluster.
- **GitLab-managed cluster** - Select this checkbox to
2020-05-24 23:13:21 +05:30
[allow GitLab to manage namespace and service accounts](../../user/project/clusters/index.md#gitlab-managed-clusters) for this cluster.
2018-03-17 18:26:18 +05:30
2020-04-22 19:07:51 +05:30
1. Click **Create Kubernetes cluster**.
2019-03-02 22:35:43 +05:30
2018-11-08 19:23:39 +05:30
After a couple of minutes, the cluster will be created. You can also see its
status on your [GCP dashboard](https://console.cloud.google.com/kubernetes).
2018-03-17 18:26:18 +05:30
2020-04-22 19:07:51 +05:30
Next, you will install some applications on your cluster that are needed
2018-11-08 19:23:39 +05:30
to take full advantage of Auto DevOps.
2018-03-17 18:26:18 +05:30
2020-04-22 19:07:51 +05:30
## Install Ingress and Prometheus
2018-11-08 19:23:39 +05:30
2020-07-28 23:09:34 +05:30
After your cluster is running, you can install your first applications.
In this guide, we will install Ingress and Prometheus:
2018-11-08 19:23:39 +05:30
2020-04-22 19:07:51 +05:30
- Ingress - Provides load balancing, SSL termination, and name-based virtual hosting,
using NGINX behind the scenes.
- Prometheus - An open-source monitoring and alerting system used to supervise the
deployed application.
2018-11-08 19:23:39 +05:30
2020-04-22 19:07:51 +05:30
NOTE: **Note:**
We won't install GitLab Runner in this quick start guide, as this guide uses the
2020-11-24 15:15:51 +05:30
shared runners provided by GitLab.com.
2018-11-08 19:23:39 +05:30
2020-04-22 19:07:51 +05:30
To install the applications:
2018-11-08 19:23:39 +05:30
2020-04-22 19:07:51 +05:30
- Click the **Install** button for **Ingress**.
- When the **Ingress Endpoint** is displayed, copy the IP address.
- Add your **Base domain**. For this guide, we will use the domain suggested by GitLab.
- Click **Save changes**.
2018-11-08 19:23:39 +05:30
2020-04-22 19:07:51 +05:30
![Cluster Base Domain](img/guide_base_domain_v12_3.png)
2018-11-08 19:23:39 +05:30
2020-04-22 19:07:51 +05:30
## Enable Auto DevOps (optional)
2018-11-08 19:23:39 +05:30
2020-04-22 19:07:51 +05:30
While Auto DevOps is enabled by default, Auto DevOps can be disabled at both
the instance level (for self-managed instances) and the group level. Complete
these steps to enable Auto DevOps if it's disabled:
2018-11-08 19:23:39 +05:30
2020-10-24 23:57:45 +05:30
1. Navigate to **Settings > CI/CD > Auto DevOps**, and click **Expand**.
2020-04-22 19:07:51 +05:30
1. Select **Default to Auto DevOps pipeline** to display more options.
1. In **Deployment strategy**, select your desired [continuous deployment strategy](index.md#deployment-strategy)
to deploy the application to production after the pipeline successfully runs on the `master` branch.
1. Click **Save changes**.
2018-11-08 19:23:39 +05:30
2020-04-22 19:07:51 +05:30
![Auto DevOps settings](img/guide_enable_autodevops_v12_3.png)
2018-11-08 19:23:39 +05:30
2020-04-22 19:07:51 +05:30
After you save your changes, GitLab creates a new pipeline. To view it, go to
**{rocket}** **CI/CD > Pipelines**.
2018-11-08 19:23:39 +05:30
2020-04-22 19:07:51 +05:30
In the next section, we explain what each job does in the pipeline.
2018-11-08 19:23:39 +05:30
2020-04-22 19:07:51 +05:30
## Deploy the application
2018-11-08 19:23:39 +05:30
2020-04-22 19:07:51 +05:30
When your pipeline runs, what is it doing?
2018-11-08 19:23:39 +05:30
2020-04-22 19:07:51 +05:30
To view the jobs in the pipeline, click the pipeline's status badge. The
**{status_running}** icon displays when pipeline jobs are running, and updates
without refreshing the page to **{status_success}** (for success) or
**{status_failed}** (for failure) when the jobs complete.
2018-11-08 19:23:39 +05:30
2020-04-22 19:07:51 +05:30
The jobs are separated into stages:
2018-03-17 18:26:18 +05:30
2020-06-23 00:09:42 +05:30
![Pipeline stages](img/guide_pipeline_stages_v13_0.png)
2018-11-08 19:23:39 +05:30
2020-04-22 19:07:51 +05:30
- **Build** - The application builds a Docker image and uploads it to your project's
[Container Registry](../../user/packages/container_registry/index.md) ([Auto Build](stages.md#auto-build)).
- **Test** - GitLab runs various checks on the application:
- The `test` job runs unit and integration tests by detecting the language and
framework ([Auto Test](stages.md#auto-test))
- The `code_quality` job checks the code quality and is allowed to fail
2020-11-24 15:15:51 +05:30
([Auto Code Quality](stages.md#auto-code-quality)) **(STARTER)**
2020-04-22 19:07:51 +05:30
- The `container_scanning` job checks the Docker container if it has any
2020-11-24 15:15:51 +05:30
vulnerabilities and is allowed to fail ([Auto Container Scanning](stages.md#auto-container-scanning))
2020-04-22 19:07:51 +05:30
- The `dependency_scanning` job checks if the application has any dependencies
susceptible to vulnerabilities and is allowed to fail
2020-11-24 15:15:51 +05:30
([Auto Dependency Scanning](stages.md#auto-dependency-scanning)) **(ULTIMATE)**
2020-06-23 00:09:42 +05:30
- Jobs suffixed with `-sast` run static analysis on the current code to check for potential
2020-11-24 15:15:51 +05:30
security issues, and are allowed to fail ([Auto SAST](stages.md#auto-sast)) **(ULTIMATE)**
- The `secret-detection` job checks for leaked secrets and is allowed to fail ([Auto Secret Detection](stages.md#auto-secret-detection)) **(ULTIMATE)**
2020-04-22 19:07:51 +05:30
- The `license_management` job searches the application's dependencies to determine each of their
licenses and is allowed to fail
2020-11-24 15:15:51 +05:30
([Auto License Compliance](stages.md#auto-license-compliance)) **(ULTIMATE)**
2020-04-22 19:07:51 +05:30
NOTE: **Note:**
All jobs except `test` are allowed to fail in the test stage.
2020-06-23 00:09:42 +05:30
- **Review** - Pipelines on `master` include this stage with a `dast_environment_deploy` job.
To learn more, see [Dynamic Application Security Testing (DAST)](../../user/application_security/dast/index.md).
2020-04-22 19:07:51 +05:30
- **Production** - After the tests and checks finish, the application deploys in
Kubernetes ([Auto Deploy](stages.md#auto-deploy)).
- **Performance** - Performance tests are run on the deployed application
2020-11-24 15:15:51 +05:30
([Auto Browser Performance Testing](stages.md#auto-browser-performance-testing)). **(PREMIUM)**
2020-04-22 19:07:51 +05:30
2020-06-23 00:09:42 +05:30
- **Cleanup** - Pipelines on `master` include this stage with a `stop_dast_environment` job.
2020-04-22 19:07:51 +05:30
After running a pipeline, you should view your deployed website and learn how
to monitor it.
### Monitor your project
After successfully deploying your application, you can view its website and check
on its health on the **Environments** page by navigating to
2020-10-24 23:57:45 +05:30
**Operations > Environments**. This page displays details about
2020-04-22 19:07:51 +05:30
the deployed applications, and the right-hand column displays icons that link
you to common environment tasks:
2018-11-08 19:23:39 +05:30
2019-12-21 20:55:43 +05:30
![Environments](img/guide_environments_v12_3.png)
2018-11-08 19:23:39 +05:30
2020-04-22 19:07:51 +05:30
- **Open live environment** (**{external-link}**) - Opens the URL of the application deployed in production
- **Monitoring** (**{chart}**) - Opens the metrics page where Prometheus collects data
about the Kubernetes cluster and how the application
affects it in terms of memory usage, CPU usage, and latency
- **Deploy to** (**{play}** **{angle-down}**) - Displays a list of environments you can deploy to
2020-05-24 23:13:21 +05:30
- **Terminal** (**{terminal}**) - Opens a [web terminal](../../ci/environments/index.md#web-terminals)
2020-04-22 19:07:51 +05:30
session inside the container where the application is running
- **Re-deploy to environment** (**{repeat}**) - For more information, see
2020-05-24 23:13:21 +05:30
[Retrying and rolling back](../../ci/environments/index.md#retrying-and-rolling-back)
2020-04-22 19:07:51 +05:30
- **Stop environment** (**{stop}**) - For more information, see
2020-05-24 23:13:21 +05:30
[Stopping an environment](../../ci/environments/index.md#stopping-an-environment)
2020-04-22 19:07:51 +05:30
GitLab displays the [Deploy Board](../../user/project/deploy_boards.md) below the
environment's information, with squares representing pods in your
Kubernetes cluster, color-coded to show their status. Hovering over a square on
the deploy board displays the state of the deployment, and clicking the square
takes you to the pod's logs page.
2018-11-08 19:23:39 +05:30
TIP: **Tip:**
2020-04-22 19:07:51 +05:30
The example shows only one pod hosting the application at the moment, but you can add
more pods by defining the [`REPLICAS` variable](customize.md#environment-variables)
2020-10-24 23:57:45 +05:30
in **Settings > CI/CD > Environment variables**.
2018-11-08 19:23:39 +05:30
2020-04-22 19:07:51 +05:30
### Work with branches
2018-11-08 19:23:39 +05:30
2019-12-26 22:10:19 +05:30
Following the [GitLab flow](../gitlab_flow.md#working-with-feature-branches),
2020-04-22 19:07:51 +05:30
you should next create a feature branch to add content to your application:
2018-11-08 19:23:39 +05:30
2020-04-22 19:07:51 +05:30
1. In your project's repository, navigate to the following file: `app/views/welcome/index.html.erb`.
This file should only contain a paragraph: `<p>You're on Rails!</p>`.
1. Open the GitLab [Web IDE](../../user/project/web_ide/index.md) to make the change.
1. Edit the file so it contains:
2018-11-08 19:23:39 +05:30
2020-04-22 19:07:51 +05:30
```html
<p>You're on Rails! Powered by GitLab Auto DevOps.</p>
```
2018-11-08 19:23:39 +05:30
2020-04-22 19:07:51 +05:30
1. Stage the file. Add a commit message, then create a new branch and a merge request
by clicking **Commit**.
2018-11-08 19:23:39 +05:30
2020-04-22 19:07:51 +05:30
![Web IDE commit](img/guide_ide_commit_v12_3.png)
2018-11-08 19:23:39 +05:30
2020-04-22 19:07:51 +05:30
After submitting the merge request, GitLab runs your pipeline, and all the jobs
in it, as [described previously](#deploy-the-application), in addition to
2018-11-08 19:23:39 +05:30
a few more that run only on branches other than `master`.
2019-12-21 20:55:43 +05:30
![Merge request](img/guide_merge_request_v12_3.png)
2018-11-08 19:23:39 +05:30
2020-04-22 19:07:51 +05:30
After a few minutes you'll notice a test failed, which means a test was
'broken' by your change. Click on the failed `test` job to see more information
about it:
2018-11-08 19:23:39 +05:30
2020-04-22 19:07:51 +05:30
```plaintext
2018-11-08 19:23:39 +05:30
Failure:
WelcomeControllerTest#test_should_get_index [/app/test/controllers/welcome_controller_test.rb:7]:
<You're on Rails!> expected but was
<You're on Rails! Powered by GitLab Auto DevOps.>..
Expected 0 to be >= 1.
bin/rails test test/controllers/welcome_controller_test.rb:4
```
2018-03-17 18:26:18 +05:30
2020-04-22 19:07:51 +05:30
To fix the broken test:
2018-03-17 18:26:18 +05:30
2020-04-22 19:07:51 +05:30
1. Return to the **Overview** page for your merge request, and click **Open in Web IDE**.
1. In the left-hand directory of files, find the `test/controllers/welcome_controller_test.rb`
file, and click it to open it.
2018-11-08 19:23:39 +05:30
1. Change line 7 to say `You're on Rails! Powered by GitLab Auto DevOps.`
1. Click **Commit**.
2020-04-22 19:07:51 +05:30
1. In the left-hand column, under **Unstaged changes**, click the checkmark icon
(**{stage-all}**) to stage the changes.
1. Write a commit message, and click **Commit**.
2018-03-17 18:26:18 +05:30
2020-04-22 19:07:51 +05:30
Return to the **Overview** page of your merge request, and you should not only
see the test passing, but also the application deployed as a
[review application](stages.md#auto-review-apps). You can visit it by clicking
the **View app** **{external-link}** button to see your changes deployed.
2018-03-17 18:26:18 +05:30
2019-12-21 20:55:43 +05:30
![Review app](img/guide_merge_request_review_app_v12_3.png)
2018-03-17 18:26:18 +05:30
2020-04-22 19:07:51 +05:30
After merging the merge request, GitLab runs the pipeline on the `master` branch,
and then deploys the application to production.
2018-03-17 18:26:18 +05:30
2018-11-08 19:23:39 +05:30
## Conclusion
2018-03-17 18:26:18 +05:30
2020-04-22 19:07:51 +05:30
After implementing this project, you should have a solid understanding of the basics of Auto DevOps.
You started from building and testing, to deploying and monitoring an application
2018-11-20 20:47:30 +05:30
all within GitLab. Despite its automatic nature, Auto DevOps can also be configured
2018-11-08 19:23:39 +05:30
and customized to fit your workflow. Here are some helpful resources for further reading:
2018-03-17 18:26:18 +05:30
2018-11-08 19:23:39 +05:30
1. [Auto DevOps](index.md)
2020-07-28 23:09:34 +05:30
1. [Multiple Kubernetes clusters](index.md#using-multiple-kubernetes-clusters)
2020-11-24 15:15:51 +05:30
1. [Incremental rollout to production](customize.md#incremental-rollout-to-production) **(PREMIUM)**
2020-04-22 19:07:51 +05:30
1. [Disable jobs you don't need with environment variables](customize.md#environment-variables)
2019-12-26 22:10:19 +05:30
1. [Use a static IP for your cluster](../../user/clusters/applications.md#using-a-static-ip)
2020-04-22 19:07:51 +05:30
1. [Use your own buildpacks to build your application](customize.md#custom-buildpacks)
2018-11-08 19:23:39 +05:30
1. [Prometheus monitoring](../../user/project/integrations/prometheus.md)