diff options
Diffstat (limited to 'doc/ci/environments')
-rw-r--r-- | doc/ci/environments/deployment_safety.md | 6 | ||||
-rw-r--r-- | doc/ci/environments/index.md | 78 | ||||
-rw-r--r-- | doc/ci/environments/protected_environments.md | 2 |
3 files changed, 55 insertions, 31 deletions
diff --git a/doc/ci/environments/deployment_safety.md b/doc/ci/environments/deployment_safety.md index 055baa78743..a4ff164a5ba 100644 --- a/doc/ci/environments/deployment_safety.md +++ b/doc/ci/environments/deployment_safety.md @@ -7,7 +7,7 @@ that help maintain deployment security and stability. You can: - [Restrict write-access to a critical environment](#restrict-write-access-to-a-critical-environment) -- [Restrict deployments for a particular period](#restrict-deployments-for-a-particular-period) +- [Prevent deployments during deploy freeze windows](#prevent-deployments-during-deploy-freeze-windows) If you are using a continuous deployment workflow and want to ensure that concurrent deployments to the same environment do not happen, you should enable the following options: @@ -77,10 +77,10 @@ The improved pipeline flow **after** enabling Skip outdated deployment jobs: 1. The `deploy` job in Pipeline-B finishes first, and deploys the newer code. 1. The `deploy` job in Pipeline-A is automatically cancelled, so that it doesn't overwrite the deployment from the newer pipeline. -## Restrict deployments for a particular period +## Prevent deployments during deploy freeze windows If you want to prevent deployments for a particular period, for example during a planned -vacation period when most employees are out, you can set up a [Deploy Freeze](../../user/project/releases/index.md#set-a-deploy-freeze). +vacation period when most employees are out, you can set up a [Deploy Freeze](../../user/project/releases/index.md#prevent-unintentional-releases-by-setting-a-deploy-freeze). During a deploy freeze period, no deployment can be executed. This is helpful to ensure that deployments do not happen unexpectedly. diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md index 84480b836f8..0273ab290a6 100644 --- a/doc/ci/environments/index.md +++ b/doc/ci/environments/index.md @@ -94,7 +94,7 @@ deploy_staging: name: staging url: https://staging.example.com only: - - master + - master ``` We have defined three [stages](../yaml/README.md#stages): @@ -124,7 +124,7 @@ The environment `name` and `url` is exposed in various places within GitLab. Each time a job that has an environment specified succeeds, a deployment is recorded, along with the Git SHA, and environment name. -CAUTION: **Caution**: +CAUTION: **Caution:** Some characters are not allowed in environment names. Use only letters, numbers, spaces, and `-`, `_`, `/`, `{`, `}`, or `.`. Also, it must not start nor end with `/`. @@ -173,8 +173,8 @@ If you want to use the environment URL in GitLab, you would have to update it ma To address this problem, you can configure a deployment job to report back a set of variables, including the URL that was dynamically-generated by the external service. -GitLab supports [dotenv](https://github.com/bkeepers/dotenv) file as the format, -and expands the `environment:url` value with variables defined in the dotenv file. +GitLab supports the [dotenv (`.env`)](https://github.com/bkeepers/dotenv) file format, +and expands the `environment:url` value with variables defined in the `.env` file. To use this feature, specify the [`artifacts:reports:dotenv`](../pipelines/job_artifacts.md#artifactsreportsdotenv) keyword in `.gitlab-ci.yml`. @@ -213,14 +213,13 @@ stop_review: As soon as the `review` job finishes, GitLab updates the `review/your-branch-name` environment's URL. -It parses the report artifact `deploy.env`, registers a list of variables as runtime-created, +It parses the `deploy.env` report artifact, registers a list of variables as runtime-created, uses it for expanding `environment:url: $DYNAMIC_ENVIRONMENT_URL` and sets it to the environment URL. You can also specify a static part of the URL at `environment:url:`, such as `https://$DYNAMIC_ENVIRONMENT_URL`. If the value of `DYNAMIC_ENVIRONMENT_URL` is -`123.awesome.com`, the final result will be `https://123.awesome.com`. +`example.com`, the final result will be `https://example.com`. -The assigned URL for the `review/your-branch-name` environment is visible in the UI. -[See where the environment URL is displayed](#using-the-environment-url). +The assigned URL for the `review/your-branch-name` environment is [visible in the UI](#using-the-environment-url). > **Notes:** > @@ -260,7 +259,7 @@ deploy_staging: name: staging url: https://staging.example.com only: - - master + - master deploy_prod: stage: deploy @@ -271,7 +270,7 @@ deploy_prod: url: https://example.com when: manual only: - - master + - master ``` The `when: manual` action: @@ -306,11 +305,6 @@ declaring their names dynamically in `.gitlab-ci.yml`. Dynamic environments are a fundamental part of [Review apps](../review_apps/index.md). -### Configuring incremental rollouts - -Learn how to release production changes to only a portion of your Kubernetes pods with -[incremental rollouts](../environments/incremental_rollouts.md). - #### Allowed variables The `name` and `url` parameters for dynamic environments can use most available CI/CD variables, @@ -408,7 +402,7 @@ deploy: kubernetes: namespace: production only: - - master + - master ``` When deploying to a Kubernetes cluster using GitLab's Kubernetes integration, @@ -423,6 +417,11 @@ that are [managed by GitLab](../../user/project/clusters/index.md#gitlab-managed To follow progress on support for GitLab-managed clusters, see the [relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/38054). +#### Configuring incremental rollouts + +Learn how to release production changes to only a portion of your Kubernetes pods with +[incremental rollouts](../environments/incremental_rollouts.md). + ### Deployment safety Deployment jobs can be more sensitive than other jobs in a pipeline, @@ -432,7 +431,7 @@ in GitLab that helps maintain deployment security and stability. - [Restrict write-access to a critical environment](deployment_safety.md#restrict-write-access-to-a-critical-environment) - [Limit the job-concurrency for deployment jobs](deployment_safety.md#ensure-only-one-deployment-job-runs-at-a-time) - [Skip outdated deployment jobs](deployment_safety.md#skip-outdated-deployment-jobs) -- [Restrict deployments for a particular period](deployment_safety.md#restrict-deployments-for-a-particular-period) +- [Prevent deployments during deploy freeze windows](deployment_safety.md#prevent-deployments-during-deploy-freeze-windows) ### Complete example @@ -484,7 +483,7 @@ deploy_staging: name: staging url: https://staging.example.com only: - - master + - master deploy_prod: stage: deploy @@ -495,7 +494,7 @@ deploy_prod: url: https://example.com when: manual only: - - master + - master ``` A more realistic example would also include copying files to a location where a @@ -740,6 +739,12 @@ To enable this feature, you need to specify the [`environment:auto_stop_in`](../ You can specify a human-friendly date as the value, such as `1 hour and 30 minutes` or `1 day`. `auto_stop_in` uses the same format of [`artifacts:expire_in` docs](../yaml/README.md#artifactsexpire_in). +NOTE: **Note:** +Due to the resource limitation, a background worker for stopping environments only +runs once every hour. This means environments will not be stopped at the exact +timestamp as the specified period, but will be stopped when the hourly cron worker +detects expired environments. + ##### Auto-stop example In the following example, there is a basic review app setup that creates a new environment @@ -779,15 +784,9 @@ and the environment will be active until it's stopped manually. ![Environment auto stop](../img/environment_auto_stop_v12_8.png) -NOTE: **NOTE** -Due to the resource limitation, a background worker for stopping environments only -runs once every hour. This means environments will not be stopped at the exact -timestamp as the specified period, but will be stopped when the hourly cron worker -detects expired environments. - #### Delete a stopped environment -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22629) in GitLab 12.9. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20620) in GitLab 12.10. You can delete [stopped environments](#stopping-an-environment) in one of two ways: through the GitLab UI or through the API. @@ -812,6 +811,31 @@ stopped environment: Environments can also be deleted by using the [Environments API](../../api/environments.md#delete-an-environment). +### Prepare an environment + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208655) in GitLab 13.2. + +By default, GitLab creates a [deployment](#viewing-deployment-history) every time a +build with the specified environment runs. Newer deployments can also +[cancel older ones](deployment_safety.md#skip-outdated-deployment-jobs). + +You may want to specify an environment keyword to +[protect builds from unauthorized access](protected_environments.md), or to get +access to [scoped variables](#scoping-environments-with-specs). In these cases, +you can use the `action: prepare` keyword to ensure deployments won't be created, +and no builds would be canceled: + +```yaml +build: + stage: build + script: + - echo "Building the app" + environment: + name: staging + action: prepare + url: https://staging.example.com +``` + ### Grouping similar environments > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7015) in GitLab 8.14. @@ -868,7 +892,7 @@ versions of the app, all without leaving GitLab. #### Embedding metrics in GitLab Flavored Markdown -Metric charts can be embedded within GitLab Flavored Markdown. See [Embedding Metrics within GitLab Flavored Markdown](../../user/project/integrations/prometheus.md#embedding-metric-charts-within-gitlab-flavored-markdown) for more details. +Metric charts can be embedded within GitLab Flavored Markdown. See [Embedding Metrics within GitLab Flavored Markdown](../../operations/metrics/embed.md) for more details. ### Web terminals diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md index 3a44fcfb182..b6141ddc7ac 100644 --- a/doc/ci/environments/protected_environments.md +++ b/doc/ci/environments/protected_environments.md @@ -22,7 +22,7 @@ specific environments are "protected" to prevent unauthorized people from affect By default, a protected environment does one thing: it ensures that only people with the right privileges can deploy to it, thus keeping it safe. -NOTE: **Note**: +NOTE: **Note:** A GitLab admin is always allowed to use environments, even if they are protected. To protect, update, or unprotect an environment, you need to have at least |