diff options
Diffstat (limited to 'doc/topics/autodevops/index.md')
| -rw-r--r-- | doc/topics/autodevops/index.md | 183 |
1 files changed, 81 insertions, 102 deletions
diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 5a8744d71f9..2fd26bb4899 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -8,20 +8,23 @@ to simplify the setup and execution of a mature & modern software development li ## Overview -NOTE: **Enabled by default:** -Starting with GitLab 11.3, the Auto DevOps pipeline is enabled by default for all -projects. If it has not been explicitly enabled for the project, Auto DevOps will be automatically -disabled on the first pipeline failure. Your project will continue to use an alternative -[CI/CD configuration file](../../ci/yaml/README.md) if one is found. A GitLab -administrator can [change this setting](../../user/admin_area/settings/continuous_integration.html#auto-devops-core-only) -in the admin area. - With Auto DevOps, the software development process becomes easier to set up as every project can have a complete workflow from verification to monitoring with minimal configuration. Just push your code and GitLab takes care of everything else. This makes it easier to start new projects and brings consistency to how applications are set up throughout a company. +For a demonstration of Auto DevOps, watch the video [GitLab Auto DevOps demo](https://youtu.be/4Uo_QP9rSGM). + +## Enabled by default + +Starting with GitLab 11.3, the Auto DevOps pipeline is enabled by default for all +projects. If it has not been explicitly enabled for the project, Auto DevOps will be automatically +disabled on the first pipeline failure. Your project will continue to use an alternative +[CI/CD configuration file](../../ci/yaml/README.md) if one is found. A GitLab +administrator can [change this setting](../../user/admin_area/settings/continuous_integration.md#auto-devops-core-only) +in the admin area. + ## Quick start If you are using GitLab.com, see the [quick start guide](quick_start_guide.md) @@ -62,7 +65,7 @@ project in a simple and automatic way: 1. [Auto SAST (Static Application Security Testing)](#auto-sast-ultimate) **[ULTIMATE]** 1. [Auto Dependency Scanning](#auto-dependency-scanning-ultimate) **[ULTIMATE]** 1. [Auto License Management](#auto-license-management-ultimate) **[ULTIMATE]** -1. [Auto Container Scanning](#auto-container-scanning) +1. [Auto Container Scanning](#auto-container-scanning-ultimate) **[ULTIMATE]** 1. [Auto Review Apps](#auto-review-apps) 1. [Auto DAST (Dynamic Application Security Testing)](#auto-dast-ultimate) **[ULTIMATE]** 1. [Auto Deploy](#auto-deploy) @@ -120,16 +123,11 @@ To make full use of Auto DevOps, you will need: [default service template](../../user/project/integrations/services_templates.md) for the entire GitLab installation. -NOTE: **Note:** If you do not have Kubernetes or Prometheus installed, then Auto Review Apps, Auto Deploy, and Auto Monitoring will be silently skipped. ## Auto DevOps base domain -NOTE: **Note** -`AUTO_DEVOPS_DOMAIN` environment variable is deprecated and -[is scheduled to be removed](https://gitlab.com/gitlab-org/gitlab-ce/issues/56959). - The Auto DevOps base domain is required if you want to make use of [Auto Review Apps](#auto-review-apps) and [Auto Deploy](#auto-deploy). It can be defined in any of the following places: @@ -139,10 +137,13 @@ in any of the following places: - or at the project level as a variable: `KUBE_INGRESS_BASE_DOMAIN` - or at the group level as a variable: `KUBE_INGRESS_BASE_DOMAIN`. -NOTE: **Note** -The Auto DevOps base domain variable (`KUBE_INGRESS_BASE_DOMAIN`) follows the same order of precedence +The base domain variable `KUBE_INGRESS_BASE_DOMAIN` follows the same order of precedence as other environment [variables](../../ci/variables/README.md#priority-of-environment-variables). +NOTE: **Note** +`AUTO_DEVOPS_DOMAIN` environment variable is deprecated and +[is scheduled to be removed](https://gitlab.com/gitlab-org/gitlab-ce/issues/56959). + A wildcard DNS A record matching the base domain(s) is required, for example, given a base domain of `example.com`, you'd need a DNS entry like: @@ -162,6 +163,12 @@ Auto DevOps base domain to `1.2.3.4.nip.io`. Once set up, all requests will hit the load balancer, which in turn will route them to the Kubernetes pods that run your application(s). +NOTE: **Note:** +From GitLab 11.8, `KUBE_INGRESS_BASE_DOMAIN` replaces `AUTO_DEVOPS_DOMAIN`. +Support for `AUTO_DEVOPS_DOMAIN` was [removed in GitLab +12.0](https://gitlab.com/gitlab-org/gitlab-ce/issues/56959). + + ## Using multiple Kubernetes clusters **[PREMIUM]** When using Auto DevOps, you may want to deploy different environments to @@ -179,7 +186,7 @@ Those environments are tied to jobs that use [Auto Deploy](#auto-deploy), so except for the environment scope, they would also need to have a different domain they would be deployed to. This is why you need to define a separate `KUBE_INGRESS_BASE_DOMAIN` variable for all the above -[based on the environment](https://docs.gitlab.com/ee/ci/variables/#limiting-environment-scopes-of-environment-variables-premium). +[based on the environment](../../ci/variables/README.md#limiting-environment-scopes-of-environment-variables-premium). The following table is an example of how the three different clusters would be configured. @@ -209,10 +216,6 @@ and verifying that your app is deployed as a review app in the Kubernetes cluster with the `review/*` environment scope. Similarly, you can check the other environments. -NOTE: **Note:** -From GitLab 11.8, `KUBE_INGRESS_BASE_DOMAIN` replaces `AUTO_DEVOPS_DOMAIN`. -`AUTO_DEVOPS_DOMAIN` [is scheduled to be removed](https://gitlab.com/gitlab-org/gitlab-ce/issues/56959). - ## Enabling/Disabling Auto DevOps When first using Auto Devops, review the [requirements](#requirements) to ensure all necessary components to make @@ -224,19 +227,20 @@ can enable/disable Auto DevOps at either the project-level or instance-level. ### Enabling/disabling Auto DevOps at the instance-level (Administrators only) +Even when disabled at the instance level, group owners and project maintainers can still enable +Auto DevOps at the group and project level, respectively. + 1. Go to **Admin area > Settings > Continuous Integration and Deployment**. 1. Toggle the checkbox labeled **Default to Auto DevOps pipeline for all projects**. 1. If enabling, optionally set up the Auto DevOps [base domain](#auto-devops-base-domain) which will be used for Auto Deploy and Auto Review Apps. 1. Click **Save changes** for the changes to take effect. -NOTE: **Note:** -Even when disabled at the instance level, group owners and project maintainers are still able to enable -Auto DevOps at group-level and project-level, respectively. - ### Enabling/disabling Auto DevOps at the group-level > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/52447) in GitLab 11.10. +Only administrators and group owners can enable or disable Auto DevOps at the group level. + To enable or disable Auto DevOps at the group-level: 1. Go to group's **Settings > CI/CD > Auto DevOps** page. @@ -247,9 +251,6 @@ When enabling or disabling Auto DevOps at group-level, group configuration will the subgroups and projects inside that group, unless Auto DevOps is specifically enabled or disabled on the subgroup or project. -NOTE: **Note** -Only administrators and group owners are allowed to enable or disable Auto DevOps at group-level. - ### Enabling/disabling Auto DevOps at the project-level If enabling, check that your project doesn't have a `.gitlab-ci.yml`, or if one exists, remove it. @@ -263,16 +264,13 @@ If enabling, check that your project doesn't have a `.gitlab-ci.yml`, or if one When the feature has been enabled, an Auto DevOps pipeline is triggered on the default branch. -NOTE: **Note:** -For GitLab versions 10.0 - 10.2, when enabling Auto DevOps, a pipeline needs to be -manually triggered either by pushing a new commit to the repository or by visiting -`https://example.gitlab.com/<username>/<project>/pipelines/new` and creating -a new pipeline for your default branch, generally `master`. +### Feature flag to enable for a percentage of projects -NOTE: **Note:** -There is also a feature flag to enable Auto DevOps to a percentage of projects -which can be enabled from the console with -`Feature.get(:force_autodevops_on_by_default).enable_percentage_of_actors(10)`. +There is also a feature flag to enable Auto DevOps by default to your chosen percentage of projects. + +This can be enabled from the console with the following, which uses the example of 10%: + +`Feature.get(:force_autodevops_on_by_default).enable_percentage_of_actors(10)` ### Deployment strategy @@ -352,7 +350,6 @@ frameworks are detected automatically, but if your language is not detected, you may succeed with a [custom buildpack](#custom-buildpacks). Check the [currently supported languages](#currently-supported-languages). -NOTE: **Note:** Auto Test uses tests you already have in your application. If there are no tests, it's up to you to add them. @@ -365,7 +362,7 @@ created, and is uploaded as an artifact which you can later download and check out. Any differences between the source and target branches are also -[shown in the merge request widget](https://docs.gitlab.com/ee/user/project/merge_requests/code_quality.html). +[shown in the merge request widget](../../user/project/merge_requests/code_quality.md). ### Auto SAST **[ULTIMATE]** @@ -373,18 +370,14 @@ Any differences between the source and target branches are also Static Application Security Testing (SAST) uses the [SAST Docker image](https://gitlab.com/gitlab-org/security-products/sast) to run static -analysis on the current code and checks for potential security issues. Once the -report is created, it's uploaded as an artifact which you can later download and +analysis on the current code and checks for potential security issues. The +the Auto SAST stage will be skipped on licenses other than Ultimate and requires GitLab Runner 11.5 or above. + +Once the report is created, it's uploaded as an artifact which you can later download and check out. Any security warnings are also shown in the merge request widget. Read more how -[SAST works](https://docs.gitlab.com/ee/user/application_security/sast/index.html). - -NOTE: **Note:** -The Auto SAST stage will be skipped on licenses other than Ultimate. - -NOTE: **Note:** -The Auto SAST job requires GitLab Runner 11.5 or above. +[SAST works](../../user/application_security/sast/index.md). ### Auto Dependency Scanning **[ULTIMATE]** @@ -392,18 +385,16 @@ The Auto SAST job requires GitLab Runner 11.5 or above. Dependency Scanning uses the [Dependency Scanning Docker image](https://gitlab.com/gitlab-org/security-products/dependency-scanning) -to run analysis on the project dependencies and checks for potential security issues. Once the +to run analysis on the project dependencies and checks for potential security issues. +The Auto Dependency Scanning stage will be skipped on licenses other than Ultimate +and requires GitLab Runner 11.5 or above. + +Once the report is created, it's uploaded as an artifact which you can later download and check out. Any security warnings are also shown in the merge request widget. Read more about -[Dependency Scanning](https://docs.gitlab.com/ee/user/application_security/dependency_scanning/index.html). - -NOTE: **Note:** -The Auto Dependency Scanning stage will be skipped on licenses other than Ultimate. - -NOTE: **Note:** -The Auto Dependency Scanning job requires GitLab Runner 11.5 or above. +[Dependency Scanning](../../user/application_security/dependency_scanning/index.md). ### Auto License Management **[ULTIMATE]** @@ -411,35 +402,34 @@ The Auto Dependency Scanning job requires GitLab Runner 11.5 or above. License Management uses the [License Management Docker image](https://gitlab.com/gitlab-org/security-products/license-management) -to search the project dependencies for their license. Once the +to search the project dependencies for their license. The Auto License Management stage +will be skipped on licenses other than Ultimate. + +Once the report is created, it's uploaded as an artifact which you can later download and check out. Any licenses are also shown in the merge request widget. Read more how -[License Management works](https://docs.gitlab.com/ee/user/application_security/license_management/index.html). +[License Management works](../../user/application_security/license_management/index.md). -NOTE: **Note:** -The Auto License Management stage will be skipped on licenses other than Ultimate. - -### Auto Container Scanning +### Auto Container Scanning **[ULTIMATE]** > Introduced in GitLab 10.4. Vulnerability Static Analysis for containers uses [Clair](https://github.com/coreos/clair) to run static analysis on a -Docker image and checks for potential security issues. Once the report is +Docker image and checks for potential security issues. The Auto Container Scanning stage +will be skipped on licenses other than Ultimate. + +Once the report is created, it's uploaded as an artifact which you can later download and check out. Any security warnings are also shown in the merge request widget. Read more how -[Container Scanning works](https://docs.gitlab.com/ee/user/application_security/container_scanning/index.html). - -NOTE: **Note:** -The Auto Container Scanning stage will be skipped on licenses other than Ultimate. +[Container Scanning works](../../user/application_security/container_scanning/index.md). ### Auto Review Apps -NOTE: **Note:** This is an optional step, since many projects do not have a Kubernetes cluster available. If the [requirements](#requirements) are not met, the job will silently be skipped. @@ -484,14 +474,13 @@ in the first place, and thus not realize that it needs to re-apply the old confi Dynamic Application Security Testing (DAST) uses the popular open source tool [OWASP ZAProxy](https://github.com/zaproxy/zaproxy) to perform an analysis on the current code and checks for potential security -issues. Once the report is created, it's uploaded as an artifact which you can +issues. The Auto DAST stage will be skipped on licenses other than Ultimate. + +Once the report is created, it's uploaded as an artifact which you can later download and check out. Any security warnings are also shown in the merge request widget. Read how -[DAST works](https://docs.gitlab.com/ee/user/application_security/dast/index.html). - -NOTE: **Note:** -The Auto DAST stage will be skipped on licenses other than Ultimate. +[DAST works](../../user/application_security/dast/index.md). ### Auto Browser Performance Testing **[PREMIUM]** @@ -506,11 +495,10 @@ Auto Browser Performance Testing utilizes the [Sitespeed.io container](https://h ``` Any performance differences between the source and target branches are also -[shown in the merge request widget](https://docs.gitlab.com/ee//user/project/merge_requests/browser_performance_testing.html). +[shown in the merge request widget](../../user/project/merge_requests/browser_performance_testing.md). ### Auto Deploy -NOTE: **Note:** This is an optional step, since many projects do not have a Kubernetes cluster available. If the [requirements](#requirements) are not met, the job will silently be skipped. @@ -549,7 +537,7 @@ in the first place, and thus not realize that it needs to re-apply the old confi For internal and private projects a [GitLab Deploy Token](../../user/project/deploy_tokens/index.md#gitlab-deploy-token) will be automatically created, when Auto DevOps is enabled and the Auto DevOps settings are saved. This Deploy Token -can be used for permanent access to the registry. +can be used for permanent access to the registry. When the GitLab Deploy Token has been manually revoked, it won't be automatically created. If the GitLab Deploy Token cannot be found, `CI_REGISTRY_PASSWORD` is used. Note that `CI_REGISTRY_PASSWORD` is only valid during deployment. @@ -559,9 +547,6 @@ be pulled again, e.g. after pod eviction, Kubernetes will fail to do so as it will be attempting to fetch the image using `CI_REGISTRY_PASSWORD`. -NOTE: **Note:** -When the GitLab Deploy Token has been manually revoked, it won't be automatically created. - #### Migrations > [Introduced][ce-21955] in GitLab 11.4 @@ -584,22 +569,19 @@ Note that a post-install hook means that if any deploy succeeds, If present, `DB_MIGRATE` will be run as a shell command within an application pod as a helm pre-upgrade hook. -For example, in a Rails application: +For example, in a Rails application in an image built with +[Herokuish](https://github.com/gliderlabs/herokuish): -- `DB_INITIALIZE` can be set to `cd /app && RAILS_ENV=production - bin/setup` -- `DB_MIGRATE` can be set to `cd /app && RAILS_ENV=production bin/update` +- `DB_INITIALIZE` can be set to `RAILS_ENV=production /bin/herokuish procfile exec bin/rails db:setup` +- `DB_MIGRATE` can be set to `RAILS_ENV=production /bin/herokuish procfile exec bin/rails db:migrate` -NOTE: **Note:** -The `/app` path is the directory of your project inside the docker image -as [configured by -Herokuish](https://github.com/gliderlabs/herokuish#paths) +Unless you have a `Dockerfile` in your repo, your image is built with +Herokuish, and you must prefix commands run in these images with `/bin/herokuish +procfile exec` to replicate the environment where your application will run. ### Auto Monitoring -NOTE: **Note:** -Check the [requirements](#requirements) for Auto Monitoring to make this stage -work. +See the [requirements](#requirements) for Auto Monitoring to enable this stage. Once your application is deployed, Auto Monitoring makes it possible to monitor your application's server and response metrics right out of the box. Auto @@ -675,7 +657,7 @@ repo or by specifying a project variable: ### Custom Helm chart per environment **[PREMIUM]** You can specify the use of a custom Helm chart per environment by scoping the environment variable -to the desired environment. See [Limiting environment scopes of variables](https://docs.gitlab.com/ee/ci/variables/#limiting-environment-scopes-of-variables-premium). +to the desired environment. See [Limiting environment scopes of variables](../../ci/variables/README.md#limiting-environment-scopes-of-environment-variables-premium). ### Customizing `.gitlab-ci.yml` @@ -734,7 +716,6 @@ also be customized, and you can easily use a [custom buildpack](#custom-buildpac | **Variable** | **Description** | | ------------ | --------------- | -| `AUTO_DEVOPS_DOMAIN` | The [Auto DevOps domain](#auto-devops-base-domain). By default, set automatically by the [Auto DevOps setting](#enablingdisabling-auto-devops). This variable is deprecated and [is scheduled to be removed](https://gitlab.com/gitlab-org/gitlab-ce/issues/56959). Use `KUBE_INGRESS_BASE_DOMAIN` instead. | | `AUTO_DEVOPS_CHART` | The Helm Chart used to deploy your apps; defaults to the one [provided by GitLab](https://gitlab.com/gitlab-org/charts/auto-deploy-app). | | `AUTO_DEVOPS_CHART_REPOSITORY` | The Helm Chart repository used to search for charts; defaults to `https://charts.gitlab.io`. | | `AUTO_DEVOPS_CHART_REPOSITORY_NAME` | From Gitlab 11.11, this variable can be used to set the name of the helm repository; defaults to "gitlab" | @@ -742,8 +723,8 @@ also be customized, and you can easily use a [custom buildpack](#custom-buildpac | `AUTO_DEVOPS_CHART_REPOSITORY_PASSWORD` | From Gitlab 11.11, this variable can be used to set a password to connect to the helm repository. Defaults to no credentials. (Also set AUTO_DEVOPS_CHART_REPOSITORY_USERNAME) | | `REPLICAS` | The number of replicas to deploy; defaults to 1. | | `PRODUCTION_REPLICAS` | The number of replicas to deploy in the production environment. This takes precedence over `REPLICAS`; defaults to 1. | -| `CANARY_REPLICAS` | The number of canary replicas to deploy for [Canary Deployments](https://docs.gitlab.com/ee/user/project/canary_deployments.html); defaults to 1 | -| `CANARY_PRODUCTION_REPLICAS` | The number of canary replicas to deploy for [Canary Deployments](https://docs.gitlab.com/ee/user/project/canary_deployments.html) in the production environment. This takes precedence over `CANARY_REPLICAS`; defaults to 1 | +| `CANARY_REPLICAS` | The number of canary replicas to deploy for [Canary Deployments](../../user/project/canary_deployments.md); defaults to 1 | +| `CANARY_PRODUCTION_REPLICAS` | The number of canary replicas to deploy for [Canary Deployments](../../user/project/canary_deployments.md) in the production environment. This takes precedence over `CANARY_REPLICAS`; defaults to 1 | | `ADDITIONAL_HOSTS` | Fully qualified domain names specified as a comma-separated list that are added to the ingress hosts. | | `<ENVIRONMENT>_ADDITIONAL_HOSTS` | For a specific environment, the fully qualified domain names specified as a comma-separated list that are added to the ingress hosts. This takes precedence over `ADDITIONAL_HOSTS`. | | `POSTGRES_ENABLED` | Whether PostgreSQL is enabled; defaults to `"true"`. Set to `false` to disable the automatic deployment of PostgreSQL. | @@ -828,11 +809,6 @@ metadata: type: Opaque ``` -CAUTION: **Caution:** -Variables with multiline values are not currently supported due to -limitations with the current Auto DevOps scripting environment. - -NOTE: **Note:** Environment variables are generally considered immutable in a Kubernetes pod. Therefore, if you update an application secret without changing any code then manually create a new pipeline, you will find that any running @@ -841,6 +817,10 @@ can either push a code update to GitLab to force the Kubernetes Deployment to recreate pods or manually delete running pods to cause Kubernetes to create new pods with updated secrets. +NOTE: **Note:** +Variables with multiline values are not currently supported due to +limitations with the current Auto DevOps scripting environment. + #### Advanced replica variables setup Apart from the two replica-related variables for production mentioned above, @@ -920,7 +900,7 @@ you when you're ready to manually deploy to production. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ci-yml/merge_requests/171) in GitLab 11.0. -A [canary environment](https://docs.gitlab.com/ee/user/project/canary_deployments.html) can be used +A [canary environment](../../user/project/canary_deployments.md) can be used before any changes are deployed to production. If `CANARY_ENABLED` is defined in your project (e.g., set `CANARY_ENABLED` to @@ -1009,8 +989,7 @@ Everything behaves the same way, except: ## Currently supported languages -NOTE: **Note:** -Not all buildpacks support Auto Test yet, as it's a relatively new +Note that not all buildpacks support Auto Test yet, as it's a relatively new enhancement. All of Heroku's [officially supported languages](https://devcenter.heroku.com/articles/heroku-ci#currently-supported-languages) support it, and some third-party buildpacks as well e.g., Go, Node, Java, PHP, |