Refactor the GitLab k8s installation method

3 files changed, 68 insertions, 60 deletions

diff --git a/doc/install/README.md b/doc/install/README.md
index 66a1941de60..9a96ab82cf0 100644
--- a/doc/install/README.md
+++ b/doc/install/README.md
@@ -5,69 +5,82 @@ description: Read through the GitLab installation methods.
 
 # Installation
 
+GitLab can be installed in most GNU/Linux distributions and in a number
+of cloud providers.
+
 ## Requirements
 
-Before installing GitLab, make sure to check the [requirements documentation](install/requirements.md)
+Before installing GitLab, make sure to check the [requirements documentation](requirements.md)
 which includes useful information on the supported Operating Systems as well as
 the hardware requirements.
 
 ## Installation methods
 
-### Choose the best installation method for your needs
-
 To get the best experience from GitLab you need to balance:
 
-1. performance
-1. reliability
-1. ease of administration (backups, upgrades and troubleshooting)
-1. cost of hosting
+1. Performance
+1. Reliability
+1. Ease of administration (backups, upgrades and troubleshooting)
+1. Cost of hosting
 
 TIP: **If in doubt, choose Omnibus:**
-For nearly all GitLab installations we recommend using an Omnibus package **GitLab can support up to 40,000 users on a single box Omnibus installation** with enough CPU and RAM. (See [requirements documentation](install/requirements.md))
+Our Omnibus GitLab packages are mature, scalable, support
+[high availability](../administration/high_availability/README.md) and are used
+today on GitLab.com. Our Helm charts are recommended for those who are familiar
+with Kubernetes.
 
-### Omnibus (recommended)
+### Install GitLab using the Omnibus GitLab package (recommended)
 
