debian-mirror-gitlab/doc/user/project/deploy_boards.md

177 lines
8.7 KiB
Markdown
Raw Normal View History

2020-06-23 00:09:42 +05:30
---
stage: Release
2021-02-22 17:27:13 +05:30
group: Release
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-06-23 00:09:42 +05:30
type: howto, reference
---
2021-12-11 22:18:48 +05:30
# Deploy boards (DEPRECATED) **(FREE)**
2019-07-31 22:56:46 +05:30
2021-03-08 18:12:59 +05:30
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1589) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.0.
2021-06-08 01:23:25 +05:30
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212320) 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](https://gitlab.com/gitlab-org/gitlab/-/issues/8463)
> in GitLab 13.6.
> - In GitLab 13.11 and earlier, environments in folders do not show deploy boards.
> This is [fixed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60525) in
> GitLab 13.12.
2021-12-11 22:18:48 +05:30
> - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
WARNING:
This feature was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
[An epic exists](https://gitlab.com/groups/gitlab-org/-/epics/2493)
to add this functionality to the [Agent](../index.md).
2019-07-31 22:56:46 +05:30
2021-11-11 11:23:49 +05:30
GitLab deploy boards offer a consolidated view of the current health and
2020-05-24 23:13:21 +05:30
status of each CI [environment](../../ci/environments/index.md) running on [Kubernetes](https://kubernetes.io), displaying the status
2019-07-31 22:56:46 +05:30
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.
2021-04-17 20:07:23 +05:30
NOTE:
If you have a Kubernetes cluster, you can Auto Deploy applications to production
environments by using [Auto DevOps](../../topics/autodevops/index.md).
2019-07-31 22:56:46 +05:30
## Overview
2021-11-11 11:23:49 +05:30
With deploy boards you can gain more insight into deploys with benefits such as:
2019-07-31 22:56:46 +05:30
- Following a deploy from the start, not just when it's done
- Watching the rollout of a build across multiple servers
2020-01-01 13:55:28 +05:30
- Finer state detail (Succeeded, Running, Failed, Pending, Unknown)
2019-07-31 22:56:46 +05:30
- See [Canary Deployments](canary_deployments.md)
2021-11-11 11:23:49 +05:30
Here's an example of a deploy board of the production environment.
2019-07-31 22:56:46 +05:30
2021-11-11 11:23:49 +05:30
![deploy boards landing page](img/deploy_boards_landing_page.png)
2019-07-31 22:56:46 +05:30
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.
2021-11-11 11:23:49 +05:30
Since deploy boards are tightly coupled with Kubernetes, there is some required
2020-03-13 15:44:24 +05:30
knowledge. In particular, you should be familiar with:
2019-07-31 22:56:46 +05:30
2020-10-24 23:57:45 +05:30
- [Kubernetes pods](https://kubernetes.io/docs/concepts/workloads/pods/)
2019-07-31 22:56:46 +05:30
- [Kubernetes labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)
2019-12-21 20:55:43 +05:30
- [Kubernetes namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)
2019-07-31 22:56:46 +05:30
- [Kubernetes canary deployments](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments)
## Use cases
2021-11-11 11:23:49 +05:30
Since the deploy board is a visual representation of the Kubernetes pods for a
2020-03-13 15:44:24 +05:30
specific environment, there are a lot of use cases. To name a few:
2019-07-31 22:56:46 +05:30
- 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
2021-10-27 15:23:28 +05:30
running, then click on the [manual job](../../ci/jobs/job_control.md#create-a-job-that-must-be-run-manually) to deploy to production.
2021-03-08 18:12:59 +05:30
- 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
2019-07-31 22:56:46 +05:30
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
2020-04-22 19:07:51 +05:30
list, find the [Review App](../../ci/review_apps/index.md) you're interested in, and click the
2019-07-31 22:56:46 +05:30
manual action to deploy it to staging.
2021-11-11 11:23:49 +05:30
## Enabling deploy boards
2019-07-31 22:56:46 +05:30
2021-11-11 11:23:49 +05:30
To display the deploy boards for a specific [environment](../../ci/environments/index.md) you should:
2019-07-31 22:56:46 +05:30
2021-04-17 20:07:23 +05:30
1. Have [defined an environment](../../ci/environments/index.md) with a deploy stage.
2019-09-30 21:07:59 +05:30
2019-07-31 22:56:46 +05:30
1. Have a Kubernetes cluster up and running.
2021-02-22 17:27:13 +05:30
NOTE:
2021-03-08 18:12:59 +05:30
If you're using OpenShift, ensure that you're using the `Deployment` resource
2021-11-11 11:23:49 +05:30
instead of `DeploymentConfiguration`. Otherwise, the deploy boards don't render
2019-09-30 21:07:59 +05:30
correctly. For more information, read the
[OpenShift docs](https://docs.openshift.com/container-platform/3.7/dev_guide/deployments/kubernetes_deployments.html#kubernetes-deployments-vs-deployment-configurations)
2020-06-23 00:09:42 +05:30
and [GitLab issue #4584](https://gitlab.com/gitlab-org/gitlab/-/issues/4584).
2019-07-31 22:56:46 +05:30
2021-09-30 23:02:18 +05:30
1. [Configure GitLab Runner](../../ci/runners/index.md) with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or
2020-11-24 15:15:51 +05:30
[`kubernetes`](https://docs.gitlab.com/runner/executors/kubernetes.html) executor.
2021-11-18 22:05:49 +05:30
1. Configure the [Kubernetes integration](../infrastructure/clusters/index.md) in your project for the
2021-03-08 18:12:59 +05:30
cluster. The Kubernetes namespace is of particular note as you need it
2021-04-17 20:07:23 +05:30
for your deployment scripts (exposed by the `KUBE_NAMESPACE` deployment variable).
2019-07-31 22:56:46 +05:30
1. Ensure Kubernetes annotations of `app.gitlab.com/env: $CI_ENVIRONMENT_SLUG`
and `app.gitlab.com/app: $CI_PROJECT_PATH_SLUG` are applied to the
deployments, replica sets, and pods, where `$CI_ENVIRONMENT_SLUG` and
2021-04-17 20:07:23 +05:30
`$CI_PROJECT_PATH_SLUG` are the values of the CI/CD variables. This is so we can
2019-07-31 22:56:46 +05:30
lookup the proper environment in a cluster/namespace which may have more
than one. These resources should be contained in the namespace defined in
2021-03-11 19:13:27 +05:30
the Kubernetes service setting. You can use an [Auto deploy](../../topics/autodevops/stages.md#auto-deploy) `.gitlab-ci.yml`
2019-07-31 22:56:46 +05:30
template which has predefined stages and commands to use, and automatically
2021-03-08 18:12:59 +05:30
applies the annotations. Each project must have a unique namespace in
2019-07-31 22:56:46 +05:30
Kubernetes as well. The image below demonstrates how this is shown inside
Kubernetes.
2021-02-22 17:27:13 +05:30
NOTE:
2019-09-30 21:07:59 +05:30
Matching based on the Kubernetes `app` label was removed in [GitLab
2020-03-13 15:44:24 +05:30
12.1](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/14020).
2019-09-04 21:01:54 +05:30
To migrate, please apply the required annotations (see above) and
2019-12-21 20:55:43 +05:30
re-deploy your application. If you are using Auto DevOps, this will
be done automatically and no action is necessary.
2019-07-31 22:56:46 +05:30
2021-03-08 18:12:59 +05:30
If you use GCP to manage clusters, you can see the deployment details in GCP itself by navigating to **Workloads > deployment name > Details**:
2021-01-03 14:25:43 +05:30
2021-11-11 11:23:49 +05:30
![deploy boards Kubernetes Label](img/deploy_boards_kubernetes_label.png)
2019-07-31 22:56:46 +05:30
Once all of the above are set up and the pipeline has run at least once,
2021-09-04 01:27:46 +05:30
navigate to the environments page under **Deployments > Environments**.
2019-07-31 22:56:46 +05:30
2021-11-11 11:23:49 +05:30
Deploy boards are visible by default. You can explicitly click
2019-07-31 22:56:46 +05:30
the triangle next to their respective environment name in order to hide them.
2020-04-22 19:07:51 +05:30
### Example manifest file
2021-11-11 11:23:49 +05:30
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**:
2020-04-22 19:07:51 +05:30
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: "APPLICATION_NAME"
annotations:
app.gitlab.com/app: ${CI_PROJECT_PATH_SLUG}
2020-05-24 23:13:21 +05:30
app.gitlab.com/env: ${CI_ENVIRONMENT_SLUG}
2020-04-22 19:07:51 +05:30
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}
```
2021-03-08 18:12:59 +05:30
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.
2020-04-22 19:07:51 +05:30
2021-02-22 17:27:13 +05:30
NOTE:
2020-05-24 23:13:21 +05:30
The YAML file is static. If you apply it using `kubectl apply`, you must
manually provide the project and environment slugs, or create a script to
replace the variables in the YAML before applying.
2019-07-31 22:56:46 +05:30
## 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.](canary_deployments.md)
## Further reading
2021-03-11 19:13:27 +05:30
- [GitLab Auto deploy](../../topics/autodevops/stages.md#auto-deploy)
2021-09-30 23:02:18 +05:30
- [GitLab CI/CD variables](../../ci/variables/index.md)
2020-05-24 23:13:21 +05:30
- [Environments and deployments](../../ci/environments/index.md)
2020-04-22 19:07:51 +05:30
- [Kubernetes deploy example](https://gitlab.com/gitlab-examples/kubernetes-deploy)