Clarify some more Auto DevOps

Notable changes:

- How to use Auto DevOps for existing projects
- Document all environment variables

2 files changed, 112 insertions, 66 deletions

diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md
index 876cfa9c6e3..c9d32cacb55 100644
--- a/doc/topics/autodevops/index.md
+++ b/doc/topics/autodevops/index.md
@@ -1,19 +1,16 @@
 # Auto DevOps
 
-> [Introduced][ce-37115] in GitLab 10.0, Auto DevOps is currently in Beta and
-_not recommended for production use_.
+> [Introduced][ce-37115] in GitLab 10.0, Auto DevOps is currently in **Beta**.
 
 With Auto DevOps, the software development process becomes easier to set up
-as every project can have a complete workflow from build to deploy, with no to
-minimal configuration. Comprised by a set of stages, Auto DevOps brings the best
+as every project can have a complete workflow from build to deploy, with minimal
+to zero configuration. Comprised by a set of stages, Auto DevOps brings the best
 practices to your project in an easy and default way.
 
 ## Overview
 
 The power of Auto DevOps lies in the fact that it can set up your project's
 CI/CD without the need to provide your own `.gitlab-ci.yml`.
-On new projects where no `.gitlab-ci.yml` is detected, a banner with info how
-to enable Auto DevOps will appear.
 
 The stages of Auto DevOps include:
 
@@ -35,15 +32,12 @@ for using Auto DevOps with GitLab.com and an external Kubernetes cluster on
 Google Cloud.
 
 For self-hosted installations, the easiest way to make use of Auto DevOps is to
