Commit 28baca8a authored by Achilleas Pipinellis's avatar Achilleas Pipinellis

Merge branch 'docs/deploy-boards' into 'master'

Add Deploy Boards docs

Closes #1932

See merge request !1467
parents 53599798 8c641bff
...@@ -615,6 +615,7 @@ Below are some links you may find interesting: ...@@ -615,6 +615,7 @@ Below are some links you may find interesting:
- [The `.gitlab-ci.yml` definition of environments](yaml/README.md#environment) - [The `.gitlab-ci.yml` definition of environments](yaml/README.md#environment)
- [A blog post on Deployments & Environments](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/) - [A blog post on Deployments & Environments](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/)
- [Review Apps - Use dynamic environments to deploy your code for every branch](review_apps/index.md) - [Review Apps - Use dynamic environments to deploy your code for every branch](review_apps/index.md)
- [Deploy Boards for your applications running on Kubernetes](../user/project/deploy_boards.md)
[Pipelines]: pipelines.md [Pipelines]: pipelines.md
[jobs]: yaml/README.md#jobs [jobs]: yaml/README.md#jobs
......
# Deploy Boards
> [Introduced][ce-1589] in [GitLab Enterprise Edition Premium][ee] 9.0.
GitLab's Deploy Boards offer a consolidated view of the current health and
status of each CI [environment] running on [Kubernetes], displaying the status
of the pods in the deployment. Developers and other teammates can view the
progress and status of a rollout, pod by pod, in the workflow they already use
without any need to access Kubernetes.
## Overview
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)
Since Deploy Boards are tightly coupled with Kubernetes, there is some required
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/)
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.
## Deploy Board 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.
![Deploy Boards Kubernetes Label](img/deploy_boards_kubernetes_label.png)
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
[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
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
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
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. GitLab
also has a [Kubernetes deployment example](#using-the-kubernetes-deploy-example-project)
which can simplify the build and deployment process.
Once all of the above are set up and the pipeline has run at least once,
navigate to the environments page under **Pipelines ➔ Environments**. GitLab
will query Kubernetes for the state of each node (e.g., waiting, deploying,
finished, unknown) and the Deploy Board status will be displayed on
the environments page.
Bear in mind that Deploy Boards are collapsed under their respective environment,
and can be expanded. Only top-level environments are expanded by default. For example if
you use `review/*` for [review apps], the Deploy Board will appear collapsed initially.
## Using the Kubernetes deploy example project
The [kubernetes-deploy][kube-deploy] project is used to simplify the deployment
process to Kubernetes by providing intelligent `build`, `deploy` and `destroy`
commands which you can use in your `.gitlab-ci.yml` as-is. It uses Heroku'ish
build packs to do some of the work, plus some of GitLab's own tools to package
it all up. For your convenience, a [Docker image][kube-image] is also provided.
---
Another simple example would be the deployment of Nginx on Kubernetes.
Consider a `nginx-deployment.yaml` file in your project with contents:
```yaml
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
name: nginx-deployment
spec:
replicas: 3
template:
metadata:
labels:
app: __CI_ENVIRONMENT_SLUG__
spec:
containers:
- name: nginx
image: nginx:1.7.9
ports:
- containerPort: 80
```
The important part is where we set up `app: __CI_ENVIRONMENT_SLUG__`. As you'll
see later this is replaced by the [`CI_ENVIRONMENT_SLUG` env variable][variables].
The `.gitlab-ci.yml` would be:
```yaml
image: registry.gitlab.com/gitlab-examples/kubernetes-deploy
stages:
- deploy
kubernetes deploy:
stage: deploy
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.yaml || kubectl replace -f nginx-deployment.yaml
```
Notice that we use a couple of environment Kubernetes variables to configure
the Kubernetes cluster. These are exposed from the
[Kubernetes service](integrations/kubernetes.md#deployment-variables).
The most important one is the `$KUBE_NAMESPACE` which should be unique for
every project.
Next, we replace `__CI_ENVIRONMENT_SLUG__` with the content of the
`CI_ENVIRONMENT_SLUG` variable, so that the `app` label has the correct value.
Finally, the Nginx pod is created from the definition of the
`nginx-deployment.yaml` file.
## Further reading
- [GitLab CI environment variables][variables]
- [Environments and deployments][environment]
- [Kubernetes project service][kube-service]
- [Kubernetes deploy example][kube-deploy]
- [GitLab Autodeploy][autodeploy]
[ce-1589]: https://gitlab.com/gitlab-org/gitlab-ee/issues/1589 "Deploy Boards intial issue"
[ee]: https://about.gitlab.com/gitlab-ee/ "GitLab Enterprise Edition landing page"
[kube-deploy]: https://gitlab.com/gitlab-examples/kubernetes-deploy "Kubernetes deploy example project"
[kubernetes]: https://kubernetes.io "Kubernetes website"
[environment]: ../../ci/environments.md "Environments and deployments documentation"
[docker-exec]: https://docs.gitlab.com/runner/executors/docker.html "GitLab Runner Docker executor"
[kube-exec]: https://docs.gitlab.com/runner/executors/kubernetes.html "GitLab Runner Kubernetes executor"
[kube-service]: integrations/kubernetes.md "Kubernetes project service"
[review apps]: ../../ci/review_apps/index.md "Review Apps documentation"
[variables]: ../../ci/variables/README.md "GitLab CI variables"
[autodeploy]: ../../ci/autodeploy/index.md "GitLab Autodeploy"
[kube-image]: https://gitlab.com/gitlab-examples/kubernetes-deploy/container_registry "Kubernetes deploy Container Registry"
...@@ -28,18 +28,26 @@ The API URL is the URL that GitLab uses to access the Kubernetes API. Kubernetes ...@@ -28,18 +28,26 @@ The API URL is the URL that GitLab uses to access the Kubernetes API. Kubernetes
exposes several APIs - we want the "base" URL that is common to all of them, exposes several APIs - we want the "base" URL that is common to all of them,
e.g., `https://kubernetes.example.com` rather than `https://kubernetes.example.com/api/v1`. e.g., `https://kubernetes.example.com` rather than `https://kubernetes.example.com/api/v1`.
A [namespace] is just a logical grouping of resources. This is mostly for ease of
management, so you can group things together. For example, if you have 50
projects using the same cluster, providing a simple list of all pods would be
really difficult to work with. In that case, you can provide a separate
namespace to group things, as well as reduce name collision issues.
GitLab authenticates against Kubernetes using service tokens, which are GitLab authenticates against Kubernetes using service tokens, which are
scoped to a particular `namespace`. If you don't have a service token yet, scoped to a particular `namespace`. If you don't have a service token yet,
you can follow the you can follow the
[Kubernetes documentation](http://kubernetes.io/docs/user-guide/service-accounts/) [Kubernetes documentation](http://kubernetes.io/docs/user-guide/service-accounts/)
to create one. You can also view or create service tokens in the to create one. You can also view or create service tokens in the
[Kubernetes dashboard](http://kubernetes.io/docs/user-guide/ui/) - visit [Kubernetes dashboard](http://kubernetes.io/docs/user-guide/ui/) - visit
`Config -> Secrets`. **Config ➔ Secrets**.
Fill in the service token and namespace according to the values you just got. Fill in the service token and namespace according to the values you just got.
If the API is using a self-signed TLS certificate, you'll also need to include If the API is using a self-signed TLS certificate, you'll also need to include
the `ca.crt` contents as the `Custom CA bundle`. the `ca.crt` contents as the `Custom CA bundle`.
[namespace]: https://kubernetes.io/docs/user-guide/namespaces/
## Deployment variables ## Deployment variables
The Kubernetes service exposes following The Kubernetes service exposes following
......
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