Merge branch 'canary-deploys-docs' into 'master'

Update documentation with canary deploys

See merge request !1684

doc/ci/README.md

@@ -67,6 +67,8 @@ learn how to leverage its potential even more.
 - [Auto deploy](autodeploy/index.md)
 - [Use SSH keys in your build environment](ssh_keys/README.md)
 - [Trigger jobs through the GitLab API](triggers/README.md)
+- [Deploy Boards](../user/project/deploy_boards.md) - Check the current health
+  and status of each CI environment running on Kubernetes
 
 ## Review Apps
 

doc/user/project/deploy_boards.md

@@ -15,6 +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
 
 Since Deploy Boards are tightly coupled with Kubernetes, there is some required
 knowledge. In particular you should be familiar with:
@@ -22,6 +23,7 @@ knowledge. In particular you should be familiar with:
 - [Kubernetes pods](https://kubernetes.io/docs/user-guide/pods)
 - [Kubernetes labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)
 - [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.
 
@@ -30,7 +32,7 @@ Here's an example of a Deploy Board of the production environment.
 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.
+to the latest release. The squares with dots represent canary deployment pods.
 
 ## Deploy Board requirements
 
@@ -48,7 +50,7 @@ The complete requirements for Deploy Boards to display for a specific [environme
 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
    for your deployment scripts (exposed by the `KUBE_NAMESPACE` env variable).
-1. Ensure a Kubernetes label of `app=$CI_ENVIRONMENT_SLUG` is applied to the
+1. Ensure a Kubernetes label of `app: $CI_ENVIRONMENT_SLUG` is applied to the
    deployments, replica sets, and pods, where `$CI_ENVIRONMENT_SLUG` the value
    of the CI variable. This is so we can lookup the proper environment in a
    cluster/namespace which may have more than one. These resources should be
@@ -57,12 +59,16 @@ The complete requirements for Deploy Boards to display for a specific [environme
    stages and commands to use, and automatically applies the labeling. GitLab
    also has a [Kubernetes deployment example](#using-the-kubernetes-deploy-example-project)
    which can simplify the build and deployment process.
+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.
 
 Once all of the above are set up and the pipeline has run at least once,
 navigate to the environments page under **Pipelines ➔ Environments**.
 
-Deploy Boards will be collapsed by default, and you have to explicitly click
-the triangle next to their respective environment name in order to see them.
+Deploy Boards is visible by default. You can explicitly click
+the triangle next to their respective environment name in order to hide them.
 GitLab will then query Kubernetes for the state of each node (e.g., waiting,
 deploying, finished, unknown), and the Deploy Board status will finally appear.
 
@@ -87,13 +93,17 @@ Consider a `nginx-deployment.yaml` file in your project with contents:
 apiVersion: extensions/v1beta1
 kind: Deployment
 metadata:
-  name: nginx-deployment
+  name: __CI_ENVIRONMENT_SLUG__
+  labels:
+    app: __CI_ENVIRONMENT_SLUG__
+    track: stable
 spec:
   replicas: 3
   template:
     metadata:
       labels:
         app: __CI_ENVIRONMENT_SLUG__
+        track: stable
     spec:
       containers:
       - name: nginx
@@ -144,6 +154,79 @@ Next, we replace `__CI_ENVIRONMENT_SLUG__` with the content of the
 Finally, the Nginx pod is created from the definition of the
 `nginx-deployment.yaml` file.
 
+## Canary deployments
+
+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.
+
+---
+
+To start using canary deployments, in addition to the
+[requirements of Deploy Boards](#deploy-boards-requirements), you also need
+to label your deployments and pods with `track: canary`. This allows GitLab to
+discover whether deployment is stable or canary (temporary).
+
+Expanding on the [Kubernetes deploy example above](#using-the-kubernetes-deploy-example-project),
+you can also use it to expose canary deployments. Canary deployments should
+include `track: canary` and have a different deployment name than normal
+deployments.
+
+```yaml
+apiVersion: extensions/v1beta1
+kind: Deployment
+metadata:
+  name: __CI_ENVIRONMENT_SLUG__-canary
+  labels:
+    app: __CI_ENVIRONMENT_SLUG__
+    track: canary
+spec:
+  replicas: 3
+  template:
+    metadata:
+      labels:
+        app: __CI_ENVIRONMENT_SLUG__
+        track: canary
+    spec:
+      containers:
+      - name: nginx
+        image: nginx:1.7.9
+        ports:
+        - containerPort: 80
+```
+
+The `.gitlab-ci.yml` would be:
+
+```yaml
+image: registry.gitlab.com/gitlab-examples/kubernetes-deploy
+
+stages:
+  - canary
+
+kubernetes canary deploy:
+  stage: canary
+  environment:
+    name: production
+  script:
+    - echo "$KUBE_CA_PEM" > kube_ca.pem
+    - cat kube_ca.pem
+    - kubectl config set-cluster default-cluster --server=$KUBE_URL --certificate-authority="$(pwd)/kube_ca.pem"
+    - kubectl config set-credentials default-admin --token=$KUBE_TOKEN
+    - kubectl config set-context default-system --cluster=default-cluster --user=default-admin --namespace $KUBE_NAMESPACE
+    - kubectl config use-context default-system
+
+    - sed -i "s/__CI_ENVIRONMENT_SLUG__/$CI_ENVIRONMENT_SLUG/" nginx-deployment.yaml
+    - cat nginx-deployment.yaml
+    - kubectl cluster-info
+    - kubectl get deployments -l app=$CI_ENVIRONMENT_SLUG
+    - kubectl create -f nginx-deployment-canary.yaml || kubectl replace -f nginx-deployment-canary.yaml
+```
+
 ## Further reading
 
 - [GitLab CI environment variables][variables]