Copyedit the GitLab chart docsupdate-chart-for-ga-doc

7 files changed, 207 insertions, 123 deletions

diff --git a/doc/install/kubernetes/gitlab_chart.md b/doc/install/kubernetes/gitlab_chart.md
index f630bfb726c..4e636ae3399 100644
--- a/doc/install/kubernetes/gitlab_chart.md
+++ b/doc/install/kubernetes/gitlab_chart.md
@@ -1,10 +1,12 @@
 # GitLab Helm Chart
 
-For more information on available GitLab Helm Charts, please see our [overview](index.md#chart-overview).
+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).
 
 ## Introduction
 
-The `gitlab` chart is the best way to operate GitLab on Kubernetes. This chart contains all the required components to get started, and can scale to large deployments.
+The `gitlab` chart is the best way to operate GitLab on Kubernetes. This chart
+contains all the required components to get started, and can scale to large deployments.
 
 The default deployment includes:
 
@@ -13,76 +15,90 @@ The default deployment includes:
 - An auto-scaling, unprivileged [GitLab Runner](https://docs.gitlab.com/runner/) using the Kubernetes executor
 - Automatically provisioned SSL via [Let's Encrypt](https://letsencrypt.org/).
 
-### Limitations
+## Limitations
 
 Some features of GitLab are not currently available:
 
-* [GitLab Pages](https://gitlab.com/charts/gitlab/issues/37)
-* [GitLab Geo](https://gitlab.com/charts/gitlab/issues/8)
-* [No in-cluster HA database](https://gitlab.com/charts/gitlab/issues/48)
-* MySQL will not be supported, as support is [deprecated within GitLab](https://docs.gitlab.com/omnibus/settings/database.html#using-a-mysql-database-management-server-enterprise-edition-only)
+- [GitLab Pages](https://gitlab.com/charts/gitlab/issues/37)
+- [GitLab Geo](https://gitlab.com/charts/gitlab/issues/8)
+- [No in-cluster HA database](https://gitlab.com/charts/gitlab/issues/48)
+- MySQL will not be supported, as support is [deprecated within GitLab](https://docs.gitlab.com/omnibus/settings/database.html#using-a-mysql-database-management-server-enterprise-edition-only)
 
 ## Installing GitLab using the Helm Chart
 
-Getting started with GitLab in Kubernetes is quick and easy. The `gitlab` chart includes all required dependencies, and takes just a few minutes to deploy.
+The `gitlab` chart includes all required dependencies, and takes a few minutes
+to deploy.
 
-TIP: **Tip:** For production deployments, we strongly recommend using the [detailed installation instructions](https://gitlab.com/charts/gitlab/blob/master/doc/installation/README.md) utilizing [external Postgres, Redis, and object storage](https://gitlab.com/charts/gitlab/tree/master/doc/advanced) services.
+TIP: **Tip:**
+For large scale deployments, we strongly recommend using the
+[detailed installation instructions](https://gitlab.com/charts/gitlab/blob/master/doc/installation/README.md)
+utilizing [external Postgres, Redis, and object storage](https://gitlab.com/charts/gitlab/tree/master/doc/advanced) services.
 
-### Prerequisites
+### Requirements
 
-In order to deploy GitLab on Kubernetes, a few prerequisites are required.
+In order to deploy GitLab on Kubernetes, the following are required:
 
 1. `helm` and `kubectl` [installed on your computer](preparation/tools_installation.md).
 1. A Kubernetes cluster, version 1.8 or higher. 6vCPU and 16GB of RAM is recommended.
-  * [Google GKE](https://cloud.google.com/kubernetes-engine/docs/how-to/creating-a-container-cluster)
-  * [Amazon EKS](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html)
-  * [Microsoft AKS](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough-portal)
+  - [Google GKE](https://cloud.google.com/kubernetes-engine/docs/how-to/creating-a-container-cluster)
+  - [Amazon EKS](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html)
+  - [Microsoft AKS](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough-portal)
 1. A [wildcard DNS entry and external IP address](preparation/networking.md)
 1. [Authenticate and connect](preparation/connect.md) to the cluster
 1. Configure and initialize [Helm Tiller](preparation/tiller.md).
 
-### Configuration of GitLab
+### Deployment of GitLab to Kubernetes
 
-To deploy GitLab, only three parameters are required:
-- `global.hosts.domain`: the [base domain](preparation/networking.md) of the wildcard host entry. For example, `mycompany.io` if the wild card entry is `*.mycompany.io`.
-- `global.hosts.externalIP`: the [external IP](preparation/networking.md) which the wildcard DNS resolves to.
-- `certmanager-issuer.email`: Email address to use when requesting new SSL certificates from Let's Encrypt.
+To deploy GitLab, the following three parameters are required:
 
-For deployments to Amazon EKS, there are [additional configuration requirements](preparation/eks.md). A full list of configuration options is  [also available](https://gitlab.com/charts/gitlab/blob/master/doc/installation/command-line-options.md).
+- `global.hosts.domain`: the [base domain](preparation/networking.md) of the
+  wildcard host entry. For example, `exampe.com` if the wild card entry is
+  `*.example.com`.
+- `global.hosts.externalIP`: the [external IP](preparation/networking.md) which
+  the wildcard DNS resolves to.
+- `certmanager-issuer.email`: the email address to use when requesting new SSL
+  certificates from Let's Encrypt.
 
-### Deployment of GitLab to Kubernetes
+NOTE: **Note:**
+For deployments to Amazon EKS, there are
+[additional configuration requirements](preparation/eks.md). A full list of
+configuration options is [also available](https://gitlab.com/charts/gitlab/blob/master/doc/installation/command-line-options.md).
 
-Once you have all of your configuration options collected, we can get any dependencies and
-run helm. In this example, we've named our helm release "gitlab".
+Once you have all of your configuration options collected, you can get any
+dependencies and run helm. In this example, the helm release is named "gitlab":
 
-```
+```sh
 helm repo add gitlab https://charts.gitlab.io/
 helm repo update
 helm upgrade --install gitlab gitlab/gitlab \
   --timeout 600 \
-  --set global.hosts.domain=example.local \
+  --set global.hosts.domain=example.com \
   --set global.hosts.externalIP=10.10.10.10 \
-  --set certmanager-issuer.email=me@example.local
+  --set certmanager-issuer.email=email@example.com
 ```
 
 ### Monitoring the Deployment
 
-This will output the list of resources installed once the deployment finishes which may take 5-10 minutes.
+This will output the list of resources installed once the deployment finishes,
+which may take 5-10 minutes.
 
-The status of the deployment can be checked by running `helm status gitlab` which can also be done while
-the deployment is taking place if you run the command in another terminal.
+The status of the deployment can be checked by running `helm status gitlab`
+which can also be done while the deployment is taking place if you run the
+command in another terminal.
 
 ### Initial login
 
-You can access the GitLab instance by visiting the domain name beginning with `gitlab.` followed by the domain specified during installation. From the example above, the URL would be `https://gitlab.example.local`.
+You can access the GitLab instance by visiting the domain name beginning with
+`gitlab.` followed by the domain specified during installation. From the example
+above, the URL would be `https://gitlab.example.com`.
 
 If you manually created the secret for initial root password, you
 can use that to sign in as `root` user. If not, Gitlab automatically
 created a random password for `root` user. This can be extracted by the
 following command (replace `<name>` by name of the release - which is `gitlab`
-if you used the command above).
+if you used the command above):
 
-```
+```sh
 kubectl get secret <name>-gitlab-initial-root-password -ojsonpath={.data.password} | base64 --decode ; echo
 ```
 
@@ -96,14 +112,14 @@ If your SMTP server requires authentication make sure to read the section on pro
 your password in the [secrets documentation](https://gitlab.com/charts/gitlab/blob/master/doc/installation/secrets.md#smtp-password).
 You can disable authentication settings with `--set global.smtp.authentication=""`.
 
-If your Kubernetes cluster is on GKE, be aware that smtp [ports 25, 465, and 587
+If your Kubernetes cluster is on GKE, be aware that SMTP ports [25, 465, and 587
 are blocked](https://cloud.google.com/compute/docs/tutorials/sending-mail/#using_standard_email_ports).
 
 ### Deploying the Community Edition
 
 To deploy the Community Edition, include these options in your `helm install` command:
 
-```shell
+```sh
 --set gitlab.migrations.image.repository=registry.gitlab.com/gitlab-org/build/cng/gitlab-rails-ce
 --set gitlab.sidekiq.image.repository=registry.gitlab.com/gitlab-org/build/cng/gitlab-sidekiq-ce
 --set gitlab.unicorn.image.repository=registry.gitlab.com/gitlab-org/build/cng/gitlab-unicorn-ce
@@ -114,7 +130,7 @@ To deploy the Community Edition, include these options in your `helm install` co
 Once your GitLab Chart is installed, configuration changes and chart updates
 should be done using `helm upgrade`:
 
-```bash
+```sh
 helm upgrade --reuse-values gitlab gitlab/gitlab
 ```
 
@@ -122,7 +138,7 @@ helm upgrade --reuse-values gitlab gitlab/gitlab
 
 To uninstall the GitLab Chart, run the following:
 
-```bash
+```sh
 helm delete gitlab
 ```
 
diff --git a/doc/install/kubernetes/gitlab_omnibus.md b/doc/install/kubernetes/gitlab_omnibus.md
index bc2fd466257..d80cb6ad374 100644
--- a/doc/install/kubernetes/gitlab_omnibus.md
+++ b/doc/install/kubernetes/gitlab_omnibus.md
@@ -1,17 +1,24 @@
 # GitLab-Omnibus Helm Chart
-CAUTION: **Caution:** This chart is **deprecated**. We recommend using the [`gitlab`](#gitlab-chart) chart. A comparison of the two charts is available [here (Video)](https://youtu.be/Z6jWR8Z8dv8).
-> **Note:**.
-* This chart has been tested on Google Kubernetes Engine and Azure Container Service.
 
-For more information on available GitLab Helm Charts, please see our [overview](index.md#chart-overview).
+CAUTION: **Caution:**
+This chart is **deprecated**. We recommend using the [`gitlab` chart](gitlab_chart.md)
+instead. A comparison of the two charts is available in [this video](https://youtu.be/Z6jWR8Z8dv8).
 
-This work is based partially on: https://github.com/lwolf/kubernetes-gitlab/. GitLab would like to thank Sergey Nuzhdin for his work.
+For more information on available GitLab Helm Charts, see the [charts overview](index.md#chart-overview).
+
+- This GitLab-Omnibus chart has been tested on Google Kubernetes Engine and Azure Container Service.
+- This work is based partially on: https://github.com/lwolf/kubernetes-gitlab/. GitLab would like to thank Sergey Nuzhdin for his work.
 
 ## Introduction
 
-This chart provides an easy way to get started with GitLab, provisioning an installation with nearly all functionality enabled. SSL is automatically provisioned via [Let's Encrypt](https://letsencrypt.org/).
+This chart provides an easy way to get started with GitLab, provisioning an
+installation with nearly all functionality enabled. SSL is automatically
+provisioned via [Let's Encrypt](https://letsencrypt.org/).
 
-This Helm chart is suited for small to medium deployments. It is **deprecated**, replaced by the [cloud native GitLab chart](https://gitlab.com/charts/helm.gitlab.io/blob/master/README.md). Due to the significant architectural changes, migrating will require backing up data out of this instance and importing it into the new deployment.
+This Helm chart is suited for small to medium deployments and is **deprecated**
+and replaced by the [cloud native GitLab chart](https://gitlab.com/charts/helm.gitlab.io/blob/master/README.md).
+Due to the significant architectural changes, migrating will require backing up
+data out of this instance and importing it into the new deployment.
 
 The deployment includes:
 
@@ -22,14 +29,12 @@ The deployment includes:
 - [NGINX Ingress](https://github.com/kubernetes/charts/tree/master/stable/nginx-ingress)
 - Persistent Volume Claims for Data, Registry, Postgres, and Redis
 
-### Limitations
-
-* This chart is in **deprecated**, and suited for small to medium size deployments. [High Availability](https://docs.gitlab.com/ee/administration/high_availability/) and [Geo](https://docs.gitlab.com/ee/gitlab-geo/README.html) are not supported.
-* We recommending using the [`gitlab` chart](index.md#cloud-native-gitlab-chart), which has an improved cloud native architecture. Due to the difficulty in supporting upgrades to the new architecture, migrating will require exporting data out of an instance deployed with this chart and into a new instance.
+## Limitations
 
-For more information on available GitLab Helm Charts, please see our [overview](index.md#chart-overview).
+[High Availability](../../administration/high_availability/README.md) and
+[Geo](https://docs.gitlab.com/ee/gitlab-geo/README.html) are not supported.
 
-## Prerequisites
+## Requirements
 
 - _At least_ 4 GB of RAM available on your cluster. 41GB of storage and 2 CPU are also required.
 - Kubernetes 1.4+ with Beta APIs enabled
@@ -38,43 +43,65 @@ For more information on available GitLab Helm Charts, please see our [overview](
 - The `kubectl` CLI installed locally and authenticated for the cluster
 - The [Helm client](https://github.com/kubernetes/helm/blob/master/docs/quickstart.md) installed locally on your machine
 
-### Networking Prerequisites
+### Networking requirements
 
-This chart configures a GitLab server and Kubernetes cluster which can support dynamic [Review Apps](https://docs.gitlab.com/ee/ci/review_apps/index.html), as well as services like the integrated [Container Registry](https://docs.gitlab.com/ee/user/project/container_registry.html) and [Mattermost](https://docs.gitlab.com/omnibus/gitlab-mattermost/).
+This chart configures a GitLab server and Kubernetes cluster which can support
+dynamic [Review Apps](../../ci/review_apps/index.md), as well as services like
+the integrated [Container Registry](../../user/project/container_registry.md)
+and [Mattermost](https://docs.gitlab.com/omnibus/gitlab-mattermost/).
 
-To support the GitLab services and dynamic environments, a wildcard DNS entry is required which resolves to the [Load Balancer](#load-balancer-ip) or [External IP](#external-ip). Configuration of the DNS entry will depend upon the DNS service being used.
+To support the GitLab services and dynamic environments, a wildcard DNS entry
+is required which resolves to the [load balancer](#load-balancer-ip) or
+[external IP](#external-ip). Configuration of the DNS entry will depend upon
+the DNS service being used.
 
-#### External IP (Recommended)
+#### External IP (recommended)
 
-To provision an external IP on GCP and Azure, simply request a new address from the Networking section. Ensure that the region matches the region your container cluster is created in. Note, it is important that the IP is not assigned at this point in time. It will be automatically assigned once the Helm chart is installed, and assigned to the Load Balancer.
+To provision an external IP on GCP and Azure, simply request a new address from
+the Networking section. Ensure that the region matches the region your container
+cluster is created in. It is important that the IP is not assigned at this point
+in time. It will be automatically assigned once the Helm chart is installed,
+and assigned to the Load Balancer.
 
-Now that an external IP address has been allocated, ensure that the wildcard DNS entry you would like to use resolves to this IP. Please consult the documentation for your DNS service for more information on creating DNS records.
+Now that an external IP address has been allocated, ensure that the wildcard
+DNS entry you would like to use resolves to this IP. Please consult the
+documentation for your DNS service for more information on creating DNS records.
 
-Finally, set the `baseIP` setting to this IP address when [deploying GitLab](#configuring-and-installing-gitlab).
+Finally, set the `baseIP` setting to this IP address when
+[deploying GitLab](#configuring-and-installing-gitlab).
 
 #### Load Balancer IP
 
-If you do not specify a `baseIP`, an IP will be assigned to the Load Balancer or Ingress. You can retrieve this IP by running the following command *after* deploying GitLab:
+If you do not specify a `baseIP`, an IP will be assigned to the Load Balancer or
+Ingress. You can retrieve this IP by running the following command *after* deploying GitLab:
 
-`kubectl get svc -w --namespace nginx-ingress nginx`
+```sh
+kubectl get svc -w --namespace nginx-ingress nginx
+```
 
-The IP address will be displayed in the `EXTERNAL-IP` field, and should be used to configure the Wildcard DNS entry. For more information on creating a wildcard DNS entry, consult the documentation for the DNS server you are using.
+The IP address will be displayed in the `EXTERNAL-IP` field, and should be used
+to configure the Wildcard DNS entry. For more information on creating a wildcard
+DNS entry, consult the documentation for the DNS server you are using.
 
-For production deployments of GitLab, we strongly recommend using an [External IP](#external-ip).
+For production deployments of GitLab, we strongly recommend using a
+[external IP](#external-ip).
 
 ## Configuring and Installing GitLab
 
-For most installations, only two parameters are required:
+For most installations, two parameters are required:
+
 - `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](#external-ip-recommended)
 - `gitlab`: Choose the [desired edition](https://about.gitlab.com/pricing), 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 [Google Kubernetes Engine](https://cloud.google.com/kubernetes-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).
+For additional configuration options, consult the
+[`values.yaml`](https://gitlab.com/charts/charts.gitlab.io/blob/master/charts/gitlab-omnibus/values.yaml).
 
 ### Choosing a different GitLab release version
 
@@ -91,13 +118,14 @@ The different images can be found in the [gitlab-ce](https://hub.docker.com/r/gi
 repositories on Docker Hub.
 
 ### 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.
 
-By default, persistent storage is enabled for GitLab and the charts it depends
-on (Redis and PostgreSQL).
+NOTE: **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.
 
-Components can have their claim size set from your `values.yaml`, along with whether to provision separate storage for Postgres and Redis.
+By default, persistent storage is enabled for GitLab and the charts it depends
+on (Redis and PostgreSQL). Components can have their claim size set from your
+`values.yaml`, along with whether to provision separate storage for Postgres and Redis.
 
 Basic configuration:
 
@@ -116,14 +144,23 @@ gitlabConfigStorageSize: 1Gi
 
 ### Routing and SSL
 
-Ingress routing and SSL are automatically configured within this Chart. An NGINX ingress is provisioned and configured, and will route traffic to any service. SSL certificates are automatically created and configured by [kube-lego](https://github.com/kubernetes/charts/tree/master/stable/kube-lego).
+Ingress routing and SSL are automatically configured within this Chart. An NGINX
+ingress is provisioned and configured, and will route traffic to any service.
+SSL certificates are automatically created and configured by
+[kube-lego](https://github.com/kubernetes/charts/tree/master/stable/kube-lego).
 
-> **Note:**
-Let's Encrypt limits a single TLD to five certificate requests within a single week. This means that common DNS wildcard services like [nip.io](http://nip.io) are unlikely to work.
+NOTE: **Note:**
+Let's Encrypt limits a single TLD to five certificate requests within a single
+week. This means that common DNS wildcard services like [nip.io](http://nip.io)
+and [xip.io](http://xip.io) are unlikely to work.
 
 ## Installing GitLab using the Helm Chart
-> **Note:**
-You may see a temporary error message `SchedulerPredicates failed due to PersistentVolumeClaim is not bound` while storage provisions. Once the storage provisions, the pods will automatically start. This may take a couple minutes depending on your cloud provider. If the error persists, please review the [prerequisites](#prerequisites) to ensure you have enough RAM, CPU, and storage.
+
+NOTE: **Note:**
+You may see a temporary error message `SchedulerPredicates failed due to PersistentVolumeClaim is not bound`
+while storage provisions. Once the storage provisions, the pods will automatically start.
+This may take a couple minutes depending on your cloud provider. If the error persists,
+please review the [requirements sections](#requirements) to ensure you have enough RAM, CPU, and storage.
 
 Add the GitLab Helm repository and initialize Helm:
 
@@ -132,15 +169,15 @@ helm init
 helm repo add gitlab https://charts.gitlab.io
 ```
 
-Once you have reviewed the [configuration settings](#configuring-and-installing-gitlab) you can install the chart. We recommending saving your configuration options in a `values.yaml` file for easier upgrades in the future.
-
-For example:
+Once you have reviewed the [configuration settings](#configuring-and-installing-gitlab),
+you can install the chart. We recommending saving your configuration options in a
+`values.yaml` file for easier upgrades in the future:
 
 ```bash
 helm install --name gitlab -f values.yaml gitlab/gitlab-omnibus
 ```
 
-or passing them on the command line:
+Or you can pass them on the command line:
 
 ```bash
 helm install --name gitlab --set baseDomain=gitlab.io,baseIP=192.0.2.1,gitlab=ee,gitlabEELicense=$LICENSE,legoEmail=email@gitlab.com gitlab/gitlab-omnibus
@@ -148,8 +185,11 @@ helm install --name gitlab --set baseDomain=gitlab.io,baseIP=192.0.2.1,gitlab=ee
 
 ## Updating GitLab using the Helm Chart
 
->**Note**: If you are upgrading from a previous version to 0.1.35 or above, you will need to change the access mode values for GitLab's storage. To do this, set the following in `values.yaml` or on the CLI:
-```
+If you are upgrading from a previous version to 0.1.35 or above, you will need to
+change the access mode values for GitLab's storage. To do this, set the following
+in `values.yaml` or on the CLI:
+
+```sh
 gitlabDataAccessMode=ReadWriteMany
 gitlabRegistryAccessMode=ReadWriteMany
 gitlabConfigAccessMode=ReadWriteMany
@@ -158,15 +198,20 @@ gitlabConfigAccessMode=ReadWriteMany
 Once your GitLab Chart is installed, configuration changes and chart updates
 should be done using `helm upgrade`:
 
-```bash
+```sh
 helm upgrade -f values.yaml gitlab gitlab/gitlab-omnibus
 ```
 
 ## Upgrading from CE to EE using the Helm Chart
 
-If you have installed the Community Edition using this chart, upgrading to Enterprise Edition is easy.
+If you have installed the Community Edition using this chart, upgrading to
+Enterprise Edition is easy.
 
-If you are using a `values.yaml` file to specify the configuration options, edit the file and set `gitlab=ee`. If you would like to run a specific version of GitLab EE, set `gitlabEEImage` to be the desired GitLab [docker image](https://hub.docker.com/r/gitlab/gitlab-ee/tags/). Then you can use `helm upgrade` to update your GitLab instance to EE:
+If you are using a `values.yaml` file to specify the configuration options, edit
+the file and set `gitlab=ee`. If you would like to run a specific version of
+GitLab EE, set `gitlabEEImage` to be the desired GitLab
+[docker image](https://hub.docker.com/r/gitlab/gitlab-ee/tags/). Then you can
+use `helm upgrade` to update your GitLab instance to EE:
 
 ```bash
 helm upgrade -f values.yaml gitlab gitlab/gitlab-omnibus
@@ -190,9 +235,12 @@ helm delete gitlab
 
 ### Storage errors when updating `gitlab-omnibus` versions prior to 0.1.35
 
-Users upgrading `gitlab-omnibus` from a version prior to 0.1.35, may see an error like: `Error: UPGRADE FAILED: PersistentVolumeClaim "gitlab-gitlab-config-storage" is invalid: spec: Forbidden: field is immutable after creation`.
+Users upgrading `gitlab-omnibus` from a version prior to 0.1.35, may see an error
+like: `Error: UPGRADE FAILED: PersistentVolumeClaim "gitlab-gitlab-config-storage" is invalid: spec: Forbidden: field is immutable after creation`.
 
-This is due to a change in the access mode for GitLab storage in version 0.1.35. To successfully upgrade, the access mode flags must be set to `ReadWriteMany` as detailed in the [update section](#updating-gitlab-using-the-helm-chart).
+This is due to a change in the access mode for GitLab storage in version 0.1.35.
+To successfully upgrade, the access mode flags must be set to `ReadWriteMany`
+as detailed in the [update section](#updating-gitlab-using-the-helm-chart).
 
 [kube-srv]: https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services---service-types
 [storageclass]: https://kubernetes.io/docs/concepts/storage/persistent-volumes/#storageclasses
diff --git a/doc/install/kubernetes/index.md b/doc/install/kubernetes/index.md
index a6976acdcf7..e67d5ba4d4c 100644
--- a/doc/install/kubernetes/index.md
+++ b/doc/install/kubernetes/index.md
@@ -4,7 +4,8 @@ description: 'Read through the different methods to deploy GitLab on Kubernetes.
 
 # Installing GitLab on Kubernetes
 
-> **Note**: These charts have been tested on Google Kubernetes Engine. Other Kubernetes installations may work as well, if not please [open an issue](https://gitlab.com/charts/issues).
+NOTE: **Note**: These charts have been tested on Google Kubernetes Engine. Other
+Kubernetes installations may work as well, if not please [open an issue](https://gitlab.com/charts/issues).
 
 The easiest method to deploy GitLab on [Kubernetes](https://kubernetes.io/) is
 to take advantage of GitLab's Helm charts. [Helm] is a package
@@ -14,28 +15,31 @@ should be deployed, upgraded, and configured.
 
 ## Chart Overview
 
-* **[GitLab Chart](gitlab_chart.html)**: Deploys GitLab on Kubernetes. Includes all the required components to get started, and can scale to large deployments.
-* **[GitLab Runner Chart](gitlab_runner_chart.md)**: For deploying just the GitLab Runner.
-* Other Charts
-  * [GitLab-Omnibus](gitlab_omnibus.md): Chart based on the Omnibus GitLab linux package, only suitable for small deployments. Deprecated, we strongly recommend using the [gitlab](#gitlab-chart) chart.
-  * [Community contributed charts](#community-contributed-charts): Community contributed charts.
+- **[GitLab Chart](gitlab_chart.html)**: Deploys GitLab on Kubernetes. Includes all the required components to get started, and can scale to large deployments.
+- **[GitLab Runner Chart](gitlab_runner_chart.md)**: For deploying just the GitLab Runner.
+- Other Charts
+  - [GitLab-Omnibus](gitlab_omnibus.md): Chart based on the Omnibus GitLab package, only suitable for small deployments. Deprecated, we strongly recommend using the [gitlab](#gitlab-chart) chart.
+  - [Community contributed charts](#community-contributed-charts): Community contributed charts.
 
 ## GitLab Chart
 
-The best way to operate GitLab on Kubernetes. This chart contains all the required components to get started, and can scale to large deployments.
+This chart contains all the required components to get started, and can scale to
+large deployments. It offers a number of benefits:
 
-This chart offers a number of benefits:
-* Horizontal scaling of individual components
-* No requirement for shared storage to scale
-* Containers do not need `root` permissions
-* Automatic SSL with Let's Encrypt
-* and plenty more.
+- Horizontal scaling of individual components
+- No requirement for shared storage to scale
+- Containers do not need `root` permissions
+- Automatic SSL with Let's Encrypt
+- and plenty more.
 
 Learn more about the [GitLab chart](gitlab_chart.md).
 
 ## GitLab Runner Chart
 
-If you already have a GitLab instance running, inside or outside of Kubernetes, and you'd like to leverage the Runner's [Kubernetes capabilities](https://docs.gitlab.com/runner/executors/kubernetes.html), it can be deployed with the GitLab Runner chart.
+If you already have a GitLab instance running, inside or outside of Kubernetes,
+and you'd like to leverage the Runner's
+[Kubernetes capabilities](https://docs.gitlab.com/runner/executors/kubernetes.html),
+it can be deployed with the GitLab Runner chart.
 
 Learn more about [gitlab-runner chart](gitlab_runner_chart.md).
 
@@ -43,9 +47,18 @@ Learn more about [gitlab-runner chart](gitlab_runner_chart.md).
 
 ### GitLab-Omnibus Chart
 
-CAUTION: **Caution:** This chart is **deprecated**. We recommend using the [`gitlab`](#gitlab-chart) chart. A comparison of the two charts is available [here (Video)](https://youtu.be/Z6jWR8Z8dv8). 
+CAUTION: **Deprecated:**
+This chart is **deprecated**. We recommend using the [GitLab Chart](gitlab_chart.md)
+instead. A comparison of the two charts is available in [this video](https://youtu.be/Z6jWR8Z8dv8).
 
-It deploys and configures nearly all features of GitLab, including: a [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 a [NGINX load balancer](https://github.com/kubernetes/ingress/tree/master/controllers/nginx). It is based on our [GitLab Omnibus Docker Images](https://docs.gitlab.com/omnibus/docker/README.html).
+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).
 
diff --git a/doc/install/kubernetes/preparation/connect.md b/doc/install/kubernetes/preparation/connect.md
index fb633c456f5..a3a0cba4bf2 100644
--- a/doc/install/kubernetes/preparation/connect.md
+++ b/doc/install/kubernetes/preparation/connect.md
@@ -2,19 +2,14 @@
 
 In order to deploy software and settings to a cluster, you must connect and authenticate to it.
 
-* [GKE cluster](#connect-to-gke-cluster)
-* [EKS cluster](#connect-to-eks-cluster)
-* [Local minikube cluster](#connect-to-local-minikube-cluster)
-
 ## Connect to GKE cluster
 
-The command for connection to the cluster can be obtained from the [Google Cloud Platform Console](https://console.cloud.google.com/kubernetes/list) by the individual cluster.
-
-Look for the **Connect** button in the clusters list page.
-
-**Or**
+The command for connection to the cluster can be obtained from the
+[Google Cloud Platform Console](https://console.cloud.google.com/kubernetes/list)
+by the individual cluster.
 
-Use the command below, filling in your cluster's informtion:
+Look for the **Connect** button in the clusters list page or use the command below,
+filling in your cluster's information:
 
 ```
 gcloud container clusters get-credentials <cluster-name> --zone <zone> --project <project-id>
@@ -22,7 +17,8 @@ gcloud container clusters get-credentials <cluster-name> --zone <zone> --project
 
 ## Connect to EKS cluster
 
-For the most up to date instructions, follow the Amazon EKS documentation on [connecting to a cluster](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#eks-configure-kubectl).
+For the most up to date instructions, follow the Amazon EKS documentation on
+[connecting to a cluster](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#eks-configure-kubectl).
 
 ## Connect to local minikube cluster
 
diff --git a/doc/install/kubernetes/preparation/networking.md b/doc/install/kubernetes/preparation/networking.md
index b157cf31aa9..34a6130de27 100644
--- a/doc/install/kubernetes/preparation/networking.md
+++ b/doc/install/kubernetes/preparation/networking.md
@@ -1,6 +1,8 @@
 # Networking Prerequisites
 
-> **Note**: Amazon EKS utilizes Elastic Load Balancers, which are addressed by DNS name and cannot be known ahead of time. Skip this section.
+NOTE: **Note:**
+Amazon EKS utilizes Elastic Load Balancers, which are addressed by DNS name and
+cannot be known ahead of time. If you're using EKS, you can skip this section.
 
 The `gitlab` chart configures a GitLab server and Kubernetes cluster which can support dynamic [Review Apps](https://docs.gitlab.com/ee/ci/review_apps/index.html), as well as services like the integrated [Container Registry](https://docs.gitlab.com/ee/user/project/container_registry.html).
 
@@ -30,7 +32,7 @@ Now that an external IP address has been allocated, ensure that the wildcard DNS
 
 Please consult the documentation for your DNS service for more information on creating DNS records:
 
-* [Google Domains](https://support.google.com/domains/answer/3290350?hl=en)
-* [GoDaddy](https://www.godaddy.com/help/add-an-a-record-19238)
+- [Google Domains](https://support.google.com/domains/answer/3290350?hl=en)
+- [GoDaddy](https://www.godaddy.com/help/add-an-a-record-19238)
 
 Set `global.hosts.domain` to this DNS name when [deploying GitLab](../gitlab_chart.md#configuring-and-installing-gitlab).
diff --git a/doc/install/kubernetes/preparation/rbac.md b/doc/install/kubernetes/preparation/rbac.md
index 240893526d3..c5f8d7a7e9e 100644
--- a/doc/install/kubernetes/preparation/rbac.md
+++ b/doc/install/kubernetes/preparation/rbac.md
@@ -1,16 +1,20 @@
 # Role Based Access Control
 
-Until Kubernetes 1.7, there were no permissions within a cluster. With the launch of 1.7, there is now a role based access control system ([RBAC](https://kubernetes.io/docs/admin/authorization/rbac/)) which determines what services can perform actions within a cluster.
+Until Kubernetes 1.7, there were no permissions within a cluster. With the launch
+of 1.7, there is now a [role based access control system (RBAC)](https://kubernetes.io/docs/admin/authorization/rbac/)
+which determines what services can perform actions within a cluster.
 
 RBAC affects a few different aspects of GitLab:
-* [Installation of GitLab using Helm](tiller.md#preparing-for-helm-with-rbac)
-* Prometheus monitoring
-* GitLab Runner
 
-## Checking that RBAC is enabled
+- [Installation of GitLab using Helm](tiller.md#preparing-for-helm-with-rbac)
+- Prometheus monitoring
+- GitLab Runner
 
-Try listing the current cluster roles, if it fails then `RBAC` is disabled
+## Checking that RBAC is enabled
 
-This command will output `false` if `RBAC` is disabled and `true` otherwise
+Try listing the current cluster roles, if it fails then `RBAC` is disabled.
+The following command will output `false` if `RBAC` is disabled and `true` otherwise:
 
-`kubectl get clusterroles > /dev/null 2>&1 && echo true || echo false`
+```sh
+kubectl get clusterroles > /dev/null 2>&1 && echo true || echo false
+```
diff --git a/doc/install/kubernetes/preparation/tiller.md b/doc/install/kubernetes/preparation/tiller.md
index 016aac2abeb..107df074b3b 100644
--- a/doc/install/kubernetes/preparation/tiller.md
+++ b/doc/install/kubernetes/preparation/tiller.md
@@ -1,10 +1,15 @@
 # Configuring and initializing Helm Tiller
 
-To make use of Helm, you must have a [Kubernetes][k8s-io] cluster. Ensure you can access your cluster using `kubectl`.
+To make use of Helm, you must have a [Kubernetes][k8s-io] cluster. Ensure you can
+access your cluster using `kubectl`.
 
 Helm consists of two parts, the `helm` client and a `tiller` server inside Kubernetes.
 
-> **Note**: If you are not able to run Tiller in your cluster, for example on OpenShift, it is possible to use [Tiller locally](https://gitlab.com/charts/gitlab/tree/master/doc/helm#local-tiller) and avoid deploying it into the cluster. This should only be used when Tiller cannot be normally deployed.
+NOTE: **Note:**
+If you are not able to run Tiller in your cluster, for example on OpenShift, it
+is possible to use [Tiller locally](https://gitlab.com/charts/gitlab/tree/master/doc/helm#local-tiller)
+and avoid deploying it into the cluster. This should only be used when Tiller
+cannot be normally deployed.
 
 ## Initialize Helm and Tiller