diff options
Diffstat (limited to 'doc/topics/autodevops')
| -rw-r--r-- | doc/topics/autodevops/cicd_variables.md | 331 | ||||
| -rw-r--r-- | doc/topics/autodevops/cloud_deployments/auto_devops_with_gke.md | 6 | ||||
| -rw-r--r-- | doc/topics/autodevops/customize.md | 350 | ||||
| -rw-r--r-- | doc/topics/autodevops/index.md | 2 | ||||
| -rw-r--r-- | doc/topics/autodevops/multiple_clusters_auto_devops.md | 6 | ||||
| -rw-r--r-- | doc/topics/autodevops/prepare_deployment.md | 4 | ||||
| -rw-r--r-- | doc/topics/autodevops/requirements.md | 4 | ||||
| -rw-r--r-- | doc/topics/autodevops/stages.md | 4 | ||||
| -rw-r--r-- | doc/topics/autodevops/troubleshooting.md | 4 | ||||
| -rw-r--r-- | doc/topics/autodevops/upgrading_auto_deploy_dependencies.md | 4 |
10 files changed, 355 insertions, 360 deletions
diff --git a/doc/topics/autodevops/cicd_variables.md b/doc/topics/autodevops/cicd_variables.md new file mode 100644 index 00000000000..db2b052784d --- /dev/null +++ b/doc/topics/autodevops/cicd_variables.md @@ -0,0 +1,331 @@ +--- +stage: Configure +group: Configure +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 +--- + +# CI/CD variables + +Use CI/CD variables to set up the Auto DevOps domain, provide a custom +Helm chart, or scale your application. + +## Build and deployment variables + +Use these variables to customize and deploy your build. + +| **CI/CD variable** | **Description** | +|-----------------------------------------|------------------------------------| +| `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`. | +| `AUTO_BUILD_IMAGE_VERSION` | Customize the image version used for the `build` job. See [list of versions](https://gitlab.com/gitlab-org/cluster-integration/auto-build-image/-/releases). | +| `AUTO_DEPLOY_IMAGE_VERSION` | Customize the image version used for Kubernetes deployment jobs. See [list of versions](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/releases). | +| `AUTO_DEVOPS_ATOMIC_RELEASE` | As of GitLab 13.0, Auto DevOps uses [`--atomic`](https://v2.helm.sh/docs/helm/#options-43) for Helm deployments by default. Set this variable to `false` to disable the use of `--atomic` | +| `AUTO_DEVOPS_BUILD_IMAGE_CNB_ENABLED` | Set to `false` to use Herokuish instead of Cloud Native Buildpacks with Auto Build. [More details](stages.md#auto-build-using-cloud-native-buildpacks). | +| `AUTO_DEVOPS_BUILD_IMAGE_CNB_BUILDER` | The builder used when building with Cloud Native Buildpacks. The default builder is `heroku/buildpacks:18`. [More details](stages.md#auto-build-using-cloud-native-buildpacks). | +| `AUTO_DEVOPS_BUILD_IMAGE_EXTRA_ARGS` | Extra arguments to be passed to the `docker build` command. Using quotes doesn't prevent word splitting. [More details](customize.md#passing-arguments-to-docker-build). | +| `AUTO_DEVOPS_BUILD_IMAGE_FORWARDED_CI_VARIABLES` | A [comma-separated list of CI/CD variable names](customize.md#forward-cicd-variables-to-the-build-environment) to be forwarded to the build environment (the buildpack builder or `docker build`). | +| `AUTO_DEVOPS_BUILD_IMAGE_CNB_PORT` | In GitLab 15.0 and later, port exposed by the generated Docker image. Set to `false` to prevent exposing any ports. Defaults to `5000`. | +| `AUTO_DEVOPS_CHART` | Helm Chart used to deploy your apps. Defaults to the one [provided by GitLab](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app). | +| `AUTO_DEVOPS_CHART_REPOSITORY` | Helm Chart repository used to search for charts. Defaults to `https://charts.gitlab.io`. | +| `AUTO_DEVOPS_CHART_REPOSITORY_NAME` | Used to set the name of the Helm repository. Defaults to `gitlab`. | +| `AUTO_DEVOPS_CHART_REPOSITORY_USERNAME` | Used to set a username to connect to the Helm repository. Defaults to no credentials. Also set `AUTO_DEVOPS_CHART_REPOSITORY_PASSWORD`. | +| `AUTO_DEVOPS_CHART_REPOSITORY_PASSWORD` | Used to set a password to connect to the Helm repository. Defaults to no credentials. Also set `AUTO_DEVOPS_CHART_REPOSITORY_USERNAME`. | +| `AUTO_DEVOPS_CHART_REPOSITORY_PASS_CREDENTIALS` | From GitLab 14.2, set to a non-empty value to enable forwarding of the Helm repository credentials to the chart server when the chart artifacts are on a different host than repository. | +| `AUTO_DEVOPS_COMMON_NAME` | From GitLab 15.5, set to a valid domain name to customize the common name used for the TLS certificate. Defaults to `le-$CI_PROJECT_ID.$KUBE_INGRESS_BASE_DOMAIN`. Set to `false` to not set this alternative host on the Ingress. | +| `AUTO_DEVOPS_DEPLOY_DEBUG` | From GitLab 13.1, if this variable is present, Helm outputs debug logs. | +| `AUTO_DEVOPS_ALLOW_TO_FORCE_DEPLOY_V<N>` | From [auto-deploy-image](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image) v1.0.0, if this variable is present, a new major version of chart is forcibly deployed. For more information, see [Ignore warnings and continue deploying](upgrading_auto_deploy_dependencies.md#ignore-warnings-and-continue-deploying). | +| `BUILDPACK_URL` | A full Buildpack URL. [Must point to a URL supported by Pack or Herokuish](customize.md#custom-buildpacks). | +| `CANARY_ENABLED` | Used to define a [deploy policy for canary environments](#deploy-policy-for-canary-environments). | +| `BUILDPACK_VOLUMES` | Specify one or more [Buildpack volumes to mount](stages.md#mount-volumes-into-the-build-container). Use a pipe `|` as list separator. | +| `CANARY_PRODUCTION_REPLICAS` | Number of canary replicas to deploy for [Canary Deployments](../../user/project/canary_deployments.md) in the production environment. Takes precedence over `CANARY_REPLICAS`. Defaults to 1. | +| `CANARY_REPLICAS` | Number of canary replicas to deploy for [Canary Deployments](../../user/project/canary_deployments.md). Defaults to 1. | +| `CI_APPLICATION_REPOSITORY` | The repository of container image being built or deployed, `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG`. For more details, read [Custom container image](customize.md#custom-container-image). | +| `CI_APPLICATION_TAG` | The tag of the container image being built or deployed, `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG`. For more details, read [Custom container image](customize.md#custom-container-image). | +| `DAST_AUTO_DEPLOY_IMAGE_VERSION` | Customize the image version used for DAST deployments on the default branch. Should usually be the same as `AUTO_DEPLOY_IMAGE_VERSION`. See [list of versions](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/releases). | +| `DOCKERFILE_PATH` | From GitLab 13.2, allows overriding the [default Dockerfile path for the build stage](customize.md#custom-dockerfile) | +| `HELM_RELEASE_NAME` | From GitLab 12.1, allows the `helm` release name to be overridden. Can be used to assign unique release names when deploying multiple projects to a single namespace. | +| `HELM_UPGRADE_VALUES_FILE` | From GitLab 12.6, allows the `helm upgrade` values file to be overridden. Defaults to `.gitlab/auto-deploy-values.yaml`. | +| `HELM_UPGRADE_EXTRA_ARGS` | Allows extra options in `helm upgrade` commands when deploying the application. Using quotes doesn't prevent word splitting. | +| `INCREMENTAL_ROLLOUT_MODE` | If present, can be used to enable an [incremental rollout](#incremental-rollout-to-production) of your application for the production environment. Set to `manual` for manual deployment jobs or `timed` for automatic rollout deployments with a 5 minute delay each one. | +| `K8S_SECRET_*` | Any variable prefixed with [`K8S_SECRET_`](#configure-application-secret-variables) is made available by Auto DevOps as environment variables to the deployed application. | +| `KUBE_CONTEXT` | From GitLab 14.5, can be used to select a context to use from `KUBECONFIG`. When `KUBE_CONTEXT` is blank, the default context in `KUBECONFIG` (if any) is used. A context must be selected when used [with the agent for Kubernetes](../../user/clusters/agent/ci_cd_workflow.md). | +| `KUBE_INGRESS_BASE_DOMAIN` | Can be used to set a domain per cluster. See [cluster domains](../../user/project/clusters/gitlab_managed_clusters.md#base-domain) for more information. | +| `KUBE_NAMESPACE` | The namespace used for deployments. When using certificate-based clusters, [this value should not be overwritten directly](../../user/project/clusters/deploy_to_cluster.md#custom-namespace). | +| `KUBECONFIG` | The kubeconfig to use for deployments. User-provided values take priority over GitLab-provided values. | +| `PRODUCTION_REPLICAS` | Number of replicas to deploy in the production environment. Takes precedence over `REPLICAS` and defaults to 1. For zero downtime upgrades, set to 2 or greater. | +| `REPLICAS` | Number of replicas to deploy. Defaults to 1. Change this variable instead of [modifying](customize.md#customize-values-for-helm-chart) `replicaCount`. | +| `ROLLOUT_RESOURCE_TYPE` | Allows specification of the resource type being deployed when using a custom Helm chart. Default value is `deployment`. | +| `ROLLOUT_STATUS_DISABLED` | From GitLab 12.0, used to disable rollout status check because it does not support all resource types, for example, `cronjob`. | +| `STAGING_ENABLED` | Used to define a [deploy policy for staging and production environments](#deploy-policy-for-staging-and-production-environments). | +| `TRACE` | Set to any value to make Helm commands produce verbose output. You can use this setting to help diagnose Auto DevOps deployment problems. | + +## Database variables + +Use these variables to integrate CI/CD with PostgreSQL databases. + +| **CI/CD variable** | **Description** | +|-----------------------------------------|------------------------------------| +| `DB_INITIALIZE` | Used to specify the command to run to initialize the application's PostgreSQL database. Runs inside the application pod. | +| `DB_MIGRATE` | Used to specify the command to run to migrate the application's PostgreSQL database. Runs inside the application pod. | +| `POSTGRES_ENABLED` | Whether PostgreSQL is enabled. Defaults to `true`. Set to `false` to disable the automatic deployment of PostgreSQL. | +| `POSTGRES_USER` | The PostgreSQL user. Defaults to `user`. Set it to use a custom username. | +| `POSTGRES_PASSWORD` | The PostgreSQL password. Defaults to `testing-password`. Set it to use a custom password. | +| `POSTGRES_DB` | The PostgreSQL database name. Defaults to the value of [`$CI_ENVIRONMENT_SLUG`](../../ci/variables/index.md#predefined-cicd-variables). Set it to use a custom database name. | +| `POSTGRES_VERSION` | Tag for the [`postgres` Docker image](https://hub.docker.com/_/postgres) to use. Defaults to `9.6.16` for tests and deployments as of GitLab 13.0 (previously `9.6.2`). If `AUTO_DEVOPS_POSTGRES_CHANNEL` is set to `1`, deployments uses the default version `9.6.2`. | +| `POSTGRES_HELM_UPGRADE_VALUES_FILE` | In GitLab 13.8 and later, and when using [auto-deploy-image v2](upgrading_auto_deploy_dependencies.md), this variable allows the `helm upgrade` values file for PostgreSQL to be overridden. Defaults to `.gitlab/auto-deploy-postgres-values.yaml`. | +| `POSTGRES_HELM_UPGRADE_EXTRA_ARGS` | In GitLab 13.8 and later, and when using [auto-deploy-image v2](upgrading_auto_deploy_dependencies.md), this variable allows extra PostgreSQL options in `helm upgrade` commands when deploying the application. Note that using quotes doesn't prevent word splitting. | +| `POSTGRES_CHART_REPOSITORY` | Helm Chart repository used to search for PostgreSQL chart. Defaults to `https://raw.githubusercontent.com/bitnami/charts/eb5f9a9513d987b519f0ecd732e7031241c50328/bitnami`. | +| `POSTGRES_CHART_VERSION` | Helm Chart version used for PostgreSQL chart. Defaults to `8.2.1`. | + +## Job-disabling variables + +Use these variables to disable CI/CD jobs. + +| **Job name** | **CI/CD variable** | **GitLab version** | **Description** | +|----------------------------------------|---------------------------------|-----------------------|-----------------| +| `.fuzz_base` | `COVFUZZ_DISABLED` | [From GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/34984) | [Read more](../../user/application_security/coverage_fuzzing/index.md) about how `.fuzz_base` provide capability for your own jobs. If the variable is present, your jobs aren't created. | +| `apifuzzer_fuzz` | `API_FUZZING_DISABLED` | [From GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39135) | If the variable is present, the job isn't created. | +| `build` | `BUILD_DISABLED` | | If the variable is present, the job isn't created. | +| `build_artifact` | `BUILD_DISABLED` | | If the variable is present, the job isn't created. | +| `bandit-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `brakeman-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `canary` | `CANARY_ENABLED` | | This manual job is created if the variable is present. | +| `cluster_image_scanning` | `CLUSTER_IMAGE_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | +| `code_intelligence` | `CODE_INTELLIGENCE_DISABLED` | From GitLab 13.6 | If the variable is present, the job isn't created. | +| `code_quality` | `CODE_QUALITY_DISABLED` | | If the variable is present, the job isn't created. | +| `container_scanning` | `CONTAINER_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | +| `dast` | `DAST_DISABLED` | | If the variable is present, the job isn't created. | +| `dast_environment_deploy` | `DAST_DISABLED_FOR_DEFAULT_BRANCH` or `DAST_DISABLED` | [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17789) | If either variable is present, the job isn't created. | +| `dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | +| `eslint-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `flawfinder-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `gemnasium-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | +| `gemnasium-maven-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | +| `gemnasium-python-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | +| `gosec-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `kubesec-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `license_management` | `LICENSE_MANAGEMENT_DISABLED` | GitLab 12.7 and earlier | If the variable is present, the job isn't created. Job deprecated [from GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22773) | +| `license_scanning` | `LICENSE_MANAGEMENT_DISABLED` | [From GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22773) | If the variable is present, the job isn't created. | +| `load_performance` | `LOAD_PERFORMANCE_DISABLED` | From GitLab 13.2 | If the variable is present, the job isn't created. | +| `nodejs-scan-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `performance` | `PERFORMANCE_DISABLED` | GitLab 13.12 and earlier | Browser performance. If the variable is present, the job isn't created. Replaced by `browser_performance`. | +| `browser_performance` | `BROWSER_PERFORMANCE_DISABLED` | From GitLab 14.0 | Browser performance. If the variable is present, the job isn't created. Replaces `performance`. | +| `phpcs-security-audit-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `pmd-apex-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `review` | `REVIEW_DISABLED` | | If the variable is present, the job isn't created. | +| `review:stop` | `REVIEW_DISABLED` | | Manual job. If the variable is present, the job isn't created. | +| `sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `sast:container` | `CONTAINER_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | +| `secret_detection` | `SECRET_DETECTION_DISABLED` | From GitLab 13.1 | If the variable is present, the job isn't created. | +| `secret_detection_default_branch` | `SECRET_DETECTION_DISABLED` | [From GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22773) | If the variable is present, the job isn't created. | +| `security-code-scan-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `secrets-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `sobelaw-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `stop_dast_environment` | `DAST_DISABLED_FOR_DEFAULT_BRANCH` or `DAST_DISABLED` | [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17789) | If either variable is present, the job isn't created. | +| `spotbugs-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | +| `test` | `TEST_DISABLED` | | If the variable is present, the job isn't created. | +| `staging` | `STAGING_ENABLED` | | The job is created if the variable is present. | +| `stop_review` | `REVIEW_DISABLED` | | If the variable is present, the job isn't created. | + +## Configure application secret variables + +Some deployed applications require access to secret variables. +Auto DevOps detects CI/CD variables starting with `K8S_SECRET_`, +and makes them available to the deployed application as +environment variables. + +To configure secret variables: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Variables**. +1. Create a CI/CD variable with the prefix `K8S_SECRET_`. For example, you + can create a variable called `K8S_SECRET_RAILS_MASTER_KEY`. +1. Run an Auto DevOps pipeline, either by manually creating a new + pipeline or by pushing a code change to GitLab. + +### Kubernetes secrets + +Auto DevOps pipelines use your application secret variables to +populate a Kubernetes secret. This secret is unique per environment. +When deploying your application, the secret is loaded as environment +variables in the container running the application. For example, if +you create a secret called `K8S_SECRET_RAILS_MASTER_KEY`, your +Kubernetes secret might look like: + +```shell +$ kubectl get secret production-secret -n minimal-ruby-app-54 -o yaml + +apiVersion: v1 +data: + RAILS_MASTER_KEY: MTIzNC10ZXN0 +kind: Secret +metadata: + creationTimestamp: 2018-12-20T01:48:26Z + name: production-secret + namespace: minimal-ruby-app-54 + resourceVersion: "429422" + selfLink: /api/v1/namespaces/minimal-ruby-app-54/secrets/production-secret + uid: 57ac2bfd-03f9-11e9-b812-42010a9400e4 +type: Opaque +``` + +## Update application secrets + +Environment variables are generally immutable in a Kubernetes pod. +If you update an application secret and then manually +create a new pipeline, running applications do not receive the +updated secret. + +To update application secrets, either: + +- Push a code update to GitLab to force the Kubernetes deployment to recreate pods. +- Manually delete running pods to cause Kubernetes to create new pods with updated + secrets. + +Variables with multi-line values are not supported due to +limitations with the Auto DevOps scripting environment. + +## Configure replica variables + +Add replica variables when you want to scale your deployments: + +1. Add a replica variable as a [project CI/CD variable](../../ci/variables/index.md#add-a-cicd-variable-to-a-project). +1. To scale your application, redeploy it. + + WARNING: + Do not scale your application using Kubernetes directly. Helm might not detect the change, + and subsequent deployments with Auto DevOps can undo your changes. + +### Custom replica variables + +You can create custom replica variables with the format `<TRACK>_<ENV>_REPLICAS`: + +- `<TRACK>` is the all-caps value of the `track` + [Kubernetes label](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) + set in the Helm Chart app definition. If `track` is not set, omit `<TRACK>` from the custom variable. +- `<ENV>` is the all-caps environment name of the deploy job set in + `.gitlab-ci.yml`. + +For example, if the environment is `qa` and the track is +`foo`, create an environment variable called `FOO_QA_REPLICAS`: + +```yaml +QA testing: + stage: deploy + environment: + name: qa + script: + - deploy foo +``` + +The track `foo` must be defined in the application's Helm chart. +For example: + +```yaml +replicaCount: 1 +image: + repository: gitlab.example.com/group/project + tag: stable + pullPolicy: Always + secrets: + - name: gitlab-registry +application: + track: foo + tier: web +service: + enabled: true + name: web + type: ClusterIP + url: http://my.host.com/ + externalPort: 5000 + internalPort: 5000 +``` + +## Deploy policy for staging and production environments + +Auto DevOps typically uses continuous deployment, and pushes +automatically to the `production` environment whenever a new pipeline +runs on the default branch. To deploy to production manually, you can +use the `STAGING_ENABLED` CI/CD variable. + +If you set `STAGING_ENABLED`, GitLab automatically deploys the +application to a `staging` environment. When you're ready to deploy to +production, GitLab creates a `production_manual` job. + +You can also enable manual deployment in your [project settings](requirements.md#auto-devops-deployment-strategy). + +## Deploy policy for canary environments **(PREMIUM)** + +You can use a [canary environment](../../user/project/canary_deployments.md) before +deploying any changes to production. + +If you set `CANARY_ENABLED`, GitLab creates two [manual jobs](../../ci/pipelines/index.md#add-manual-interaction-to-your-pipeline): + +- `canary` - Deploys the application to the canary environment. +- `production_manual` - Deploys the application to production. + +## Incremental rollout to production **(PREMIUM)** + +Use an incremental rollout to continuously deploy your application, +starting with only a few pods. You can increase the number of pods +manually. + +You can enable manual deployment in your [project settings](requirements.md#auto-devops-deployment-strategy), +or by setting `INCREMENTAL_ROLLOUT_MODE` to `manual`. + +If you set `INCREMENTAL_ROLLOUT_MODE` to `manual`, GitLab creates four +manual jobs: + +1. `rollout 10%` +1. `rollout 25%` +1. `rollout 50%` +1. `rollout 100%` + +The percentage is based on the `REPLICAS` CI/CD variable, and defines the number of +pods used for deployment. For example, if the value is `10` and you run the +`10%` rollout job, your application is deployed to only one pod. + +You can run the rollout jobs in any order. To scale down, rerun a +lower percentage job. + +After you run the `rollout 100%` job, you cannot scale down, and must +[rollback your deployment](../../ci/environments/index.md#retry-or-roll-back-a-deployment). + +### Example incremental rollout configurations + +Without `INCREMENTAL_ROLLOUT_MODE` and without `STAGING_ENABLED`: + + + +Without `INCREMENTAL_ROLLOUT_MODE` and with `STAGING_ENABLED`: + + + +With `INCREMENTAL_ROLLOUT_MODE` set to `manual` and without `STAGING_ENABLED`: + + + +With `INCREMENTAL_ROLLOUT_MODE` set to `manual` and with `STAGING_ENABLED`: + + + +WARNING: +This configuration is deprecated, and is scheduled to be removed in the future. + +## Timed incremental rollout to production **(PREMIUM)** + +Use a timed incremental rollout to continuously deploy your application, starting with +only a few pods. + +You can enable timed incremental deployment in your [project settings](requirements.md#auto-devops-deployment-strategy), +or by setting the `INCREMENTAL_ROLLOUT_MODE` CI/CD variable to `timed`. + +If you set `INCREMENTAL_ROLLOUT_MODE` to `timed`, GitLab creates four jobs: + +1. `timed rollout 10%` +1. `timed rollout 25%` +1. `timed rollout 50%` +1. `timed rollout 100%` + +There is a five-minute delay between jobs. diff --git a/doc/topics/autodevops/cloud_deployments/auto_devops_with_gke.md b/doc/topics/autodevops/cloud_deployments/auto_devops_with_gke.md index 8a041b08a4d..78c51572973 100644 --- a/doc/topics/autodevops/cloud_deployments/auto_devops_with_gke.md +++ b/doc/topics/autodevops/cloud_deployments/auto_devops_with_gke.md @@ -231,7 +231,7 @@ 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](../customize.md#cicd-variables) +more pods by defining the [`REPLICAS` CI/CD variable](../cicd_variables.md) in **Settings > CI/CD > Variables**. ### Work with branches @@ -300,7 +300,7 @@ and customized to fit your workflow. Here are some helpful resources for further 1. [Auto DevOps](../index.md) 1. [Multiple Kubernetes clusters](../multiple_clusters_auto_devops.md) -1. [Incremental rollout to production](../customize.md#incremental-rollout-to-production) -1. [Disable jobs you don't need with CI/CD variables](../customize.md#cicd-variables) +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) 1. [Prometheus monitoring](../../../user/project/integrations/prometheus.md) diff --git a/doc/topics/autodevops/customize.md b/doc/topics/autodevops/customize.md index 264ac790453..c42f5825b6a 100644 --- a/doc/topics/autodevops/customize.md +++ b/doc/topics/autodevops/customize.md @@ -105,7 +105,7 @@ You can override this behavior by defining specific variables: These variables also affect Auto Build and Auto Container Scanning. If you don't want to build and push an image to `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG`, consider -including only `Jobs/Deploy.gitlab-ci.yml`, or [disabling the `build` jobs](#disable-jobs). +including only `Jobs/Deploy.gitlab-ci.yml`, or [disabling the `build` jobs](cicd_variables.md#job-disabling-variables). If you use Auto Container Scanning and set a value for `$CI_APPLICATION_REPOSITORY`, then you should also update `$CS_DEFAULT_BRANCH_IMAGE`. See [Setting the default branch image](../../user/application_security/container_scanning/index.md#setting-the-default-branch-image) @@ -187,11 +187,11 @@ You can override the default values in the `values.yaml` file in the - Adding a file named `.gitlab/auto-deploy-values.yaml` to your repository, which is automatically used, if found. - Adding a file with a different name or path to the repository, and setting the - `HELM_UPGRADE_VALUES_FILE` [CI/CD variable](#cicd-variables) with + `HELM_UPGRADE_VALUES_FILE` [CI/CD variable](cicd_variables.md) with the path and name. Some values cannot be overridden with the options above. Settings like `replicaCount` should instead be overridden with the `REPLICAS` -[build and deployment](#build-and-deployment) CI/CD variable. Follow [this issue](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/issues/31) for more information. +[build and deployment](cicd_variables.md#build-and-deployment-variables) CI/CD variable. Follow [this issue](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/issues/31) for more information. NOTE: For GitLab 12.5 and earlier, use the `HELM_UPGRADE_EXTRA_ARGS` variable @@ -308,13 +308,13 @@ You can configure many Auto DevOps jobs to run in an [offline environment](../.. To support applications requiring a database, [PostgreSQL](https://www.postgresql.org/) is provisioned by default. The credentials to access the database are preconfigured, but can be customized by setting the associated -[CI/CD variables](#cicd-variables). You can use these credentials to define a `DATABASE_URL`: +[CI/CD variables](cicd_variables.md). You can use these credentials to define a `DATABASE_URL`: ```yaml postgres://user:password@postgres-host:postgres-port/postgres-database ``` -### Upgrading PostgresSQL +### Upgrading PostgreSQL WARNING: The CI/CD variable `AUTO_DEVOPS_POSTGRES_CHANNEL` that controls default provisioned @@ -340,9 +340,9 @@ To set custom values, do one of the following: - Add a file named `.gitlab/auto-deploy-postgres-values.yaml` to your repository. If found, this file is used automatically. This file is used by default for PostgreSQL Helm upgrades. - Add a file with a different name or path to the repository, and set the - `POSTGRES_HELM_UPGRADE_VALUES_FILE` [environment variable](#database) with the path + `POSTGRES_HELM_UPGRADE_VALUES_FILE` [environment variable](cicd_variables.md#database-variables) with the path and name. -- Set the `POSTGRES_HELM_UPGRADE_EXTRA_ARGS` [environment variable](#database). +- Set the `POSTGRES_HELM_UPGRADE_EXTRA_ARGS` [environment variable](cicd_variables.md#database-variables). ### Using external PostgreSQL database providers @@ -371,342 +371,6 @@ You must define environment-scoped CI/CD variables for `POSTGRES_ENABLED` and You must ensure that your Kubernetes cluster has network access to wherever PostgreSQL is hosted. -## CI/CD variables - -The following variables can be used for setting up the Auto DevOps domain, -providing a custom Helm chart, or scaling your application. PostgreSQL can -also be customized, and you can use a [custom buildpack](#custom-buildpacks). - -### Build and deployment - -The following table lists CI/CD variables related to building and deploying -applications. - -| **CI/CD Variable** | **Description** | -|-----------------------------------------|------------------------------------| -| `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`. | -| `AUTO_BUILD_IMAGE_VERSION` | Customize the image version used for the `build` job. See [list of versions](https://gitlab.com/gitlab-org/cluster-integration/auto-build-image/-/releases). | -| `AUTO_DEPLOY_IMAGE_VERSION` | Customize the image version used for Kubernetes deployment jobs. See [list of versions](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/releases). | -| `AUTO_DEVOPS_ATOMIC_RELEASE` | As of GitLab 13.0, Auto DevOps uses [`--atomic`](https://v2.helm.sh/docs/helm/#options-43) for Helm deployments by default. Set this variable to `false` to disable the use of `--atomic` | -| `AUTO_DEVOPS_BUILD_IMAGE_CNB_ENABLED` | Set to `false` to use Herokuish instead of Cloud Native Buildpacks with Auto Build. [More details](stages.md#auto-build-using-cloud-native-buildpacks). | -| `AUTO_DEVOPS_BUILD_IMAGE_CNB_BUILDER` | The builder used when building with Cloud Native Buildpacks. The default builder is `heroku/buildpacks:18`. [More details](stages.md#auto-build-using-cloud-native-buildpacks). | -| `AUTO_DEVOPS_BUILD_IMAGE_EXTRA_ARGS` | Extra arguments to be passed to the `docker build` command. Note that using quotes doesn't prevent word splitting. [More details](#passing-arguments-to-docker-build). | -| `AUTO_DEVOPS_BUILD_IMAGE_FORWARDED_CI_VARIABLES` | A [comma-separated list of CI/CD variable names](#forward-cicd-variables-to-the-build-environment) to be forwarded to the build environment (the buildpack builder or `docker build`). | -| `AUTO_DEVOPS_BUILD_IMAGE_CNB_PORT` | In GitLab 15.0 and later, port exposed by the generated Docker image. Set to `false` to prevent exposing any ports. Defaults to `5000`. | -| `AUTO_DEVOPS_CHART` | Helm Chart used to deploy your apps. Defaults to the one [provided by GitLab](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app). | -| `AUTO_DEVOPS_CHART_REPOSITORY` | Helm Chart repository used to search for charts. Defaults to `https://charts.gitlab.io`. | -| `AUTO_DEVOPS_CHART_REPOSITORY_NAME` | Used to set the name of the Helm repository. Defaults to `gitlab`. | -| `AUTO_DEVOPS_CHART_REPOSITORY_USERNAME` | Used to set a username to connect to the Helm repository. Defaults to no credentials. Also set `AUTO_DEVOPS_CHART_REPOSITORY_PASSWORD`. | -| `AUTO_DEVOPS_CHART_REPOSITORY_PASSWORD` | Used to set a password to connect to the Helm repository. Defaults to no credentials. Also set `AUTO_DEVOPS_CHART_REPOSITORY_USERNAME`. | -| `AUTO_DEVOPS_CHART_REPOSITORY_PASS_CREDENTIALS` | From GitLab 14.2, set to a non-empty value to enable forwarding of the Helm repository credentials to the chart server when the chart artifacts are on a different host than repository. | -| `AUTO_DEVOPS_COMMON_NAME` | From GitLab 15.5, set to a valid domain name to customize the common name used for the TLS certificate. Defaults to `le-$CI_PROJECT_ID.$KUBE_INGRESS_BASE_DOMAIN`. Set to `false` to not set this alternative host on the Ingress. | -| `AUTO_DEVOPS_DEPLOY_DEBUG` | From GitLab 13.1, if this variable is present, Helm outputs debug logs. | -| `AUTO_DEVOPS_ALLOW_TO_FORCE_DEPLOY_V<N>` | From [auto-deploy-image](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image) v1.0.0, if this variable is present, a new major version of chart is forcibly deployed. For more information, see [Ignore warnings and continue deploying](upgrading_auto_deploy_dependencies.md#ignore-warnings-and-continue-deploying). | -| `BUILDPACK_URL` | Buildpack's full URL. [Must point to a URL supported by Pack or Herokuish](#custom-buildpacks). | -| `CANARY_ENABLED` | Used to define a [deploy policy for canary environments](#deploy-policy-for-canary-environments). | -| `BUILDPACK_VOLUMES` | Specify one or more [Buildpack volumes to mount](stages.md#mount-volumes-into-the-build-container). Use a pipe `|` as list separator. | -| `CANARY_PRODUCTION_REPLICAS` | Number of canary replicas to deploy for [Canary Deployments](../../user/project/canary_deployments.md) in the production environment. Takes precedence over `CANARY_REPLICAS`. Defaults to 1. | -| `CANARY_REPLICAS` | Number of canary replicas to deploy for [Canary Deployments](../../user/project/canary_deployments.md). Defaults to 1. | -| `CI_APPLICATION_REPOSITORY` | The repository of container image being built or deployed, `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG`. For more details, read [Custom container image](#custom-container-image). | -| `CI_APPLICATION_TAG` | The tag of the container image being built or deployed, `$CI_APPLICATION_REPOSITORY:$CI_APPLICATION_TAG`. For more details, read [Custom container image](#custom-container-image). | -| `DAST_AUTO_DEPLOY_IMAGE_VERSION` | Customize the image version used for DAST deployments on the default branch. Should usually be the same as `AUTO_DEPLOY_IMAGE_VERSION`. See [list of versions](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/releases). | -| `DOCKERFILE_PATH` | From GitLab 13.2, allows overriding the [default Dockerfile path for the build stage](#custom-dockerfile) | -| `HELM_RELEASE_NAME` | From GitLab 12.1, allows the `helm` release name to be overridden. Can be used to assign unique release names when deploying multiple projects to a single namespace. | -| `HELM_UPGRADE_VALUES_FILE` | From GitLab 12.6, allows the `helm upgrade` values file to be overridden. Defaults to `.gitlab/auto-deploy-values.yaml`. | -| `HELM_UPGRADE_EXTRA_ARGS` | Allows extra options in `helm upgrade` commands when deploying the application. Note that using quotes doesn't prevent word splitting. | -| `INCREMENTAL_ROLLOUT_MODE` | If present, can be used to enable an [incremental rollout](#incremental-rollout-to-production) of your application for the production environment. Set to `manual` for manual deployment jobs or `timed` for automatic rollout deployments with a 5 minute delay each one. | -| `K8S_SECRET_*` | Any variable prefixed with [`K8S_SECRET_`](#application-secret-variables) is made available by Auto DevOps as environment variables to the deployed application. | -| `KUBE_CONTEXT` | From GitLab 14.5, can be used to select a context to use from `KUBECONFIG`. When `KUBE_CONTEXT` is blank, the default context in `KUBECONFIG` (if any) is used. A context must be selected when used [with the agent for Kubernetes](../../user/clusters/agent/ci_cd_workflow.md). | -| `KUBE_INGRESS_BASE_DOMAIN` | Can be used to set a domain per cluster. See [cluster domains](../../user/project/clusters/gitlab_managed_clusters.md#base-domain) for more information. | -| `KUBE_NAMESPACE` | The namespace used for deployments. When using certificate-based clusters, [this value should not be overwritten directly](../../user/project/clusters/deploy_to_cluster.md#custom-namespace). | -| `KUBECONFIG` | The kubeconfig to use for deployments. User-provided values take priority over GitLab-provided values. | -| `PRODUCTION_REPLICAS` | Number of replicas to deploy in the production environment. Takes precedence over `REPLICAS` and defaults to 1. For zero downtime upgrades, set to 2 or greater. | -| `REPLICAS` | Number of replicas to deploy. Defaults to 1. Change this variable instead of [modifying](#customize-values-for-helm-chart) `replicaCount`. | -| `ROLLOUT_RESOURCE_TYPE` | Allows specification of the resource type being deployed when using a custom Helm chart. Default value is `deployment`. | -| `ROLLOUT_STATUS_DISABLED` | From GitLab 12.0, used to disable rollout status check because it does not support all resource types, for example, `cronjob`. | -| `STAGING_ENABLED` | Used to define a [deploy policy for staging and production environments](#deploy-policy-for-staging-and-production-environments). | -| `TRACE` | Set to any value to make Helm commands produce verbose output. You can use this setting to help diagnose Auto DevOps deployment problems. | - -NOTE: -After you set up your replica variables using a -[project CI/CD variable](../../ci/variables/index.md), -you can scale your application by redeploying it. - -WARNING: -You should *not* scale your application using Kubernetes directly. This can -cause confusion with Helm not detecting the change, and subsequent deploys with -Auto DevOps can undo your changes. - -### Database - -The following table lists CI/CD variables related to the database. - -| **CI/CD Variable** | **Description** | -|-----------------------------------------|------------------------------------| -| `DB_INITIALIZE` | Used to specify the command to run to initialize the application's PostgreSQL database. Runs inside the application pod. | -| `DB_MIGRATE` | Used to specify the command to run to migrate the application's PostgreSQL database. Runs inside the application pod. | -| `POSTGRES_ENABLED` | Whether PostgreSQL is enabled. Defaults to `true`. Set to `false` to disable the automatic deployment of PostgreSQL. | -| `POSTGRES_USER` | The PostgreSQL user. Defaults to `user`. Set it to use a custom username. | -| `POSTGRES_PASSWORD` | The PostgreSQL password. Defaults to `testing-password`. Set it to use a custom password. | -| `POSTGRES_DB` | The PostgreSQL database name. Defaults to the value of [`$CI_ENVIRONMENT_SLUG`](../../ci/variables/index.md#predefined-cicd-variables). Set it to use a custom database name. | -| `POSTGRES_VERSION` | Tag for the [`postgres` Docker image](https://hub.docker.com/_/postgres) to use. Defaults to `9.6.16` for tests and deployments as of GitLab 13.0 (previously `9.6.2`). If `AUTO_DEVOPS_POSTGRES_CHANNEL` is set to `1`, deployments uses the default version `9.6.2`. | -| `POSTGRES_HELM_UPGRADE_VALUES_FILE` | In GitLab 13.8 and later, and when using [auto-deploy-image v2](upgrading_auto_deploy_dependencies.md), this variable allows the `helm upgrade` values file for PostgreSQL to be overridden. Defaults to `.gitlab/auto-deploy-postgres-values.yaml`. | -| `POSTGRES_HELM_UPGRADE_EXTRA_ARGS` | In GitLab 13.8 and later, and when using [auto-deploy-image v2](upgrading_auto_deploy_dependencies.md), this variable allows extra PostgreSQL options in `helm upgrade` commands when deploying the application. Note that using quotes doesn't prevent word splitting. | -| `POSTGRES_CHART_REPOSITORY` | Helm Chart repository used to search for PostgreSQL chart. Defaults to `https://raw.githubusercontent.com/bitnami/charts/eb5f9a9513d987b519f0ecd732e7031241c50328/bitnami`. | -| `POSTGRES_CHART_VERSION` | Helm Chart version used for PostgreSQL chart. Defaults to `8.2.1`. | - -### Disable jobs - -The following table lists variables used to disable jobs. - -| **Job Name** | **CI/CDVariable** | **GitLab version** | **Description** | -|----------------------------------------|---------------------------------|-----------------------|-----------------| -| `.fuzz_base` | `COVFUZZ_DISABLED` | [From GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/34984) | [Read more](../../user/application_security/coverage_fuzzing/index.md) about how `.fuzz_base` provide capability for your own jobs. If the variable is present, your jobs aren't created. | -| `apifuzzer_fuzz` | `API_FUZZING_DISABLED` | [From GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39135) | If the variable is present, the job isn't created. | -| `build` | `BUILD_DISABLED` | | If the variable is present, the job isn't created. | -| `build_artifact` | `BUILD_DISABLED` | | If the variable is present, the job isn't created. | -| `bandit-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | -| `brakeman-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | -| `canary` | `CANARY_ENABLED` | | This manual job is created if the variable is present. | -| `cluster_image_scanning` | `CLUSTER_IMAGE_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | -| `code_intelligence` | `CODE_INTELLIGENCE_DISABLED` | From GitLab 13.6 | If the variable is present, the job isn't created. | -| `code_quality` | `CODE_QUALITY_DISABLED` | | If the variable is present, the job isn't created. | -| `container_scanning` | `CONTAINER_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | -| `dast` | `DAST_DISABLED` | | If the variable is present, the job isn't created. | -| `dast_environment_deploy` | `DAST_DISABLED_FOR_DEFAULT_BRANCH` or `DAST_DISABLED` | [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17789) | If either variable is present, the job isn't created. | -| `dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | -| `eslint-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | -| `flawfinder-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | -| `gemnasium-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | -| `gemnasium-maven-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | -| `gemnasium-python-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | -| `gosec-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | -| `kubesec-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | -| `license_management` | `LICENSE_MANAGEMENT_DISABLED` | GitLab 12.7 and earlier | If the variable is present, the job isn't created. Job deprecated [from GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22773) | -| `license_scanning` | `LICENSE_MANAGEMENT_DISABLED` | [From GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22773) | If the variable is present, the job isn't created. | -| `load_performance` | `LOAD_PERFORMANCE_DISABLED` | From GitLab 13.2 | If the variable is present, the job isn't created. | -| `nodejs-scan-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | -| `performance` | `PERFORMANCE_DISABLED` | GitLab 13.12 and earlier | Browser performance. If the variable is present, the job isn't created. Replaced by `browser_performance`. | -| `browser_performance` | `BROWSER_PERFORMANCE_DISABLED` | From GitLab 14.0 | Browser performance. If the variable is present, the job isn't created. Replaces `performance`. | -| `phpcs-security-audit-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | -| `pmd-apex-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | -| `review` | `REVIEW_DISABLED` | | If the variable is present, the job isn't created. | -| `review:stop` | `REVIEW_DISABLED` | | Manual job. If the variable is present, the job isn't created. | -| `sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | -| `sast:container` | `CONTAINER_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | -| `secret_detection` | `SECRET_DETECTION_DISABLED` | From GitLab 13.1 | If the variable is present, the job isn't created. | -| `secret_detection_default_branch` | `SECRET_DETECTION_DISABLED` | [From GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22773) | If the variable is present, the job isn't created. | -| `security-code-scan-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | -| `secrets-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | -| `sobelaw-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | -| `stop_dast_environment` | `DAST_DISABLED_FOR_DEFAULT_BRANCH` or `DAST_DISABLED` | [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17789) | If either variable is present, the job isn't created. | -| `spotbugs-sast` | `SAST_DISABLED` | | If the variable is present, the job isn't created. | -| `test` | `TEST_DISABLED` | | If the variable is present, the job isn't created. | -| `staging` | `STAGING_ENABLED` | | The job is created if the variable is present. | -| `stop_review` | `REVIEW_DISABLED` | | If the variable is present, the job isn't created. | - -### Application secret variables - -Some applications need to define secret variables that are accessible by the deployed -application. Auto DevOps detects CI/CD variables starting with `K8S_SECRET_`, and makes -these prefixed variables available to the deployed application as environment variables. - -To configure your application variables: - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > CI/CD**. -1. Expand **Variables**. -1. Create a CI/CD variable, ensuring the key is prefixed with - `K8S_SECRET_`. For example, you can create a variable with key - `K8S_SECRET_RAILS_MASTER_KEY`. - -1. Run an Auto DevOps pipeline, either by manually creating a new - pipeline or by pushing a code change to GitLab. - -Auto DevOps pipelines take your application secret variables to -populate a Kubernetes secret. This secret is unique per environment. -When deploying your application, the secret is loaded as environment -variables in the container running the application. Following the -example above, you can see the secret below containing the -`RAILS_MASTER_KEY` variable. - -```shell -$ kubectl get secret production-secret -n minimal-ruby-app-54 -o yaml - -apiVersion: v1 -data: - RAILS_MASTER_KEY: MTIzNC10ZXN0 -kind: Secret -metadata: - creationTimestamp: 2018-12-20T01:48:26Z - name: production-secret - namespace: minimal-ruby-app-54 - resourceVersion: "429422" - selfLink: /api/v1/namespaces/minimal-ruby-app-54/secrets/production-secret - uid: 57ac2bfd-03f9-11e9-b812-42010a9400e4 -type: Opaque -``` - -Environment variables are generally considered immutable in a Kubernetes pod. -If you update an application secret without changing any code, then manually -create a new pipeline, any running application pods don't receive -the updated secrets. To update the secrets, either: - -- Push a code update to GitLab to force the Kubernetes deployment to recreate pods. -- Manually delete running pods to cause Kubernetes to create new pods with updated - secrets. - -Variables with multi-line 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, -you can also use other variables for different environments. - -The Kubernetes' label named `track`, GitLab CI/CD environment names, and the -replicas environment variable are combined into the format `TRACK_ENV_REPLICAS`, -enabling you to define your own variables for scaling the pod's replicas: - -- `TRACK`: The capitalized value of the `track` - [Kubernetes label](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) - in the Helm Chart app definition. If not set, it isn't taken into account - to the variable name. -- `ENV`: The capitalized environment name of the deploy job, set in - `.gitlab-ci.yml`. - -In the example below, the environment's name is `qa`, and it deploys the track -`foo`, which results in an environment variable named `FOO_QA_REPLICAS`: - -```yaml -QA testing: - stage: deploy - environment: - name: qa - script: - - deploy foo -``` - -The track `foo` being referenced must also be defined in the application's Helm chart, like: - -```yaml -replicaCount: 1 -image: - repository: gitlab.example.com/group/project - tag: stable - pullPolicy: Always - secrets: - - name: gitlab-registry -application: - track: foo - tier: web -service: - enabled: true - name: web - type: ClusterIP - url: http://my.host.com/ - externalPort: 5000 - internalPort: 5000 -``` - -### Deploy policy for staging and production environments - -NOTE: -You can also set this inside your [project's settings](requirements.md#auto-devops-deployment-strategy). - -The normal behavior of Auto DevOps is to use continuous deployment, pushing -automatically to the `production` environment every time a new pipeline is run -on the default branch. However, there are cases where you might want to use a -staging environment, and deploy to production manually. For this scenario, the -`STAGING_ENABLED` CI/CD variable was introduced. - -If you define `STAGING_ENABLED` with a non-empty value, then GitLab automatically deploys the application -to a `staging` environment, and creates a `production_manual` job for -you when you're ready to manually deploy to production. - -### Deploy policy for canary environments **(PREMIUM)** - -You can use a [canary environment](../../user/project/canary_deployments.md) before -deploying any changes to production. - -If you define `CANARY_ENABLED` with a non-empty value, then two manual jobs are created: - -- `canary` - Deploys the application to the canary environment. -- `production_manual` - Manually deploys the application to production. - -### Incremental rollout to production **(PREMIUM)** - -NOTE: -You can also set this inside your [project's settings](requirements.md#auto-devops-deployment-strategy). - -When you're ready to deploy a new version of your app to production, you may want -to use an incremental rollout to replace just a few pods with the latest code to -check how the application is behaving before manually increasing the rollout up to 100%. - -If `INCREMENTAL_ROLLOUT_MODE` is set to `manual` in your project, then instead -of the standard `production` job, 4 different -[manual jobs](../../ci/pipelines/index.md#add-manual-interaction-to-your-pipeline) -are created: - -1. `rollout 10%` -1. `rollout 25%` -1. `rollout 50%` -1. `rollout 100%` - -The percentage is based on the `REPLICAS` CI/CD variable, and defines the number of -pods you want to have for your deployment. If the value is `10`, and you run the -`10%` rollout job, there is `1` new pod and `9` old ones. - -To start a job, select the play icon (**{play}**) next to the job's name. You're not -required to go from `10%` to `100%`, you can jump to whatever job you want. -You can also scale down by running a lower percentage job, just before hitting -`100%`. Once you get to `100%`, you can't scale down, and you'd have to roll -back by redeploying the old version using the -[rollback button](../../ci/environments/index.md#retry-or-roll-back-a-deployment) in the -environment page. - -Below, you can see how the pipeline appears if the rollout or staging -variables are defined. - -Without `INCREMENTAL_ROLLOUT_MODE` and without `STAGING_ENABLED`: - - - -Without `INCREMENTAL_ROLLOUT_MODE` and with `STAGING_ENABLED`: - - - -With `INCREMENTAL_ROLLOUT_MODE` set to `manual` and without `STAGING_ENABLED`: - - - -With `INCREMENTAL_ROLLOUT_MODE` set to `manual` and with `STAGING_ENABLED` - - - -WARNING: -This configuration is deprecated, and is scheduled to be removed in the future. - -### Timed incremental rollout to production **(PREMIUM)** - -NOTE: -You can also set this inside your [project's settings](requirements.md#auto-devops-deployment-strategy). - -This configuration is based on -[incremental rollout to production](#incremental-rollout-to-production). - -Everything behaves the same way, except: - -- To enable it, set the `INCREMENTAL_ROLLOUT_MODE` CI/CD variable to `timed`. -- Instead of the standard `production` job, the following jobs are created with - a 5 minute delay between each: - - 1. `timed rollout 10%` - 1. `timed rollout 25%` - 1. `timed rollout 50%` - 1. `timed rollout 100%` - ## Auto DevOps banner The following Auto DevOps banner displays for users with Maintainer or greater diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 73e87aa190f..d16229b525f 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -129,7 +129,7 @@ for the subgroups and projects where you don't want to use it. Prerequisites: -- You must have at least the Owner role for the group. +- You must have the Owner role for the group. To enable Auto DevOps for a group: diff --git a/doc/topics/autodevops/multiple_clusters_auto_devops.md b/doc/topics/autodevops/multiple_clusters_auto_devops.md index af8c54a8edd..cf775a35eb7 100644 --- a/doc/topics/autodevops/multiple_clusters_auto_devops.md +++ b/doc/topics/autodevops/multiple_clusters_auto_devops.md @@ -25,7 +25,7 @@ To deploy your environments to different Kubernetes clusters: 1. [Install a GitLab Agent on each cluster](../../user/clusters/agent/index.md). 1. [Configure each agent to access your project](../../user/clusters/agent/install/index.md#configure-your-agent). 1. [Install NGINX Ingress Controller](cloud_deployments/auto_devops_with_gke.md#install-ingress) in each cluster. Save the IP address and Kubernetes namespace for the next step. -1. [Configure the Auto DevOps CI/CD Pipeline variables](customize.md#build-and-deployment) +1. [Configure the Auto DevOps CI/CD Pipeline variables](cicd_variables.md#build-and-deployment-variables) - Set up a `KUBE_CONTEXT` variable [for each environment](../../ci/variables/index.md#limit-the-environment-scope-of-a-cicd-variable). The value must point to the agent of the relevant cluster. - Set up a `KUBE_INGRESS_BASE_DOMAIN`. You must [configure the base domain](requirements.md#auto-devops-base-domain) for each environment to point to the Ingress of the relevant cluster. - Add a `KUBE_NAMESPACE` variable with a value of the Kubernetes namespace you want your deployments to target. You can scope the variable to multiple environments. @@ -44,8 +44,8 @@ NOTE: | Cluster name | Cluster environment scope | `KUBE_INGRESS_BASE_DOMAIN` value | `KUBE CONTEXT` value | Variable environment scope | Notes | | :------------| :-------------------------| :------------------------------- | :--------------------------------- | :--------------------------|:--| | review | `review/*` | `review.example.com` | `path/to/project:review-agent` | `review/*` | A review cluster that runs all [Review Apps](../../ci/review_apps/index.md).| -| staging | `staging` | `staging.example.com` | `path/to/project:staging-agent` | `staging` | Optional. A staging cluster that runs the deployments of the staging environments. You must [enable it first](customize.md#deploy-policy-for-staging-and-production-environments). | -| production | `production` | `example.com` | `path/to/project:production-agent` | `production` | A production cluster that runs the production environment deployments. You can use [incremental rollouts](customize.md#incremental-rollout-to-production). | +| staging | `staging` | `staging.example.com` | `path/to/project:staging-agent` | `staging` | Optional. A staging cluster that runs the deployments of the staging environments. You must [enable it first](cicd_variables.md#deploy-policy-for-staging-and-production-environments). | +| production | `production` | `example.com` | `path/to/project:production-agent` | `production` | A production cluster that runs the production environment deployments. You can use [incremental rollouts](cicd_variables.md#incremental-rollout-to-production). | ## Test your configuration diff --git a/doc/topics/autodevops/prepare_deployment.md b/doc/topics/autodevops/prepare_deployment.md index 7805f9cd9c6..ebba20ca821 100644 --- a/doc/topics/autodevops/prepare_deployment.md +++ b/doc/topics/autodevops/prepare_deployment.md @@ -21,8 +21,8 @@ that works best for your needs: | Deployment strategy | Setup | Methodology | |--|--|--| | **Continuous deployment to production** | Enables [Auto Deploy](stages.md#auto-deploy) with the default branch continuously deployed to production. | Continuous deployment to production.| -| **Continuous deployment to production using timed incremental rollout** | Sets the [`INCREMENTAL_ROLLOUT_MODE`](customize.md#timed-incremental-rollout-to-production) variable to `timed`. | Continuously deploy to production with a 5 minutes delay between rollouts. | -| **Automatic deployment to staging, manual deployment to production** | Sets [`STAGING_ENABLED`](customize.md#deploy-policy-for-staging-and-production-environments) to `1` and [`INCREMENTAL_ROLLOUT_MODE`](customize.md#incremental-rollout-to-production) to `manual`. | The default branch is continuously deployed to staging and continuously delivered to production. | +| **Continuous deployment to production using timed incremental rollout** | Sets the [`INCREMENTAL_ROLLOUT_MODE`](cicd_variables.md#timed-incremental-rollout-to-production) variable to `timed`. | Continuously deploy to production with a 5 minutes delay between rollouts. | +| **Automatic deployment to staging, manual deployment to production** | Sets [`STAGING_ENABLED`](cicd_variables.md#deploy-policy-for-staging-and-production-environments) to `1` and [`INCREMENTAL_ROLLOUT_MODE`](cicd_variables.md#incremental-rollout-to-production) to `manual`. | The default branch is continuously deployed to staging and continuously delivered to production. | You can choose the deployment method when enabling Auto DevOps or later: diff --git a/doc/topics/autodevops/requirements.md b/doc/topics/autodevops/requirements.md index 7c69e0327c8..f5e06843e60 100644 --- a/doc/topics/autodevops/requirements.md +++ b/doc/topics/autodevops/requirements.md @@ -36,8 +36,8 @@ that works best for your needs: | Deployment strategy | Setup | Methodology | |--|--|--| | **Continuous deployment to production** | Enables [Auto Deploy](stages.md#auto-deploy) with the default branch continuously deployed to production. | Continuous deployment to production.| -| **Continuous deployment to production using timed incremental rollout** | Sets the [`INCREMENTAL_ROLLOUT_MODE`](customize.md#timed-incremental-rollout-to-production) variable to `timed`. | Continuously deploy to production with a 5 minutes delay between rollouts. | -| **Automatic deployment to staging, manual deployment to production** | Sets [`STAGING_ENABLED`](customize.md#deploy-policy-for-staging-and-production-environments) to `1` and [`INCREMENTAL_ROLLOUT_MODE`](customize.md#incremental-rollout-to-production) to `manual`. | The default branch is continuously deployed to staging and continuously delivered to production. | +| **Continuous deployment to production using timed incremental rollout** | Sets the [`INCREMENTAL_ROLLOUT_MODE`](cicd_variables.md#timed-incremental-rollout-to-production) variable to `timed`. | Continuously deploy to production with a 5 minutes delay between rollouts. | +| **Automatic deployment to staging, manual deployment to production** | Sets [`STAGING_ENABLED`](cicd_variables.md#deploy-policy-for-staging-and-production-environments) to `1` and [`INCREMENTAL_ROLLOUT_MODE`](cicd_variables.md#incremental-rollout-to-production) to `manual`. | The default branch is continuously deployed to staging and continuously delivered to production. | You can choose the deployment method when enabling Auto DevOps or later: diff --git a/doc/topics/autodevops/stages.md b/doc/topics/autodevops/stages.md index 022ee131e40..0ca9c6fa3de 100644 --- a/doc/topics/autodevops/stages.md +++ b/doc/topics/autodevops/stages.md @@ -385,7 +385,7 @@ default, but the [Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) contains job definitions for these tasks if you want to enable them. -You can use [CI/CD variables](customize.md#cicd-variables) to automatically +You can use [CI/CD variables](cicd_variables.md) to automatically scale your pod replicas, and to apply custom arguments to the Auto DevOps `helm upgrade` commands. This is an easy way to [customize the Auto Deploy Helm chart](customize.md#custom-helm-chart). @@ -620,4 +620,4 @@ for updates. This stage is enabled by default. You can disable it by adding the `CODE_INTELLIGENCE_DISABLED` CI/CD variable. Read more about -[disabling Auto DevOps jobs](../../topics/autodevops/customize.md#disable-jobs). +[disabling Auto DevOps jobs](../../topics/autodevops/cicd_variables.md#job-disabling-variables). diff --git a/doc/topics/autodevops/troubleshooting.md b/doc/topics/autodevops/troubleshooting.md index ae3cc42223f..ef420323b32 100644 --- a/doc/topics/autodevops/troubleshooting.md +++ b/doc/topics/autodevops/troubleshooting.md @@ -13,7 +13,7 @@ Auto DevOps, and any available workarounds. Set the CI/CD variable `TRACE` to any value to make Helm commands produce verbose output. You can use this output to diagnose Auto DevOps deployment problems. -You can resolve some problems with Auto DevOps deployment by changing advanced Auto DevOps configuration variables. Read more about [customizing Auto DevOps CI/CD variables](customize.md#cicd-variables). +You can resolve some problems with Auto DevOps deployment by changing advanced Auto DevOps configuration variables. Read more about [customizing Auto DevOps CI/CD variables](cicd_variables.md). ## Unable to select a buildpack @@ -40,7 +40,7 @@ The following are possible reasons: If your pipeline fails with the following message: ```plaintext -Found errors in your .gitlab-ci.yml: +Unable to create pipeline jobs:test config key may not be used with `rules`: only ``` diff --git a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md index 602bdec6140..4fafc89cac1 100644 --- a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md +++ b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md @@ -128,7 +128,7 @@ with the [v1 auto-deploy-image](#use-a-specific-version-of-auto-deploy-dependenc > [Introduced](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/merge_requests/109) in GitLab 13.4. -Auto Deploy supports advanced deployment strategies such as [canary deployments](customize.md#deploy-policy-for-canary-environments) +Auto Deploy supports advanced deployment strategies such as [canary deployments](cicd_variables.md#deploy-policy-for-canary-environments) and [incremental rollouts](../../ci/environments/incremental_rollouts.md). Previously, `auto-deploy-image` created one service to balance the traffic between @@ -171,7 +171,7 @@ Alternatively, you can use the [v13.12 Auto DevOps templates archive](https://gi ### Ignore warnings and continue deploying If you are certain that the new chart version is safe to be deployed, you can add -the `AUTO_DEVOPS_FORCE_DEPLOY_V<major-version-number>` [CI/CD variable](customize.md#build-and-deployment) +the `AUTO_DEVOPS_FORCE_DEPLOY_V<major-version-number>` [CI/CD variable](cicd_variables.md#build-and-deployment-variables) to force the deployment to continue. For example, if you want to deploy the `v2.0.0` chart on a deployment that previously |