diff options
Diffstat (limited to 'doc/topics/autodevops')
| -rw-r--r-- | doc/topics/autodevops/customize.md | 120 | ||||
| -rw-r--r-- | doc/topics/autodevops/index.md | 42 | ||||
| -rw-r--r-- | doc/topics/autodevops/quick_start_guide.md | 36 | ||||
| -rw-r--r-- | doc/topics/autodevops/requirements.md | 48 | ||||
| -rw-r--r-- | doc/topics/autodevops/stages.md | 56 | ||||
| -rw-r--r-- | doc/topics/autodevops/upgrading_auto_deploy_dependencies.md | 16 | ||||
| -rw-r--r-- | doc/topics/autodevops/upgrading_chart.md | 3 | ||||
| -rw-r--r-- | doc/topics/autodevops/upgrading_postgresql.md | 22 |
8 files changed, 200 insertions, 143 deletions
diff --git a/doc/topics/autodevops/customize.md b/doc/topics/autodevops/customize.md index 95b6241583f..0d4f86f1284 100644 --- a/doc/topics/autodevops/customize.md +++ b/doc/topics/autodevops/customize.md @@ -1,7 +1,7 @@ --- 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/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Customizing Auto DevOps @@ -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`. @@ -78,7 +78,7 @@ Use Base64 encoding if you need to pass complex values, such as newlines and spaces. Left unencoded, complex values like these can cause escaping issues due to how Auto DevOps uses the arguments. -CAUTION: **Warning:** +WARNING: Avoid passing secrets as Docker build arguments if possible, as they may be persisted in your image. See [this discussion of best practices with secrets](https://github.com/moby/moby/issues/13490) for details. @@ -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: @@ -154,7 +154,7 @@ You can override the default values in the `values.yaml` file in the `HELM_UPGRADE_VALUES_FILE` [environment variable](#environment-variables) with the path and name. -NOTE: **Note:** +NOTE: For GitLab 12.5 and earlier, use the `HELM_UPGRADE_EXTRA_ARGS` environment variable to override the default chart values by setting `HELM_UPGRADE_EXTRA_ARGS` to `--values <my-values.yaml>`. @@ -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:** +WARNING: 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 @@ -268,7 +268,7 @@ postgres://user:password@postgres-host:postgres-port/postgres-database ### Upgrading PostgresSQL -CAUTION: **Deprecation:** +WARNING: The variable `AUTO_DEVOPS_POSTGRES_CHANNEL` that controls default provisioned PostgreSQL was changed to `2` in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/210499). To keep using the old PostgreSQL, set the `AUTO_DEVOPS_POSTGRES_CHANNEL` variable to @@ -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. | @@ -355,12 +355,12 @@ applications. | `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` | From GitLab 10.8, used to define a [deploy policy for staging and production environments](#deploy-policy-for-staging-and-production-environments). | -TIP: **Tip:** +NOTE: After you set up your replica variables using a [project variable](../../ci/variables/README.md#gitlab-cicd-environment-variables), you can scale your application by redeploying it. -CAUTION: **Caution:** +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. @@ -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 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. | +| `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. | +| `bundler-audit-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job isn't 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 isn't 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 isn't created. | +| `container_scanning` | `CONTAINER_SCANNING_DISABLED` | From GitLab 11.0 | If the variable is present, the job isn't created. | +| `dast` | `DAST_DISABLED` | From GitLab 11.0 | 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` | From GitLab 11.0 | 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 11.0 to 12.7 | 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` | From GitLab 11.0 | Browser performance. If the variable is present, the job isn't created. | +| `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. | +| `retire-js-dependency_scanning` | `DEPENDENCY_SCANNING_DISABLED` | | If the variable is present, the job isn't created. | +| `review` | `REVIEW_DISABLED` | From GitLab 11.0 | If the variable is present, the job isn't created. | +| `review:stop` | `REVIEW_DISABLED` | From GitLab 11.0 | Manual job. If the variable is present, the job isn't created. | +| `sast` | `SAST_DISABLED` | From GitLab 11.0 | If the variable is present, the job isn't created. | +| `sast:container` | `CONTAINER_SCANNING_DISABLED` | From GitLab 11.0 | 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` | From GitLab 11.0 | 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` | From GitLab 11.0 | 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 @@ -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`. @@ -508,7 +538,7 @@ service: > [Introduced](https://gitlab.com/gitlab-org/gitlab-ci-yml/-/merge_requests/160) in GitLab 10.8. -TIP: **Tip:** +NOTE: You can also set this inside your [project's settings](index.md#deployment-strategy). The normal behavior of Auto DevOps is to use continuous deployment, pushing @@ -537,7 +567,7 @@ If you define `CANARY_ENABLED` with a non-empty value, then two manual jobs are > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5415) in GitLab 10.8. -TIP: **Tip:** +NOTE: You can also set this inside your [project's settings](index.md#deployment-strategy). When you're ready to deploy a new version of your app to production, you may want @@ -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,16 +615,16 @@ With `INCREMENTAL_ROLLOUT_MODE` set to `manual` and with `STAGING_ENABLED`  -CAUTION: **Caution:** +WARNING: 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)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7545) in GitLab 11.4. -TIP: **Tip:** +NOTE: You can also set this inside your [project's settings](index.md#deployment-strategy). This configuration is based on @@ -632,5 +662,5 @@ The banner can be disabled for: - Through the REST API with an admin access token: ```shell - curl --data "value=true" --header "PRIVATE-TOKEN: <personal_access_token>" https://gitlab.example.com/api/v4/features/auto_devops_banner_disabled + curl --data "value=true" --header "PRIVATE-TOKEN: <personal_access_token>" "https://gitlab.example.com/api/v4/features/auto_devops_banner_disabled" ``` diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 014690c4cdf..7234bca8e12 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -1,7 +1,7 @@ --- 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/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Auto DevOps @@ -38,18 +38,21 @@ For requirements, see [Requirements for Auto DevOps](requirements.md) for more i > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41729) in GitLab 11.3. -Auto DevOps is enabled by default for all projects and attempts to run on all pipelines -in each project. An instance administrator can enable or disable this default in the +On self-managed instances, Auto DevOps is enabled by default for all projects. +It attempts to run on all pipelines in each project. An instance administrator can +enable or disable this default in the [Auto DevOps settings](../../user/admin_area/settings/continuous_integration.md#auto-devops). Auto DevOps automatically disables in individual projects on their first pipeline failure, -if it has not been explicitly enabled for the project. + +NOTE: +Auto DevOps is not enabled by default on GitLab.com. Since [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/issues/26655), Auto DevOps runs on pipelines automatically only if a [`Dockerfile` or matching buildpack](stages.md#auto-build) exists. If a [CI/CD configuration file](../../ci/yaml/README.md) is present in the project, -it will continue to be used, whether or not Auto DevOps is enabled. +it continues to be used, whether or not Auto DevOps is enabled. ## Quick start @@ -73,7 +76,7 @@ innovative work done by [Heroku](https://www.heroku.com/) and goes beyond it in multiple ways: - Auto DevOps works with any Kubernetes cluster; you're not limited to running - on GitLab's infrastructure. (Note that many features also work without Kubernetes). + on infrastructure managed by GitLab. (Note that many features also work without Kubernetes). - There is no additional cost (no markup on the infrastructure costs), and you can use a Kubernetes cluster you host or Containers as a Service on any public cloud (for example, [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/)). @@ -85,6 +88,9 @@ in multiple ways: ## Features +NOTE: +Depending on your target platform, some features might not be available to you. + Comprised of a set of [stages](stages.md), Auto DevOps brings these best practices to your project in a simple and automatic way: @@ -120,7 +126,7 @@ Auto DevOps provides great defaults for all the stages and makes use of For an overview on the creation of Auto DevOps, read more [in this blog post](https://about.gitlab.com/blog/2017/06/29/whats-next-for-gitlab-ci/). -NOTE: **Note:** +NOTE: Kubernetes clusters can [be used without](../../user/project/clusters/index.md) Auto DevOps. @@ -146,14 +152,14 @@ any of the following places: 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). If the CI/CD variable is not set and the cluster setting is left blank, the instance-wide **Auto DevOps domain** -setting will be used if set. +setting is used if set. -TIP: **Tip:** +NOTE: If you use the [GitLab managed app for Ingress](../../user/clusters/applications.md#ingress), the URL endpoint should be automatically configured for you. All you must do is use its value for the `KUBE_INGRESS_BASE_DOMAIN` variable. -NOTE: **Note:** +NOTE: `AUTO_DEVOPS_DOMAIN` was [deprecated in GitLab 11.8](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/52363) and replaced with `KUBE_INGRESS_BASE_DOMAIN`, and removed in [GitLab 12.0](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/56959). @@ -236,7 +242,7 @@ Auto DevOps at the group and project level, respectively. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/38542) in GitLab 11.0. -You can change the deployment strategy used by Auto DevOps by going to your +You can change the deployment strategy used by Auto DevOps by visiting your project's **Settings > CI/CD > Auto DevOps**. The following options are available: @@ -254,7 +260,7 @@ are available: - `master` branch is directly deployed to staging. - Manual actions are provided for incremental rollout to production. -TIP: **Tip:** +NOTE: Use the [blue-green deployment](../../ci/environments/incremental_rollouts.md#blue-green-deployment) technique to minimize downtime and risk. @@ -313,7 +319,7 @@ simplify configuration and prevent any unforeseen issues. ### Install applications behind a proxy -GitLab's Helm integration does not support installing applications when +The GitLab integration with Helm does not support installing applications when behind a proxy. Users who want to do so must inject their proxy settings into the installation pods at runtime, such as by using a [`PodPreset`](https://kubernetes.io/docs/concepts/workloads/pods/podpreset/): @@ -372,7 +378,7 @@ To fix this issue, you must either: ### Failure to create a Kubernetes namespace -Auto Deploy will fail if GitLab can't create a Kubernetes namespace and +Auto Deploy fails if GitLab can't create a Kubernetes namespace and service account for your project. For help debugging this issue, see [Troubleshooting failed deployment jobs](../../user/project/clusters/index.md#troubleshooting). @@ -407,7 +413,7 @@ If you receive this error, you can do one of the following actions: database by setting `AUTO_DEVOPS_POSTGRES_DELETE_V1` to a non-empty value and redeploying. - DANGER: **Warning:** + WARNING: Deleting the channel 1 PostgreSQL database permanently deletes the existing channel 1 database and all its data. See [Upgrading PostgreSQL](upgrading_postgresql.md) @@ -421,7 +427,7 @@ If you receive this error, you can do one of the following actions: and persisted by Helm, regardless of whether or not your chart uses the variable. -DANGER: **Warning:** +WARNING: Setting `POSTGRES_ENABLED` to `false` permanently deletes any existing channel 1 database for your environment. @@ -476,7 +482,7 @@ that works for this problem. Follow these steps to use the tool in Auto DevOps: ### Error: error initializing: Looks like "https://kubernetes-charts.storage.googleapis.com" is not a valid chart repository or cannot be reached As [announced in the official CNCF blogpost](https://www.cncf.io/blog/2020/10/07/important-reminder-for-all-helm-users-stable-incubator-repos-are-deprecated-and-all-images-are-changing-location/), -the stable Helm chart repository will be deprecated and removed on November 13th, 2020. +the stable Helm chart repository was deprecated and removed on November 13th, 2020. You may encounter this error after that date. Some GitLab features had dependencies on the stable chart. To mitigate the impact, we changed them @@ -495,7 +501,7 @@ include: image: "registry.gitlab.com/gitlab-org/cluster-integration/auto-deploy-image:v1.0.5" ``` -Keep in mind that this approach will eventually stop working when the stable repository is removed, +Keep in mind that this approach stops working when the stable repository is removed, so you must eventually fix your custom chart. To fix your custom chart: diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md index 3531035eb67..5c3b296fdea 100644 --- a/doc/topics/autodevops/quick_start_guide.md +++ b/doc/topics/autodevops/quick_start_guide.md @@ -1,20 +1,20 @@ --- 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/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Getting started with Auto DevOps -This step-by-step guide will help you use [Auto DevOps](index.md) to +This step-by-step guide helps you use [Auto DevOps](index.md) to deploy a project hosted on GitLab.com to Google Kubernetes Engine. -You will use GitLab's native Kubernetes integration, so you won't need +You are using the GitLab native Kubernetes integration, so you don't need to create a Kubernetes cluster manually using the Google Cloud Platform console. -You will create and deploy a simple application that you create from a GitLab template. +You are creating and deploying a simple application that you create from a GitLab template. -These instructions will also work for a self-managed GitLab instance; you'll just -need to ensure your own [runners are configured](../../ci/runners/README.md) and +These instructions also work for a self-managed GitLab instance; +ensure your own [runners are configured](../../ci/runners/README.md) and [Google OAuth is enabled](../../integration/google.md). ## Configure your Google account @@ -29,16 +29,16 @@ or Google Drive, or create a new one. 1. Ensure you've created a [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account) with Google Cloud Platform. -TIP: **Tip:** +NOTE: Every new Google Cloud Platform (GCP) account receives [$300 in credit](https://console.cloud.google.com/freetrial), and in partnership with Google, GitLab is able to offer an additional $200 for new -GCP accounts to get started with GitLab's Google Kubernetes Engine Integration. +GCP accounts to get started with the GitLab integration with Google Kubernetes Engine. [Follow this link](https://cloud.google.com/partners/partnercredit/?pcn_code=0014M00001h35gDQAQ#contact-form) and apply for credit. ## Create a new project from a template -We will use one of GitLab's project templates to get started. As the name suggests, +We are using a GitLab project template to get started. As the name suggests, those projects provide a bare-bones application built on some well-known frameworks. 1. In GitLab, click the plus icon (**{plus-square}**) at the top of the navigation bar, and select @@ -57,7 +57,7 @@ those projects provide a bare-bones application built on some well-known framewo 1. Click **Create project**. -Now that you've created a project, you'll next create the Kubernetes cluster +Now that you've created a project, create the Kubernetes cluster to deploy this project to. ## Create a Kubernetes cluster from within GitLab @@ -98,30 +98,30 @@ to deploy this project to. 1. Click **Create Kubernetes cluster**. -After a couple of minutes, the cluster will be created. You can also see its +After a couple of minutes, the cluster is created. You can also see its status on your [GCP dashboard](https://console.cloud.google.com/kubernetes). -Next, you will install some applications on your cluster that are needed +Next, install some applications on your cluster that are needed to take full advantage of Auto DevOps. ## Install Ingress and Prometheus -After your cluster is running, you can install your first applications. -In this guide, we will install Ingress and Prometheus: +After your cluster is running, you can install your first applications, +Ingress and Prometheus: - Ingress - Provides load balancing, SSL termination, and name-based virtual hosting, using NGINX behind the scenes. - Prometheus - An open-source monitoring and alerting system used to supervise the deployed application. -We won't install GitLab Runner in this quick start guide, as this guide uses the +We aren't installing GitLab Runner in this quick start guide, as this guide uses the shared runners provided by GitLab.com. To install the applications: - Click the **Install** button for **Ingress**. - When the **Ingress Endpoint** is displayed, copy the IP address. -- Add your **Base domain**. For this guide, we will use the domain suggested by GitLab. +- Add your **Base domain**. For this guide, use the domain suggested by GitLab. - Click **Save changes**.  @@ -221,7 +221,7 @@ Kubernetes cluster, color-coded to show their status. Hovering over a square on the deploy board displays the state of the deployment, and clicking the square takes you to the pod's logs page. -TIP: **Tip:** +NOTE: The example shows only one pod hosting the application at the moment, but you can add more pods by defining the [`REPLICAS` variable](customize.md#environment-variables) in **Settings > CI/CD > Environment variables**. @@ -251,7 +251,7 @@ a few more that run only on branches other than `master`.  -After a few minutes you'll notice a test failed, which means a test was +After a few minutes a test fails, which means a test was 'broken' by your change. Click on the failed `test` job to see more information about it: diff --git a/doc/topics/autodevops/requirements.md b/doc/topics/autodevops/requirements.md index acec7b79d6b..824874ed4d4 100644 --- a/doc/topics/autodevops/requirements.md +++ b/doc/topics/autodevops/requirements.md @@ -1,13 +1,14 @@ --- 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/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Requirements for Auto DevOps -You can set up Auto DevOps for [Kubernetes](#auto-devops-requirements-for-kubernetes) -or [Amazon Elastic Container Service (ECS)](#auto-devops-requirements-for-amazon-ecs). +You can set up Auto DevOps for [Kubernetes](#auto-devops-requirements-for-kubernetes), +[Amazon Elastic Container Service (ECS)](#auto-devops-requirements-for-amazon-ecs), +or [Amazon Cloud Compute](#auto-devops-requirements-for-amazon-ecs). For more information about Auto DevOps, see [the main Auto DevOps page](index.md) or the [quick start guide](quick_start_guide.md). @@ -27,15 +28,15 @@ To make full use of Auto DevOps with Kubernetes, you need: [Auto Deploy for Kubernetes 1.16+](stages.md#kubernetes-116). 1. NGINX Ingress. You can deploy it to your Kubernetes cluster by installing the [GitLab-managed app for Ingress](../../user/clusters/applications.md#ingress), - after configuring GitLab's Kubernetes integration in the previous step. + after configuring the GitLab integration with Kubernetes in the previous step. Alternatively, you can use the [`nginx-ingress`](https://github.com/helm/charts/tree/master/stable/nginx-ingress) Helm chart to install Ingress manually. - NOTE: **Note:** - If you use your own Ingress instead of the one provided by GitLab's managed - apps, ensure you're running at least version 0.9.0 of NGINX Ingress and + NOTE: + If you use your own Ingress instead of the one provided by GitLab Managed + Apps, ensure you're running at least version 0.9.0 of NGINX Ingress and [enable Prometheus metrics](https://github.com/helm/charts/tree/master/stable/nginx-ingress#prometheus-metrics) for the response metrics to appear. You must also [annotate](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) @@ -46,7 +47,7 @@ To make full use of Auto DevOps with Kubernetes, you need: [Auto Deploy](stages.md#auto-deploy), and [Auto Monitoring](stages.md#auto-monitoring)) You need a domain configured with wildcard DNS, which all of your Auto DevOps - applications will use. If you're using the + applications use. If you're using the [GitLab-managed app for Ingress](../../user/clusters/applications.md#ingress), the URL endpoint is automatically configured for you. @@ -63,7 +64,7 @@ To make full use of Auto DevOps with Kubernetes, you need: You can configure Docker-based runners to autoscale as well, using [Docker Machine](https://docs.gitlab.com/runner/install/autoscaling.html). - If you've configured GitLab's Kubernetes integration in the first step, you + If you've configured the GitLab integration with Kubernetes in the first step, you can deploy it to your cluster by installing the [GitLab-managed app for GitLab Runner](../../user/clusters/applications.md#gitlab-runner). @@ -76,7 +77,7 @@ To make full use of Auto DevOps with Kubernetes, you need: To enable Auto Monitoring, you need Prometheus installed either inside or outside your cluster, and configured to scrape your Kubernetes cluster. - If you've configured GitLab's Kubernetes integration, you can deploy it to + If you've configured the GitLab integration with Kubernetes, you can deploy it to your cluster by installing the [GitLab-managed app for Prometheus](../../user/clusters/applications.md#prometheus). @@ -94,8 +95,8 @@ To make full use of Auto DevOps with Kubernetes, you need: a native Kubernetes certificate management controller that helps with issuing certificates. Installing cert-manager on your cluster issues a [Let’s Encrypt](https://letsencrypt.org/) certificate and ensures the - certificates are valid and up-to-date. If you've configured GitLab's Kubernetes - integration, you can deploy it to your cluster by installing the + certificates are valid and up-to-date. If you've configured the GitLab integration + with Kubernetes, you can deploy it to your cluster by installing the [GitLab-managed app for cert-manager](../../user/clusters/applications.md#cert-manager). If you don't have Kubernetes or Prometheus installed, then @@ -111,7 +112,7 @@ After all requirements are met, you can [enable Auto DevOps](index.md#enablingdi You can choose to target [AWS ECS](../../ci/cloud_deployment/index.md) as a deployment platform instead of using Kubernetes. -To get started on Auto DevOps to AWS ECS, you'll have to add a specific Environment +To get started on Auto DevOps to AWS ECS, you must add a specific Environment Variable. To do so, follow these steps: 1. In your project, go to **Settings > CI / CD** and expand the **Variables** @@ -124,19 +125,30 @@ Variable. To do so, follow these steps: When you trigger a pipeline, if you have Auto DevOps enabled and if you have correctly [entered AWS credentials as environment variables](../../ci/cloud_deployment/index.md#deploy-your-application-to-the-aws-elastic-container-service-ecs), -your application will be deployed to AWS ECS. +your application is deployed to AWS ECS. [GitLab Managed Apps](../../user/clusters/applications.md) are not available when deploying to AWS ECS. You must manually configure your application (such as Ingress or Help) on AWS ECS. If you have both a valid `AUTO_DEVOPS_PLATFORM_TARGET` variable and a Kubernetes cluster tied to your project, -only the deployment to Kubernetes will run. +only the deployment to Kubernetes runs. -CAUTION: **Warning:** -Setting the `AUTO_DEVOPS_PLATFORM_TARGET` variable to `ECS` will trigger jobs +WARNING: +Setting the `AUTO_DEVOPS_PLATFORM_TARGET` variable to `ECS` triggers jobs defined in the [`Jobs/Deploy/ECS.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy/ECS.gitlab-ci.yml). However, it's not recommended to [include](../../ci/yaml/README.md#includetemplate) it on its own. This template is designed to be used with Auto DevOps only. It may change unexpectedly causing your pipeline to fail if included on its own. Also, the job names within this template may also change. Do not override these jobs' names in your -own pipeline, as the override will stop working when the name changes. +own pipeline, as the override stops working when the name changes. + +## Auto DevOps requirements for Amazon EC2 + +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216008) in GitLab 13.6. + +You can target [AWS EC2](../../ci/cloud_deployment/index.md) +as a deployment platform instead of Kubernetes. To use Auto DevOps with AWS EC2, you must add a +specific environment variable. + +For more details, see [Custom build job for Auto DevOps](../../ci/cloud_deployment/index.md#custom-build-job-for-auto-devops) +for deployments to AWS EC2. diff --git a/doc/topics/autodevops/stages.md b/doc/topics/autodevops/stages.md index f2d3b78e2b0..23ba6ad3356 100644 --- a/doc/topics/autodevops/stages.md +++ b/doc/topics/autodevops/stages.md @@ -1,7 +1,7 @@ --- 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/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Stages of Auto DevOps @@ -11,6 +11,9 @@ Read them carefully to understand how each one works. ## Auto Build +NOTE: +Auto Build is not supported if Docker in Docker is not available for your GitLab Runners, like in OpenShift clusters. The OpenShift support in GitLab is tracked [in a dedicated epic](https://gitlab.com/groups/gitlab-org/-/epics/2068). + Auto Build creates a build of the application using an existing `Dockerfile` or Heroku buildpacks. The resulting Docker image is pushed to the [Container Registry](../../user/packages/container_registry/index.md), and tagged @@ -48,7 +51,7 @@ language: For the requirements of other languages and frameworks, read the [Heroku buildpacks documentation](https://devcenter.heroku.com/articles/buildpacks#officially-supported-buildpacks). -TIP: **Tip:** +NOTE: If Auto Build fails despite the project meeting the buildpack requirements, set a project variable `TRACE=true` to enable verbose logging, which may help you troubleshoot. @@ -64,7 +67,7 @@ value. The default builder is `heroku/buildpacks:18` but a different builder can be selected using the CI variable `AUTO_DEVOPS_BUILD_IMAGE_CNB_BUILDER`. Cloud Native Buildpacks (CNBs) are an evolution of Heroku buildpacks, and -will eventually supersede Herokuish-based builds within Auto DevOps. For more +GitLab expects them to eventually supersede Herokuish-based builds within Auto DevOps. For more information, see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/212692). Builds using Cloud Native Buildpacks support the same options as builds using @@ -78,7 +81,7 @@ Heroku buildpacks, with the following caveats: - The `/bin/herokuish` command is not present in the resulting image, and prefixing commands with `/bin/herokuish procfile exec` is no longer required (nor possible). -NOTE: **Note:** +NOTE: Auto Test still uses Herokuish, as test suite detection is not yet part of the Cloud Native Buildpack specification. For more information, see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/212689). @@ -96,7 +99,7 @@ Check the [currently supported languages](#currently-supported-languages). Auto Test uses tests you already have in your application. If there are no tests, it's up to you to add them. -NOTE: **Note:** +NOTE: Not all buildpacks supported by [Auto Build](#auto-build) are supported by Auto Test. Auto Test uses [Herokuish](https://gitlab.com/gitlab-org/gitlab/-/issues/212689), *not* Cloud Native Buildpacks, and only buildpacks that implement the @@ -147,16 +150,13 @@ out. The merge request widget also displays any > - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. > - Select functionality made available in all tiers beginning in 13.1 -Static Application Security Testing (SAST) uses the -[SAST Docker image](https://gitlab.com/gitlab-org/security-products/sast) to run static +Static Application Security Testing (SAST) runs static analysis on the current code, and checks for potential security issues. The -Auto SAST stage will be skipped on licenses other than -[Ultimate](https://about.gitlab.com/pricing/), and requires -[GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or above. +Auto SAST stage requires [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or above. After creating the report, it's uploaded as an artifact which you can later download and check out. The merge request widget also displays any security -warnings. +warnings on [Ultimate](https://about.gitlab.com/pricing/) licenses. To learn more about [how SAST works](../../user/application_security/sast/index.md), see the documentation. @@ -171,7 +171,7 @@ Secret Detection uses the After creating the report, it's uploaded as an artifact which you can later download and evaluate. The merge request widget also displays any security -warnings. +warnings on [Ultimate](https://about.gitlab.com/pricing/) licenses. To learn more, see [Secret Detection](../../user/application_security/secret_detection/index.md). @@ -179,9 +179,7 @@ To learn more, see [Secret Detection](../../user/application_security/secret_det > Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.7. -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 check for potential security issues. +Dependency Scanning runs analysis on the project's dependencies and checks for potential security issues. The Auto Dependency Scanning stage is skipped on licenses other than [Ultimate](https://about.gitlab.com/pricing/) and requires [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or above. @@ -254,7 +252,7 @@ In GitLab 11.4 and later, [local Tiller](https://gitlab.com/gitlab-org/gitlab-fo used. Previous versions of GitLab had a Tiller installed in the project namespace. -CAUTION: **Caution:** +WARNING: Your apps should *not* be manipulated outside of Helm (using Kubernetes directly). This can cause confusion with Helm not detecting the change and subsequent deploys with Auto DevOps can undo your changes. Also, if you change something @@ -288,7 +286,7 @@ see the documentation. To use a custom target instead of the auto-deployed review apps, set a `DAST_WEBSITE` environment variable to the URL for DAST to scan. -DANGER: **Warning:** +WARNING: If [DAST Full Scan](../../user/application_security/dast/index.md#full-scan) is enabled, GitLab strongly advises **not** to set `DAST_WEBSITE` to any staging or production environment. DAST Full Scan @@ -373,7 +371,7 @@ In GitLab 11.4 and later, a used. Previous versions of GitLab had a Tiller installed in the project namespace. -CAUTION: **Caution:** +WARNING: Your apps should *not* be manipulated outside of Helm (using Kubernetes directly). This can cause confusion with Helm not detecting the change and subsequent deploys with Auto DevOps can undo your changes. Also, if you change something @@ -387,16 +385,16 @@ in the first place, and thus not realize that it needs to re-apply the old confi [GitLab Deploy Tokens](../../user/project/deploy_tokens/index.md#gitlab-deploy-token) are created for internal and private projects when Auto DevOps is enabled, and the Auto DevOps settings are saved. You can use a Deploy Token for permanent access to -the registry. After you manually revoke the GitLab Deploy Token, it won't be +the registry. After you manually revoke the GitLab Deploy Token, it isn't automatically created. If the GitLab Deploy Token can't be found, `CI_REGISTRY_PASSWORD` is used. -NOTE: **Note:** -`CI_REGISTRY_PASSWORD` is only valid during deployment. Kubernetes will be able -to successfully pull the container image during deployment, but if the image must -be pulled again, such as after pod eviction, Kubernetes will fail to do so +NOTE: +`CI_REGISTRY_PASSWORD` is only valid during deployment. Kubernetes can +successfully pull the container image during deployment, but if the image must +be pulled again, such as after pod eviction, Kubernetes cannot do so as it attempts to fetch the image using `CI_REGISTRY_PASSWORD`. ### Kubernetes 1.16+ @@ -405,7 +403,7 @@ as it attempts to fetch the image using `CI_REGISTRY_PASSWORD`. > - Support for deploying a PostgreSQL version that supports Kubernetes 1.16+ was [introduced](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/merge_requests/49) in GitLab 12.9. > - Supported out of the box for new deployments as of GitLab 13.0. -CAUTION: **Deprecation:** +WARNING: The default value for the `deploymentApiVersion` setting was changed from `extensions/v1beta` to `apps/v1` in [GitLab 13.0](https://gitlab.com/gitlab-org/charts/auto-deploy-app/-/issues/47). @@ -431,7 +429,7 @@ To use Auto Deploy on a Kubernetes 1.16+ cluster: 1. If you are deploying your application for the first time and are using GitLab 12.9 or 12.10, set `AUTO_DEVOPS_POSTGRES_CHANNEL` to `2`. -DANGER: **Warning:** +WARNING: On GitLab 12.9 and 12.10, opting into `AUTO_DEVOPS_POSTGRES_CHANNEL` version `2` deletes the version `1` PostgreSQL database. Follow the [guide to upgrading PostgreSQL](upgrading_postgresql.md) @@ -455,7 +453,7 @@ initialization completes, GitLab deploys a second release with the application deployment as normal. Note that a post-install hook means that if any deploy succeeds, -`DB_INITIALIZE` won't be processed thereafter. +`DB_INITIALIZE` isn't processed thereafter. If present, `DB_MIGRATE` is run as a shell command within an application pod as a Helm pre-upgrade hook. @@ -492,7 +490,7 @@ the standard health checks, which expect a successful HTTP response on port the [`sidekiq_alive` gem](https://rubygems.org/gems/sidekiq_alive). To work with Sidekiq, you must also ensure your deployments have -access to a Redis instance. Auto DevOps won't deploy this instance for you, so +access to a Redis instance. Auto DevOps doesn't deploy this instance for you, so you must: - Maintain your own Redis instance. @@ -531,7 +529,7 @@ and accept traffic to and from any source. You can use [NetworkPolicy](https://kubernetes.io/docs/concepts/services-networking/network-policies/) to restrict connections to and from selected pods, namespaces, and the Internet. -NOTE: **Note:** +NOTE: You must use a Kubernetes network plugin that implements support for `NetworkPolicy`. The default network plugin for Kubernetes (`kubenet`) [does not implement](https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/#kubenet) @@ -623,7 +621,7 @@ may require commands to be wrapped as follows: Some of the reasons you may need to wrap commands: - Attaching using `kubectl exec`. -- Using GitLab's [Web Terminal](../../ci/environments/index.md#web-terminals). +- Using the GitLab [Web Terminal](../../ci/environments/index.md#web-terminals). For example, to start a Rails console from the application root directory, run: diff --git a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md index 16536e5b586..c45390e935d 100644 --- a/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md +++ b/doc/topics/autodevops/upgrading_auto_deploy_dependencies.md @@ -1,7 +1,7 @@ --- stage: Release -group: Progressive Delivery -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +group: Release +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments type: reference --- @@ -73,7 +73,9 @@ please proceed with the following upgrade guide. Otherwise, you can skip this pr #### Kubernetes 1.16+ -The v2 auto-deploy-image also drops support for Kubernetes 1.15 and lower. +The v2 auto-deploy-image drops support for Kubernetes 1.15 and lower. If you need to upgrade your +Kubernetes cluster, follow your cloud provider's instructions. Here's +[an example on GKE](https://cloud.google.com/kubernetes-engine/docs/how-to/upgrading-a-cluster). #### Helm 3 @@ -114,6 +116,12 @@ If your Auto DevOps project has an active environment that was deployed with the `kubectl apply -f $backup`. 1. Remove the `MIGRATE_HELM_2TO3` variable. +#### In-Cluster PostgreSQL Channel 2 + +The v2 auto-deploy-image drops support for [legacy in-cluster PostgreSQL](upgrading_postgresql.md). +If your Kubernetes cluster still depends on it, [upgrade and migrate your data](upgrading_postgresql.md) +with the [v1 auto-deploy-image](#use-a-specific-version-of-auto-deploy-dependencies). + #### Traffic routing change for canary deployments and incremental rollouts > [Introduced](https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image/-/merge_requests/109) in GitLab 13.4. @@ -176,7 +184,7 @@ include: - remote: https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.latest.gitlab-ci.yml ``` -CAUTION: **Warning:** +WARNING: Using a beta or unstable `auto-deploy-image` could cause unrecoverable damage to your environments. Do not test it with important projects or environments. diff --git a/doc/topics/autodevops/upgrading_chart.md b/doc/topics/autodevops/upgrading_chart.md index e4fb84d4509..2162969b53e 100644 --- a/doc/topics/autodevops/upgrading_chart.md +++ b/doc/topics/autodevops/upgrading_chart.md @@ -3,3 +3,6 @@ redirect_to: 'upgrading_auto_deploy_dependencies.md' --- This document was moved to [another location](upgrading_auto_deploy_dependencies.md). + +<!-- This redirect file can be deleted after February 1, 2021. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/topics/autodevops/upgrading_postgresql.md b/doc/topics/autodevops/upgrading_postgresql.md index a3c9f562f5e..55432ad61fa 100644 --- a/doc/topics/autodevops/upgrading_postgresql.md +++ b/doc/topics/autodevops/upgrading_postgresql.md @@ -1,7 +1,7 @@ --- 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/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Upgrading PostgreSQL for Auto DevOps @@ -36,7 +36,7 @@ involves: any existing channel 1 database. For more information, see [Detected an existing PostgreSQL database](index.md#detected-an-existing-postgresql-database). -TIP: **Tip:** +NOTE: If you have configured Auto DevOps to have staging, consider trying out the backup and restore steps on staging first, or trying this out on a review app. @@ -79,7 +79,7 @@ being modified after the database dump is created. deployment.extensions/production scaled ``` -1. You also will need to set replicas to zero for workers if you have any. +1. You must also set replicas to zero for workers if you have any. ## Backup @@ -112,7 +112,7 @@ being modified after the database dump is created. - `USERNAME` is the username you have configured for PostgreSQL. The default is `user`. - `DATABASE_NAME` is usually the environment name. - - You will be asked for the database password, the default is `testing-password`. + - When prompted for the database password, the default is `testing-password`. ```shell ## Format is: @@ -168,12 +168,12 @@ pvc-9085e3d3-5239-11ea-9c8d-42010a8e0096 8Gi RWO Retain ## Install new PostgreSQL -CAUTION: **Caution:** -Using the newer version of PostgreSQL will delete +WARNING: +Using the newer version of PostgreSQL deletes the older 0.7.1 PostgreSQL. To prevent the underlying data from being deleted, you can choose to retain the [persistent volume](#retain-persistent-volumes). -TIP: **Tip:** +NOTE: You can also [scope](../../ci/environments/index.md#scoping-environments-with-specs) the `AUTO_DEVOPS_POSTGRES_CHANNEL`, `AUTO_DEVOPS_POSTGRES_DELETE_V1` and @@ -196,9 +196,9 @@ higher*. This is the `XDB_INITIALIZE` or the `XDB_MIGRATE` to effectively disable them. 1. Run a new CI pipeline for the branch. In this case, we run a new CI pipeline for `master`. -1. Once the pipeline is successful, your application will now be upgraded - with the new PostgreSQL installed. There will also be zero replicas - which means no traffic will be served for your application (to prevent +1. After the pipeline is successful, your application is upgraded + with the new PostgreSQL installed. Zero replicas exist at this time, so + no traffic is served for your application (to prevent new data from coming in). ## Restore @@ -226,7 +226,7 @@ higher*. This is the 1. Once connected to the pod, run the following command to restore the database. - - You will be asked for the database password, the default is `testing-password`. + - When asked for the database password, the default is `testing-password`. - `USERNAME` is the username you have configured for PostgreSQL. The default is `user`. - `DATABASE_NAME` is usually the environment name. |