1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
|
---
stage: Deploy
group: Environments
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
---
# Use Auto DevOps to deploy an application to Google Kubernetes Engine **(FREE)**
In this tutorial, we'll help you to get started with [Auto DevOps](../index.md)
through an example of how to deploy an application to Google Kubernetes Engine (GKE).
You are using the GitLab native Kubernetes integration, so you don't need
to create a Kubernetes cluster manually using the Google Cloud Platform console.
You are creating and deploying an application that you create from a GitLab template.
These instructions also work for self-managed GitLab instances.
Ensure your own [runners are configured](../../../ci/runners/index.md) and
[Google OAuth is enabled](../../../integration/google.md).
To deploy a project to Google Kubernetes Engine, follow the steps below:
1. [Configure your Google account](#configure-your-google-account)
1. [Create a Kubernetes cluster and deploy the agent](#create-a-kubernetes-cluster)
1. [Create a new project from a template](#create-an-application-project-from-a-template)
1. [Configure the agent](#configure-the-agent)
1. [Install Ingress](#install-ingress)
1. [Configure Auto DevOps](#configure-auto-devops)
1. [Enable Auto DevOps and run the pipeline](#enable-auto-devops-and-run-the-pipeline)
1. [Deploy the application](#deploy-the-application)
## Configure your Google account
Before creating and connecting your Kubernetes cluster to your GitLab project,
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.
1. Follow the steps described in the ["Before you begin" section](https://cloud.google.com/kubernetes-engine/docs/deploy-app-cluster#before-you-begin)
of the Kubernetes Engine documentation 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.
NOTE:
Every new Google Cloud Platform (GCP) account receives [$300 in credit](https://console.cloud.google.com/freetrial),
and in partnership with Google, GitLab is able to offer an additional $200 for new
GCP accounts to get started with the GitLab integration with Google Kubernetes Engine.
[Follow this link](https://cloud.google.com/partners/partnercredit/?pcn_code=0014M00001h35gDQAQ#contact-form)
and apply for credit.
## Create a Kubernetes cluster
To create a new cluster on Google Kubernetes Engine (GKE), use Infrastructure as Code (IaC) approach
by following steps in [Create a Google GKE cluster](../../../user/infrastructure/clusters/connect/new_gke_cluster.md) guide.
The guide requires you to create a new project that uses [Terraform](https://www.terraform.io/) to create a GKE cluster and install a GitLab agent for Kubernetes.
This project is where configuration for GitLab agent resides.
## Create an application project from a template
Use a GitLab project template to get started. As the name suggests,
those projects provide a bare-bones application built on some well-known frameworks.
WARNING:
Create the application project in the group hierarchy at the same level or below the project for cluster management. Otherwise, it fails to [authorize the agent](../../../user/clusters/agent/ci_cd_workflow.md#authorize-the-agent).
1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
1. Select **Create from template**.
1. Select the **Ruby on Rails** template.
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 Ultimate plan](https://about.gitlab.com/pricing/).
1. Select **Create project**.
Now you have an application project you are going to deploy to the GKE cluster.
## Configure the agent
Now we need to configure the GitLab agent for Kubernetes for us to be able to use it to deploy the application project.
1. Go to the project [we created to manage the cluster](#create-a-kubernetes-cluster).
1. Navigate to the [agent configuration file](../../../user/clusters/agent/install/index.md#create-an-agent-configuration-file) (`.gitlab/agents/gke-agent/config.yaml`) and edit it.
1. Configure `ci_access:projects` attribute. Use application's project path as `id`:
```yaml
ci_access:
projects:
- id: path/to/application-project
```
## Install Ingress
After your cluster is running, you must install NGINX Ingress Controller as a
load balancer, to route traffic from the internet to your application.
Install the NGINX Ingress Controller
through the GitLab [Cluster management project template](../../../user/clusters/management_project_template.md),
or manually with Google Cloud Shell:
1. Go to your cluster's details page, and select the **Advanced Settings** tab.
1. Select the link to Google Kubernetes Engine to visit the cluster on Google Cloud Console.
1. On the GKE cluster page, select **Connect**, then select **Run in Cloud Shell**.
1. After the Cloud Shell starts, run these commands to install NGINX Ingress Controller:
```shell
helm upgrade --install ingress-nginx ingress-nginx \
--repo https://kubernetes.github.io/ingress-nginx \
--namespace gitlab-managed-apps --create-namespace
# Check that the ingress controller is installed successfully
kubectl get service ingress-nginx-controller -n gitlab-managed-apps
```
## Configure Auto DevOps
Follow these steps to configure the base domain and other settings required for Auto DevOps.
1. A few minutes after you install NGINX, the load balancer obtains an IP address, and you can
get the external IP address with the following command:
```shell
kubectl get service ingress-nginx-controller -n gitlab-managed-apps -ojson | jq -r '.status.loadBalancer.ingress[].ip'
```
Replace `gitlab-managed-apps` if you have overwritten your namespace.
Copy this IP address, as you need it in the next step.
1. Go back to the application project.
1. On the left sidebar, select **Settings > CI/CD** and expand **Variables**.
- Add a key called `KUBE_INGRESS_BASE_DOMAIN` with the application deployment domain as the value. For this example, use the domain `<IP address>.nip.io`.
- Add a key called `KUBE_NAMESPACE` with a value of the Kubernetes namespace for your deployments to target. You can use different namespaces per environment. Configure the environment, use the environment scope.
- Add a key called `KUBE_CONTEXT` with a value like `path/to/agent/project:gke-agent`. Select the environment scope of your choice.
- Select **Save changes**.
## Enable Auto DevOps and run the pipeline
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:
1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find the application project.
1. Select **Settings > CI/CD**.
1. Expand **Auto DevOps**.
1. Select **Default to Auto DevOps pipeline** to display more options.
1. In **Deployment strategy**, select your desired [continuous deployment strategy](../requirements.md#auto-devops-deployment-strategy)
to deploy the application to production after the pipeline successfully runs on the default branch.
1. Select **Save changes**.
1. Edit `.gitlab-ci.yml` file to include Auto DevOps template and commit the change to `master` branch:
```yaml
include:
- template: Auto-DevOps.gitlab-ci.yml
```
The commit should trigger a pipeline. In the next section, we explain what each job does in the pipeline.
## Deploy the application
When your pipeline runs, what is it doing?
To view the jobs in the pipeline, select 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.
The jobs are separated into stages:
![Pipeline stages](img/guide_pipeline_stages_v13_0.png)
- **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, but all jobs except `test`
are allowed to fail in the test stage:
- The `test` job runs unit and integration tests by detecting the language and
framework ([Auto Test](../stages.md#auto-test-deprecated))
- The `code_quality` job checks the code quality and is allowed to fail
([Auto Code Quality](../stages.md#auto-code-quality))
- The `container_scanning` job checks the Docker container if it has any
vulnerabilities and is allowed to fail ([Auto Container Scanning](../stages.md#auto-container-scanning))
- The `dependency_scanning` job checks if the application has any dependencies
susceptible to vulnerabilities and is allowed to fail
([Auto Dependency Scanning](../stages.md#auto-dependency-scanning))
- Jobs suffixed with `-sast` run static analysis on the current code to check for potential
security issues, and are allowed to fail ([Auto SAST](../stages.md#auto-sast))
- The `secret-detection` job checks for leaked secrets and is allowed to fail ([Auto Secret Detection](../stages.md#auto-secret-detection))
- The `license_scanning` job searches the application's dependencies to determine each of their
licenses and is allowed to fail
([Auto License Compliance](../stages.md#auto-license-compliance))
- **Review** - Pipelines on the default branch include this stage with a `dast_environment_deploy` job.
For more information, see [Dynamic Application Security Testing (DAST)](../../../user/application_security/dast/index.md).
- **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
([Auto Browser Performance Testing](../stages.md#auto-browser-performance-testing)).
- **Cleanup** - Pipelines on the default branch include this stage with a `stop_dast_environment` job.
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
**Operate > Environments**. This page displays details about
the deployed applications, and the right-hand column displays icons that link
you to common environment tasks:
![Environments](img/guide_environments_v12_3.png)
- **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}** **{chevron-lg-down}**) - Displays a list of environments you can deploy to
- **Terminal** (**{terminal}**) - Opens a [web terminal](../../../ci/environments/index.md#web-terminals-deprecated)
session inside the container where the application is running
- **Re-deploy to environment** (**{repeat}**) - For more information, see
[Retrying and rolling back](../../../ci/environments/index.md#retry-or-roll-back-a-deployment)
- **Stop environment** (**{stop}**) - For more information, see
[Stopping an environment](../../../ci/environments/index.md#stopping-an-environment)
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 selecting the square
takes you to the pod's logs page.
NOTE:
The example shows only one pod hosting the application at the moment, but you can add
more pods by defining the [`REPLICAS` CI/CD variable](../cicd_variables.md)
in **Settings > CI/CD > Variables**.
### Work with branches
Following the [GitLab flow](../../gitlab_flow.md#working-with-feature-branches),
you should next create a feature branch to add content to your application:
1. In your project's repository, go 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:
```html
<p>You're on Rails! Powered by GitLab Auto DevOps.</p>
```
1. Stage the file. Add a commit message, then create a new branch and a merge request
by selecting **Commit**.
![Web IDE commit](img/guide_ide_commit_v12_3.png)
After submitting the merge request, GitLab runs your pipeline, and all the jobs
in it, as [described previously](#deploy-the-application), in addition to
a few more that run only on branches other than the default branch.
After a few minutes a test fails, which means a test was
'broken' by your change. Select the failed `test` job to see more information
about it:
```plaintext
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
```
To fix the broken test:
1. Return to your merge request.
1. In the upper-right corner, select **Code**, then select **Open in Gitpod**.
1. In the left-hand directory of files, find the `test/controllers/welcome_controller_test.rb`
file, and select it to open it.
1. Change line 7 to say `You're on Rails! Powered by GitLab Auto DevOps.`
1. Select **Commit**.
1. In the left-hand column, under **Unstaged changes**, select the checkmark icon
(**{stage-all}**) to stage the changes.
1. Write a commit message, and select **Commit**.
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 selecting
the **View app** **{external-link}** button to see your changes deployed.
After merging the merge request, GitLab runs the pipeline on the default branch,
and then deploys the application to production.
## Conclusion
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
all in GitLab. Despite its automatic nature, Auto DevOps can also be configured
and customized to fit your workflow. Here are some helpful resources for further reading:
1. [Auto DevOps](../index.md)
1. [Multiple Kubernetes clusters](../multiple_clusters_auto_devops.md)
1. [Incremental rollout to production](../cicd_variables.md#incremental-rollout-to-production)
1. [Disable jobs you don't need with CI/CD variables](../cicd_variables.md)
1. [Use your own buildpacks to build your application](../customize.md#custom-buildpacks)
|