Merge branch 'docs/autodeploy-refactor' into 'master'

Refactor the Autodeploy docs

Closes #37151

See merge request !13906

7 files changed, 151 insertions, 27 deletions

diff --git a/doc/ci/autodeploy/img/auto_deploy_btn.png b/doc/ci/autodeploy/img/auto_deploy_btn.png
new file mode 100644
index 00000000000..25915ed1c9d
--- /dev/null
+++ b/doc/ci/autodeploy/img/auto_deploy_btn.png
diff --git a/doc/ci/autodeploy/img/auto_deploy_dropdown.png b/doc/ci/autodeploy/img/auto_deploy_dropdown.png
index b93b0a08fea..5815937a4af 100644
--- a/doc/ci/autodeploy/img/auto_deploy_dropdown.png
+++ b/doc/ci/autodeploy/img/auto_deploy_dropdown.png
diff --git a/doc/ci/autodeploy/img/guide_connect_cluster.png b/doc/ci/autodeploy/img/guide_connect_cluster.png
new file mode 100644
index 00000000000..b856b81a1d0
--- /dev/null
+++ b/doc/ci/autodeploy/img/guide_connect_cluster.png
diff --git a/doc/ci/autodeploy/img/guide_integration.png b/doc/ci/autodeploy/img/guide_integration.png
new file mode 100644
index 00000000000..723b2619ea2
--- /dev/null
+++ b/doc/ci/autodeploy/img/guide_integration.png
diff --git a/doc/ci/autodeploy/img/guide_secret.png b/doc/ci/autodeploy/img/guide_secret.png
new file mode 100644
index 00000000000..01f5aa49908
--- /dev/null
+++ b/doc/ci/autodeploy/img/guide_secret.png
diff --git a/doc/ci/autodeploy/index.md b/doc/ci/autodeploy/index.md
index a714689ebd5..a128cf69c20 100644
--- a/doc/ci/autodeploy/index.md
+++ b/doc/ci/autodeploy/index.md
@@ -1,8 +1,13 @@
-# Auto deploy
+# Auto Deploy
 
