Split docs for canary deployments and add use cases

doc/README.md

@@ -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.
 

doc/user/project/canary_deployments.md

+# 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/

doc/user/project/deploy_boards.md

@@ -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