-install GitLab inside a Kubernetes cluster using the [GitLab-Omnibus Helm
+install GitLab inside a Kubernetes cluster using the [Omnibus GitLab Helm
 Chart](../../install/kubernetes/gitlab_omnibus.md) which automatically installs
 and configures everything you need.
 
 ## Prerequisites
 
-| Stage | Requirements |
-| ----- | ------------ |
-
 You will need one or more GitLab Runners, a Kubernetes cluster, and Prometheus
 installed in the cluster to make full use of Auto DevOps. If you do not have
 Kubernetes or Prometheus installed, then Auto Review Apps, Auto Deploy, and Auto
@@ -68,7 +62,7 @@ you should take these prerequisites into account:
    for the entire GitLab instance, or [specific Runners](../../ci/runners/README.md#registering-a-specific-runner)
    that are assigned to specific projects.
 
-1. **Kubernetes** - To enable deploys, you will need Kubernetes 1.5+, with NGINX
+1. **Kubernetes** - To enable deployments, you will need Kubernetes 1.5+, with NGINX
    ingress and wildcard SSL termination, for example using the
    [`nginx-ingress`](https://github.com/kubernetes/charts/tree/master/stable/nginx-ingress)
    and [`kube-lego`](https://github.com/kubernetes/charts/tree/master/stable/kube-lego)
@@ -88,10 +82,42 @@ you should take these prerequisites into account:
 
 ## Enabling Auto DevOps
 
-In your GitLab.com project, go to **Settings > CI/CD** and find the Auto DevOps
-section. Select "Enable Auto DevOps", add in your base domain, and save.
+NOTE: **Note:**
+If you haven't done already, read the [prerequisites](#prerequisites) to make
+full use of Auto DevOps. If this is your fist time, we recommend you follow the
+[quick start guide](#quick-start).
+
+### New projects
+
+To enable Auto DevOps for new projects in GitLab:
+
+1. Go to your project's **Settings > CI/CD > General pipelines settings** and
+   find the Auto DevOps section. On new projects where no `.gitlab-ci.yml` is
+   detected, a banner with info how to enable Auto DevOps will appear. Clicking
+   on that link will take you straight to the relevant CI/CD settings page.
+1. Select "Enable Auto DevOps".
+1. Add in your base domain that will be used by Kubernetes to deploy your
+   application.
+1. Hit **Save changes** for the changes to take effect.
+
+Finally, a pipeline needs to be triggered. Since new projects don't have a
+`.gitlab-ci.yml`, you need to either push a change to the repository or
+manually visit `https://example.gitlab.com/<username>/<project>/pipelines/new`,
+and create one for the `master` branch.
 
-![auto devops settings](img/auto_devops_settings.png)
+### Existing projects
+
+To enable Auto DevOps for existing projects in GitLab:
+
+1. Go to your project's **Settings > CI/CD > General pipelines settings** and
+   find the Auto DevOps section.
+1. Select "Enable Auto DevOps".
+1. Add in your base domain that will be used by Kubernetes to deploy your
+   application.
+1. Hit **Save changes** for the changes to take effect.
+
+Now all you need to do is either remove your existing `.gitlab-ci.yml` or
+[customize it](#customizing-gitlab-ci-yml) to your liking.
 
 ## Stages of Auto DevOps
 
@@ -133,6 +159,9 @@ affiliated with Code Climate.*
 
 ### Auto Review Apps
 
+>**Note:**
+Your apps should be manipulated only using Helm and not directly from Kubernetes.
+
 Auto Review Apps create a [Review App][review-app] for each branch. Review Apps
 are temporary application environments based on the branch's code so developers,
 designers, QA, product managers, and other reviewers can actually see and
@@ -152,6 +181,9 @@ DevOps setting), the job will silently be skipped.
 
 ### Auto Deploy
 
+>**Note:**
+Your apps should be manipulated only using Helm and not directly from Kubernetes.
+
 After a branch or merge request is merged into `master`, Auto Deploy deploys the
 application to a `production` environment in the Kubernetes cluster, with a
 namespace based on the project name and unique project ID. e.g. `project-4321`.
@@ -172,8 +204,7 @@ Monitoring uses [Prometheus](../../user/project/integrations/prometheus.md) to
 get system metrics such as CPU and memory usage directly from
 [Kubernetes](../../user/project/integrations/prometheus_library/kubernetes.md),
 and response metrics such as HTTP error rates, latency, and throughput from the
-[NGINX
-server](../../user/project/integrations/prometheus_library/nginx_ingress.md).
+[NGINX server](../../user/project/integrations/prometheus_library/nginx_ingress.md).
 
 * Response Metrics: latency, throughput, error rate
 * System Metrics: CPU utilization, memory utilization
@@ -238,43 +269,58 @@ deployed.
 **Project variable** - Create a project variable `AUTO_DEVOPS_CHART` with the
 URL of a custom chart to use.
 
-### Enable staging, canaries, and more with custom `.gitlab-ci.yml`
+### Customizing `.gitlab-ci.yml`
 
 If you want to modify the CI/CD pipeline used by Auto DevOps, you can copy the
-Auto DevOps template into your project's repo and edit as you see fit.
+[Auto DevOps template] into your project's repo and edit as you see fit.
+
+Assuming that your project is new or it doesn't have a `.gitlab-ci.yml` file
+present:
 
-From your project home page, click on the `Set up CI` button, or click on the `+`
-button and `New file` and pick `.gitlab-ci.yml` as the template type, or view an
-existing `.gitlab-ci.yml` file. Then select "Auto DevOps" from the template
-dropdown. You will then be able to edit or add any jobs needed.
+1. From your project home page, click on the 'Set up CI' button, or click on the
+   plus button and ('+'), then 'New file' and pick `.gitlab-ci.yml` as the
+   template type.
+1. Select "Auto-DevOps" from the template dropdown.
+1. Edit the template or add any jobs needed.
+1. Give an appropriate commit message and hit 'Commit changes'.
 
-For example, if you want deploys to go to a staging environment instead of
-directly to a production environment, you can enable the `staging` job by
+TIP: **Tip:** The Auto DevOps template includes useful comments to help you
+customize it. For example, if you want deployments to go to a staging environment
+instead of directly to a production one, you can enable the `staging` job by
 renaming `.staging` to `staging`. Then make sure to uncomment the `when` key of
 the `production` job to turn it into a manual action instead of deploying
 automatically.
 
-### PostgreSQL Database Support
+### PostgreSQL database support
 
 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
+[PostgreSQL][postgresql] is provisioned by default. The credentials to access
+the database are preconfigured, but can be customized by setting the associated
+[variables](#environment-variables). These credentials can be used for defining a
 `DATABASE_URL` of the format:
-`postgres://user:password@postgres-host:postgres-port/postgres-database`.
 
-PostgreSQL provisioning can be disabled by creating a project variable
-`POSTGRES_ENABLED` set to `false`.
+```yaml
+postgres://user:password@postgres-host:postgres-port/postgres-database
+```
 
-#### PostgreSQL Variables
+### Environment variables
 
 Any variables set at the project or group level will override variables set in
-the CI/CD configuration.
-
-1. `POSTGRES_ENABLED: "false"`: 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
+the CI/CD configuration. The following are supported:
+
+| **Variable** | **Description** |
+| ------------ | --------------- |
+| `POSTGRES_ENABLED`  | Whether PostgreSQL is enabled, defaults to `"true"`. Set to `false` to disable the automatic deployment of PostgreSQL. |
+| `POSTGRES_USER`     | The PostgreSQL user, defaults to `user`. Set it to use a custom username. |
+| `POSTGRES_PASSWORD` | The PostgreSQL password, defaults to `testing-password`. Set it to use a custom password. |
+| `POSTGRES_DB`       | The PostgreSQL database name, defaults to the value of [`$CI_ENVIRONMENT_SLUG`](../../ci/variables/README.md#predefined-variables-environment-variables). Set it to use a custom database name. |
+| `*_REPLICAS`        | The number of replicas to scale your app, defaults to 1. The format of this variable is `<env>_REPLICAS` or `<track>_<env>_REPLICAS` so that any environment can set the number of replicas they want to use. The two most common ones are `PRODUCTION_REPLICAS` and `CANARY_PRODUCTION_REPLICAS` as described below.
+| `PRODUCTION_REPLICAS` | The number of replica sets to deploy in the production environment, defaults to 1. This variable can be used only when `environment: production` is set in your deploy job in `.gitlab-ci.yml`. Optionally, the label `track: stable` can be set in the app definition in Kubernetes. If not set, Auto DevOps will default to `stable`. |
+| `CANARY_PRODUCTION_REPLICAS` | The number of canary replica sets to deploy for [Canary Deployments](https://docs.gitlab.com/ee/user/project/canary_deployments.html). This variable can be used only when `environment: production` is set under a job in `.gitlab-ci.yml` **and** the label `track: canary` is defined in the app definition in Kubernetes.
+
+TIP: **Tip:** Regarding the replica variables (`*_REPLICAS`), technically, you
+could name your track `beta` or `whatever`. The Auto DevOps template defaults
+to `canary` and empty for canary and stable deployments respectively.
 
 ## Currently supported languages
 
@@ -289,19 +335,19 @@ multi-buildpack does not.
 As of GitLab 10.0, the supported buildpacks are:
 
 ```
-* heroku-buildpack-multi     v1.0.0
-* heroku-buildpack-ruby      v168
-* heroku-buildpack-nodejs    v99
-* heroku-buildpack-clojure   v77
-* heroku-buildpack-python    v99
-* heroku-buildpack-java      v53
-* heroku-buildpack-gradle    v23
-* heroku-buildpack-scala     v78
-* heroku-buildpack-play      v26
-* heroku-buildpack-php       v122
-* heroku-buildpack-go        v72
-* heroku-buildpack-erlang    fa17af9
-* buildpack-nginx            v8
+- heroku-buildpack-multi     v1.0.0
+- heroku-buildpack-ruby      v168
+- heroku-buildpack-nodejs    v99
+- heroku-buildpack-clojure   v77
+- heroku-buildpack-python    v99
+- heroku-buildpack-java      v53
+- heroku-buildpack-gradle    v23
+- heroku-buildpack-scala     v78
+- heroku-buildpack-play      v26
+- heroku-buildpack-php       v122
+- heroku-buildpack-go        v72
+- heroku-buildpack-erlang    fa17af9
+- buildpack-nginx            v8
 ```
 
 ## Restrictions
@@ -324,7 +370,18 @@ Container Registry. **Restarting a pod, scaling a service, or other actions whic
 require on-going access to the registry will fail**. On-going secure access is
 planned for a subsequent release.
 
-## Disable the banner instance wide
+## Troubleshooting
+
+- Auto Build and Auto Test may fail in detecting your language/framework. There
+  may be no buildpack for your application, or your application may be missing the
+  key files the buildpack is looking for. For example, for ruby apps, you must
+  have a `Gemfile` to be properly detected, even though it is possible to write a
+  Ruby app without a `Gemfile`. Try specifying a [custom
+  buildpack](#custom-buildpacks).
+- Auto Test may fail because of a mismatch between testing frameworks. In this
+  case, you may need to customize your `.gitlab-ci.yml` with your test commands.
+
+### Disable the banner instance wide
 
 If an administrator would like to disable the banners on an instance level, this
 feature can be disabled either through the console:
@@ -341,20 +398,10 @@ Or through the HTTP API with the admin access token:
 curl --data "value=true" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/features/auto_devops_banner_disabled
 ```
 
-## Troubleshooting
-
-- Auto Build and Auto Test may fail in detecting your language/framework. There
-  may be no buildpack for your application, or your application may be missing the
-  key files the buildpack is looking for. For example, for ruby apps, you must
-  have a `Gemfile` to be properly detected, even though it is possible to write a
-  Ruby app without a `Gemfile`. Try specifying a [custom
-  buildpack](#custom-buildpacks).
-- Auto Test may fail because of a mismatch between testing frameworks. In this
-  case, you may need to customize your `.gitlab-ci.yml` with your test commands.
-
 [ce-37115]: https://gitlab.com/gitlab-org/gitlab-ce/issues/37115
 [kubernetes-service]: ../../user/project/integrations/kubernetes.md
 [docker-in-docker]: ../../docker/using_docker_build.md#use-docker-in-docker-executor
 [review-app]: ../../ci/review_apps/index.md
 [container-registry]: ../../user/project/container_registry.md
 [postgresql]: https://www.postgresql.org/
+[Auto DevOps template]: https://gitlab.com/gitlab-org/gitlab-ci-yml/blob/master/Auto-DevOps.gitlab-ci.yml
diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md
index 564dd3222ac..c51a8cbef98 100644
--- a/doc/topics/autodevops/quick_start_guide.md
+++ b/doc/topics/autodevops/quick_start_guide.md
@@ -1,7 +1,6 @@
 # Auto DevOps: quick start guide
 
-> [Introduced][ce-37115] in GitLab 10.0. Auto DevOps is currently in Beta and
-**not recommended for production use**.
+> [Introduced][ce-37115] in GitLab 10.0, Auto DevOps is currently in **Beta**.
 
 This is a step-by-step guide to deploying a project hosted on GitLab.com to
 Google Cloud, using Auto DevOps.
@@ -117,7 +116,7 @@ section. Select "Enable Auto DevOps", add in your base domain, and save.
 
 Next, a pipeline needs to be triggered. Since the test project doesn't have a
 `.gitlab-ci.yml`, you need to either push a change to the repository or
-manually visit `https://gitlab.com/<username>/minimal-ruby-app/pipelines/run`,
+manually visit `https://gitlab.com/<username>/minimal-ruby-app/pipelines/new`,
 where `<username>` is your username.
 
 This will create a new pipeline with several jobs: `build`, `test`, `codequality`,