-> [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.
+>**Notes:**
+- [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`
@@ -11,9 +16,23 @@ powering them. These scripts are responsible for packaging your application,
 setting up the infrastructure and spinning up necessary services (for
 example a database).
 
-You can use [project services][project-services] to store credentials to
-your infrastructure provider and they will be available during the
-deployment.
+## How it works
+
+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 [Herokuish](https://github.com/gliderlabs/herokuish),
+which uses [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks)
+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.
+
+You can use the [Kubernetes project service](../../user/project/integrations/kubernetes.md)
+to store credentials to your infrastructure provider and they will be available
+during the deployment.
+
+## Quick start
+
+We made a [simple guide](quick_start_guide.md) to using Auto Deploy with GitLab.com.
 
 ## Supported templates
 
@@ -22,20 +41,27 @@ The list of supported auto deploy templates is available in the
 
 ## Configuration
 
+>**Note:**
+In order to understand why the following steps are required, read the
+[how it works](#how-it-works) section.
+
+To configure Autodeploy, you will need to:
+
 1. Enable a deployment [project service][project-services] to store your
-credentials. For example, if you want to deploy to OpenShift you have to
-enable [Kubernetes service][kubernetes-service].
-1. Configure GitLab Runner to use Docker or Kubernetes executor with
-[privileged mode enabled][docker-in-docker].
+   credentials. For example, if you want to deploy to OpenShift you have to
+   enable [Kubernetes service][kubernetes-service].
+1. Configure GitLab Runner to use the
+   [Docker or Kubernetes executor](https://docs.gitlab.com/runner/executors/) with
+   [privileged mode enabled][docker-in-docker].
 1. Navigate to the "Project" tab and click "Set up auto deploy" button.
    ![Auto deploy button](img/auto_deploy_button.png)
 1. Select a template.
   ![Dropdown with auto deploy templates](img/auto_deploy_dropdown.png)
 1. Commit your changes and create a merge request.
 1. Test your deployment configuration using a [Review App][review-app] that was
-created automatically for you.
+   created automatically for you.
 
-## Private Project Support
+## Private project support
 
 > Experimental support [introduced][mr-2] in GitLab 9.1.
 
@@ -43,7 +69,7 @@ When a project has been marked as private, GitLab's [Container Registry][contain
 
 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
+## PostgreSQL database support
 
 > Experimental support [introduced][mr-8] in GitLab 9.1.
 
@@ -51,25 +77,13 @@ In order to support applications that require a database, [PostgreSQL][postgresq
 
 PostgreSQL provisioning can be disabled by setting the variable `DISABLE_POSTGRES` to `"yes"`.
 
-### PostgreSQL Variables
+The following PostgreSQL variables are supported:
 
 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
-[container-registry]: https://docs.gitlab.com/ce/user/project/container_registry.html
-[postgresql]: https://www.postgresql.org/
-
 ## Auto Monitoring
 
 > Introduced in [GitLab 9.5](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13438).
@@ -94,3 +108,18 @@ If you have installed GitLab using a different method:
 1. [Deploy Prometheus](../../user/project/integrations/prometheus.md#configuring-your-own-prometheus-server-within-kubernetes) into your Kubernetes cluster
 1. If you would like response metrics, ensure you are running at least version 0.9.0 of NGINX Ingress and [enable Prometheus metrics](https://github.com/kubernetes/ingress/blob/master/examples/customization/custom-vts-metrics/nginx/nginx-vts-metrics-conf.yaml).
 1. Finally, [annotate](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) the NGINX Ingress deployment to be scraped by Prometheus using `prometheus.io/scrape: "true"` and `prometheus.io/port: "10254"`.
+
+[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/
+
diff --git a/doc/ci/autodeploy/quick_start_guide.md b/doc/ci/autodeploy/quick_start_guide.md
new file mode 100644
index 00000000000..f76c2a2cf31
--- /dev/null
+++ b/doc/ci/autodeploy/quick_start_guide.md
@@ -0,0 +1,95 @@
+# Auto Deploy: quick start guide
+
+This is a step-by-step guide to deploying a project hosted on GitLab.com to Google Cloud, using Auto Deploy.
+
+We made a minimal [Ruby application](https://gitlab.com/gitlab-examples/minimal-ruby-app) to use as an example for this guide. It contains two files:
+
+* `server.rb` - our application. It will start an HTTP server on port 5000 and render “Hello, world!”
+* `Dockerfile` - to build our app into a container image. It will use a ruby base image and run `server.rb`
+
+## Fork sample project on GitLab.com
+
+Let’s start by forking our sample application. Go to [the project page](https://gitlab.com/gitlab-examples/minimal-ruby-app) and press the `Fork` button. Soon you should have a project under your namespace with the necessary files.
+
+## Setup your own cluster on Google Container Engine
+
+If you do not already have a Google Cloud account, create one at https://console.cloud.google.com.
+
+Visit the [`Container Engine`](https://console.cloud.google.com/kubernetes/list) tab and create a new cluster. You can change the name and leave the rest of the default settings. Once you have your cluster running, you need to connect to the cluster by following the Google interface.
+
+## Connect to Kubernetes cluster
+
+You need to have the Google Cloud SDK installed. e.g.
+On OSX, install [homebrew](https://brew.sh):
+
+1. Install Brew Caskroom: `brew install caskroom/cask/brew-cask`
+2. Install Google Cloud SDK: `brew cask install google-cloud-sdk`
+3. Add `kubectl`: `gcloud components install kubectl`
+4. Log in: `gcloud auth login`
+
+Now go back to the Google interface, find your cluster, and follow the instructions under `Connect to the cluster` and open the Kubernetes Dashboard. It will look something like `gcloud container clusters get-credentials ruby-autodeploy \ --zone europe-west2-c --project api-project-XXXXXXX` and then `kubectl proxy`.
+
+![connect to cluster](img/guide_connect_cluster.png)
+
+## Copy credentials to GitLab.com project
+
+Once you have the Kubernetes Dashboard interface running, you should visit `Secrets` under the  `Config` section. There you should find the settings we need for GitLab integration: ca.crt and token.
+
+![connect to cluster](img/guide_secret.png)
+
+You need to copy-paste the ca.crt and token into your project on GitLab.com in the Kubernetes integration page under project `Settings` > `Integrations` > `Project services` > `Kubernetes`. Don't actually copy the namespace though. Each project should have a unique namespace, and by leaving it blank, GitLab will create one for you.
+
+![connect to cluster](img/guide_integration.png)
+
+For API URL, you should use the `Endpoint` IP from your cluster page on Google Cloud Platform.
+
+## Expose the application to the internet
+
+In order to be able to visit your application, you need to install an NGINX ingress controller and point your domain name to its external IP address.
+
+### Set up Ingress controller
+
+You’ll need to make sure you have an ingress controller. If you don’t have one, do:
+
+```sh
+brew install kubernetes-helm
+helm init
+helm install --name ruby-app stable/nginx-ingress
+```
+
+This should create several services including `ruby-app-nginx-ingress-controller`. You can list your services by running `kubectl get svc` to confirm that.
+
+### Point DNS at Cluster IP
+
+Find out the external IP address of the `ruby-app-nginx-ingress-controller` by running:
+
+```sh
+kubectl get svc ruby-app-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
+```
+
+Use this IP address to configure your DNS. This part heavily depends on your preferences and domain provider. But in case you are not sure, just create an A record with a wildcard host like `*.<your-domain>` pointing to the external IP address you found above.
+
+Use `nslookup minimal-ruby-app-staging.<yourdomain>` to confirm that domain is assigned to the cluster IP.
+
+## Setup Auto Deploy
+
+Visit the home page of your GitLab.com project and press "Set up Auto Deploy" button.
+
+![auto deploy button](img/auto_deploy_btn.png)
+
+You will be redirected to the "New file" page where you can apply one of the Auto Deploy templates. Select "Kubernetes" to apply the template, then in the file, replace `domain.example.com` with your domain name and make any other adjustments you need.
+
+![auto deploy template](img/auto_deploy_dropdown.png)
+
+Change the target branch to `master`, and submit your changes. This should create
+a new pipeline with several jobs. If you made only the domain name change, the
+pipeline will have three jobs: `build`, `staging`, and `production`.
+
+The `build` job will create a Docker image with your new change and push it to
+the GitLab Container Registry. The `staging` job will deploy this image on your
+cluster. Once the deploy job succeeds you should be able to see your application by
+visiting the Kubernetes dashboard. Select the namespace of your project, which
+will look like `ruby-autodeploy-23`, but with a unique ID for your project, and
+your app will be listed as "staging" under the "Deployment" tab.
+
+Once its ready - just visit http://minimal-ruby-app-staging.yourdomain.com to see “Hello, world!”