diff options
Diffstat (limited to 'doc/topics/autodevops/customize.md')
| -rw-r--r-- | doc/topics/autodevops/customize.md | 100 |
1 files changed, 65 insertions, 35 deletions
diff --git a/doc/topics/autodevops/customize.md b/doc/topics/autodevops/customize.md index 95b6241583f..d1733789856 100644 --- a/doc/topics/autodevops/customize.md +++ b/doc/topics/autodevops/customize.md @@ -38,7 +38,7 @@ For example: ### Multiple buildpacks Using multiple buildpacks is not fully supported by Auto DevOps, because Auto Test -won't work when using the `.buildpacks` file. The buildpack +can't use the `.buildpacks` file. The buildpack [heroku-buildpack-multi](https://github.com/heroku/heroku-buildpack-multi/), used in the backend to parse the `.buildpacks` file, does not provide the necessary commands `bin/test-compile` and `bin/test`. @@ -133,7 +133,7 @@ You can override the Helm chart used by bundling up a chart into your project repository or by specifying a project variable: - **Bundled chart** - If your project has a `./chart` directory with a `Chart.yaml` - file in it, Auto DevOps will detect the chart and use it instead of the + file in it, Auto DevOps detects the chart and uses it instead of the [default chart](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app), enabling you to control exactly how your application is deployed. - **Project variable** - Create a [project variable](../../ci/variables/README.md#gitlab-cicd-environment-variables) @@ -143,7 +143,7 @@ repository or by specifying a project variable: ## Customize values for Helm Chart -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30628) in GitLab 12.6, `.gitlab/auto-deploy-values.yaml` will be used by default for Helm upgrades. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30628) in GitLab 12.6, `.gitlab/auto-deploy-values.yaml` is used by default for Helm upgrades. You can override the default values in the `values.yaml` file in the [default Helm chart](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/tree/master/assets/auto-deploy-app) by either: @@ -190,7 +190,7 @@ include: - template: Auto-DevOps.gitlab-ci.yml ``` -Add your changes, and your additions will be merged with the +Add your changes, and your additions are merged with the [Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) using the behavior described for [`include`](../../ci/yaml/README.md#include). @@ -243,9 +243,9 @@ include: See the [Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) for information on available jobs. -CAUTION: **Deprecation:** +DANGER: **Deprecated:** Auto DevOps templates using the [`only`](../../ci/yaml/README.md#onlyexcept-basic) or -[`except`](../../ci/yaml/README.md#onlyexcept-basic) syntax will switch +[`except`](../../ci/yaml/README.md#onlyexcept-basic) syntax have switched to the [`rules`](../../ci/yaml/README.md#rules) syntax, starting in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/213336). If your `.gitlab-ci.yml` extends these Auto DevOps templates and override the `only` or @@ -295,12 +295,12 @@ You must define environment-scoped variables for `POSTGRES_ENABLED` and 1. Disable the built-in PostgreSQL installation for the required environments using scoped [environment variables](../../ci/environments/index.md#scoping-environments-with-specs). - For this use case, it's likely that only `production` will need to be added to this + For this use case, it's likely that only `production` must be added to this list. The built-in PostgreSQL setup for Review Apps and staging is sufficient.  -1. Define the `DATABASE_URL` CI variable as a scoped environment variable that will be +1. Define the `DATABASE_URL` CI variable as a scoped environment variable that is available to your application. This should be a URL in the following format: ```yaml @@ -328,14 +328,14 @@ applications. | `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` | When set to a non-empty value and no `Dockerfile` is present, Auto Build builds your application using Cloud Native Buildpacks instead of Herokuish. [More details](stages.md#auto-build-using-cloud-native-buildpacks-beta). | | `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-beta). | -| `AUTO_DEVOPS_BUILD_IMAGE_EXTRA_ARGS` | Extra arguments to be passed to the `docker build` command. Note that using quotes won't prevent word splitting. [More details](#passing-arguments-to-docker-build). | +| `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 variable names](#forward-ci-variables-to-the-build-environment) to be forwarded to the build environment (the buildpack builder or `docker build`). | | `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` | From GitLab 11.11, used to set the name of the Helm repository. Defaults to `gitlab`. | | `AUTO_DEVOPS_CHART_REPOSITORY_USERNAME` | From GitLab 11.11, 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` | From GitLab 11.11, used to set a password to connect to the Helm repository. Defaults to no credentials. Also set `AUTO_DEVOPS_CHART_REPOSITORY_USERNAME`. | -| `AUTO_DEVOPS_DEPLOY_DEBUG` | From GitLab 13.1, if this variable is present, Helm will output debug logs. | +| `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). | | `AUTO_DEVOPS_MODSECURITY_SEC_RULE_ENGINE` | From GitLab 12.5, used in combination with [ModSecurity feature flag](../../user/clusters/applications.md#web-application-firewall-modsecurity) to toggle [ModSecurity's `SecRuleEngine`](https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual-(v2.x)#SecRuleEngine) behavior. Defaults to `DetectionOnly`. | | `BUILDPACK_URL` | Buildpack's full URL. Can point to either [a Git repository URL or a tarball URL](#custom-buildpacks). | @@ -345,9 +345,9 @@ applications. | `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` | From GitLab 11.11, allows extra options in `helm upgrade` commands when deploying the application. Note that using quotes won't prevent word splitting. | +| `HELM_UPGRADE_EXTRA_ARGS` | From GitLab 11.11, allows extra options in `helm upgrade` commands when deploying the application. Note that using quotes doesn't prevent word splitting. | | `INCREMENTAL_ROLLOUT_MODE` | From GitLab 11.4, 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_*` | From GitLab 11.7, any variable prefixed with [`K8S_SECRET_`](#application-secret-variables) will be made available by Auto DevOps as environment variables to the deployed application. | +| `K8S_SECRET_*` | From GitLab 11.7, any variable prefixed with [`K8S_SECRET_`](#application-secret-variables) is made available by Auto DevOps as environment variables to the deployed application. | | `KUBE_INGRESS_BASE_DOMAIN` | From GitLab 11.8, can be used to set a domain per cluster. See [cluster domains](../../user/project/clusters/index.md#base-domain) for more information. | | `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. | @@ -377,26 +377,56 @@ The following table lists variables related to the database. | `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/README.md#predefined-environment-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 will use the default version `9.6.2`. | +| `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`. | ### Disable jobs The following table lists variables used to disable jobs. -| **Variable** | **Description** | -|-----------------------------------------|------------------------------------| -| `CODE_QUALITY_DISABLED` | From GitLab 11.0, used to disable the `codequality` job. If the variable is present, the job won't be created. | -| `CONTAINER_SCANNING_DISABLED` | From GitLab 11.0, used to disable the `sast:container` job. If the variable is present, the job won't be created. | -| `DAST_DISABLED` | From GitLab 11.0, used to disable the `dast` job. If the variable is present, the job won't be created. | -| `DEPENDENCY_SCANNING_DISABLED` | From GitLab 11.0, used to disable the `dependency_scanning` job. If the variable is present, the job won't be created. | -| `LICENSE_MANAGEMENT_DISABLED` | From GitLab 11.0, used to disable the `license_management` job. If the variable is present, the job won't be created. | -| `PERFORMANCE_DISABLED` | From GitLab 11.0, used to disable the browser `performance` job. If the variable is present, the job won't be created. | -| `LOAD_PERFORMANCE_DISABLED` | From GitLab 13.2, used to disable the `load_performance` job. If the variable is present, the job won't be created. | -| `REVIEW_DISABLED` | From GitLab 11.0, used to disable the `review` and the manual `review:stop` job. If the variable is present, these jobs won't be created. | -| `SAST_DISABLED` | From GitLab 11.0, used to disable the `sast` job. If the variable is present, the job won't be created. | -| `TEST_DISABLED` | From GitLab 11.0, used to disable the `test` job. If the variable is present, the job won't be created. | -| `SECRET_DETECTION_DISABLED` | From GitLab 13.1, used to disable the `secret_detection` job. If the variable is present, the job won't be created. | -| `CODE_INTELLIGENCE_DISABLED` | From GitLab 13.6, used to disable the `code_intelligence` job. If the variable is present, the job won't be created. | +| **Job Name** | **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/) about how `.fuzz_base` provide capability for your own jobs. If the variable is present, your jobs won't be 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 won't be created. | +| `bandit-sast` | `SAST_DISABLED` | | If the variable is present, the job won't be created. | +| `brakeman-sast` | `SAST_DISABLED` | | If the variable is present, the job won't be created. | +| `bundler-audit-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job won't be created. | +| `canary` | `CANARY_ENABLED` | | This manual job is created if the variable is present. | +| `code_intelligence` | `CODE_INTELLIGENCE_DISABLED` | From GitLab 13.6 | If the variable is present, the job isn't created. | +| `codequality` | `CODE_QUALITY_DISABLED` | Until GitLab 11.0 | If the variable is present, the job won't be created. | +| `code_quality` | `CODE_QUALITY_DISABLED` | [From GitLab 11.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5773) | If the variable is present, the job won't be created. | +| `container_scanning` | `CONTAINER_SCANNING_DISABLED` | From GitLab 11.0 | If the variable is present, the job won't be created. | +| `dast` | `DAST_DISABLED` | From GitLab 11.0 | If the variable is present, the job won't be 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 won't be created. | +| `dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | From GitLab 11.0 | If the variable is present, the job won't be created. | +| `eslint-sast` | `SAST_DISABLED` | | If the variable is present, the job won't be created. | +| `flawfinder-sast` | `SAST_DISABLED` | | If the variable is present, the job won't be created. | +| `gemnasium-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job won't be created. | +| `gemnasium-maven-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job won't be created. | +| `gemnasium-python-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job won't be created. | +| `gosec-sast` | `SAST_DISABLED` | | If the variable is present, the job won't be created. | +| `kubesec-sast` | `SAST_DISABLED` | | If the variable is present, the job won't be created. | +| `license_management` | `LICENSE_MANAGEMENT_DISABLED` | GitLab 11.0 to 12.7 | If the variable is present, the job won't be 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 won't be created. | +| `load_performance` | `LOAD_PERFORMANCE_DISABLED` | From GitLab 13.2 | If the variable is present, the job won't be created. | +| `nodejs-scan-sast` | `SAST_DISABLED` | | If the variable is present, the job won't be created. | +| `performance` | `PERFORMANCE_DISABLED` | From GitLab 11.0 | Browser performance. If the variable is present, the job won't be created. | +| `phpcs-security-audit-sast` | `SAST_DISABLED` | | If the variable is present, the job won't be created. | +| `pmd-apex-sast` | `SAST_DISABLED` | | If the variable is present, the job won't be created. | +| `retire-js-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job won't be created. | +| `review` | `REVIEW_DISABLED` | From GitLab 11.0 | If the variable is present, the job won't be created. | +| `review:stop` | `REVIEW_DISABLED` | From GitLab 11.0 | Manual job. If the variable is present, the job won't be created. | +| `sast` | `SAST_DISABLED` | From GitLab 11.0 | If the variable is present, the job won't be created. | +| `sast:container` | `CONTAINER_SCANNING_DISABLED` | From GitLab 11.0 | If the variable is present, the job won't be created. | +| `secret_detection` | `SECRET_DETECTION_DISABLED` | From GitLab 13.1 | If the variable is present, the job won't be 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 won't be created. | +| `security-code-scan-sast` | `SAST_DISABLED` | | If the variable is present, the job won't be created. | +| `secrets-sast` | `SAST_DISABLED` | From GitLab 11.0 | If the variable is present, the job won't be created. | +| `sobelaw-sast` | `SAST_DISABLED` | | If the variable is present, the job won't be 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 won't be created. | +| `spotbugs-sast` | `SAST_DISABLED` | | If the variable is present, the job won't be created. | +| `test` | `TEST_DISABLED` | From GitLab 11.0 | If the variable is present, the job won't be created. | +| `staging` | `STAGING_ENABLED` | | The job is created if the variable is present. | +| `stop_review` | `REVIEW_DISABLED` | | If the variable is present, the job won't be created. | ### Application secret variables @@ -418,7 +448,7 @@ To configure your application variables: 1. Run an Auto DevOps pipeline, either by manually creating a new pipeline or by pushing a code change to GitLab. -Auto DevOps pipelines will take your application secret variables to +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 @@ -444,7 +474,7 @@ 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, you will find any running application pods won't have +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. @@ -465,7 +495,7 @@ 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 won't be taken into account + 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`. @@ -547,7 +577,7 @@ check how the application is behaving before manually increasing the rollout up 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) -will be created: +are created: 1. `rollout 10%` 1. `rollout 25%` @@ -556,7 +586,7 @@ will be created: The percentage is based on the `REPLICAS` 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 will be `1` new pod + `9` old ones. +`10%` rollout job, there is `1` new pod and `9` old ones. To start a job, click 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. @@ -566,7 +596,7 @@ back by redeploying the old version using the [rollback button](../../ci/environments/index.md#retrying-and-rolling-back) in the environment page. -Below, you can see how the pipeline will look if the rollout or staging +Below, you can see how the pipeline appears if the rollout or staging variables are defined. Without `INCREMENTAL_ROLLOUT_MODE` and without `STAGING_ENABLED`: @@ -585,9 +615,9 @@ With `INCREMENTAL_ROLLOUT_MODE` set to `manual` and with `STAGING_ENABLED`  -CAUTION: **Caution:** +WARNING: **Deprecation:** Before GitLab 11.4, the presence of the `INCREMENTAL_ROLLOUT_ENABLED` environment -variable enabled this feature. This configuration is deprecated, and will be +variable enabled this feature. This configuration is deprecated, and is scheduled to be removed in the future. ### Timed incremental rollout to production **(PREMIUM)** |