Merge branch 'tatkins-installation-method-docs' into 'master'

Add docs to help choose the best GitLab installation method

Closes #54308

See merge request gitlab-org/gitlab-ce!23254

4 files changed, 93 insertions, 67 deletions

diff --git a/doc/install/README.md b/doc/install/README.md
index 92116305775..ae48306e65e 100644
--- a/doc/install/README.md
+++ b/doc/install/README.md
@@ -5,8 +5,25 @@ description: Read through the GitLab installation methods.
 
 # Installation
 
-GitLab can be installed via various ways. Check the [installation methods][methods]
-for an overview.
+GitLab can be installed in most GNU/Linux distributions and in a number
+of cloud providers. To get the best experience from GitLab you need to balance
+performance, reliability, ease of administration (backups, upgrades and troubleshooting),
+and cost of hosting.
+
+There are many ways you can install GitLab depending on your platform:
+
+1. **Omnibus Gitlab**: The official deb/rpm packages that contain a bundle of GitLab
+   and the various components it depends on like PostgreSQL, Redis, Sidekiq, etc.
+1. **GitLab Helm chart**: The cloud native Helm chart for installing GitLab and all
+   its components on Kubernetes.
+1. **Docker**: The Omnibus GitLab packages dockerized.
+1. **Source**: Install GitLab and all its components from scratch.
+
+TIP: **If in doubt, choose Omnibus:**
+The Omnibus GitLab packages are mature, scalable, support
+[high availability](../administration/high_availability/README.md) and are used
+today on GitLab.com. The Helm charts are recommended for those who are familiar
+with Kubernetes.
 
 ## Requirements
 
