Merge branch '37295-further-improvements-to-helm-chart-documentation-docs' into 'master'

Further improvements to Helm Chart documentation - docs

Closes #37295

See merge request !13964

3 files changed, 23 insertions, 28 deletions

diff --git a/doc/install/kubernetes/gitlab_chart.md b/doc/install/kubernetes/gitlab_chart.md
index 6bcc58bb805..a339bc23809 100644
--- a/doc/install/kubernetes/gitlab_chart.md
+++ b/doc/install/kubernetes/gitlab_chart.md
@@ -1,9 +1,9 @@
 # GitLab Helm Chart
 > **Note:**
-* GitLab is working on a [cloud native set of Charts](https://gitlab.com/charts/helm.gitlab.io/blob/master/README.md) which will replace these.
+* > **Note**: This chart will be replaced by the [gitlab-omnibus](gitlab_omnibus.md) chart, once it supports [additional configuration options](https://gitlab.com/charts/charts.gitlab.io/issues/68).
 * Officially supported cloud providers are Google Container Service and Azure Container Service.
 
-The `gitlab` Helm chart deploys GitLab into your Kubernetes cluster.
+The `gitlab` Helm chart deploys just GitLab into your Kubernetes cluster, and offers extensive configuration options. For most deployments we recommended the [gitlab-omnibus](gitlab_omnibus.md) chart,
 
 This chart includes the following:
 
diff --git a/doc/install/kubernetes/gitlab_omnibus.md b/doc/install/kubernetes/gitlab_omnibus.md
index 8636ce2507c..d7fd8613633 100644
--- a/doc/install/kubernetes/gitlab_omnibus.md
+++ b/doc/install/kubernetes/gitlab_omnibus.md
@@ -21,13 +21,6 @@ The deployment includes:
 
 A video demonstration of GitLab utilizing this chart [is available](https://about.gitlab.com/handbook/sales/demo/).
 
-Terms:
-
--  Google Cloud Platform (**GCP**)
--  Google Container Engine (**GKE**)
--  Azure Container Service (**ACS**)
--  Kubernetes (**k8s**)
-
 ## Prerequisites
 
 - _At least_ 4 GB of RAM available on your cluster. 41GB of storage and 2 CPU are also required.
@@ -64,14 +57,14 @@ For production deployments of GitLab, we strongly recommend using an [External I
 ## Configuring and Installing GitLab
 
 For most installations, only two parameters are required:
-- `baseDomain`: the [base domain](#networking-prerequisites) with the wildcard host entry resolving to the `baseIP`. For example, `mycompany.io`.
-- `legoEmail`: Email address to use when requesting new SSL certificates from Let's Encrypt
+- `baseDomain`: the [base domain](#networking-prerequisites) of the wildcard host entry. For example, `mycompany.io` if the wild card entry is `*.mycompany.io`.
+- `legoEmail`: Email address to use when requesting new SSL certificates from Let's Encrypt.
 
 Other common configuration options:
-- `baseIP`: the desired [external IP address](#networking-prerequisites)
+- `baseIP`: the desired [external IP address](#external-ip-recommended)
 - `gitlab`: Choose the [desired edition](https://about.gitlab.com/products), either `ee` or `ce`. `ce` is the default.
 - `gitlabEELicense`: For Enterprise Edition, the [license](https://docs.gitlab.com/ee/user/admin_area/license.html) can be installed directly via the Chart
-- `provider`: Optimizes the deployment for a cloud provider. The default is `gke` for GCP, with `acs` also supported for Azure.
+- `provider`: Optimizes the deployment for a cloud provider. The default is `gke` for [Google Container Engine](https://cloud.google.com/container-engine/), with `acs` also supported for the [Azure Container Service](https://azure.microsoft.com/en-us/services/container-service/).
 
 For additional configuration options, consult the [values.yaml](https://gitlab.com/charts/charts.gitlab.io/blob/master/charts/gitlab-omnibus/values.yaml).
 
@@ -82,20 +75,16 @@ the value of the corresponding helm setting: `gitlabCEImage` or `gitabEEImage`.
 
 ```yaml
 gitlab: CE
-gitlabCEImage: gitlab/gitlab-ce:9.1.2-ce.0
-gitlabEEImage: gitlab/gitlab-ee:9.1.2-ee.0
+gitlabCEImage: gitlab/gitlab-ce:9.5.2-ce.0
+gitlabEEImage: gitlab/gitlab-ee:9.5.2-ee.0
 ```
 
 The different images can be found in the [gitlab-ce](https://hub.docker.com/r/gitlab/gitlab-ce/tags/) and [gitlab-ee](https://hub.docker.com/r/gitlab/gitlab-ee/tags/)
 repositories on Docker Hub.
 
-> **Note:**
-There is no guarantee that other release versions of GitLab, other than what are
-used by default in the chart, will be supported by a chart install.
-
 ### Persistent storage
 > **Note:**
-If you are using a machine type with support for less than 4 attached disks, like an Azure trial, you should disable dedicated storage for [Postgres and Redis](#persistent-storage).
+If you are using a machine type with support for less than 4 attached disks, like an Azure trial, you should disable dedicated storage for Postgres and Redis.
 
 By default, persistent storage is enabled for GitLab and the charts it depends
 on (Redis and PostgreSQL).
diff --git a/doc/install/kubernetes/index.md b/doc/install/kubernetes/index.md
index 8418b04936b..fb6c0c2d263 100644
--- a/doc/install/kubernetes/index.md
+++ b/doc/install/kubernetes/index.md
@@ -7,31 +7,37 @@ 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.
 
-GitLab provides [official Helm Charts](#official-gitlab-helm-charts-recommended) which is the recommended way to run GitLab with Kubernetes.
+GitLab provides [official Helm Charts](#official-gitlab-helm-charts-recommended) which are the recommended way to run GitLab within Kubernetes.
 
 There are also two other sets of charts:
 * Our [upcoming cloud native Charts](#upcoming-cloud-native-helm-charts), which are in development but will eventually replace the current official charts.
 * [Community contributed charts](#community-contributed-helm-charts). These charts should be considered deprecated, in favor of the official charts.
 
-## Official GitLab Helm Charts (Recommended)
+## Official GitLab Helm Charts
 
 These charts utilize our [GitLab Omnibus Docker images](https://docs.gitlab.com/omnibus/docker/README.html). You can report any issues and feedback related to these charts at
 https://gitlab.com/charts/charts.gitlab.io/issues.
 
-### Deploying GitLab on Kubernetes (Recommended)
-> *Note*: This chart will eventually be replaced by the [cloud native charts](#upcoming-cloud-native-helm-charts), which are presently in development.
+### Deploying GitLab on Kubernetes
+> **Note**: This chart will eventually be replaced by the [cloud native charts](#upcoming-cloud-native-helm-charts), which are presently in development.
 
-The best way to deploy GitLab on Kubernetes is to use the [gitlab-omnibus](gitlab_omnibus.md) chart. It includes everything needed to run GitLab, including: a [Runner](https://docs.gitlab.com/runner/), [Container Registry](https://docs.gitlab.com/ee/user/project/container_registry.html#gitlab-container-registry), [automatic SSL](https://github.com/kubernetes/charts/tree/master/stable/kube-lego), and an [Ingress](https://github.com/kubernetes/ingress/tree/master/controllers/nginx). This chart is in beta while [additional features](https://gitlab.com/charts/charts.gitlab.io/issues/68) are being completed.
+The best way to deploy GitLab on Kubernetes is to use the [gitlab-omnibus](gitlab_omnibus.md) chart.
+
+It includes everything needed to run GitLab, including: a [Runner](https://docs.gitlab.com/runner/), [Container Registry](https://docs.gitlab.com/ee/user/project/container_registry.html#gitlab-container-registry), [automatic SSL](https://github.com/kubernetes/charts/tree/master/stable/kube-lego), and an [Ingress](https://github.com/kubernetes/ingress/tree/master/controllers/nginx). This chart is in beta while [additional features](https://gitlab.com/charts/charts.gitlab.io/issues/68) are being completed.
 
 ### Deploying just the GitLab Runner
 
-To deploy just the GitLab Runner, utilize the [gitlab-runner](gitlab_runner_chart.md) chart. It offers a quick way to configure and deploy the Runner on Kubernetes, regardless of where your GitLab server may be running.
+To deploy just the [GitLab Runner](https://docs.gitlab.com/runner/), utilize the [gitlab-runner](gitlab_runner_chart.md) chart.
+
+It offers a quick way to configure and deploy the Runner on Kubernetes, regardless of where your GitLab server may be running.
 
-### Advanced deployment of GitLab (Not recommended)
-> *Note*: This chart will eventually be replaced by the [cloud native charts](#upcoming-cloud-native-helm-charts), which are presently in development.
+### Advanced deployment of GitLab
+> **Note**: This chart will be replaced by the [gitlab-omnibus](gitlab_omnibus.md) chart, once it supports [additional configuration options](https://gitlab.com/charts/charts.gitlab.io/issues/68).
 
 If advanced configuration of GitLab is required, the beta [gitlab](gitlab_chart.md) chart can be used which deploys the GitLab service along with optional Postgres and Redis. It offers extensive configuration, but requires deep knowledge of Kubernetes and Helm to use.
 
+For most deployments we recommend using our [gitlab-omnibus](gitlab_omnibus.md) chart.
+
 ## Upcoming Cloud Native Helm Charts
 
 GitLab is working towards a building a [cloud native deployment method](https://gitlab.com/charts/helm.gitlab.io/blob/master/README.md). A key part of this effort is to isolate each service into it's [own Docker container and Helm chart](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/2420), rather than utilizing the all-in-one container image of the [current charts](#official-gitlab-helm-charts-recommended).