Commit 16a0ee10 authored by Job van der Voort's avatar Job van der Voort

Merge branch 'docs/canary-deployments' into 'master'

Split docs for canary deployments and add use cases

See merge request !2359
parents adc0fdc1 06d52399
......@@ -114,7 +114,7 @@ Manage files and branches from the UI (user interface):
- [Auto Deploy](ci/autodeploy/index.md): Configure GitLab CI for the deployment of your application.
- [Review Apps](ci/review_apps/index.md): Preview changes to your app right from a merge request.
- **(EEP)** [Deploy Boards](user/project/deploy_boards.md): View of the current health and status of each CI environment running on Kubernetes, displaying the status of the pods in the deployment.
- **(EEP)** [Canary Deployments](user/project/deploy_boards.md#canary-deployments): A popular CI strategy, where a small portion of the fleet is updated to the new version first.
- **(EEP)** [Canary Deployments](user/project/canary_deployments.md): A popular CI strategy, where a small portion of the fleet is updated to the new version first.
- [GitLab Cycle Analytics](user/project/cycle_analytics.md): Cycle Analytics measures the time it takes to go from an [idea to production](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab) for each project you have.
- [GitLab Container Registry](user/project/container_registry.md): Learn how to use GitLab's built-in Container Registry.
......
# Canary Deployments
> [Introduced][ee-1659] in [GitLab Enterprise Edition Premium][eep] 9.1.
A popular [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration)
strategy, where a small portion of the fleet is updated to the new version of
your application.
## Overview
When embracing [Continuous Delivery][cd-blog], a company needs to decide what
type of deployment strategy to use. One of the most popular strategies is canary
deployments, where a small portion of the fleet is updated to the new version
first. This subset, the canaries, then serve as the proverbial
[canary in the coal mine](https://en.wiktionary.org/wiki/canary_in_a_coal_mine).
If there is a problem with the new version of the application, only a small
percentage of users are affected and the change can either be fixed or quickly
reverted.
Leveraging [Kubernetes' Canary deployments][kube-canary], visualize your canary
deployments right inside the [Deploy Board], without the need to leave GitLab.
## Use cases
Canary deployments can be used you want to ship features to only a portion of
your pods fleet and watch their behavior as a percentage of your user base
visits the temporarily deployed feature. If all works well, you can deploy the
feature to production knowing that it won't cause any problems.
## Enabling Canary Deployments
Canary deployments require that you properly configure Deploy Boards:
1. Follow the steps to [enable Deploy Boards](deploy_boards.md#enabling-deploy-boards).
1. To track canary deployments you need to label your Kubernetes deployments and
pods with `track: canary`. To get started quickly, you can use the [Autodeploy]
template for canary deployments that GitLab provides.
Depending on the deploy, the label should be either `stable` or `canary`.
This allows GitLab to discover whether deployment is stable or canary (temporary).
Once all of the above are set up and the pipeline has run at least once,
navigate to the environments page under **Pipelines > Environments**.
As the pipeline executes Deploy Boards will clearly mark canary pods, enabling
quick and easy insight into the status of each environment and deployment.
Canary deployments are marked with a yellow dot in the Deploy Board so that you
can easily notice them.
![Canary deployments on Deploy Board](img/deploy_boards_canary_deployments.png)
[autodeploy]: ../../ci/autodeploy/index.md "GitLab Autodeploy"
[eep]: https://about.gitlab.com/gitlab-ee/
[ee-1659]: https://gitlab.com/gitlab-org/gitlab-ee/issues/1659
[kube-canary]: https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments
[deploy board]: deploy_boards.md
[cd-blog]: https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/
......@@ -15,7 +15,7 @@ With Deploy Boards you can gain more insight into deploys with benefits such as:
- Following a deploy from the start, not just when it's done
- Watching the rollout of a build across multiple servers
- Finer state detail (Waiting, Deploying, Finished, Unknown)
- See canary deployments
- See [Canary Deployments](canary_deployments.md)
Since Deploy Boards are tightly coupled with Kubernetes, there is some required
knowledge. In particular you should be familiar with:
......@@ -25,15 +25,6 @@ knowledge. In particular you should be familiar with:
- [Kubernetes namespaces](https://kubernetes.io/docs/user-guide/namespaces/)
- [Kubernetes canary deployments](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments)
Here's an example of a Deploy Board of the production environment.
![Deploy Boards landing page](img/deploy_boards_landing_page.png)
The squares represent pods in your Kubernetes cluster that are associated with
the given environment. Hovering above each square you can see the state of a
deploy rolling out. The percentage is the percent of the pods that are updated
to the latest release. The squares with dots represent canary deployment pods.
## Use cases
Since the Deploy Board is a visual representation of the Kubernetes pods for a
......@@ -52,21 +43,15 @@ specific environment, there are lot of uses cases. To name a few:
stuck or failed.
- You've got an MR that looks good, but you want to run it on staging because
staging is set up in some way closer to production. You go to the environment
list, find the [review app][review apps] you're interested in, and click the
list, find the [Review App][review apps] you're interested in, and click the
manual action to deploy it to staging.
## Requirements
In order to gather the deployment status you need to label your deployments,
replica sets, and pods with the `app` key and use the `CI_ENVIRONMENT_SLUG` as
a value. Each project will need to have a unique namespace in Kubernetes as well.
## Enabling Deploy Boards
![Deploy Boards Kubernetes Label](img/deploy_boards_kubernetes_label.png)
To display the Deploy Boards for a specific [environment] you should:
The complete requirements for Deploy Boards to display for a specific [environment] are:
1. You should have a Kubernetes cluster up and running.
1. GitLab Runner should be configured with the [Docker][docker-exec] or
1. Have a Kubernetes cluster up and running.
1. [Configure GitLab Runner][runners] with the [Docker][docker-exec] or
[Kubernetes][kube-exec] executor.
1. Configure the [Kubernetes service][kube-service] in your project for the
cluster. The Kubernetes namespace is of particular note as you will need it
......@@ -78,13 +63,13 @@ The complete requirements for Deploy Boards to display for a specific [environme
contained in the namespace defined in the Kubernetes service setting.
You can use an [Autodeploy] `.gitlab-ci.yml` template which has predefined
stages and commands to use, and automatically applies the labeling.
1. To track canary deployments you need to label your deployments and pods
with `track: canary`. This allows GitLab to discover whether deployment
is stable or canary (temporary). Read more in the [Canary deployments](#canary-deployments)
section.
Each project will need to have a unique namespace in Kubernetes as well.
The image below demonstrates how this is shown inside Kubernetes.
![Deploy Boards Kubernetes Label](img/deploy_boards_kubernetes_label.png)
Once all of the above are set up and the pipeline has run at least once,
navigate to the environments page under **Pipelines Environments**.
navigate to the environments page under **Pipelines > Environments**.
Deploy Boards are visible by default. You can explicitly click
the triangle next to their respective environment name in order to hide them.
......@@ -95,30 +80,23 @@ GitLab will only display a Deploy Board for top-level environments. Foldered
environments like `review/*` (usually used for [Review Apps]) won't have a
Deploy Board attached to them.
## Canary deployments
## How it works
Here's an example of a Deploy Board of the production environment.
When embracing [Continuous Delivery](https://en.wikipedia.org/wiki/Continuous_delivery),
a company needs to decide what type of deployment strategy to use. One of the
most popular strategies is canary deployments, where a small portion of the fleet
is updated to the new version first. This subset, the canaries, then serve as
the proverbial [canary in the coal mine](https://en.wiktionary.org/wiki/canary_in_a_coal_mine).
If there is a problem with the new version of the application, only a small
percentage of users are affected and the change can either be fixed or quickly
reverted.
![Deploy Boards landing page](img/deploy_boards_landing_page.png)
To start using canary deployments, in addition to the
[requirements of Deploy Boards](#requirements), you also need to label your
deployments and pods with the `canary` label (`track: canary`).
The squares represent pods in your Kubernetes cluster that are associated with
the given environment. Hovering above each square you can see the state of a
deploy rolling out. The percentage is the percent of the pods that are updated
to the latest release.
In the end, depending on the deploy, the label should be either `stable` or `canary`.
This allows GitLab to discover whether deployment is stable or canary (temporary).
To get started quickly, you can use the [Autodeploy] template for canary deployments
that GitLab provides.
## Canary Deployments
Canary deployments are marked with a yellow dot in the Deploy Board so that you
can easily notice them.
A popular CI strategy, where a small portion of the fleet is updated to the new
version of your application.
![Canary deployments on Deploy Board](img/deploy_boards_canary_deployments.png)
[Read more about Canary Deployments.](canary_deployments.md)
## Further reading
......@@ -140,3 +118,4 @@ can easily notice them.
[autodeploy]: ../../ci/autodeploy/index.md "GitLab Autodeploy"
[kube-image]: https://gitlab.com/gitlab-examples/kubernetes-deploy/container_registry "Kubernetes deploy Container Registry"
[manual action]: ../../ci/yaml/README.md#manual-actions
[runners]: ../../ci/runners/README.md
\ No newline at end of file
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