diff options
author | Marcel Amirault <ravlen@gmail.com> | 2019-04-29 02:13:52 +0300 |
---|---|---|
committer | Evan Read <eread@gitlab.com> | 2019-04-29 02:13:52 +0300 |
commit | da37f5a07d16bf944a209474e6b7694a6920bcb4 (patch) | |
tree | 9267069fe608058836f0686cfec8950021b42dac /doc/ci/environments.md | |
parent | 05cad997cdeedc0733df5eaad9db1e61591eff6c (diff) |
Docs: Environments Documentation review
Diffstat (limited to 'doc/ci/environments.md')
-rw-r--r-- | doc/ci/environments.md | 177 |
1 files changed, 91 insertions, 86 deletions
diff --git a/doc/ci/environments.md b/doc/ci/environments.md index 3e52cc786dd..6b4d4f1b9d4 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -16,11 +16,11 @@ For example: 1. Test your code. 1. Deploy your code into a testing or staging environment before you release it to the public. -This helps prevent bugs not only in your software, but in the deployment process as well. +This helps find bugs in your software, and also in the deployment process as well. GitLab CI/CD is capable of not only testing or building your projects, but also deploying them in your infrastructure, with the added benefit of giving you a -way to track your deployments. In other words, you can always know what is +way to track your deployments. In other words, you will always know what is currently being deployed or has been deployed on your servers. It's important to know that: @@ -31,12 +31,12 @@ It's important to know that: GitLab: -- Provides a full history of your deployments per every environment. +- Provides a full history of your deployments for each environment. - Keeps track of your deployments, so you always know what is currently being deployed on your servers. If you have a deployment service such as [Kubernetes](../user/project/clusters/index.md) -enabled for your project, you can use it to assist with your deployments, and +associated with your project, you can use it to assist with your deployments, and can even access a [web terminal](#web-terminals) for your environment from within GitLab! ## Configuring environments @@ -46,8 +46,8 @@ Configuring environments involves: 1. Understanding how [pipelines](pipelines.md) work. 1. Defining environments in your project's [`.gitlab-ci.yml`](yaml/README.md) file. -The rest of this section illustrates how to configure environments and deployments using an example. -It assumes you have already: +The rest of this section illustrates how to configure environments and deployments using +an example scenario. It assumes you have already: - Created a [project](../gitlab-basics/create-project.md) in GitLab. - Set up [a Runner](runners/README.md). @@ -94,9 +94,8 @@ We have defined 3 [stages](yaml/README.md#stages): - `build` - `deploy` -The jobs assigned to these stages will run in this order. If a job fails, then -the jobs that are assigned to the next stage won't run, rendering the pipeline -as failed. +The jobs assigned to these stages will run in this order. If any job fails, then +the pipeline fails and jobs that are assigned to the next stage won't run. In our case: @@ -104,15 +103,15 @@ In our case: - Then the `build` job. - Lastly the `deploy_staging` job. -With this configuration, we ensure that: +With this configuration, we: -- The tests pass. -- Our app is able to be built successfully. +- Check that the tests pass. +- Ensure that our app is able to be built successfully. - Lastly we deploy to the staging server. NOTE: **Note:** The `environment` keyword is just a hint for GitLab that this job actually -deploys to this environment's `name`. It can also have a `url` that is +deploys to the `name` environment. It can also have a `url` that is exposed in various places within GitLab. Each time a job that has an environment specified succeeds, a deployment is recorded, storing the Git SHA and environment name. @@ -134,14 +133,13 @@ In summary, with the above `.gitlab-ci.yml` we have achieved the following: > etc. > Starting with GitLab 9.3, the environment URL is exposed to the Runner via -> `$CI_ENVIRONMENT_URL`. The URL would be expanded from `.gitlab-ci.yml`, or if -> the URL was not defined there, the external URL from the environment would be -> used. +> `$CI_ENVIRONMENT_URL`. The URL is expanded from `.gitlab-ci.yml`, or if +> the URL was not defined there, the external URL from the environment is used. ### Configuring manual deployments -Converting automatically executed job into jobs requiring to a manual action involves -adding `when: manual` to the job's configuration. +Adding `when: manual` to an automatically executed job's configuration converts it to +a job requiring manual action. To expand on the [previous example](#defining-environments), the following includes another job that deploys our app to a production server and is @@ -187,7 +185,7 @@ deploy_prod: The `when: manual` action: -- Exposes a "play" button in GitLab's UI. +- Exposes a "play" button in GitLab's UI for that job. - Means the `deploy_prod` job will only be triggered when the "play" button is clicked. You can find the "play" button in the pipelines, environments, deployments, and jobs views. @@ -200,8 +198,8 @@ You can find the "play" button in the pipelines, environments, deployments, and | Deployments | ![Deployments manual action](img/environments_manual_action_deployments.png) | | Jobs | ![Builds manual action](img/environments_manual_action_jobs.png) | -Clicking on the play button in any view will trigger the `deploy_prod` job, and the deployment will be recorded under a new -environment named `production`. +Clicking on the play button in any view will trigger the `deploy_prod` job, and the +deployment will be recorded as a new environment named `production`. NOTE: **Note:** If your environment's name is `production` (all lowercase), @@ -209,14 +207,13 @@ it will get recorded in [Cycle Analytics](../user/project/cycle_analytics.md). ### Configuring dynamic environments -Other environments are good for deploying to stable environments like staging or production. +Regular environments are good when deploying to "stable" environments like staging or production. -However, what about environments for branches other than `master`? Dynamic environments can be used to achieve these. - -Dynamic environments make it possible to create environments on the fly by +However, for environments for branches other than `master`, dynamic environments +can be used. Dynamic environments make it possible to create environments on the fly by declaring their names dynamically in `.gitlab-ci.yml`. -Dynamic environments form the basis of [Review apps](review_apps/index.md). +Dynamic environments are a fundamental part of [Review apps](review_apps/index.md). #### Allowed variables @@ -237,10 +234,10 @@ For more information, see [Where variables can be used](variables/where_variable #### Example configuration -GitLab Runner exposes various [environment variables](variables/README.md) when a job runs and so +GitLab Runner exposes various [environment variables](variables/README.md) when a job runs, so you can use them as environment names. -In the following example, a job will deploy to all branches except `master`: +In the following example, the job will deploy to all branches except `master`: ```yaml deploy_review: @@ -261,28 +258,33 @@ In this example: - The job's name is `deploy_review` and it runs on the `deploy` stage. - We set the `environment` with the `environment:name` as `review/$CI_COMMIT_REF_NAME`. Since the [environment name](yaml/README.md#environmentname) can contain slashes (`/`), we can - use this pattern to distinguish between dynamic environments and the regular ones. -- We tell the job to run [`only`](yaml/README.md#onlyexcept-basic) on branches [`except`](yaml/README.md#onlyexcept-basic) `master`. + use this pattern to distinguish between dynamic and regular environments. +- We tell the job to run [`only`](yaml/README.md#onlyexcept-basic) on branches, + [`except`](yaml/README.md#onlyexcept-basic) `master`. For the value of: - `environment:name`, the first part is `review`, followed by a `/` and then `$CI_COMMIT_REF_NAME`, - which takes the value of the branch name. -- `environment:url`, since `$CI_COMMIT_REF_NAME` itself may also contain `/`, or other characters that - would be invalid in a domain name or URL, we use `$CI_ENVIRONMENT_SLUG` so that the environment can get a specific and distinct URL for each branch. + which receives the value of the branch name. +- `environment:url`, we want a specific and distinct URL for each branch. `$CI_COMMIT_REF_NAME` + may contain a `/` or other characters that would be invalid in a domain name or URL, + so we use `$CI_ENVIRONMENT_SLUG` to get a "clean" or "safe" URL. For example, given a `$CI_COMMIT_REF_NAME` of `100-Do-The-Thing`, the URL will be something like `https://100-do-the-4f99a2.example.com`. Again, the way you set up the web server to serve these requests is based on your setup. - You could also use `$CI_COMMIT_REF_SLUG` in `environment:url`. For example, `https://$CI_COMMIT_REF_SLUG.example.com`. - We have used `$CI_ENVIRONMENT_SLUG` here because it is guaranteed to be unique. If you're using a workflow like - [GitLab Flow](../workflow/gitlab_flow.md), collisions are unlikely and you may prefer environment names to be more closely based on the branch name. The example - above would give you an URL like `https://100-do-the-thing.example.com`. + We have used `$CI_ENVIRONMENT_SLUG` here because it is guaranteed to be unique. If + you're using a workflow like [GitLab Flow](../workflow/gitlab_flow.md), collisions + are unlikely and you may prefer environment names to be more closely based on the + branch name. In that case, you could use `$CI_COMMIT_REF_SLUG` in `environment:url` in + the example above: `https://$CI_COMMIT_REF_SLUG.example.com`, which would give a URL + of `https://100-do-the-thing.example.com`. NOTE: **Note:** -You are not bound to use the same prefix or only slashes in the dynamic -environments' names (`/`). However, this will enable the [grouping similar environments](#grouping-similar-environments) feature. +You are not required to use the same prefix or only slashes (`/`) in the dynamic environments' +names. However, using this format will enable the [grouping similar environments](#grouping-similar-environments) +feature. ### Complete example @@ -292,7 +294,7 @@ The configuration in this section provides a full development workflow where you - Built. - Deployed as a Review App. - Deployed to a staging server once the merge request is merged. -- Finally, manually deployed to the production server. +- Finally, able to be manually deployed to the production server. The following combines the previous configuration examples, including: @@ -348,8 +350,8 @@ deploy_prod: - master ``` -A more realistic example would include copying files to a location where a -webserver (for example, NGINX) could then read and serve. +A more realistic example would also include copying files to a location where a +webserver (for example, NGINX) could then acess and serve them. The example below will copy the `public` directory to `/srv/nginx/$CI_COMMIT_REF_SLUG/public`: @@ -366,32 +368,33 @@ review_app: This example requires that NGINX and GitLab Runner are set up on the server this job will run on. NOTE: **Note:** -See the [limitations](#limitations) section for some edge cases regarding naming of your branches and Review Apps. +See the [limitations](#limitations) section for some edge cases regarding the naming of +your branches and Review Apps. -The complete example provides the following workflow for developers: +The complete example provides the following workflow to developers: - Create a branch locally. -- Make changes and commit them +- Make changes and commit them. - Push the branch to GitLab. - Create a merge request. -Behind the scenes, GitLab runner will: +Behind the scenes, GitLab Runner will: - Pick up the changes and start running the jobs. - Run the jobs sequentially as defined in `stages`: - First, run the tests. - If the tests succeed, build the app. - - If the build succeeds, the app will be is deployed to an environment with a name specific to the + - If the build succeeds, the app is deployed to an environment with a name specific to the branch. So now, every branch: - Gets its own environment. -- Is deployed to its own location, with the added benefit of: +- Is deployed to its own unique location, with the added benefit of: - Having a [history of deployments](#viewing-deployment-history). - Being able to [rollback changes](#retrying-and-rolling-back) if needed. -For more information on using the URL, see [Using the environment URL](#using-the-environment-url). +For more information, see [Using the environment URL](#using-the-environment-url). ### Protected environments @@ -401,11 +404,12 @@ For more information, see [Protected environments](environments/protected_enviro ## Working with environments -Having configured environments, GitLab provides many features to work with them. These are documented below. +Once environments are configured, GitLab provides many features for working with them, +as documented below. ### Viewing environments and deployments -A list of environments and deployment statuses is available on project's **Operations > Environments** page. +A list of environments and deployment statuses is available on each project's **Operations > Environments** page. For example: @@ -416,11 +420,11 @@ This example shows: - The environment's name with a link to its deployments. - The last deployment ID number and who performed it. - The job ID of the last deployment with its respective job name. -- The commit information of the last deployment such as who committed, to what +- The commit information of the last deployment, such as who committed it, to what branch, and the Git SHA of the commit. - The exact time the last deployment was performed. -- A button that takes you to the URL that you have defined under the - `environment` keyword in `.gitlab-ci.yml`. +- A button that takes you to the URL that you defined under the `environment` keyword + in `.gitlab-ci.yml`. - A button that re-deploys the latest deployment, meaning it runs the job defined by the environment name for that specific commit. @@ -432,8 +436,8 @@ deployments, but an environment can have multiple deployments. > - While you can create environments manually in the web interface, we recommend > that you define your environments in `.gitlab-ci.yml` first. They will > be automatically created for you after the first deploy. -> - The environments page can only be viewed by Reporters and above. For more -> information on the permissions, see the [permissions documentation](../user/permissions.md). +> - The environments page can only be viewed by users with [Reporter permission](../user/permissions.md#project-members-permissions) +> and above. For more information on permissions, see the [permissions documentation](../user/permissions.md). > - Only deploys that happen after your `.gitlab-ci.yml` is properly configured > will show up in the **Environment** and **Last deployment** lists. @@ -442,7 +446,7 @@ deployments, but an environment can have multiple deployments. GitLab keeps track of your deployments, so you: - Always know what is currently being deployed on your servers. -- Can have the full history of your deployments per every environment. +- Can have the full history of your deployments for every environment. Clicking on an environment shows the history of its deployments. Here's an example **Environments** page with multiple deployments: @@ -460,9 +464,9 @@ To retry or rollback a deployment: 1. Navigate to **Operations > Environments**. 1. Click on the environment. -1. On the page that lists the deployment history for the environment, click the: - - **Rollback** button against a previously successful deployment, to roll back to that deployment. - - **Retry** button against the last deployment, to retry that deployment. +1. In the deployment history list for the environment, click the: + - **Retry** button next to the last deployment, to retry that deployment. + - **Rollback** button next to a previously successful deployment, to roll back to that deployment. NOTE: **Note:** The defined deployment process in the job's `script` determines whether the rollback succeeds or not. @@ -470,9 +474,7 @@ The defined deployment process in the job's `script` determines whether the roll ### Using the environment URL The [environment URL](yaml/README.md#environmenturl) is exposed in a few -places within GitLab. - -These are: +places within GitLab: - In a merge request widget as a link: ![Environment URL in merge request](img/environments_mr_review_app.png) @@ -493,27 +495,28 @@ For example: #### Going from source files to public pages With GitLab's [Route Maps](review_apps/index.md#route-maps) you can go directly -from source files to public pages on the environment set for Review Apps. +from source files to public pages in the environment set for Review Apps. ### Stopping an environment Stopping an environment: -- Moves it from the list of **Available** environments to the list of **Stopped** environments on the [**Environments** page](#viewing-environments-and-deployments). +- Moves it from the list of **Available** environments to the list of **Stopped** + environments on the [**Environments** page](#viewing-environments-and-deployments). - Executes an [`on_stop` action](yaml/README.md#environmenton_stop), if defined. This is often used when multiple developers are working on a project at the same time, each of them pushing to their own branches, causing many dynamic environments to be created. NOTE: **Note:** -Starting with GitLab 8.14, dynamic environments will be stopped automatically +Starting with GitLab 8.14, dynamic environments are stopped automatically when their associated branch is deleted. #### Automatically stopping an environment Environments can be stopped automatically using special configuration. -Consider the following example where the `deploy_review` calls the `stop_review` +Consider the following example where the `deploy_review` job calls `stop_review` to clean up and stop the environment: ```yaml @@ -542,14 +545,14 @@ stop_review: action: stop ``` -Setting the [`GIT_STRATEGY`](yaml/README.md#git-strategy) to `none` is necessary on the -`stop_review` job so that the [GitLab Runner](https://docs.gitlab.com/runner/) won't try to check out the code -after the branch is deleted. +Setting the [`GIT_STRATEGY`](yaml/README.md#git-strategy) to `none` is necessary in the +`stop_review` job so that the [GitLab Runner](https://docs.gitlab.com/runner/) won'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 will automatically trigger a stop action when the associated branch is deleted. The `stop_review` job must -be in the same `stage` as the `deploy_review` one in order for the environment +be in the same `stage` as the `deploy_review` job in order for the environment to automatically stop. You can read more in the [`.gitlab-ci.yml` reference](yaml/README.md#environmenton_stop). @@ -562,8 +565,8 @@ As documented in [Configuring dynamic environments](#configuring-dynamic-environ prepend environment name with a word, followed by a `/`, and finally the branch name, which is automatically defined by the `CI_COMMIT_REF_NAME` variable. -In short, environments that are named like `type/foo` are presented under a -group named `type`. +In short, environments that are named like `type/foo` are all presented under the same +group, named `type`. In our [minimal example](#example-configuration), we named the environments `review/$CI_COMMIT_REF_NAME` where `$CI_COMMIT_REF_NAME` is the branch name. Here is a snippet of the example: @@ -588,13 +591,14 @@ exist, you should see something like: > > - For the monitoring dashboard to appear, you need to: > - Enable the [Prometheus integration](../user/project/integrations/prometheus.md). -> - Configure Prometheus to collect at least one [supported metric](../user/project/integrations/prometheus_library/index.md) +> - Configure Prometheus to collect at least one [supported metric](../user/project/integrations/prometheus_library/index.md). > - With GitLab 9.2, all deployments to an environment are shown directly on the monitoring dashboard. -If you have enabled [Prometheus for monitoring system and response metrics](../user/project/integrations/prometheus.md), you can monitor the performance behavior of your app running in each environment. +If you have enabled [Prometheus for monitoring system and response metrics](../user/project/integrations/prometheus.md), +you can monitor the behavior of your app running in each environment. -Once configured, GitLab will attempt 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 +Once configured, GitLab will attempt 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 will appear for each environment. ![Environment Detail with Metrics](img/deployments_view.png) @@ -604,8 +608,8 @@ Clicking on the **Monitoring** button will display a new page showing up to the after initial deployment. All deployments to an environment are shown directly on the monitoring dashboard, -which allows easy correlation between any changes in performance and a new -version of the app, all without leaving GitLab. +which allows easy correlation between any changes in performance and new +versions of the app, all without leaving GitLab. ![Monitoring dashboard](img/environments_monitoring.png) @@ -617,8 +621,8 @@ If you deploy to your environments with the help of a deployment service (for ex the [Kubernetes integration](../user/project/clusters/index.md)), GitLab can open a terminal session to your environment. -This is a powerful feature that allows you to debug issues without leaving the comfort of your web browser. To -enable it, just follow the instructions given in the service integration +This is a powerful feature that allows you to debug issues without leaving the comfort +of your web browser. To enable it, just follow the instructions given in the service integration documentation. Once enabled, your environments will gain a "terminal" button: @@ -663,8 +667,9 @@ fetch = +refs/environments/*:refs/remotes/origin/environments/* ### Scoping environments with specs **[PREMIUM]** -Some GitLab [Enterprise Edition](https://about.gitlab.com/pricing/) features can behave differently for each -environment. For example, you can [create a secret variable to be injected only into a production environment](https://docs.gitlab.com/ee/ci/variables/#limiting-environment-scopes-of-environment-variables-premium). +Some GitLab [Enterprise Edition](https://about.gitlab.com/pricing/) features can +behave differently for each environment. For example, you can +[create a secret variable to be injected only into a production environment](https://docs.gitlab.com/ee/ci/variables/README.md#limiting-environment-scopes-of-environment-variables-premium). In most cases, these features use the _environment specs_ mechanism, which offers an efficient way to implement scoping within each environment group. @@ -696,9 +701,8 @@ In this case, `review/feature-1` spec takes precedence over `review/*` and `*` s ## Limitations -You are limited to use only the [CI predefined variables](variables/README.md) in the -`environment: name`. If you try to re-use variables defined inside `script` -as part of the environment name, it will not work. +In the `environment: name`, you are limited to only the [predefined environment variables](variables/predefined_variables.md). +Re-using variables defined inside `script` as part of the environment name will not work. ## Further reading @@ -707,3 +711,4 @@ Below are some links you may find interesting: - [The `.gitlab-ci.yml` definition of environments](yaml/README.md#environment) - [A blog post on Deployments & Environments](https://about.gitlab.com/2016/08/26/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](https://docs.gitlab.com/ee/user/project/deploy_boards.html) **[PREMIUM]** |