Commit 04393d02 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis

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

Update documentation with canary deploys

See merge request !1684
parents 7c73aeb9 d3fbe089
......@@ -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
......
......@@ -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]
......
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