Deploy boards (deprecated) All tiers All offerings
- Introduced in GitLab 9.0.
- Moved from GitLab Premium to GitLab Free in 13.8.
- In GitLab 13.5 and earlier, apps that consist of multiple deployments are shown as duplicates on the deploy board. This is fixed in GitLab 13.6.
- In GitLab 13.11 and earlier, environments in folders do not show deploy boards. This is fixed in GitLab 13.12.
- Deprecated in GitLab 14.5.
- Disabled on self-managed in GitLab 15.0.
certificate_based_clusters
.GitLab 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 (Succeeded, Running, Failed, Pending, Unknown)
- See Canary Deployments
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.
Since deploy boards are tightly coupled with Kubernetes, there is some required knowledge. In particular, you should be familiar with:
Use cases
Since the deploy board is a visual representation of the Kubernetes pods for a specific environment, there are a lot of use cases. To name a few:
- You want to promote what’s running in staging, to production. You go to the environments list, verify that what’s running in staging is what you think is running, then select the manual job to deploy to production.
- You trigger a deploy, and you have many containers to upgrade so you know this takes a while (you’ve also throttled your deploy to only take down X containers at a time). But you need to tell someone when it’s deployed, so you go to the environments list, look at the production environment to see what the progress is in real-time as each pod is rolled.
- You get a report that something is weird in production, so you look at the production environment to see what is running, and if a deploy is ongoing or 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 you’re interested in, and select the manual action to deploy it to staging.
Enabling deploy boards
To display the deploy boards for a specific environment you should:
-
Have defined an environment with a deploy stage.
-
Have a Kubernetes cluster up and running.
If you’re using OpenShift, ensure that you’re using theDeployment
resource instead ofDeploymentConfiguration
. Otherwise, the deploy boards don’t render correctly. For more information, read the OpenShift docs and GitLab issue #4584. -
Configure GitLab Runner with the
docker
orkubernetes
executor. - Configure the Kubernetes integration in your project for the
cluster. The Kubernetes namespace is of particular note as you need it
for your deployment scripts (exposed by the
KUBE_NAMESPACE
deployment variable). -
Ensure Kubernetes annotations of
app.gitlab.com/env: $CI_ENVIRONMENT_SLUG
andapp.gitlab.com/app: $CI_PROJECT_PATH_SLUG
are applied to the deployments, replica sets, and pods, where$CI_ENVIRONMENT_SLUG
and$CI_PROJECT_PATH_SLUG
are the values of the CI/CD variables. 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 Auto deploy.gitlab-ci.yml
template which has predefined stages and commands to use, and automatically applies the annotations. Each project must have a unique namespace in Kubernetes as well. The image below demonstrates how this is shown inside Kubernetes.Matching based on the Kubernetesapp
label was removed in GitLab 12.1. To migrate, apply the required annotations (see above) and re-deploy your application. If you are using Auto DevOps, this will be done automatically and no action is necessary.If you use GCP to manage clusters, you can see the deployment details in GCP itself by navigating to Workloads > deployment name > Details:
Once all of the above are set up and the pipeline has run at least once, go to the environments page under Operate > Environments.
Deploy boards are visible by default. You can explicitly select the triangle next to their respective environment name to hide them.
Example manifest file
The following example is an extract of a Kubernetes manifest deployment file, using the two annotations app.gitlab.com/env
and app.gitlab.com/app
to enable the deploy boards:
apiVersion: apps/v1
kind: Deployment
metadata:
name: "APPLICATION_NAME"
annotations:
app.gitlab.com/app: ${CI_PROJECT_PATH_SLUG}
app.gitlab.com/env: ${CI_ENVIRONMENT_SLUG}
spec:
replicas: 1
selector:
matchLabels:
app: "APPLICATION_NAME"
template:
metadata:
labels:
app: "APPLICATION_NAME"
annotations:
app.gitlab.com/app: ${CI_PROJECT_PATH_SLUG}
app.gitlab.com/env: ${CI_ENVIRONMENT_SLUG}
The annotations are applied to the deployments, replica sets, and pods. By changing the number of replicas, like kubectl scale --replicas=3 deploy APPLICATION_NAME -n ${KUBE_NAMESPACE}
, you can follow the instances’ pods from the board.
kubectl apply
, you must
manually provide the project and environment slugs, or create a script to
replace the variables in the YAML before applying.Canary Deployments
A popular CI strategy, where a small portion of the fleet is updated to the new version of your application.
Read more about Canary Deployments.