Skip to content

G
gitlab-ce
Commit bc54a3bc authored by Nick Gaskill's avatar Nick Gaskill
Browse files
Options

Merge branch 'selhorn-environments-another-mr' into 'master' 

Style edits and info updates

See merge request gitlab-org/gitlab!56040
parents 84dbfc94 a5dab58d
Show whitespace changes
Inline Side-by-side
Showing with 84 additions and 141 deletions
doc/ci/environments/index.md
View file @ bc54a3bc
......@@ -18,7 +18,7 @@ a deployment is created.
GitLab:
- Provides a full history of deployments to each environment.
- Tracks your deployments, so you always know what is currently deployed on your
- Tracks your deployments, so you always know what is deployed on your
servers.
If you have a deployment service like [Kubernetes](../../user/project/clusters/index.md)
......@@ -116,8 +116,7 @@ In this example:
use `$CI_ENVIRONMENT_SLUG` instead. The `$CI_ENVIRONMENT_SLUG` variable is guaranteed to be unique.
You do not have to use the same prefix or only slashes (`/`) in the dynamic environment name.
However, when you use this format, you can use the [grouping similar environments](#grouping-similar-environments)
feature.
However, when you use this format, you can [group similar environments](#group-similar-environments).
NOTE:
Some variables cannot be used as environment names or URLs.
......@@ -184,8 +183,8 @@ deploy:
- master
```
When deploying to a Kubernetes cluster using the GitLab Kubernetes integration,
information about the cluster and namespace is displayed above the job
When you use the GitLab Kubernetes integration to deploy to a Kubernetes cluster,
cluster and namespace information is displayed above the job
trace on the deployment job page:
![Deployment cluster information](../img/environments_deployment_cluster_v12_8.png)
......@@ -202,8 +201,8 @@ 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 URLs,
DNS, etc. This variable is guaranteed to be unique.
- `$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.
......@@ -220,12 +219,12 @@ If you change the name of an existing environment, the:
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`,
you don't know the URL before the deployment script finishes.
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, including the URL that was dynamically-generated by the external service.
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.
......@@ -286,23 +285,6 @@ Note the following:
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).
## Deployment safety
Deployment jobs can be more sensitive than other jobs in a pipeline,
and might need to be treated with an extra care. There are multiple features
in GitLab that help 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)
- [Prevent deployments during deploy freeze windows](deployment_safety.md#prevent-deployments-during-deploy-freeze-windows)
## Protected environments
Environments can be "protected", restricting access to them.
For more information, see [Protected environments](protected_environments.md).
## Working with environments
Once environments are configured, GitLab provides many features for working with them,
......@@ -331,8 +313,8 @@ To retry or rollback a deployment:
### Environment URL
The [environment URL](../yaml/README.md#environmenturl) is exposed in a few
places within GitLab:
The [environment URL](../yaml/README.md#environmenturl) is displayed in a few
places in GitLab:
- In a merge request as a link:
![Environment URL in merge request](../img/environments_mr_review_app.png)
......@@ -359,8 +341,8 @@ from source files to public pages in the environment set for Review Apps.
When you stop an environment:
- It moves from the list of **Available** environments to the list of **Stopped**
environments on the [**Environments** page](#view-environments-and-deployments).
- On the **Environments** page, it moves from the list of **Available** environments
to the list of **Stopped** environments.
- An [`on_stop` action](../yaml/README.md#environmenton_stop), if defined, is executed.
Dynamic environments stop automatically when their associated branch is
......@@ -368,10 +350,16 @@ deleted.
#### Stop an environment when a branch is deleted
Environments can be stopped automatically using special configuration.
You can configure environments to stop when a branch is deleted.
Consider the following example where the `deploy_review` job calls `stop_review`
to clean up and stop the environment:
The following example shows a `deploy_review` job that calls a `stop_review` job
to clean up and stop the environment. The `stop_review` job must be in the same
`stage` as the `deploy_review` job.
Both jobs must have the same [`rules`](../yaml/README.md#onlyexcept-basic)
or [`only/except`](../yaml/README.md#onlyexcept-basic) configuration. Otherwise,
the `stop_review` job might not be included in all pipelines that include the
`deploy_review` job, and you cannot trigger `action: stop` to stop the environment automatically.
```yaml
deploy_review:
......@@ -397,55 +385,30 @@ stop_review:
when: manual
```
If you can't use [Pipelines for merge requests](../merge_request_pipelines/index.md),
setting the [`GIT_STRATEGY`](../runners/README.md#git-strategy) to `none` is necessary in the
`stop_review` job so that the [runner](https://docs.gitlab.com/runner/) doesn't
If you can't use [pipelines for merge requests](../merge_request_pipelines/index.md),
set the [`GIT_STRATEGY`](../runners/README.md#git-strategy) to `none` in the
`stop_review` job. Then the [runner](https://docs.gitlab.com/runner/) doesn't
try to check out the code after the branch is deleted.
When you have an environment that has a stop action defined (typically when
the environment describes a Review App), GitLab automatically triggers a
stop action when the associated branch is deleted. The `stop_review` job must
be in the same `stage` as the `deploy_review` job in order for the environment
to automatically stop.
Additionally, both jobs should have matching [`rules`](../yaml/README.md#onlyexcept-basic)
or [`only/except`](../yaml/README.md#onlyexcept-basic) configuration. In the example
above, if the configuration isn't identical, the `stop_review` job might not be
included in all pipelines that include the `deploy_review` job, and it isn't
possible to trigger `action: stop` to stop the environment automatically.
You can read more in the [`.gitlab-ci.yml` reference](../yaml/README.md#environmenton_stop).
Read more in the [`.gitlab-ci.yml` reference](../yaml/README.md#environmenton_stop).
#### Stop an environment after a certain time period
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20956) in GitLab 12.8.
You can set an expiry time for environments and stop them automatically after a certain period.
For example, consider the use of this feature with Review App environments. When you set up Review
Apps, sometimes they keep running for a long time because some merge requests are left open and
forgotten. Such idle environments waste resources and should be terminated as soon as possible.
You can set environments to stop automatically after a certain time period.
To address this problem, you can specify an optional expiration date for Review App environments.
When the expiry time is reached, GitLab automatically triggers a job to stop the environment,
eliminating the need of manually doing so. In case an environment is updated, the expiration is
renewed ensuring that only active merge requests keep running Review Apps.
In your `.gitlab-ci.yml` file, specify the [`environment:auto_stop_in`](../yaml/README.md#environmentauto_stop_in)
keyword. You can specify a human-friendly date as the value, such as `1 hour and 30 minutes` or `1 day`.
After the time period passes, GitLab automatically triggers a job to stop the environment.
To enable this feature, you must specify the [`environment:auto_stop_in`](../yaml/README.md#environmentauto_stop_in)
keyword in `.gitlab-ci.yml`. 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 that due to resource limitation, a background worker for stopping environments only runs once
Due to resource limitations, a background worker for stopping environments only runs once
every hour. This means that environments aren't stopped at the exact timestamp specified, but are
instead 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
per merge request. The `review_app` job is triggered by every push and
creates or updates an environment named `review/your-branch-name`.
The environment keeps running until `stop_review_app` is executed:
In the following example, each merge request creates a new Review App environment.
Each push triggers the `review_app` job and an environment named `review/your-branch-name`
is created or updated. The environment runs until `stop_review_app` is executed:
```yaml
review_app:
......@@ -467,48 +430,48 @@ stop_review_app:
when: manual
```
As long as a merge request is active and keeps getting new commits,
the review app doesn't stop, so developers don't need to worry about
re-initiating review app.
As long as the merge request is active and keeps getting new commits,
the Review App doesn't stop. Developers don't need to worry about
re-initiating Review App.
On the other hand, since `stop_review_app` is set to `auto_stop_in: 1 week`,
if a merge request becomes inactive for more than a week,
Because `stop_review_app` is set to `auto_stop_in: 1 week`,
if a merge request is inactive for more than a week,
GitLab automatically triggers the `stop_review_app` job to stop the environment.
You can also check the expiration date of environments through the GitLab UI. To do so,
go to **Operations > Environments > Environment**. You can see the auto-stop period
at the left-top section and a pin-mark button at the right-top section. This pin-mark
button can be used to prevent auto-stopping the environment. By clicking this button, the
`auto_stop_in` setting is overwritten and the environment is active until it's stopped manually.
#### View a deployment's scheduled stop time
![Environment auto stop](../img/environment_auto_stop_v12_8.png)
You can view a deployment's expiration date in the GitLab UI.
#### Delete a stopped environment
1. Go to the project's **Operations > Environments** page.
1. Select the name of the deployment.
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20620) in GitLab 12.10.
In the top left, next to the environment name, the expiration date is displayed.
You can delete [stopped environments](#stopping-an-environment) in one of two
ways: through the GitLab UI or through the API.
#### Override a deployment's scheduled stop time
##### Delete environments through the UI
You can manually override a deployment's expiration date.
To view the list of **Stopped** environments, navigate to **Operations > Environments**
and click the **Stopped** tab.
1. Go to the project's **Operations > Environments** page.
1. Select the deployment name.
1. In the top right, select the thumbtack (**{thumbtack}**).
![Environment auto stop](img/environment_auto_stop_v13_10.png)
From there, you can click the **Delete** button directly, or you can click the
environment name to see its details and **Delete** it from there.
The `auto_stop_in` setting is overwritten and the environment remains active until it's stopped manually.
#### Delete a stopped environment
You can also delete environments by viewing the details for a
stopped environment:
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20620) in GitLab 12.10.
1. Go to the project's **Operations > Environments** page.
1. Click on the name of an environment within the **Stopped** environments list.
1. Click on the **Delete** button that appears at the top for all stopped environments.
1. Finally, confirm your chosen environment in the modal that appears to delete it.
You can delete [stopped environments](#stopping-an-environment) in the GitLab UI or by using
[the API](../../api/environments.md#delete-an-environment).
##### Delete environments through the API
To delete a stopped environment in the GitLab UI:
Environments can also be deleted by using the [Environments API](../../api/environments.md#delete-an-environment).
1. Go to the project's **Operations > Environments** page.
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**.
### Prepare an environment
......@@ -535,19 +498,19 @@ build:
url: https://staging.example.com
```
### Grouping similar environments
### Group similar environments
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7015) in GitLab 8.14.
As documented in [Create a dynamic environment](#create-a-dynamic-environment), you can
prepend environment name with a word, followed by a `/`, and finally the branch
name, which is automatically defined by the `CI_COMMIT_REF_NAME` predefined CI/CD variable.
You can group environments into collapsible sections in the UI.
In short, environments that are named like `type/foo` are all presented under the same
group, named `type`.
For example, if all of your environments start with the name `review`,
then in the UI, the environments are grouped under that heading:
If you name the environments `review/$CI_COMMIT_REF_NAME`
where `$CI_COMMIT_REF_NAME` is the branch name:
![Environment groups](img/environments_dynamic_groups_v13_10.png)
The following example shows how to start your environment names with `review`.
The `$CI_COMMIT_REF_NAME` variable is populated with the branch name at runtime:
```yaml
deploy_review:
......@@ -558,11 +521,6 @@ deploy_review:
name: review/$CI_COMMIT_REF_NAME
```
If you visit the **Environments** page and the branches
exist, you should see something like:
![Environment groups](../img/environments_dynamic_groups.png)
### Environment incident management
You have successfully setup a Continuous Delivery/Deployment workflow in your project.
......@@ -634,8 +592,6 @@ Once configured, GitLab attempts to retrieve [supported performance metrics](../
for any environment that has had a successful deployment. If monitoring data was
successfully retrieved, a **Monitoring** button appears for each environment.
![Environment Detail with Metrics](../img/deployments_view.png)
Clicking the **Monitoring** button displays a new page showing up to the last
8 hours of performance data. It may take a minute or two for data to appear
after initial deployment.
......@@ -666,13 +622,13 @@ Note that container-based deployments often lack basic tools (like an editor), a
be stopped or restarted at any time. If this happens, you lose all your
changes. Treat this as a debugging tool, not a comprehensive online IDE.
Once enabled, your environments gain a **Terminal** button:
Once enabled, your environments display a **Terminal** button:
![Terminal button on environment index](../img/environments_terminal_button_on_index.png)
![Terminal button on environment index](img/environments_terminal_button_on_index_v13_10.png)
You can also access the terminal button from the page for a specific environment:
![Terminal button for an environment](../img/environments_terminal_button_on_show.png)
![Terminal button for an environment](img/environments_terminal_button_on_show_v13_10.png)
Wherever you find it, clicking the button takes you to a separate page to
establish the terminal session:
......@@ -749,24 +705,15 @@ such as [Review Apps](../review_apps/index.md) (`review/*`).
Note that the most _specific_ spec takes precedence over the other wildcard matching. In this case,
the `review/feature-1` spec takes precedence over `review/*` and `*` specs.
### Environments Dashboard **(PREMIUM)**
See [Environments Dashboard](../environments/environments_dashboard.md) for a summary of each
environment's operational health.
## Limitations
In the `environment: name`, you are limited to only the [predefined CI/CD variables](../variables/predefined_variables.md).
Re-using variables defined inside `script` as part of the environment name doesn't work.
## Further reading
Below are some links you may find interesting:
## Related topics
- [The `.gitlab-ci.yml` definition of environments](../yaml/README.md#environment)
- [A blog post on Deployments & Environments](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/)
- [Review Apps - Use dynamic environments to deploy your code for every branch](../review_apps/index.md)
- [Deploy Boards for your applications running on Kubernetes](../../user/project/deploy_boards.md)
- [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.
<!-- ## Troubleshooting
......
doc/ci/review_apps/index.md
View file @ bc54a3bc
......@@ -321,7 +321,3 @@ the user must enter a [personal access token](../../user/profile/personal_access
with `api` scope before submitting feedback.
This same method can be used to require authentication for any public projects.
## Limitations
Review App limitations are the same as [environments limitations](../environments/index.md#limitations).
doc/development/testing_guide/review_apps.md
View file @ bc54a3bc
......@@ -112,7 +112,7 @@ Review Apps are automatically stopped 2 days after the last deployment thanks to
the [Environment auto-stop](../../ci/environments/index.md#stop-an-environment-after-a-certain-time-period) feature.
If you need your Review App to stay up for a longer time, you can
[pin its environment](../../ci/environments/index.md#auto-stop-example) or retry the
[pin its environment](../../ci/environments/index.md#override-a-deployments-scheduled-stop-time) or retry the
`review-deploy` job to update the "latest deployed at" time.
The `review-cleanup` job that automatically runs in scheduled
......
doc/user/project/clusters/protect/container_host_security/quick_start_guide.md
View file @ bc54a3bc
......@@ -57,7 +57,7 @@ initial troubleshooting steps that resolve the most common problems:
1. If things still aren't working, a more assertive set of actions may help get things back to a
good state:
- Stop and [delete the problematic environment](../../../../../ci/environments/#delete-environments-through-the-ui)
- Stop and [delete the problematic environment](../../../../../ci/environments/#delete-a-stopped-environment)
in GitLab.
- Delete the relevant namespace in Kubernetes by running
`kubectl delete namespaces <insert-some-namespace-name>` in your Kubernetes cluster.
......
doc/user/project/clusters/protect/container_network_security/quick_start_guide.md
View file @ bc54a3bc
......@@ -131,7 +131,7 @@ initial troubleshooting steps that resolve the most common problems:
1. If things still aren't working, a more assertive set of actions may help get things back into a
good state:
- Stop and [delete the problematic environment](../../../../../ci/environments/index.md#delete-environments-through-the-ui) in GitLab.
- Stop and [delete the problematic environment](../../../../../ci/environments/index.md#delete-a-stopped-environment) in GitLab.
- Delete the relevant namespace in Kubernetes by running `kubectl delete namespaces <insert-some-namespace-name>` in your Kubernetes cluster.
- Rerun the application project pipeline to redeploy the application.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7