Merge branch 'docs/canary-deployments-vol-2' into 'master'

Docs for canary deployments vol 2

Closes gitlab-ce#31270

See merge request !1704

doc/ci/autodeploy/index.md

 # Auto deploy
 
-> [Introduced][mr-8135] in GitLab 8.15. Currently requires a [Public project][project-settings].
+> [Introduced][mr-8135] in GitLab 8.15.
+> Auto deploy is an experimental feature and is not recommended for Production use at this time.
+> As of GitLab 9.1, access to the container registry is only available while the Pipeline is running. Restarting a pod, scaling a service, or other actions which require on-going access will fail. On-going secure access is planned for a subsequent release.
 
 Auto deploy is an easy way to configure GitLab CI for the deployment of your
 application. GitLab Community maintains a list of `.gitlab-ci.yml`
@@ -15,7 +17,8 @@ deployment.
 
 ## Supported templates
 
-The list of supported auto deploy templates is available [here][auto-deploy-templates].
+The list of supported auto deploy templates is available in the
+[gitlab-ci-yml project][auto-deploy-templates].
 
 ## Configuration
 
@@ -32,10 +35,118 @@ enable [Kubernetes service][kubernetes-service].
 1. Test your deployment configuration using a [Review App][review-app] that was
 created automatically for you.
 
