1--- 2stage: Configure 3group: Configure 4info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments 5--- 6 7# Tutorial: Use Auto DevOps to deploy an application to Google Kubernetes Engine **(FREE)** 8 9In this tutorial, we'll help you to get started with [Auto DevOps](index.md) 10through an example of how to deploy an application to Google Kubernetes Engine (GKE). 11 12You are using the GitLab native Kubernetes integration, so you don't need 13to create a Kubernetes cluster manually using the Google Cloud Platform console. 14You are creating and deploying an application that you create from a GitLab template. 15 16These instructions also work for self-managed GitLab instances. 17Ensure your own [runners are configured](../../ci/runners/index.md) and 18[Google OAuth is enabled](../../integration/google.md). 19 20To deploy a project to Google Kubernetes Engine, follow the steps below: 21 221. [Configure your Google account](#configure-your-google-account) 231. [Create a new project from a template](#create-a-new-project-from-a-template) 241. [Create a Kubernetes cluster from GitLab](#create-a-kubernetes-cluster-from-gitlab) 251. [Install Ingress](#install-ingress) 261. [Configure your base domain](#configure-your-base-domain) 271. [Enable Auto DevOps](#enable-auto-devops-optional) 281. [Deploy the application](#deploy-the-application) 29 30## Configure your Google account 31 32Before creating and connecting your Kubernetes cluster to your GitLab project, 33you need a [Google Cloud Platform account](https://console.cloud.google.com). 34Sign in with an existing Google account, such as the one you use to access Gmail 35or Google Drive, or create a new one. 36 371. Follow the steps described in the ["Before you begin" section](https://cloud.google.com/kubernetes-engine/docs/quickstart#before-you-begin) 38 of the Kubernetes Engine documentation to enable the required APIs and related services. 391. Ensure you've created a [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account) 40 with Google Cloud Platform. 41 42NOTE: 43Every new Google Cloud Platform (GCP) account receives [$300 in credit](https://console.cloud.google.com/freetrial), 44and in partnership with Google, GitLab is able to offer an additional $200 for new 45GCP accounts to get started with the GitLab integration with Google Kubernetes Engine. 46[Follow this link](https://cloud.google.com/partners/partnercredit/?pcn_code=0014M00001h35gDQAQ#contact-form) 47and apply for credit. 48 49## Create a new project from a template 50 51Use a GitLab project template to get started. As the name suggests, 52those projects provide a bare-bones application built on some well-known frameworks. 53 541. On the top bar in GitLab, select the plus icon (**{plus-square}**), and select 55 **New project/repository**. 561. Go to the **Create from template** tab, where you can choose a Ruby on 57 Rails, Spring, or NodeJS Express project. 58 For this tutorial, use the Ruby on Rails template. 59 60 ![Select project template](img/guide_project_template_v12_3.png) 61 621. Give your project a name, optionally a description, and make it public so that 63 you can take advantage of the features available in the 64 [GitLab Ultimate plan](https://about.gitlab.com/pricing/). 65 66 ![Create project](img/guide_create_project_v12_3.png) 67 681. Select **Create project**. 69 70Now that you've created a project, create the Kubernetes cluster 71to deploy this project to. 72 73## Create a Kubernetes cluster from GitLab 74 751. On your project's landing page, select the button **Add Kubernetes cluster**. 76 77 ![Project landing page](img/guide_project_landing_page_v12_10.png) 78 791. On the **Add a Kubernetes cluster integration** page, select the **Create new cluster** tab, 80 then select **Google GKE**. 81 821. Connect with your Google account, and select **Allow** to allow access to your 83 Google account. (This authorization request is only displayed the first time 84 you connect GitLab with your Google account.) 85 86 After authorizing access, the **Add a Kubernetes cluster integration** page 87 is displayed. 88 891. In the **Enter the details for your Kubernetes cluster** section, provide 90 details about your cluster: 91 92 - **Kubernetes cluster name** 93 - **Environment scope** - Leave this field unchanged. 94 - **Google Cloud Platform project** - Select a project. When you 95 [configured your Google account](#configure-your-google-account), a project 96 should have already been created for you. 97 - **Zone** - The [region/zone](https://cloud.google.com/compute/docs/regions-zones/) to 98 create the cluster in. 99 - **Number of nodes** 100 - **Machine type** - For more information about 101 [machine types](https://cloud.google.com/compute/docs/machine-types), see Google's documentation. 102 - **Enable Cloud Run for Anthos** - Select this checkbox to use the 103 [Cloud Run](../../user/project/clusters/add_gke_clusters.md#cloud-run-for-anthos), 104 Istio, and HTTP Load Balancing add-ons for this cluster. 105 - **GitLab-managed cluster** - Select this checkbox to 106 [allow GitLab to manage namespace and service accounts](../../user/project/clusters/gitlab_managed_clusters.md) for this cluster. 107 1081. Select **Create Kubernetes cluster**. 109 110After a couple of minutes, the cluster is created. You can also see its 111status on your [GCP dashboard](https://console.cloud.google.com/kubernetes). 112 113## Install Ingress 114 115After your cluster is running, you must install NGINX Ingress Controller as a 116load balancer, to route traffic from the internet to your application. 117Install the NGINX Ingress Controller 118through the GitLab [Cluster management project template](../../user/clusters/management_project_template.md), 119or manually with Google Cloud Shell: 120 1211. Go to your cluster's details page, and select the **Advanced Settings** tab. 1221. Select the link to Google Kubernetes Engine to visit the cluster on Google Cloud Console. 1231. On the GKE cluster page, select **Connect**, then select **Run in Cloud Shell**. 1241. After the Cloud Shell starts, run these commands to install NGINX Ingress Controller: 125 126 ```shell 127 kubectl create ns gitlab-managed-apps 128 helm repo add stable https://charts.helm.sh/stable 129 helm repo update 130 helm install ingress stable/nginx-ingress -n gitlab-managed-apps 131 132 # Check that the ingress controller is installed successfully 133 kubectl get service ingress-nginx-ingress-controller -n gitlab-managed-apps 134 ``` 135 136## Configure your base domain 137 138Follow these steps to configure the base domain where you access your apps. 139 1401. A few minutes after you install NGINX, the load balancer obtains an IP address, and you can 141 get the external IP address with the following command: 142 143 ```shell 144 kubectl get service ingress-nginx-ingress-controller -n gitlab-managed-apps -ojson | jq -r '.status.loadBalancer.ingress[].ip' 145 ``` 146 147 Replace `gitlab-managed-apps` if you have overwritten your namespace. 148 149 Copy this IP address, as you need it in the next step. 150 1511. Go back to the cluster page on GitLab, and go to the **Details** tab. 152 - Add your **Base domain**. For this example, use the domain `<IP address>.nip.io`. 153 - Select **Save changes**. 154 155 ![Cluster Base Domain](img/guide_base_domain_v12_3.png) 156 157## Enable Auto DevOps (optional) 158 159While Auto DevOps is enabled by default, Auto DevOps can be disabled at both 160the instance level (for self-managed instances) and the group level. Complete 161these steps to enable Auto DevOps if it's disabled: 162 1631. Go to **Settings > CI/CD > Auto DevOps**, and select **Expand**. 1641. Select **Default to Auto DevOps pipeline** to display more options. 1651. In **Deployment strategy**, select your desired [continuous deployment strategy](requirements.md#auto-devops-deployment-strategy) 166 to deploy the application to production after the pipeline successfully runs on the default branch. 1671. Select **Save changes**. 168 169 ![Auto DevOps settings](img/guide_enable_autodevops_v12_3.png) 170 171After you save your changes, GitLab creates a new pipeline. To view it, go to 172**{rocket}** **CI/CD > Pipelines**. 173 174In the next section, we explain what each job does in the pipeline. 175 176## Deploy the application 177 178When your pipeline runs, what is it doing? 179 180To view the jobs in the pipeline, select the pipeline's status badge. The 181**{status_running}** icon displays when pipeline jobs are running, and updates 182without refreshing the page to **{status_success}** (for success) or 183**{status_failed}** (for failure) when the jobs complete. 184 185The jobs are separated into stages: 186 187![Pipeline stages](img/guide_pipeline_stages_v13_0.png) 188 189- **Build** - The application builds a Docker image and uploads it to your project's 190 [Container Registry](../../user/packages/container_registry/index.md) ([Auto Build](stages.md#auto-build)). 191- **Test** - GitLab runs various checks on the application, but all jobs except `test` 192 are allowed to fail in the test stage: 193 194 - The `test` job runs unit and integration tests by detecting the language and 195 framework ([Auto Test](stages.md#auto-test)) 196 - The `code_quality` job checks the code quality and is allowed to fail 197 ([Auto Code Quality](stages.md#auto-code-quality)) 198 - The `container_scanning` job checks the Docker container if it has any 199 vulnerabilities and is allowed to fail ([Auto Container Scanning](stages.md#auto-container-scanning)) 200 - The `dependency_scanning` job checks if the application has any dependencies 201 susceptible to vulnerabilities and is allowed to fail 202 ([Auto Dependency Scanning](stages.md#auto-dependency-scanning)) 203 - Jobs suffixed with `-sast` run static analysis on the current code to check for potential 204 security issues, and are allowed to fail ([Auto SAST](stages.md#auto-sast)) 205 - The `secret-detection` job checks for leaked secrets and is allowed to fail ([Auto Secret Detection](stages.md#auto-secret-detection)) 206 - The `license_scanning` job searches the application's dependencies to determine each of their 207 licenses and is allowed to fail 208 ([Auto License Compliance](stages.md#auto-license-compliance)) 209 210- **Review** - Pipelines on the default branch include this stage with a `dast_environment_deploy` job. 211 To learn more, see [Dynamic Application Security Testing (DAST)](../../user/application_security/dast/index.md). 212 213- **Production** - After the tests and checks finish, the application deploys in 214 Kubernetes ([Auto Deploy](stages.md#auto-deploy)). 215 216- **Performance** - Performance tests are run on the deployed application 217 ([Auto Browser Performance Testing](stages.md#auto-browser-performance-testing)). 218 219- **Cleanup** - Pipelines on the default branch include this stage with a `stop_dast_environment` job. 220 221After running a pipeline, you should view your deployed website and learn how 222to monitor it. 223 224### Monitor your project 225 226After successfully deploying your application, you can view its website and check 227on its health on the **Environments** page by navigating to 228**Deployments > Environments**. This page displays details about 229the deployed applications, and the right-hand column displays icons that link 230you to common environment tasks: 231 232![Environments](img/guide_environments_v12_3.png) 233 234- **Open live environment** (**{external-link}**) - Opens the URL of the application deployed in production 235- **Monitoring** (**{chart}**) - Opens the metrics page where Prometheus collects data 236 about the Kubernetes cluster and how the application 237 affects it in terms of memory usage, CPU usage, and latency 238- **Deploy to** (**{play}** **{angle-down}**) - Displays a list of environments you can deploy to 239- **Terminal** (**{terminal}**) - Opens a [web terminal](../../ci/environments/index.md#web-terminals-deprecated) 240 session inside the container where the application is running 241- **Re-deploy to environment** (**{repeat}**) - For more information, see 242 [Retrying and rolling back](../../ci/environments/index.md#retry-or-roll-back-a-deployment) 243- **Stop environment** (**{stop}**) - For more information, see 244 [Stopping an environment](../../ci/environments/index.md#stop-an-environment) 245 246GitLab displays the [deploy board](../../user/project/deploy_boards.md) below the 247environment's information, with squares representing pods in your 248Kubernetes cluster, color-coded to show their status. Hovering over a square on 249the deploy board displays the state of the deployment, and selecting the square 250takes you to the pod's logs page. 251 252NOTE: 253The example shows only one pod hosting the application at the moment, but you can add 254more pods by defining the [`REPLICAS` CI/CD variable](customize.md#cicd-variables) 255in **Settings > CI/CD > Variables**. 256 257### Work with branches 258 259Following the [GitLab flow](../gitlab_flow.md#working-with-feature-branches), 260you should next create a feature branch to add content to your application: 261 2621. In your project's repository, go to the following file: `app/views/welcome/index.html.erb`. 263 This file should only contain a paragraph: `<p>You're on Rails!</p>`. 2641. Open the GitLab [Web IDE](../../user/project/web_ide/index.md) to make the change. 2651. Edit the file so it contains: 266 267 ```html 268 <p>You're on Rails! Powered by GitLab Auto DevOps.</p> 269 ``` 270 2711. Stage the file. Add a commit message, then create a new branch and a merge request 272 by selecting **Commit**. 273 274 ![Web IDE commit](img/guide_ide_commit_v12_3.png) 275 276After submitting the merge request, GitLab runs your pipeline, and all the jobs 277in it, as [described previously](#deploy-the-application), in addition to 278a few more that run only on branches other than the default branch. 279 280![Merge request](img/guide_merge_request_v12_3.png) 281 282After a few minutes a test fails, which means a test was 283'broken' by your change. Select the failed `test` job to see more information 284about it: 285 286```plaintext 287Failure: 288WelcomeControllerTest#test_should_get_index [/app/test/controllers/welcome_controller_test.rb:7]: 289<You're on Rails!> expected but was 290<You're on Rails! Powered by GitLab Auto DevOps.>.. 291Expected 0 to be >= 1. 292 293bin/rails test test/controllers/welcome_controller_test.rb:4 294``` 295 296To fix the broken test: 297 2981. Return to the **Overview** page for your merge request, and select **Open in Web IDE**. 2991. In the left-hand directory of files, find the `test/controllers/welcome_controller_test.rb` 300 file, and select it to open it. 3011. Change line 7 to say `You're on Rails! Powered by GitLab Auto DevOps.` 3021. Select **Commit**. 3031. In the left-hand column, under **Unstaged changes**, select the checkmark icon 304 (**{stage-all}**) to stage the changes. 3051. Write a commit message, and select **Commit**. 306 307Return to the **Overview** page of your merge request, and you should not only 308see the test passing, but also the application deployed as a 309[review application](stages.md#auto-review-apps). You can visit it by selecting 310the **View app** **{external-link}** button to see your changes deployed. 311 312![Review app](img/guide_merge_request_review_app_v12_3.png) 313 314After merging the merge request, GitLab runs the pipeline on the default branch, 315and then deploys the application to production. 316 317## Conclusion 318 319After implementing this project, you should have a solid understanding of the basics of Auto DevOps. 320You started from building and testing, to deploying and monitoring an application 321all in GitLab. Despite its automatic nature, Auto DevOps can also be configured 322and customized to fit your workflow. Here are some helpful resources for further reading: 323 3241. [Auto DevOps](index.md) 3251. [Multiple Kubernetes clusters](multiple_clusters_auto_devops.md) 3261. [Incremental rollout to production](customize.md#incremental-rollout-to-production) 3271. [Disable jobs you don't need with CI/CD variables](customize.md#cicd-variables) 3281. [Use your own buildpacks to build your application](customize.md#custom-buildpacks) 3291. [Prometheus monitoring](../../user/project/integrations/prometheus.md) 330