Commit 536b97a7 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis

Add Deploy Boards docs

parent 12bde5a7
...@@ -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.
If [Kubernetes] is your tool of choice for your application deployments, GitLab
offers a single place to view the current health and deployment status of each
[environment], displaying the specific status of each pod 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 (Ready, Preparing, Waiting, Deploying, Finished, Failed)
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/)
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.
## Enabling deploy boards
In order to have the Deploy Boards show up, you need to label your
deployments, replica sets and pods with `app=$CI_ENVIRONMENT_SLUG`.
Each project will need to have a unique namespace in Kubernetes as well.
In particular, here are the requirements for the Deploy Boards to show up in
your environments page:
1. You should have a Kubernetes cluster up and running
1. You should be using GitLab Runner using the [Docker][docker-exec] or
[Kubernetes executor][kube-exec]
1. Enable the [Kubernetes service](integrations/kubernetes.md) in your project
1. Use the Kubernetes labels and label your deployments `app=$CI_ENVIRONMENT_SLUG`
in the unique namespace specified in the Kubernetes service setting.
Simplified by using the
[Kubernetes deploy example](#using-the-kubernetes-deploy-example-project)
Docker image.
1. Optionally, use an [auto-deploy](../../ci/autodeploy/index.md) `.gitlab-ci.yml`
template which has some predefined stages and commands to use.
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 inspect Kubernetes for the state of each node (e.g., spinning up, down,
running version A, running version B) and Deploy Boards will be displayed on
the environments page.
Bare in mind that Deploy Boards are by default collapsed under their respective
environment but can be expanded. Only top-level environments can be expanded
by default, so if you for example use `review/*` for [review apps], the Deploy
Boards won't show up for that environment.
## Using the Kubernetes deploy example project
The [kubernetes-deploy] project is used to simplify the deployment process to
Kubernetes by providing the `build`, `deploy` and `destroy` commands which you
can use to your `.gitlab-ci.yml` as-is.
## Example
`nginx-deployment.yaml`:
```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
```
.gitlab-ci.yml:
```yaml
image: registry.gitlab.com/gitlab-examples/kubernetes-deploy
kubernetes deploy:
stage:
- deploy
environment:
name: $CI_BUILD_REF_NAME
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
```
[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"
[kubernetes-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"
[review apps]: ../../ci/review_apps/index.md "Review Apps documentation"
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