@@ -14,36 +31,58 @@ Before installing GitLab, make sure to check the [requirements documentation](re
 which includes useful information on the supported Operating Systems as well as
 the hardware requirements.
 
-## Installation methods
-
-- [Installation using the Omnibus packages](https://about.gitlab.com/downloads/) -
-  Install GitLab using our official deb/rpm repositories. This is the
-  recommended way.
-- [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 using Docker.
-
-## Install GitLab on cloud providers
-
-- [Installing in Kubernetes](kubernetes/index.md): Install GitLab into a Kubernetes
-  Cluster using our official Helm Chart Repository.
-- [Install GitLab on OpenShift](openshift_and_gitlab/index.md)
-- [Install GitLab on DC/OS](https://mesosphere.com/blog/gitlab-dcos/) via [GitLab-Mesosphere integration](https://about.gitlab.com/2016/09/16/announcing-gitlab-and-mesosphere/)
-- [Install GitLab on Azure](azure/index.md)
-- [Install GitLab on Google Cloud Platform](google_cloud_platform/index.md)
-- [Install GitLab on Google Kubernetes Engine (GKE)](https://about.gitlab.com/2017/01/23/video-tutorial-idea-to-production-on-google-container-engine-gke/): video tutorial on
-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.
-- [Install on AWS](aws/index.md): Install GitLab on AWS using the community AMIs that GitLab provides.
-- [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) -
-  Quickly test any version of GitLab on DigitalOcean using Docker Machine.
+## Installing GitLab using the Omnibus GitLab package (recommended)
+
+The Omnibus GitLab package uses our official deb/rpm repositories. This is
+recommended for most users.
+
+If you need additional flexibility and resilience, we recommend deploying
+GitLab as described in our [High Availability documentation](../administration/high_availability/README.md).
+
+[**> Install GitLab using the Omnibus GitLab package.**](https://about.gitlab.com/install/)
+
+## Installing GitLab on Kubernetes via the GitLab Helm charts
+
+NOTE: **Kubernetes experience required:**
+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.
+
+When installing GitLab on Kubernetes, there are some trade-offs that you
+need to be aware of:
 
-## Database
+- 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).
 
-While the recommended database is PostgreSQL, we provide information to install
-GitLab using MySQL. Check the [MySQL documentation](database_mysql.md) for more
-information.
+[**> Install GitLab on Kubernetes using the GitLab Helm charts.**](kubernetes/index.md)
 
-[methods]: https://about.gitlab.com/installation/
+## Installing GitLab with Docker
+
+GitLab maintains a set of official Docker images based on the Omnibus GitLab package.
+
+[**> Install GitLab using the official GitLab Docker images.**](docker.md)
+
+## Installing GitLab from source
+
+If the GitLab Omnibus package is not available in your distribution, you can
+install GitLab from source: Useful for unsupported systems like *BSD. For an
+overview of the directory structure, read the [structure documentation](structure.md).
+
+[**> Install GitLab from source.**](installation.md)
+
+## Installing GitLab on cloud providers
+
+GitLab can be installed on a variety of cloud providers by using any of
+the above methods, provided the cloud provider supports it.
+
+- [Install on AWS](aws/index.md): Install Omnibus GitLab on AWS using the community AMIs that GitLab provides.
+- [Install GitLab on Google Cloud Platform](google_cloud_platform/index.md): Install Omnibus GitLab on a VM in GCP.
+- [Install GitLab on Azure](azure/index.md): Install Omnibus GitLab from Azure Marketplace.
+- [Install GitLab on OpenShift](openshift_and_gitlab/index.md): Install GitLab using the Docker image on OpenShift.
+- [Install GitLab on DC/OS](https://mesosphere.com/blog/gitlab-dcos/): Install GitLab on Mesosphere DC/OS via the [GitLab-Mesosphere integration](https://about.gitlab.com/2016/09/16/announcing-gitlab-and-mesosphere/).
+- [Install GitLab on DigitalOcean](https://about.gitlab.com/2016/04/27/getting-started-with-gitlab-and-digitalocean/): Install Omnibus GitLab on DigitalOcean.
+- _Testing only!_ [DigitalOcean and Docker Machine](digitaloceandocker.md):
+  Quickly test any version of GitLab on DigitalOcean using Docker Machine.
diff --git a/doc/install/docker.md b/doc/install/docker.md
index e90f6645b0c..d0129f0f5c4 100644
--- a/doc/install/docker.md
+++ b/doc/install/docker.md
@@ -8,9 +8,9 @@ GitLab provides official Docker images to allowing you to easily take advantage
 
 GitLab maintains a set of [official Docker images](https://hub.docker.com/r/gitlab) based on our [Omnibus GitLab package](https://docs.gitlab.com/omnibus/README.html). These images include:
 
-- [GitLab Community Edition](https://hub.docker.com/r/gitlab/gitlab-ce/).
-- [GitLab Enterprise Edition](https://hub.docker.com/r/gitlab/gitlab-ee/).
-- [GitLab Runner](https://hub.docker.com/r/gitlab/gitlab-runner/).
+- [GitLab Community Edition](https://hub.docker.com/r/gitlab/gitlab-ce/)
+- [GitLab Enterprise Edition](https://hub.docker.com/r/gitlab/gitlab-ee/)
+- [GitLab Runner](https://hub.docker.com/r/gitlab/gitlab-runner/)
 
 A [complete usage guide](https://docs.gitlab.com/omnibus/docker/) to these images is available, as well as the [Dockerfile used for building the images](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/docker).
 
diff --git a/doc/install/kubernetes/gitlab_chart.md b/doc/install/kubernetes/gitlab_chart.md
index 5749eb0a9ec..85fa04731eb 100644
--- a/doc/install/kubernetes/gitlab_chart.md
+++ b/doc/install/kubernetes/gitlab_chart.md
@@ -1,7 +1,13 @@
 # GitLab Helm Chart
 
-This is the official and recommended 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).
+This is the official way to install GitLab on a cloud native environment.
+
+NOTE: **Kubernetes experience required:**
+Our Helm charts are recommended for those who are familiar with Kubernetes.
+If you're not sure if Kubernetes is for you, 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.
 
 ## Introduction
 
diff --git a/doc/install/kubernetes/index.md b/doc/install/kubernetes/index.md
index 69171fbb341..37f5451b792 100644
--- a/doc/install/kubernetes/index.md
+++ b/doc/install/kubernetes/index.md
@@ -4,11 +4,18 @@ description: 'Read through the different methods to deploy GitLab on Kubernetes.
 
 # Installing GitLab on Kubernetes
 
+NOTE: **Kubernetes experience required:**
+Our Helm charts are recommended for those who are familiar with Kubernetes.
+If you're not sure if Kubernetes is for you, 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.
+
 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
 
@@ -32,29 +39,3 @@ and you'd like to leverage the Runner's
 it can be deployed with the GitLab Runner chart.
 
 Learn more about [gitlab-runner chart](gitlab_runner_chart.md).
-
-## Deprecated Charts
-
-CAUTION: **Deprecated:**
-These charts are **deprecated**. We recommend using the [GitLab Chart](gitlab_chart.md)
-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/)
-- [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).
-
-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