diff options
Diffstat (limited to 'doc/ci/environments/index.md')
| -rw-r--r-- | doc/ci/environments/index.md | 307 |
1 files changed, 113 insertions, 194 deletions
diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md index f4d155369e9..f2fb8eaa27e 100644 --- a/doc/ci/environments/index.md +++ b/doc/ci/environments/index.md @@ -51,8 +51,8 @@ Deployments show up in this list only after a deployment job has created them. To search environments by name: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Deployments > Environments**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Operate > Environments**. 1. In the search bar, enter your search term. - The length of your **search term should be 3 or more characters**. - Matching applies from the beginning of the environment name. @@ -61,6 +61,12 @@ To search environments by name: - For example when the name is `review/test-app`, search term `test` matches `review/test-app`. - Also searching with the folder name prefixed like `review/test` matches `review/test-app`. +## CI/CD variables + +To customize your environments and deployments, you can use any of the +[predefined CI/CD variables](../../ci/variables/predefined_variables.md), +and define custom CI/CD variables. + ## Types of environments An environment is either static or dynamic: @@ -87,9 +93,9 @@ Prerequisites: To create a static environment in the UI: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Deployments > Environments**. -1. Select **New environment**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Operate > Environments**. +1. Select **Create an environment**. 1. Complete the fields. 1. Select **Save**. @@ -123,7 +129,8 @@ deploy_staging: ### Create a dynamic environment -To create a dynamic environment, you use [CI/CD variables](../variables/index.md) that are unique to each pipeline. +To create a dynamic environment, you use [CI/CD variables](#cicd-variables) that are +unique to each pipeline. Prerequisites: @@ -158,6 +165,79 @@ deploy_review_app: - main ``` +#### Set a dynamic environment URL + +Some external hosting platforms generate a random URL for each deployment, for example: +`https://94dd65b.amazonaws.com/qa-lambda-1234567`. That makes it difficult to reference the URL in +the `.gitlab-ci.yml` file. + +To address this problem, you can configure a deployment job to report back a set of +variables. These variables include the URL that was dynamically generated by the external service. +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`](../yaml/artifacts_reports.md#artifactsreportsdotenv) keyword in `.gitlab-ci.yml`. + +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 `example.com`, the +final result is `https://example.com`. + +The assigned URL for the `review/your-branch-name` environment is visible in the UI. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> +For an overview, see [Set dynamic URLs after a job finished](https://youtu.be/70jDXtOf4Ig). + +In the following example a review app creates a new environment for each merge request: + +- The `review` job is triggered by every push, and creates or updates an environment named + `review/your-branch-name`. The environment URL is set to `$DYNAMIC_ENVIRONMENT_URL`. +- When the `review` job finishes, GitLab updates the `review/your-branch-name` environment's URL. + It parses the `deploy.env` report artifact, registers a list of variables as runtime-created, + expands the `environment:url: $DYNAMIC_ENVIRONMENT_URL` and sets it to the environment + URL. + +```yaml +review: + script: + - DYNAMIC_ENVIRONMENT_URL=$(deploy-script) # In script, get the environment URL. + - echo "DYNAMIC_ENVIRONMENT_URL=$DYNAMIC_ENVIRONMENT_URL" >> deploy.env # Add the value to a dotenv file. + artifacts: + reports: + dotenv: deploy.env # Report back dotenv file to rails. + environment: + name: review/$CI_COMMIT_REF_SLUG + url: $DYNAMIC_ENVIRONMENT_URL # and set the variable produced in script to `environment:url` + on_stop: stop_review + +stop_review: + script: + - ./teardown-environment + when: manual + environment: + name: review/$CI_COMMIT_REF_SLUG + action: stop +``` + +Note the following: + +- `stop_review` doesn't generate a dotenv report artifact, so it doesn't recognize the + `DYNAMIC_ENVIRONMENT_URL` environment variable. Therefore you shouldn't set `environment:url` in the + `stop_review` job. +- If the environment URL isn't valid (for example, the URL is malformed), the system doesn't update + the environment URL. +- If the script that runs in `stop_review` exists only in your repository and therefore can't use + `GIT_STRATEGY: none`, configure [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md) + for these jobs. This ensures that runners can fetch the repository even after a feature branch is + deleted. For more information, see [Ref Specs for Runners](../pipelines/index.md#ref-specs-for-runners). + +NOTE: +For Windows runners, you should use the PowerShell `Add-Content` command to write to `.env` files. + +```powershell +Add-Content -Path deploy.env -Value "DYNAMIC_ENVIRONMENT_URL=$DYNAMIC_ENVIRONMENT_URL" +``` + ### Rename an environment > - Renaming an environment by using the UI was [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68550) in GitLab 14.3. @@ -220,153 +300,6 @@ The `when: manual` action: You can find the play button in the pipelines, environments, deployments, and jobs views. -## Configure Kubernetes deployments (deprecated) - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27630) in GitLab 12.6. -> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. - -WARNING: -This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. - -If you are deploying to a [Kubernetes cluster](../../user/infrastructure/clusters/index.md) -associated with your project, you can configure these deployments from your -`.gitlab-ci.yml` file. - -NOTE: -Kubernetes configuration isn't supported for Kubernetes clusters -[managed by GitLab](../../user/project/clusters/gitlab_managed_clusters.md). - -The following configuration options are supported: - -- [`namespace`](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) - -In the following example, the job deploys your application to the -`production` Kubernetes namespace. - -```yaml -deploy: - stage: deploy - script: - - echo "Deploy to production server" - environment: - name: production - url: https://example.com - kubernetes: - namespace: production - rules: - - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH -``` - -When you use the GitLab Kubernetes integration to deploy to a Kubernetes cluster, -you can view cluster and namespace information. On the deployment -job page, it's displayed above the job trace: - - - -### Configure incremental rollouts - -Learn how to release production changes to only a portion of your Kubernetes pods with -[incremental rollouts](../environments/incremental_rollouts.md). - -## CI/CD variables for environments and deployments - -When you create an environment, you specify the name and URL. - -If you want to use the name or URL in another job, you can use: - -- `$CI_ENVIRONMENT_NAME`. The name defined in the `.gitlab-ci.yml` file. -- `$CI_ENVIRONMENT_SLUG`. A "cleaned-up" version of the name, suitable for use in URL and DNS, for example. - This variable is guaranteed to be unique. -- `$CI_ENVIRONMENT_URL`. The environment's URL, which was specified in the - `.gitlab-ci.yml` file or automatically assigned. - -If you change the name of an existing environment, the: - -- `$CI_ENVIRONMENT_NAME` variable is updated with the new environment name. -- `$CI_ENVIRONMENT_SLUG` variable remains unchanged to prevent unintended side - effects. - -## Set dynamic environment URLs after a job finishes - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17066) in GitLab 12.9. - -In a job script, you can specify a static environment URL. -However, there may be times when you want a dynamic URL. For example, -if you deploy a Review App to an external hosting -service that generates a random URL per deployment, like `https://94dd65b.amazonaws.com/qa-lambda-1234567`. -In this case, you don't know the URL before the deployment script finishes. -If you want to use the environment URL in GitLab, you would have to update it manually. - -To address this problem, you can configure a deployment job to report back a set of -variables. These variables include the URL that was dynamically-generated by the external service. -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`](../yaml/artifacts_reports.md#artifactsreportsdotenv) keyword in `.gitlab-ci.yml`. - -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see [Set dynamic URLs after a job finished](https://youtu.be/70jDXtOf4Ig). - -### Example of setting dynamic environment URLs - -The following example shows a Review App that creates a new environment -for each merge request. The `review` job is triggered by every push, and -creates or updates an environment named `review/your-branch-name`. -The environment URL is set to `$DYNAMIC_ENVIRONMENT_URL`: - -```yaml -review: - script: - - DYNAMIC_ENVIRONMENT_URL=$(deploy-script) # In script, get the environment URL. - - echo "DYNAMIC_ENVIRONMENT_URL=$DYNAMIC_ENVIRONMENT_URL" >> deploy.env # Add the value to a dotenv file. - artifacts: - reports: - dotenv: deploy.env # Report back dotenv file to rails. - environment: - name: review/$CI_COMMIT_REF_SLUG - url: $DYNAMIC_ENVIRONMENT_URL # and set the variable produced in script to `environment:url` - on_stop: stop_review - -stop_review: - script: - - ./teardown-environment - when: manual - environment: - name: review/$CI_COMMIT_REF_SLUG - action: stop -``` - -As soon as the `review` job finishes, GitLab updates the `review/your-branch-name` -environment's URL. -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 -`example.com`, the final result is `https://example.com`. - -The assigned URL for the `review/your-branch-name` environment is visible in the UI. - -Note the following: - -- `stop_review` doesn't generate a dotenv report artifact, so it doesn't recognize the - `DYNAMIC_ENVIRONMENT_URL` environment variable. Therefore you shouldn't set `environment:url` in the - `stop_review` job. -- If the environment URL isn't valid (for example, the URL is malformed), the system doesn't update - the environment URL. -- If the script that runs in `stop_review` exists only in your repository and therefore can't use - `GIT_STRATEGY: none`, configure [merge request pipelines](../../ci/pipelines/merge_request_pipelines.md) - for these jobs. This ensures that runners can fetch the repository even after a feature branch is - deleted. For more information, see [Ref Specs for Runners](../pipelines/index.md#ref-specs-for-runners). - -NOTE: -For Windows runners, using `echo` to write to `.env` files may fail. Using the PowerShell `Add-Content`command -helps in such cases. For example: - -```powershell -Add-Content -Path deploy.env -Value "DYNAMIC_ENVIRONMENT_URL=$DYNAMIC_ENVIRONMENT_URL" -``` - ## Track newly included merge requests per deployment GitLab can track newly included merge requests per deployment. @@ -412,8 +345,8 @@ If there is a problem with a deployment, you can retry it or roll it back. To retry or rollback a deployment: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Deployments > Environments**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Operate > Environments**. 1. Select the environment. 1. To the right of the deployment name: - To retry a deployment, select **Re-deploy to environment**. @@ -627,8 +560,8 @@ you can view its expiration date and time. To view an environment's expiration date and time: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Deployments > Environments**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Operate > Environments**. 1. Select the name of the environment. The expiration date and time is displayed in the upper-left corner, next to the environment's name. @@ -640,8 +573,8 @@ you can override its expiration. To override an environment's expiration: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Deployments > Environments**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Operate > Environments**. 1. Select the deployment name. 1. in the upper-right corner, select the thumbtack (**{thumbtack}**). @@ -652,7 +585,7 @@ manually. There may be times when you want to stop an environment without running the defined [`on_stop`](../yaml/index.md#environmenton_stop) action. For example, you want to delete many -environments without using CI/CD minutes. +environments without using [compute quota](../pipelines/cicd_minutes.md). To stop an environment without running the defined `on_stop` action, execute the [Stop an environment API](../../api/environments.md#stop-an-environment) with the parameter @@ -667,8 +600,8 @@ Environments view, the stop and deploy jobs must be in the same To stop an environment in the GitLab UI: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Deployments > Environments**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Operate > Environments**. 1. Next to the environment you want to stop, select **Stop**. 1. On the confirmation dialog box, select **Stop environment**. @@ -731,8 +664,8 @@ Prerequisites: To delete an environment: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Deployments > Environments**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Operate > Environments**. 1. Select the **Stopped** tab. 1. Next to the environment you want to delete, select **Delete environment**. 1. On the confirmation dialog box, select **Delete environment**. @@ -800,7 +733,7 @@ to get alerts when there are critical issues that need immediate attention. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214634) in GitLab 13.4. -If you [set up alerts for Prometheus metrics](../../operations/metrics/alerts.md), +If you [set up alerts for Prometheus metrics](../../operations/incident_management/integrations.md#configuration), alerts for environments are shown on the environments page. The alert with the highest severity is shown, so you can identify which environments need immediate attention. @@ -834,34 +767,20 @@ Limitations of GitLab Auto Rollback: GitLab Auto Rollback is turned off by default. To turn it on: -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > CI/CD**. +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > CI/CD**. 1. Expand **Automatic deployment rollbacks**. 1. Select the checkbox for **Enable automatic rollbacks**. 1. Select **Save changes**. -### Monitor environments - -To monitor the behavior of your app as it runs in each environment, -enable [Prometheus for monitoring system and response metrics](../../user/project/integrations/prometheus.md). -For the monitoring dashboard to appear, configure Prometheus to collect at least one -[supported metric](../../user/project/integrations/prometheus_library/index.md). - -All deployments to an environment are shown on the monitoring dashboard. -You can view changes in performance for each version of your application. - -GitLab attempts to retrieve [supported performance metrics](../../user/project/integrations/prometheus_library/index.md) -for any environment that has had a successful deployment. If monitoring data was -successfully retrieved, a **Monitoring** button appears for each environment. - -To view the last eight hours of performance data, select the **Monitoring** button. -It may take a minute or two for data to appear after initial deployment. +<!--- start_remove The following content will be removed on remove_date: '2023-09-22' --> - +### Monitor environments (removed) -#### Embed metrics in GitLab Flavored Markdown +This feature was [deprecated](https://gitlab.com/groups/gitlab-org/-/epics/10107) in GitLab 14.7 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. -Metric charts can be embedded in GitLab Flavored Markdown. See [Embedding Metrics in GitLab Flavored Markdown](../../operations/metrics/embed.md) for more details. +<!--- end_remove --> ### Web terminals (deprecated) @@ -990,14 +909,14 @@ the `review/feature-1` spec takes precedence over `review/*` and `*` specs. ## Related topics -- [Use GitLab CI to deploy to multiple environments (blog post)](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/) -- [Review Apps](../review_apps/index.md): Use dynamic environments to deploy your code for every branch. -- [Deploy boards](../../user/project/deploy_boards.md): View the status of your applications running on Kubernetes. -- [Protected environments](protected_environments.md): Determine who can deploy code to your environments. -- [Environments Dashboard](../environments/environments_dashboard.md): View a summary of each - environment's operational health. **(PREMIUM)** -- [Deployment safety](deployment_safety.md#restrict-write-access-to-a-critical-environment): Secure your deployments. -- [Track deployments of an external deployment tool](external_deployment_tools.md): Use an external deployment tool instead of built-in deployment solution. +- [Dashboard for Kubernetes](kubernetes_dashboard.md) +- [Deploy to multiple environments with GitLab CI/CD (blog post)](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/) +- [Review Apps](../review_apps/index.md) +- [Protected environments](protected_environments.md) +- [Environments Dashboard](../environments/environments_dashboard.md) +- [Deployment safety](deployment_safety.md#restrict-write-access-to-a-critical-environment) +- [Track deployments of an external deployment tool](external_deployment_tools.md) +- [Configure Kubernetes deployments (deprecated)](configure_kubernetes_deployments.md) ## Troubleshooting |