+## Using the Kubernetes deploy example project with Nginx
+
+The Autodeploy templates are based on the [kubernetes-deploy][kube-deploy]
+project which 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.
+
+---
+
+A 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: __CI_ENVIRONMENT_SLUG__
+  labels:
+    app: __CI_ENVIRONMENT_SLUG__
+    track: stable
+spec:
+  replicas: 3
+  template:
+    metadata:
+      labels:
+        app: __CI_ENVIRONMENT_SLUG__
+        track: stable
+    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 Kubernetes environment variables to configure
+the Kubernetes cluster. These are exposed from the
+[Kubernetes service](../../user/project/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.
+
+## Private Project Support
+
+> Experimental support [introduced][mr-2] in GitLab 9.1.
+
+When a project has been marked as private, GitLab's [Container Registry][container-registry] requires authentication when downloading containers. Auto deploy will automatically provide the required authentication information to Kubernetes, allowing temporary access to the registry. Authentication credentials will be valid while the pipeline is running, allowing for a successful initial deployment.
+
+After the pipeline completes, Kubernetes will no longer be able to access the container registry. Restarting a pod, scaling a service, or other actions which require on-going access to the registry will fail. On-going secure access is planned for a subsequent release.
+
+## PostgreSQL Database Support
+
+> Experimental support [introduced][mr-8] in GitLab 9.1.
+
+In order to support applications that require a database, [PostgreSQL][postgresql] is provisioned by default. Credentials to access the database are preconfigured, but can be customized by setting the associated [variables](#postgresql-variables). These credentials can be used for defining a `DATABASE_URL` of the format: `postgres://user:password@postgres-host:postgres-port/postgres-database`. It is important to note that the database itself is temporary, and contents will be not be saved.
+
+PostgreSQL provisioning can be disabled by setting the variable `DISABLE_POSTGRES` to `"yes"`.
+
+### PostgreSQL Variables
+
+1. `DISABLE_POSTGRES: "yes"`: disable automatic deployment of PostgreSQL
+1. `POSTGRES_USER: "my-user"`: use custom username for PostgreSQL
+1. `POSTGRES_PASSWORD: "password"`: use custom password for PostgreSQL
+1. `POSTGRES_DB: "my database"`: use custom database name for PostgreSQL
+
 [mr-8135]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8135
+[mr-2]: https://gitlab.com/gitlab-examples/kubernetes-deploy/merge_requests/2
+[mr-8]: https://gitlab.com/gitlab-examples/kubernetes-deploy/merge_requests/8
 [project-settings]: https://docs.gitlab.com/ce/public_access/public_access.html
 [project-services]: ../../user/project/integrations/project_services.md
 [auto-deploy-templates]: https://gitlab.com/gitlab-org/gitlab-ci-yml/tree/master/autodeploy
 [kubernetes-service]: ../../user/project/integrations/kubernetes.md
 [docker-in-docker]: ../docker/using_docker_build.md#use-docker-in-docker-executor
 [review-app]: ../review_apps/index.md
+[kube-image]: https://gitlab.com/gitlab-examples/kubernetes-deploy/container_registry "Kubernetes deploy Container Registry"
+[kube-deploy]: https://gitlab.com/gitlab-examples/kubernetes-deploy "Kubernetes deploy example project"
+[container-registry]: https://docs.gitlab.com/ce/user/project/container_registry.html
+[postgresql]: https://www.postgresql.org/

doc/user/project/deploy_boards.md

@@ -34,7 +34,7 @@ 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. The squares with dots represent canary deployment pods.
 
-## Deploy Board requirements
+## 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
@@ -56,9 +56,7 @@ The complete requirements for Deploy Boards to display for a specific [environme
    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.
+   stages and commands to use, and automatically applies the labeling.
 1. To track canary deployments you need to label your deployments and pods
    with `track: canary`. This allows GitLab to discover whether deployment
    is stable or canary (temporary). Read more in the [Canary deployments](#canary-deployments)
@@ -67,7 +65,7 @@ The complete requirements for Deploy Boards to display for a specific [environme
 Once all of the above are set up and the pipeline has run at least once,
 navigate to the environments page under **Pipelines ➔ Environments**.
 
-Deploy Boards is visible by default. You can explicitly click
+Deploy Boards are visible by default. You can explicitly click
 the triangle next to their respective environment name in order to hide them.
 GitLab will then query Kubernetes for the state of each node (e.g., waiting,
 deploying, finished, unknown), and the Deploy Board status will finally appear.
@@ -76,84 +74,6 @@ GitLab will only display a Deploy Board for top-level environments. Foldered
 environments like `review/*` (usually used for [Review Apps]) won't have a
 Deploy Board attached to them.
 
-## 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: __CI_ENVIRONMENT_SLUG__
-  labels:
-    app: __CI_ENVIRONMENT_SLUG__
-    track: stable
-spec:
-  replicas: 3
-  template:
-    metadata:
-      labels:
-        app: __CI_ENVIRONMENT_SLUG__
-        track: stable
-    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.
-
 ## Canary deployments
 
 When embracing [Continuous Delivery](https://en.wikipedia.org/wiki/Continuous_delivery),
@@ -165,75 +85,26 @@ If there is a problem with the new version of the application, only a small
 percentage of users are affected and the change can either be fixed or quickly
 reverted.
 
----
-
 To start using canary deployments, in addition to the
-[requirements of Deploy Boards](#deploy-boards-requirements), you also need
-to label your deployments and pods with `track: canary`. This allows GitLab to
-discover whether deployment is stable or canary (temporary).
-
-Expanding on the [Kubernetes deploy example above](#using-the-kubernetes-deploy-example-project),
-you can also use it to expose canary deployments. Canary deployments should
-include `track: canary` and have a different deployment name than normal
-deployments.
-
-```yaml
-apiVersion: extensions/v1beta1
-kind: Deployment
-metadata:
-  name: __CI_ENVIRONMENT_SLUG__-canary
-  labels:
-    app: __CI_ENVIRONMENT_SLUG__
-    track: canary
-spec:
-  replicas: 3
-  template:
-    metadata:
-      labels:
-        app: __CI_ENVIRONMENT_SLUG__
-        track: canary
-    spec:
-      containers:
-      - name: nginx
-        image: nginx:1.7.9
-        ports:
-        - containerPort: 80
-```
-
-The `.gitlab-ci.yml` would be:
-
-```yaml
-image: registry.gitlab.com/gitlab-examples/kubernetes-deploy
-
-stages:
-  - canary
-
-kubernetes canary deploy:
-  stage: canary
-  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-canary.yaml || kubectl replace -f nginx-deployment-canary.yaml
-```
+[requirements of Deploy Boards](#requirements), you also need to label your
+deployments and pods with the `canary` label (`track: canary`).
+
+In the end, depending on the deploy, the label should be either `stable` or `canary`.
+This allows GitLab to discover whether deployment is stable or canary (temporary).
+To get started quickly, you can use the [Autodeploy] template for canary deployments
+that GitLab provides.
+
+Canary deployments are marked with a yellow dot in the Deploy Board so that you
+can easily notice them.
+
+![Canary deployments on Deploy Board](img/deploy_boards_canary_deployments.png)
 
 ## Further reading
 
+- [GitLab Autodeploy][autodeploy]
 - [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"