diff options
Diffstat (limited to 'doc/topics/autodevops/stages.md')
| -rw-r--r-- | doc/topics/autodevops/stages.md | 404 |
1 files changed, 216 insertions, 188 deletions
diff --git a/doc/topics/autodevops/stages.md b/doc/topics/autodevops/stages.md index 66b76dcc05a..8c56a87ba30 100644 --- a/doc/topics/autodevops/stages.md +++ b/doc/topics/autodevops/stages.md @@ -1,47 +1,50 @@ # Stages of Auto DevOps -The following sections describe the stages of Auto DevOps. Read them carefully -to understand how each one works. +The following sections describe the stages of [Auto DevOps](index.md). +Read them carefully to understand how each one works. ## Auto Build Auto Build creates a build of the application using an existing `Dockerfile` or -Heroku buildpacks. - -Either way, the resulting Docker image is automatically pushed to the -[Container Registry](../../user/packages/container_registry/index.md) and tagged with the commit SHA or tag. +Heroku buildpacks. The resulting Docker image is pushed to the +[Container Registry](../../user/packages/container_registry/index.md), and tagged +with the commit SHA or tag. ### Auto Build using a Dockerfile -If a project's repository contains a `Dockerfile` at its root, Auto Build will use +If a project's repository contains a `Dockerfile` at its root, Auto Build uses `docker build` to create a Docker image. -If you are also using Auto Review Apps and Auto Deploy and choose to provide -your own `Dockerfile`, make sure you expose your application to port -`5000` as this is the port assumed by the -[default Helm chart](https://gitlab.com/gitlab-org/charts/auto-deploy-app). Alternatively you can override the default values by [customizing the Auto Deploy Helm chart](customize.md#custom-helm-chart) +If you're also using Auto Review Apps and Auto Deploy, and you choose to provide +your own `Dockerfile`, you must either: + +- Expose your application to port `5000`, as the + [default Helm chart](https://gitlab.com/gitlab-org/charts/auto-deploy-app) + assumes this port is available. +- Override the default values by + [customizing the Auto Deploy Helm chart](customize.md#custom-helm-chart). ### Auto Build using Heroku buildpacks -Auto Build builds an application using a project's `Dockerfile` if present, or -otherwise it will use [Herokuish](https://github.com/gliderlabs/herokuish) +Auto Build builds an application using a project's `Dockerfile` if present. If no +`Dockerfile` is present, it uses [Herokuish](https://github.com/gliderlabs/herokuish) and [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) -to automatically detect and build the application into a Docker image. +to detect and build the application into a Docker image. -Each buildpack requires certain files to be in your project's repository for -Auto Build to successfully build your application. For example, the following -files are required at the root of your application's repository, depending on -the language: +Each buildpack requires your project's repository to contain certain files for +Auto Build to build your application successfully. For example, your application's +root directory must contain the appropriate file for your application's +language: -- A `Pipfile` or `requirements.txt` file for Python projects. -- A `Gemfile` or `Gemfile.lock` file for Ruby projects. +- For Python projects, a `Pipfile` or `requirements.txt` file. +- For Ruby projects, a `Gemfile` or `Gemfile.lock` file. For the requirements of other languages and frameworks, read the -[buildpacks docs](https://devcenter.heroku.com/articles/buildpacks#officially-supported-buildpacks). +[Heroku buildpacks documentation](https://devcenter.heroku.com/articles/buildpacks#officially-supported-buildpacks). TIP: **Tip:** If Auto Build fails despite the project meeting the buildpack requirements, set -a project variable `TRACE=true` to enable verbose logging, which may help to +a project variable `TRACE=true` to enable verbose logging, which may help you troubleshoot. ### Auto Build using Cloud Native Buildpacks (beta) @@ -73,13 +76,13 @@ yet part of the Cloud Native Buildpack specification. For more information, see ## Auto Test -Auto Test automatically runs the appropriate tests for your application using -[Herokuish](https://github.com/gliderlabs/herokuish) and [Heroku -buildpacks](https://devcenter.heroku.com/articles/buildpacks) by analyzing +Auto Test runs the appropriate tests for your application using +[Herokuish](https://github.com/gliderlabs/herokuish) and +[Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) by analyzing your project to detect the language and framework. Several languages and frameworks are detected automatically, but if your language is not detected, -you may succeed with a [custom buildpack](customize.md#custom-buildpacks). Check the -[currently supported languages](index.md#currently-supported-languages). +you may be able to create a [custom buildpack](customize.md#custom-buildpacks). +Check the [currently supported languages](index.md#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. @@ -88,12 +91,10 @@ tests, it's up to you to add them. Auto Code Quality uses the [Code Quality image](https://gitlab.com/gitlab-org/ci-cd/codequality) to run -static analysis and other code checks on the current code. The report is -created, and is uploaded as an artifact which you can later download and check -out. - -Any differences between the source and target branches are also -[shown in the merge request widget](../../user/project/merge_requests/code_quality.md). +static analysis and other code checks on the current code. 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 +[differences between the source and target branches](../../user/project/merge_requests/code_quality.md). ## Auto SAST **(ULTIMATE)** @@ -101,14 +102,17 @@ Any differences between the source and target branches are also Static Application Security Testing (SAST) uses the [SAST Docker image](https://gitlab.com/gitlab-org/security-products/sast) to run static -analysis on the current code and checks for potential security issues. The -Auto SAST stage will be skipped on licenses other than Ultimate and requires GitLab Runner 11.5 or above. +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. -Once the report is created, it's uploaded as an artifact which you can later download and -check out. +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. -Any security warnings are also shown in the merge request widget. Read more how -[SAST works](../../user/application_security/sast/index.md). +To learn more about [how SAST works](../../user/application_security/sast/index.md), +see the documentation. ## Auto Dependency Scanning **(ULTIMATE)** @@ -116,16 +120,17 @@ Any security warnings are also shown in the merge request widget. Read more how Dependency Scanning uses the [Dependency Scanning Docker image](https://gitlab.com/gitlab-org/security-products/dependency-scanning) -to run analysis on the project dependencies and checks for potential security issues. -The Auto Dependency Scanning stage will be skipped on licenses other than Ultimate -and requires GitLab Runner 11.5 or above. +to run analysis on the project dependencies and check 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. -Once the -report is created, it's uploaded as an artifact which you can later download and -check out. +After creating the report, it's uploaded as an artifact which you can later download and +check out. The merge request widget displays any security warnings detected, -Any security warnings are also shown in the merge request widget. Read more about -[Dependency Scanning](../../user/application_security/dependency_scanning/index.md). +To learn more about +[Dependency Scanning](../../user/application_security/dependency_scanning/index.md), +see the documentation. ## Auto License Compliance **(ULTIMATE)** @@ -134,60 +139,57 @@ Any security warnings are also shown in the merge request widget. Read more abou License Compliance uses the [License Compliance Docker image](https://gitlab.com/gitlab-org/security-products/license-management) to search the project dependencies for their license. The Auto License Compliance stage -will be skipped on licenses other than Ultimate. +is skipped on licenses other than [Ultimate](https://about.gitlab.com/pricing/). -Once the -report is created, it's uploaded as an artifact which you can later download and -check out. +After creating the report, it's uploaded as an artifact which you can later download and +check out. The merge request displays any detected licenses. -Any licenses are also shown in the merge request widget. Read more how -[License Compliance works](../../user/compliance/license_compliance/index.md). +To learn more about +[License Compliance](../../user/compliance/license_compliance/index.md), see the +documentation. ## Auto Container Scanning **(ULTIMATE)** > Introduced in GitLab 10.4. -Vulnerability Static Analysis for containers uses -[Clair](https://github.com/quay/clair) to run static analysis on a -Docker image and checks for potential security issues. The Auto Container Scanning stage -will be skipped on licenses other than Ultimate. +Vulnerability Static Analysis for containers uses [Clair](https://github.com/quay/clair) +to check for potential security issues on Docker images. The Auto Container Scanning +stage is skipped on licenses other than [Ultimate](https://about.gitlab.com/pricing/). -Once the report is -created, it's uploaded as an artifact which you can later download and -check out. +After creating the report, it's uploaded as an artifact which you can later download and +check out. The merge request displays any detected security issues. -Any security warnings are also shown in the merge request widget. Read more how -[Container Scanning works](../../user/application_security/container_scanning/index.md). +To learn more about +[Container Scanning](../../user/application_security/container_scanning/index.md), +see the documentation. ## Auto Review Apps -This is an optional step, since many projects do not have a Kubernetes cluster -available. If the [requirements](index.md#requirements) are not met, the job will -silently be skipped. +This is an optional step, since many projects don't have a Kubernetes cluster +available. If the [requirements](index.md#requirements) are not met, the job is +silently skipped. [Review Apps](../../ci/review_apps/index.md) are temporary application environments based on the branch's code so developers, designers, QA, product managers, and other reviewers can actually see and interact with code changes as part of the review process. Auto Review Apps create a Review App for each branch. -Auto Review Apps will deploy your app to your Kubernetes cluster only. When no cluster -is available, no deployment will occur. +Auto Review Apps deploy your application to your Kubernetes cluster only. If no cluster +is available, no deployment occurs. -The Review App will have a unique URL based on the project ID, the branch or tag -name, and a unique number, combined with the Auto DevOps base domain. For -example, `13083-review-project-branch-123456.example.com`. A link to the Review App shows -up in the merge request widget for easy discovery. When the branch or tag is deleted, -for example after the merge request is merged, the Review App will automatically -be deleted. +The Review App has a unique URL based on a combination of the project ID, the branch +or tag name, a unique number, and the Auto DevOps base domain, such as +`13083-review-project-branch-123456.example.com`. The merge request widget displays +a link to the Review App for easy discovery. When the branch or tag is deleted, +such as after merging a merge request, the Review App is also deleted. Review apps are deployed using the [auto-deploy-app](https://gitlab.com/gitlab-org/charts/auto-deploy-app) chart with -Helm, which can be [customized](customize.md#custom-helm-chart). The app will be deployed into the [Kubernetes -namespace](../../user/project/clusters/index.md#deployment-variables) +Helm, which you can [customize](customize.md#custom-helm-chart). The application deploys +into the [Kubernetes namespace](../../user/project/clusters/index.md#deployment-variables) for the environment. -Since GitLab 11.4, a [local -Tiller](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22036) is +Since GitLab 11.4, [local Tiller](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22036) is used. Previous versions of GitLab had a Tiller installed in the project namespace. @@ -196,52 +198,64 @@ 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 and want to undo it by deploying again, Helm may not detect that anything changed -in the first place, and thus not realize that it needs to re-apply the old config. +in the first place, and thus not realize that it needs to re-apply the old configuration. ## Auto DAST **(ULTIMATE)** > Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.4. -Dynamic Application Security Testing (DAST) uses the -popular open source tool [OWASP ZAProxy](https://github.com/zaproxy/zaproxy) -to perform an analysis on the current code and checks for potential security -issues. The Auto DAST stage will be skipped on licenses other than Ultimate. +Dynamic Application Security Testing (DAST) uses the popular open source tool +[OWASP ZAProxy](https://github.com/zaproxy/zaproxy) to analyze the current code +and check for potential security issues. The Auto DAST stage is skipped on +licenses other than [Ultimate](https://about.gitlab.com/pricing/). -Once the DAST scan is complete, any security warnings are shown -on the [Security Dashboard](../../user/application_security/security_dashboard/index.md) -and the Merge Request Widget. Read how -[DAST works](../../user/application_security/dast/index.md). +- On your default branch, DAST scans an application deployed specifically for that purpose + unless you [override the target branch](#overriding-the-dast-target). + The app is deleted after DAST has run. +- On feature branches, DAST scans the [review app](#auto-review-apps). -On your default branch, DAST scans an app deployed specifically for that purpose. -The app is deleted after DAST has run. +After the DAST scan completes, any security warnings are displayed +on the [Security Dashboard](../../user/application_security/security_dashboard/index.md) +and the merge request widget. -On feature branches, DAST scans the [review app](#auto-review-apps). +To learn more about +[Dynamic Application Security Testing](../../user/application_security/dast/index.md), +see the documentation. ### Overriding the DAST target 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. -NOTE: **Note:** -If [DAST Full Scan](../../user/application_security/dast/index.md#full-scan) is enabled, it is strongly advised **not** +DANGER: **Danger:** +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 -actively attacks the target, which can take down the application and lead to +actively attacks the target, which can take down your application and lead to data loss or corruption. ### Disabling Auto DAST -DAST can be disabled: +You can disable DAST: - On all branches by setting the `DAST_DISABLED` environment variable to `"true"`. -- Only on the default branch by setting the `DAST_DISABLED_FOR_DEFAULT_BRANCH` environment variable to `"true"`. +- Only on the default branch by setting the `DAST_DISABLED_FOR_DEFAULT_BRANCH` + environment variable to `"true"`. +- Only on feature branches by setting `REVIEW_DISABLED` environment variable to + `"true"`. This also disables the Review App. ## Auto Browser Performance Testing **(PREMIUM)** > Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 10.4. -Auto Browser Performance Testing utilizes the [Sitespeed.io container](https://hub.docker.com/r/sitespeedio/sitespeed.io/) to measure the performance of a web page. A JSON report is created and uploaded as an artifact, which includes the overall performance score for each page. By default, the root page of Review and Production environments will be tested. If you would like to add additional URL's to test, simply add the paths to a file named `.gitlab-urls.txt` in the root directory, one per line. For example: +Auto Browser Performance Testing measures the performance of a web page with the +[Sitespeed.io container](https://hub.docker.com/r/sitespeedio/sitespeed.io/), +creates a JSON report including the overall performance score for each page, and +uploads the report as an artifact. By default, it tests the root page of your Review and +Production environments. If you want to test additional URLs, add the paths to a +file named `.gitlab-urls.txt` in the root directory, one file per line. For example: -```text +```plaintext / /features /direction @@ -252,30 +266,31 @@ Any performance differences between the source and target branches are also ## Auto Deploy -This is an optional step, since many projects do not have a Kubernetes cluster -available. If the [requirements](index.md#requirements) are not met, the job will -silently be skipped. +This is an optional step, since many projects don't have a Kubernetes cluster +available. If the [requirements](index.md#requirements) are not met, the job is skipped. After a branch or merge request is merged into the project's default branch (usually `master`), Auto Deploy deploys the application to a `production` environment in the Kubernetes cluster, with a namespace based on the project name and unique -project ID, for example `project-4321`. +project ID, such as `project-4321`. -Auto Deploy doesn't include deployments to staging or canary by 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. +Auto Deploy does not include deployments to staging or canary environments by +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 make use of [environment variables](customize.md#environment-variables) 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). +You can use [environment variables](customize.md#environment-variables) 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). -Apps are deployed using the -[auto-deploy-app](https://gitlab.com/gitlab-org/charts/auto-deploy-app) chart with -Helm. The app will be deployed into the [Kubernetes -namespace](../../user/project/clusters/index.md#deployment-variables) +Helm uses the [auto-deploy-app](https://gitlab.com/gitlab-org/charts/auto-deploy-app) +chart to deploy the application into the +[Kubernetes namespace](../../user/project/clusters/index.md#deployment-variables) for the environment. -Since GitLab 11.4, a [local -Tiller](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22036) is +Since GitLab 11.4, a +[local Tiller](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22036) is used. Previous versions of GitLab had a Tiller installed in the project namespace. @@ -284,76 +299,85 @@ 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 and want to undo it by deploying again, Helm may not detect that anything changed -in the first place, and thus not realize that it needs to re-apply the old config. +in the first place, and thus not realize that it needs to re-apply the old configuration. + +### GitLab deploy tokens > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/19507) in GitLab 11.0. -For internal and private projects a [GitLab Deploy Token](../../user/project/deploy_tokens/index.md#gitlab-deploy-token) -will be automatically created, when Auto DevOps is enabled and the Auto DevOps settings are saved. This Deploy Token -can be used for permanent access to the registry. When the GitLab Deploy Token has been manually revoked, it won't be automatically created. +[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 +automatically created. + +If the GitLab Deploy Token can't be found, `CI_REGISTRY_PASSWORD` is +used. -If the GitLab Deploy Token cannot be found, `CI_REGISTRY_PASSWORD` is -used. Note that `CI_REGISTRY_PASSWORD` is only valid during deployment. -This means that Kubernetes will be able to successfully pull the -container image during deployment but in cases where the image needs to -be pulled again, e.g. after pod eviction, Kubernetes will fail to do so -as it will be attempting to fetch the image using -`CI_REGISTRY_PASSWORD`. +NOTE: **Note:** +`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 +as it attempts to fetch the image using `CI_REGISTRY_PASSWORD`. ### Kubernetes 1.16+ > - [Introduced](https://gitlab.com/gitlab-org/charts/auto-deploy-app/-/merge_requests/51) in GitLab 12.8. > - 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** -The default value of `extensions/v1beta1` for the `deploymentApiVersion` setting is -deprecated, and is scheduled to be changed to a new default of `apps/v1` in -[GitLab 13.0](https://gitlab.com/gitlab-org/charts/auto-deploy-app/issues/47). +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). -In Kubernetes 1.16 onwards, a number of [APIs were removed](https://kubernetes.io/blog/2019/07/18/api-deprecations-in-1-16/), +In Kubernetes 1.16 and later, a number of +[APIs were removed](https://kubernetes.io/blog/2019/07/18/api-deprecations-in-1-16/), including support for `Deployment` in the `extensions/v1beta1` version. -To use Auto Deploy on a Kubernetes 1.16+ cluster, you must: +To use Auto Deploy on a Kubernetes 1.16+ cluster: -1. Set the following in the [`.gitlab/auto-deploy-values.yaml` file](customize.md#customize-values-for-helm-chart): +1. If you are deploying your application for the first time on GitLab 13.0 or + newer, no configuration should be required. - ```yml +1. On GitLab 12.10 or older, set the following in the [`.gitlab/auto-deploy-values.yaml` file](customize.md#customize-values-for-helm-chart): + + ```yaml deploymentApiVersion: apps/v1 ``` -1. Set the: - - - `AUTO_DEVOPS_POSTGRES_CHANNEL` variable to `2`. - - `POSTGRES_VERSION` variable to `9.6.16` or higher. +1. If you have an in-cluster PostgreSQL database installed with + `AUTO_DEVOPS_POSTGRES_CHANNEL` set to `1`, follow the [guide to upgrade + PostgreSQL](upgrading_postgresql.md). - This will opt-in to using a version of the PostgreSQL chart that supports Kubernetes - 1.16 and higher. +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: **Danger:** Opting into `AUTO_DEVOPS_POSTGRES_CHANNEL` version -`2` will delete the version `1` PostgreSQL database. Please follow the -guide on [upgrading PostgreSQL](upgrading_postgresql.md) to backup and -restore your database before opting into version `2`. +DANGER: **Danger:** 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) +to back up and restore your database before opting into version `2` (On +GitLab 13.0, an additional variable is required to trigger the database +deletion). ### Migrations > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/21955) in GitLab 11.4 -Database initialization and migrations for PostgreSQL can be configured to run +You can configure database initialization and migrations for PostgreSQL to run within the application pod by setting the project variables `DB_INITIALIZE` and `DB_MIGRATE` respectively. -If present, `DB_INITIALIZE` will be run as a shell command within an -application pod as a Helm post-install hook. As some applications will -not run without a successful database initialization step, GitLab will -deploy the first release without the application deployment and only the -database initialization step. After the database initialization completes, -GitLab will deploy a second release with the application deployment as -normal. +If present, `DB_INITIALIZE` is run as a shell command within an application pod +as a Helm post-install hook. As some applications can't run without a successful +database initialization step, GitLab deploys the first release without the +application deployment, and only the database initialization step. After the database +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` will not be processed thereafter. +`DB_INITIALIZE` won't be processed thereafter. -If present, `DB_MIGRATE` will be run as a shell command within an application pod as +If present, `DB_MIGRATE` is run as a shell command within an application pod as a Helm pre-upgrade hook. For example, in a Rails application in an image built with @@ -362,38 +386,39 @@ For example, in a Rails application in an image built with - `DB_INITIALIZE` can be set to `RAILS_ENV=production /bin/herokuish procfile exec bin/rails db:setup` - `DB_MIGRATE` can be set to `RAILS_ENV=production /bin/herokuish procfile exec bin/rails db:migrate` -Unless you have a `Dockerfile` in your repo, your image is built with -Herokuish, and you must prefix commands run in these images with `/bin/herokuish -procfile exec` to replicate the environment where your application will run. +Unless your repository contains a `Dockerfile`, your image is built with +Herokuish, and you must prefix commands run in these images with +`/bin/herokuish procfile exec` to replicate the environment where your application +will run. ### Workers -Some web applications need to run extra deployments for "worker processes". For -example, it is common in a Rails application to have a separate worker process +Some web applications must run extra deployments for "worker processes". For +example, Rails applications commonly use separate worker processes to run background tasks like sending emails. The [default Helm chart](https://gitlab.com/gitlab-org/charts/auto-deploy-app) -used in Auto Deploy [has support for running worker -processes](https://gitlab.com/gitlab-org/charts/auto-deploy-app/-/merge_requests/9). +used in Auto Deploy +[has support for running worker processes](https://gitlab.com/gitlab-org/charts/auto-deploy-app/-/merge_requests/9). -In order to run a worker, you'll need to ensure that it is able to respond to +To run a worker, you must ensure the worker can respond to the standard health checks, which expect a successful HTTP response on port -`5000`. For [Sidekiq](https://github.com/mperham/sidekiq), you could make use of -the [`sidekiq_alive` gem](https://rubygems.org/gems/sidekiq_alive) to do this. +`5000`. For [Sidekiq](https://github.com/mperham/sidekiq), you can use +the [`sidekiq_alive` gem](https://rubygems.org/gems/sidekiq_alive). -In order to work with Sidekiq, you'll also need to ensure your deployments have -access to a Redis instance. Auto DevOps won't deploy this for you so you'll -need to: +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 +you must: - Maintain your own Redis instance. -- Set a CI variable `K8S_SECRET_REDIS_URL`, which the URL of this instance to - ensure it's passed into your deployments. +- Set a CI variable `K8S_SECRET_REDIS_URL`, which is the URL of this instance, + to ensure it's passed into your deployments. -Once you have configured your worker to respond to health checks, run a Sidekiq +After configuring your worker to respond to health checks, run a Sidekiq worker for your Rails application. You can enable workers by setting the following in the [`.gitlab/auto-deploy-values.yaml` file](customize.md#customize-values-for-helm-chart): -```yml +```yaml workers: sidekiq: replicaCount: 1 @@ -417,7 +442,7 @@ workers: By default, all Kubernetes pods are [non-isolated](https://kubernetes.io/docs/concepts/services-networking/network-policies/#isolated-and-non-isolated-pods), -meaning that they will accept traffic to and from any source. You can use +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. @@ -437,13 +462,13 @@ networkPolicy: enabled: true ``` -The default policy deployed by the auto deploy pipeline will allow -traffic within a local namespace and from the `gitlab-managed-apps` -namespace. All other inbound connection will be blocked. Outbound +The default policy deployed by the Auto Deploy pipeline allows +traffic within a local namespace, and from the `gitlab-managed-apps` +namespace. All other inbound connections are blocked. Outbound traffic (for example, to the Internet) is not affected by the default policy. You can also provide a custom [policy specification](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.16/#networkpolicyspec-v1-networking-k8s-io) -via the `.gitlab/auto-deploy-values.yaml` file, for example: +in the `.gitlab/auto-deploy-values.yaml` file, for example: ```yaml networkPolicy: @@ -461,16 +486,19 @@ networkPolicy: app.gitlab.com/managed_by: gitlab ``` -For more information on how to install Network Policies, see +For more information on installing Network Policies, see [Install Cilium using GitLab CI/CD](../../user/clusters/applications.md#install-cilium-using-gitlab-cicd). ### Web Application Firewall (ModSecurity) customization > [Introduced](https://gitlab.com/gitlab-org/charts/auto-deploy-app/-/merge_requests/44) in GitLab 12.8. -Customization on an [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) or on a deployment base is available for clusters with [ModSecurity installed](../../user/clusters/applications.md#web-application-firewall-modsecurity). +Customization on an [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) +or on a deployment base is available for clusters with +[ModSecurity installed](../../user/clusters/applications.md#web-application-firewall-modsecurity). -To enable ModSecurity with Auto Deploy, you need to create a `.gitlab/auto-deploy-values.yaml` file in your project with the following attributes. +To enable ModSecurity with Auto Deploy, you must create a `.gitlab/auto-deploy-values.yaml` +file in your project with the following attributes. |Attribute | Description | Default | -----------|-------------|---------| @@ -481,7 +509,7 @@ To enable ModSecurity with Auto Deploy, you need to create a `.gitlab/auto-deplo In the following `auto-deploy-values.yaml` example, some custom settings are enabled for ModSecurity. Those include setting its engine to process rules instead of only logging them, while adding two specific -rules which are header-based: +header-based rules: ```yaml ingress: @@ -500,17 +528,17 @@ ingress: ### Running commands in the container Applications built with [Auto Build](#auto-build) using Herokuish, the default -unless you have [a custom Dockerfile](#auto-build-using-a-dockerfile), may require -commands to be wrapped as follows: +unless your repository contains [a custom Dockerfile](#auto-build-using-a-dockerfile), +may require commands to be wrapped as follows: ```shell /bin/herokuish procfile exec $COMMAND ``` -This might be necessary, for example, when: +Some of the reasons you may need to wrap commands: - Attaching using `kubectl exec`. -- Using GitLab's [Web Terminal](../../ci/environments.md#web-terminals). +- Using GitLab's [Web Terminal](../../ci/environments/index.md#web-terminals). For example, to start a Rails console from the application root directory, run: @@ -520,12 +548,12 @@ For example, to start a Rails console from the application root directory, run: ## Auto Monitoring -Once your application is deployed, Auto Monitoring makes it possible to monitor +After your application deploys, Auto Monitoring helps you monitor your application's server and response metrics right out of the box. Auto Monitoring uses [Prometheus](../../user/project/integrations/prometheus.md) to -get system metrics such as CPU and memory usage directly from +retrieve system metrics, such as CPU and memory usage, directly from [Kubernetes](../../user/project/integrations/prometheus_library/kubernetes.md), -and response metrics such as HTTP error rates, latency, and throughput from the +and response metrics, such as HTTP error rates, latency, and throughput, from the [NGINX server](../../user/project/integrations/prometheus_library/nginx_ingress.md). The metrics include: @@ -538,14 +566,14 @@ GitLab provides some initial alerts for you after you install Prometheus: - Ingress status code `500` > 0.1% - NGINX status code `500` > 0.1% -To make use of Auto Monitoring: +To use Auto Monitoring: 1. [Install and configure the requirements](index.md#requirements). -1. [Enable Auto DevOps](index.md#enablingdisabling-auto-devops) if you haven't done already. -1. Finally, go to your project's **CI/CD > Pipelines** and run a pipeline. -1. Once the pipeline finishes successfully, open the - [monitoring dashboard for a deployed environment](../../ci/environments.md#monitoring-environments) +1. [Enable Auto DevOps](index.md#enablingdisabling-auto-devops), if you haven't done already. +1. Navigate to your project's **{rocket}** **CI/CD > Pipelines** and click **Run Pipeline**. +1. After the pipeline finishes successfully, open the + [monitoring dashboard for a deployed environment](../../ci/environments/index.md#monitoring-environments) to view the metrics of your deployed application. To view the metrics of the - whole Kubernetes cluster, navigate to **Operations > Metrics**. + whole Kubernetes cluster, navigate to **{cloud-gear}** **Operations > Metrics**.  |