diff options
Diffstat (limited to 'doc/ci/environments.md')
| -rw-r--r-- | doc/ci/environments.md | 80 |
1 files changed, 60 insertions, 20 deletions
diff --git a/doc/ci/environments.md b/doc/ci/environments.md index 3c31ba45d3d..df5c66a4c85 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -94,6 +94,12 @@ the name given in `.gitlab-ci.yml` (with any variables expanded), while the second is a "cleaned-up" version of the name, suitable for use in URLs, DNS, etc. +>**Note:** +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. + To sum up, with the above `.gitlab-ci.yml` we have achieved that: - All branches will run the `test` and `build` jobs. @@ -263,7 +269,7 @@ This works just like any other terminal - you'll be in the container created by your deployment, so you can run shell commands and get responses in real time, check the logs, try out configuration or code tweaks, etc. You can open multiple terminals to the same environment - they each get their own shell -session - and even a multiplexer like `screen` or `tmux`! +session - and even a multiplexer like `screen` or `tmux`! >**Note:** Container-based deployments often lack basic tools (like an editor), and may @@ -295,7 +301,7 @@ deploy_review: script: - echo "Deploy a review app" environment: - name: review/$CI_BUILD_REF_NAME + name: review/$CI_COMMIT_REF_NAME url: https://$CI_ENVIRONMENT_SLUG.example.com only: - branches @@ -306,22 +312,22 @@ deploy_review: Let's break it down in pieces. The job's name is `deploy_review` and it runs on the `deploy` stage. The `script` at this point is fictional, you'd have to use your own based on your deployment. Then, we set the `environment` with the -`environment:name` being `review/$CI_BUILD_REF_NAME`. Now that's an interesting +`environment:name` being `review/$CI_COMMIT_REF_NAME`. Now that's an interesting one. Since the [environment name][env-name] can contain slashes (`/`), we can use this pattern to distinguish between dynamic environments and the regular ones. -So, the first part is `review`, followed by a `/` and then `$CI_BUILD_REF_NAME` -which takes the value of the branch name. Since `$CI_BUILD_REF_NAME` itself may +So, the first part is `review`, followed by a `/` and then `$CI_COMMIT_REF_NAME` +which takes the value of the branch name. 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` in the `environment:url` so that the environment can get a specific and distinct URL for each branch. In this case, -given a `$CI_BUILD_REF_NAME` of `100-Do-The-Thing`, the URL will be something +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_BUILD_REF_SLUG` in `environment:url`, e.g.: -`https://$CI_BUILD_REF_SLUG.example.com`. We use `$CI_ENVIRONMENT_SLUG` +You could also use `$CI_COMMIT_REF_SLUG` in `environment:url`, e.g.: +`https://$CI_COMMIT_REF_SLUG.example.com`. We use `$CI_ENVIRONMENT_SLUG` here because it is guaranteed to be unique, but if you're using a workflow like [GitLab Flow][gitlab-flow], collisions are very unlikely, and you may prefer environment names to be more closely based on the branch name - the example @@ -356,7 +362,7 @@ deploy_review: script: - echo "Deploy a review app" environment: - name: review/$CI_BUILD_REF_NAME + name: review/$CI_COMMIT_REF_NAME url: https://$CI_ENVIRONMENT_SLUG.example.com only: - branches @@ -387,16 +393,16 @@ deploy_prod: A more realistic example would include copying files to a location where a webserver (NGINX) could then read and serve. The example below will copy the -`public` directory to `/srv/nginx/$CI_BUILD_REF_SLUG/public`: +`public` directory to `/srv/nginx/$CI_COMMIT_REF_SLUG/public`: ```yaml review_app: stage: deploy script: - - rsync -av --delete public /srv/nginx/$CI_BUILD_REF_SLUG + - rsync -av --delete public /srv/nginx/$CI_COMMIT_REF_SLUG environment: - name: review/$CI_BUILD_REF_NAME - url: https://$CI_BUILD_REF_SLUG.example.com + name: review/$CI_COMMIT_REF_NAME + url: https://$CI_COMMIT_REF_SLUG.example.com ``` It is assumed that the user has already setup NGINX and GitLab Runner in the @@ -442,7 +448,8 @@ and/or `production`) you can see this information in the merge request itself.  -### Go directly from source files to public pages on the environment +### <a name="route-map"></a>Go directly from source files to public pages on the environment + > Introduced in GitLab 8.17. @@ -526,7 +533,7 @@ deploy_review: script: - echo "Deploy a review app" environment: - name: review/$CI_BUILD_REF_NAME + name: review/$CI_COMMIT_REF_NAME url: https://$CI_ENVIRONMENT_SLUG.example.com on_stop: stop_review only: @@ -542,7 +549,7 @@ stop_review: - echo "Remove review app" when: manual environment: - name: review/$CI_BUILD_REF_NAME + name: review/$CI_COMMIT_REF_NAME action: stop ``` @@ -568,13 +575,13 @@ You can read more in the [`.gitlab-ci.yml` reference][onstop]. As we've seen in the [dynamic environments](#dynamic-environments), you can prepend their name with a word, then followed by a `/` and finally the branch -name which is automatically defined by the `CI_BUILD_REF_NAME` variable. +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 our minimal example, we name the environments `review/$CI_BUILD_REF_NAME` -where `$CI_BUILD_REF_NAME` is the branch name: +In our minimal example, we name the environments `review/$CI_COMMIT_REF_NAME` +where `$CI_COMMIT_REF_NAME` is the branch name: ```yaml deploy_review: @@ -582,7 +589,7 @@ deploy_review: script: - echo "Deploy a review app" environment: - name: review/$CI_BUILD_REF_NAME + name: review/$CI_COMMIT_REF_NAME ``` In that case, if you visit the Environments page, and provided the branches @@ -590,6 +597,37 @@ exist, you should see something like:  +## Monitoring environments + +>**Notes:** +> +- For the monitor dashboard to appear, you need to: + - Have enabled the [Prometheus integration][prom] + - Configured Prometheus to collect at least one [supported metric](../user/project/integrations/prometheus_library/metrics.md) +- With GitLab 9.2, all deployments to an environment are shown directly on the + monitoring dashboard + +If your application is deployed on Kubernetes and you have enabled Prometheus +collecting metrics, you can monitor the performance behavior of your app +through the environments. + +Once configured, GitLab will attempt to retrieve performance metrics for any +environment which has had a successful deployment. If monitoring data was +successfully retrieved, a Monitoring button will appear on the environment's +detail page. + + + +Clicking on the Monitoring button will display 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. + +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. + + + ## Checkout deployments locally Since 8.13, a reference in the git repository is saved for each deployment, so @@ -631,3 +669,5 @@ Below are some links you may find interesting: [gitlab-flow]: ../workflow/gitlab_flow.md [gitlab runner]: https://docs.gitlab.com/runner/ [git-strategy]: yaml/README.md#git-strategy +[kube]: ../user/project/integrations/kubernetes.md +[prom]: ../user/project/integrations/prometheus.md |