-- [Installation using the Omnibus packages](https://about.gitlab.com/downloads/) -
-  Install GitLab using our official deb/rpm repositories. This is the
-  recommended way.
+This installation method [uses the Omnibus GitLab package](https://about.gitlab.com/install/),
+using our official deb/rpm repositories. This is the recommended way.
 
-If you need additional flexibility and resilience you can scale GitLab Omnibus as described in our [Scaling and High Availability docs](administration/high_availability/README.md).
+If you need additional flexibility and resilience, we recommend deploying
+GitLab as described in our [High Availability documentation](../administration/high_availability/README.md).
 
-### Alternative Omnibus 
+### Alternative to Omnibus GitLab
 
-- [Installation from source](installation.md) - Install GitLab from source.
+If the GitLab Omnibus package is not available in your distribution, you can
+choose between:
+
+- [Installation from source](installation.md): Install GitLab from source.
   Useful for unsupported systems like *BSD. For an overview of the directory
   structure, read the [structure documentation](structure.md).
-- [Docker](docker.md) - Install GitLab Omnibus using Docker.
-
-### Kubernetes via GitLab Helm charts
+  While the recommended database is PostgreSQL, we provide information to install
+  GitLab [using MySQL](database_mysql.md).
+- [Docker](docker.md): Install Omnibus GitLab using Docker.
 
-CAUTION: **If in doubt, choose Omnibus:**
-Installing GitLab in Kubernetes is not currently recommended unless you're experienced with Kubernetes and you know why you need GitLab to be installed in Kubernetes.
+### Install GitLab on Kubernetes via the GitLab Helm charts
 
-GitLab is committed to Kubernetes as a foundational technology. There are three areas where Kubernetes intersects with GitLab:
+NOTE: **If in doubt, choose Omnibus:**
+We recommend being familiar with Kubernetes before using it to deploy GitLab in
+production. The methods for management, observability, and some concepts are
+different than traditional deployments.
 
-1. Deploying your applications from GitLab projects to Kubernetes (e.g. see [Auto DevOps](autodevops/index.md))
-1. [Running GitLab CI Runners in a Kubernetes Cluster](runner/install/kubernetes.md)
-1. Installing GitLab in Kubernetes
+GitLab is committed to Kubernetes as a foundational technology. There are three
+areas where Kubernetes intersects with GitLab:
 
-While we recommend using GitLab for the first two points above, for most scenarios we do not currently recommend installing GitLab in Kubernetes. There are a number of trade-offs that you need to be aware of that may not be immediately obvious and could prevent you getting the best experience from GitLab:
+1. Deploying your applications from GitLab projects to Kubernetes (e.g., see [Auto DevOps](../topics/autodevops/index.md)).
+1. [Running GitLab CI/CD Runners in a Kubernetes Cluster](https://docs.gitlab.com/runner/install/kubernetes.html).
+1. Installing GitLab in Kubernetes.
 
-1. Configuration of features such as object storage, backups and certificates can be more challenging
-1. Administration and troubleshooting requires Kubernetes knowledge
-1. It can be more expensive for smaller installations. You need multiple nodes for a basic installation when a single box Omnibus installation would work well
-1. There are some feature [limitations to be aware of](install/kubernetes/gitlab_chart.md#limitations)
+While we recommend using GitLab for the first two points above, for most scenarios
+we do not currently recommend installing GitLab in Kubernetes. There are a number
+of trade-offs that you need to be aware of that may not be immediately obvious
+and could prevent you getting the best experience from GitLab:
 
- Unless you are experienced with Kubernetes and have a very large user-base (thousands of users) we recommend an Omnibus installation at this time.
+- Configuration of features such as object storage and backups can be more challenging.
+- Administration and troubleshooting requires Kubernetes knowledge.
+- It can be more expensive for smaller installations. The default installation
+  requires more resources than a single node Omnibus deployment, as most services
+  are deployed in a redundant fashion.
+- There are some feature [limitations to be aware of](kubernetes/gitlab_chart.md#limitations).
 
- Over time Kubernetes will mature, hosting options will improve, and GitLab Helm charts and documentation will be refined in production environments.  We'll update our recommendations as conditions change.
+If you're happy with the trade-offs, you can use our official Helm charts to get
+started and [install GitLab in Kubernetes](kubernetes/index.md).
 
-If you're happy with the trade-offs, you can use our official Helm charts to get started with GitLab on Kubernetes:
+### Install GitLab on cloud providers
 
-- [Install in Kubernetes](kubernetes/index.md): Install GitLab into a Kubernetes
-  Cluster using our official Helm Chart Repository.
-
-### Guides to install GitLab on cloud providers
+GitLab can be installed on a variety of cloud providers:
 
 - [Install on AWS](aws/index.md): Install GitLab on AWS using the community AMIs that GitLab provides.
 - [Install GitLab on Google Cloud Platform](google_cloud_platform/index.md)
@@ -78,13 +91,5 @@ If you're happy with the trade-offs, you can use our official Helm charts to get
 the full process of installing GitLab on Google Kubernetes Engine (GKE), pushing an application to GitLab, building the app with GitLab CI/CD, and deploying to production.
 - [Getting started with GitLab and DigitalOcean](https://about.gitlab.com/2016/04/27/getting-started-with-gitlab-and-digitalocean/): requirements, installation process, updates.
 - [Demo: Cloud Native Development with GitLab](https://about.gitlab.com/2017/04/18/cloud-native-demo/): video demonstration on how to install GitLab on Kubernetes, build a project, create Review Apps, store Docker images in Container Registry, deploy to production on Kubernetes, and monitor with Prometheus.
-- _Testing only!_ [DigitalOcean and Docker Machine](digitaloceandocker.md) -
+- _Testing only!_ [DigitalOcean and Docker Machine](digitaloceandocker.md):
   Quickly test any version of GitLab on DigitalOcean using Docker Machine.
-
-## Database
-
-While the recommended database is PostgreSQL, we provide information to install
-GitLab using MySQL. Check the [MySQL documentation](database_mysql.md) for more
-information.
-
-[methods]: https://about.gitlab.com/installation/
diff --git a/doc/install/kubernetes/gitlab_chart.md b/doc/install/kubernetes/gitlab_chart.md
index 5f3f49bddb5..316eb788009 100644
--- a/doc/install/kubernetes/gitlab_chart.md
+++ b/doc/install/kubernetes/gitlab_chart.md
@@ -3,8 +3,11 @@
 This is the official way to install GitLab on a cloud native environment.
 For more information on other available GitLab Helm Charts, see the [charts overview](index.md#chart-overview).
 
-TIP: **If in doubt, choose Omnibus:**
-For nearly all GitLab installations we recommend using an Omnibus package. **GitLab can support up to 40,000 users on a single box Omnibus installation** with enough CPU and RAM. (See [requirements documentation](install/requirements.md)). Before starting to install GitLab in Kubernetes, please read [Choose the best installation method for your needs](install/README.md)
+TIP: **If in doubt, choose Omnibus GitLab:**
+Our [Omnibus GitLab packages](../README.md#install-gitlab-using-the-omnibus-gitlab-package-recommended)
+are mature, scalable, support [high availability](../../administration/high_availability/README.md)
+and are used today on GitLab.com. Our Helm charts are recommended for those who
+are familiar with Kubernetes.
 
 ## Introduction
 
diff --git a/doc/install/kubernetes/index.md b/doc/install/kubernetes/index.md
index 2c44437d74d..174f0a5f366 100644
--- a/doc/install/kubernetes/index.md
+++ b/doc/install/kubernetes/index.md
@@ -4,14 +4,17 @@ description: 'Read through the different methods to deploy GitLab on Kubernetes.
 
 # Installing GitLab on Kubernetes
 
-TIP: **If in doubt, choose Omnibus:**
-For nearly all GitLab installations we recommend using an Omnibus package. **GitLab can support up to 40,000 users on a single box Omnibus installation** with enough CPU and RAM. (See [requirements documentation](install/requirements.md)). Before starting to install GitLab in Kubernetes, please read [Choose the best installation method for your needs](install/README.md)
+TIP: **If in doubt, choose Omnibus GitLab:**
+Our [Omnibus GitLab packages](../README.md#install-gitlab-using-the-omnibus-gitlab-package-recommended)
+are mature, scalable, support [high availability](../../administration/high_availability/README.md)
+and are used today on GitLab.com. Our Helm charts are recommended for those who
+are familiar with Kubernetes.
 
 The easiest method to deploy GitLab on [Kubernetes](https://kubernetes.io/) is
-to take advantage of GitLab's Helm charts. [Helm] is a package
-management tool for Kubernetes, allowing apps to be easily managed via their
-Charts. A [Chart] is a detailed description of the application including how it
-should be deployed, upgraded, and configured.
+to take advantage of GitLab's Helm charts. [Helm](https://github.com/kubernetes/helm/blob/master/README.md)
+is a package management tool for Kubernetes, allowing apps to be easily managed via their
+Charts. A [Chart](https://github.com/kubernetes/charts) is a detailed description
+of the application including how it should be deployed, upgraded, and configured.
 
 ## GitLab Chart
 
@@ -40,24 +43,21 @@ Learn more about [gitlab-runner chart](gitlab_runner_chart.md).
 
 CAUTION: **Deprecated:**
 These charts are **deprecated**. We recommend using the [GitLab Chart](gitlab_chart.md)
-instead. (**Note:** Omnibus is still the recommended installation for most use cases - only the Omnibus Helm chart is deprecated.)
+instead.
 
 ### GitLab-Omnibus Chart
 
 This chart is based on the [GitLab Omnibus Docker images](https://docs.gitlab.com/omnibus/docker/).
 It deploys and configures nearly all features of GitLab, including:
 
-- a [GitLab Runner](https://docs.gitlab.com/runner/)
+- [A GitLab Runner](https://docs.gitlab.com/runner/)
 - [Container Registry](../../user/project/container_registry.html#gitlab-container-registry)
 - [Mattermost](https://docs.gitlab.com/omnibus/gitlab-mattermost/)
-- [automatic SSL](https://github.com/kubernetes/charts/tree/master/stable/kube-lego)
-- and an [NGINX load balancer](https://github.com/kubernetes/ingress/tree/master/controllers/nginx).
+- [Automatic SSL](https://github.com/kubernetes/charts/tree/master/stable/kube-lego)
+- [An NGINX load balancer](https://github.com/kubernetes/ingress/tree/master/controllers/nginx)
 
 Learn more about the [gitlab-omnibus chart](gitlab_omnibus.md).
 
 ### Community Contributed Charts
 
 The community has also contributed GitLab [CE](https://github.com/kubernetes/charts/tree/master/stable/gitlab-ce) and [EE](https://github.com/kubernetes/charts/tree/master/stable/gitlab-ee) charts to the [Helm Stable Repository](https://github.com/kubernetes/charts#repository-structure). These charts are [deprecated](https://github.com/kubernetes/charts/issues/1138) in favor of the [official Chart](gitlab_chart.md).
-
-[chart]: https://github.com/kubernetes/charts
-[helm]: https://github.com/kubernetes/helm/blob/master/README.md