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

Add Deploy Boards docs

Closes #1932

See merge request !1467

doc/ci/environments.md

@@ -615,6 +615,7 @@ Below are some links you may find interesting:
 - [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/)
 - [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
 [jobs]: yaml/README.md#jobs

doc/user/project/deploy_boards.md

+# 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"

doc/user/project/integrations/kubernetes.md

@@ -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,
 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
 scoped to a particular `namespace`. If you don't have a service token yet,
 you can follow the
 [Kubernetes documentation](http://kubernetes.io/docs/user-guide/service-accounts/)
 to create one. You can also view or create service tokens in the
 [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.
 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`.
 
+[namespace]: https://kubernetes.io/docs/user-guide/namespaces/
+
 ## Deployment variables
 
 The Kubernetes service exposes following