Add `gitlab` chart documentation

8 files changed, 395 insertions, 32 deletions

diff --git a/doc/install/kubernetes/gitlab_chart.md b/doc/install/kubernetes/gitlab_chart.md
index 429519a92e1..3d16b3cadd8 100644
--- a/doc/install/kubernetes/gitlab_chart.md
+++ b/doc/install/kubernetes/gitlab_chart.md
@@ -1,6 +1,136 @@
 # GitLab Helm Chart
-> **Note:** This chart is currently in alpha.
+> **Note:** The chart is currently **beta**, if you encounter any problems please [open an issue](https://gitlab.com/charts/gitlab/issues/new).
 
-The cloud native `gitlab` chart is the next generation Helm chart, currently in alpha, and will replace the [`gitlab-omnibus`](gitlab_omnibus.md) chart. It will support large deployments with horizontal scaling of individual GitLab components.
+For more information on available GitLab Helm Charts, please see our [overview](index.md#chart-overview).
 
-Installation instructions and known issues during alpha are available at the [project page](https://gitlab.com/charts/gitlab/).
\ No newline at end of file
+## 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 default deployment includes:
+
+- Core GitLab components: Unicorn, Shell, Workhorse, Registry, Sidekiq, and Gitaly
+- Optional dependencies: Postgres, Redis, Minio
+- 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
+
+Some features and functions are not currently available in the beta release:
+* [GitLab Pages](../../user/project/pages/)
+* [Reply by email](../../administration/reply_by_email.html)
+* [Project templates](../../gitlab-basics/create-project.html)
+* [Project import/export](../../user/project/settings/import_export.html)
+* [Geo](https://docs.gitlab.com/ee/administration/geo/replication/)
+
+Currently out of scope:
+* [Mattermost](https://docs.gitlab.com/omnibus/gitlab-mattermost/)
+* [MySQL support](https://docs.gitlab.com/omnibus/settings/database.html#using-a-mysql-database-management-server-enterprise-edition-only)
+
+## Prerequisites
+
+In order to deploy GitLab on Kubernetes, a few prerequisites are required.
+
+1. `helm` and `kubectl` [installed on your computer](preparation/tools_installation.md).
+1. A Kubernetes cluster, version 1.8 or higher. 4vCPU 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)
+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).
+
+## Configuring and Installing GitLab
+
+> **Note**: For deployments to Amazon EKS, there are [additional configuration requirements](preparation/eks.md).
+
+For simple deployments, running all services within Kubernetes, 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.
+
+For enterprise deployments, or to utilize advanced settings, please use the instructions in the [`gitlab` chart project](https://gitlab.com/charts/gitlab) for the most up to date directions.
+- [External Postgres, Redis, and other dependencies](https://gitlab.com/charts/gitlab/tree/master/doc/advanced)
+- [Persistence settings](https://gitlab.com/charts/gitlab/blob/master/doc/installation/storage.md)
+- [Manual TLS certificates](https://gitlab.com/charts/gitlab/blob/master/doc/installation/tls.md)
+- [Manual secret creation](https://gitlab.com/charts/gitlab/blob/master/doc/installation/secrets.md)
+
+For additional configuration options, consult the [full list of settings](https://gitlab.com/charts/gitlab/blob/master/doc/installation/command-line-options.md).
+
+## Installing GitLab using the Helm Chart
+
+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".
+
+```
+helm repo add gitlab https://charts.gitlab.io/
+helm dependencies update
+helm upgrade --install gitlab gitlab/gitlab \
+  --timeout 600 \
+  --set global.hosts.domain=example.local \
+  --set global.hosts.externalIP=10.10.10.10 \
+  --set certmanager-issuer.email=me@example.local
+```
+
+### Monitoring the Deployment
+
+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.
+
+### Initial login
+
+You can access the GitLab instance by visiting the domain specified during
+installation. If you manually created the secret for initial root password, you
+can use that to sign in as `root` user. If not, Gitlab would've 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)
+
+```
+kubectl get secret <name>-gitlab-initial-root-password -ojsonpath={.data.password} | base64 -d
+```
+
+## Outgoing email
+
+By default outgoing email is disabled. To enable it, provide details for your SMTP server
+using the `global.smtp` and `global.email` settings. You can find details for these settings in the
+[command line options](https://gitlab.com/charts/gitlab/blob/master/doc/installation/command-line-options.md#email-configuration).
+
+If your SMTP server requires authentication make sure to read the section on providing
+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
+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
+--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
+```
+
+## Updating GitLab using the Helm Chart
+
+Once your GitLab Chart is installed, configuration changes and chart updates
+should be done using `helm upgrade`:
+
+```bash
+helm upgrade -f values.yaml gitlab gitlab/gitlab
+```
+
+## Uninstalling GitLab using the Helm Chart
+
+To uninstall the GitLab Chart, run the following:
+
+```bash
+helm delete gitlab
+```
+
+[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 aeaa739edab..b1cecf46697 100644
--- a/doc/install/kubernetes/index.md
+++ b/doc/install/kubernetes/index.md
@@ -4,7 +4,7 @@ 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 and Azure Container Service. Other Kubernetes installations may work as well, if not please [open an issue](https://gitlab.com/charts/charts.gitlab.io/issues).
+> **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,51 +14,44 @@ should be deployed, upgraded, and configured.
 
 ## Chart Overview
 
-* **[GitLab-Omnibus](gitlab_omnibus.md)**: The best way to run GitLab on Kubernetes today, suited for small deployments. The chart is in beta and will be deprecated by the [cloud native GitLab chart](#cloud-native-gitlab-chart).
-* **[Cloud Native GitLab Chart](https://gitlab.com/charts/gitlab/blob/master/README.md)**: The next generation GitLab chart, currently in alpha. Will support large deployments with horizontal scaling of individual GitLab components.
+* **[GitLab Chart](https://gitlab.com/charts/gitlab/blob/master/README.md)**: The recommended GitLab chart, currently in beta. Support large deployments with horizontal scaling of individual GitLab components, and does not require NFS.
+* **[GitLab Runner Chart](gitlab_runner_chart.md)**: For deploying just the GitLab Runner.
 * Other Charts
-  * [GitLab Runner Chart](gitlab_runner_chart.md): For deploying just the GitLab Runner.
+  * [GitLab-Omnibus](gitlab_omnibus.md): Chart based on the Omnibus GitLab linux package, only suitable for small deployments. The chart will be deprecated by the [GitLab chart](#gitlab-chart) when it is GA.
   * [Community Contributed Charts](#community-contributed-charts): Community contributed charts, deprecated by the official GitLab chart.
 
-## GitLab-Omnibus Chart (Recommended)
+## GitLab Chart
 
-> **Note**: This chart is in beta while [additional features](https://gitlab.com/charts/charts.gitlab.io/issues/68) are being added.
+> **Note**: This chart is **beta**, while we work on the [remaining items for GA](https://gitlab.com/groups/charts/-/epics/15).
 
-This chart is the best available way to operate GitLab on Kubernetes. 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 [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).
+The best way to operate GitLab on Kubernetes. This chart contains all the required components to get started, and can scale to large deployments.
 
-Once the [cloud native GitLab chart](#cloud-native-gitlab-chart) is ready for production use, this chart will be deprecated. Due to the difficulty in supporting upgrades to the new architecture, migrating will require exporting data out of this instance and importing it into the new deployment.
-
-Learn more about the [gitlab-omnibus chart](gitlab_omnibus.md).
-
-## Cloud Native GitLab Chart
-
-GitLab is working towards building a [cloud native GitLab chart](https://gitlab.com/charts/gitlab/blob/master/README.md). A key part of this effort is to isolate each service into its [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 chart](#gitlab-omnibus-chart-recommended).
-
-By offering individual containers and charts, we will be able to provide a number of benefits:
-* Easier horizontal scaling of each service,
-* Smaller, more efficient images,
-* Potential for rolling updates and canaries within a service,
+This chart includes 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.
 
-Presently this chart is available in alpha for testing, and not recommended for production use. 
+Learn more about the [GitLab chart here](gitlab_chart.md) and [here [Video]](https://youtu.be/Z6jWR8Z8dv8).
 
-Learn more about the [cloud native GitLab chart here ](https://gitlab.com/charts/gitlab/blob/master/README.md) and [here [Video]](https://youtu.be/Z6jWR8Z8dv8).
+## GitLab Runner Chart
 
-## Other Charts
+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.
 
-### GitLab Runner Chart
+Learn more about [gitlab-runner chart](gitlab_runner_chart.md).
 
-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.
+## Other Charts
 
-Learn more about [gitlab-runner chart.](gitlab_runner_chart.md)
+### GitLab-Omnibus Chart
 
-### Advanced GitLab Installation
+> **Note**: This chart is beta, and **will be deprecated** when the [`gitlab`](#gitlab-chart) chart is GA.
 
-If advanced configuration of GitLab is required, the beta [gitlab](gitlab_chart.md) chart can be used which deploys the core GitLab service along with optional Postgres and Redis. It offers extensive configuration, but offers limited functionality out-of-the-box; it's lacking Pages support, the container registry, and Mattermost. It requires deep knowledge of Kubernetes and Helm to use.
+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 [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 will be deprecated and replaced by the [gitlab-omnibus](gitlab_omnibus.md) chart, once it supports [additional configuration options](https://gitlab.com/charts/charts.gitlab.io/issues/68). It's beta quality, and since it is not actively under development, it will never be GA.
+Once the [GitLab chart](#gitlab-chart) is GA, this chart will be deprecated. Migrating to the `gitlab` chart will require exporting data out of this instance and importing it into a new deployment.
 
-Learn more about the [gitlab chart.](gitlab_chart.md)
+Learn more about the [gitlab-omnibus chart](gitlab_omnibus.md).
 
 ### Community Contributed Charts
 
diff --git a/doc/install/kubernetes/preparation/connect.md b/doc/install/kubernetes/preparation/connect.md
new file mode 100644
index 00000000000..fb633c456f5
--- /dev/null
+++ b/doc/install/kubernetes/preparation/connect.md
@@ -0,0 +1,31 @@
+# Connecting your computer to a cluster
+
+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**
+
+Use the command below, filling in your cluster's informtion:
+
+```
+gcloud container clusters get-credentials <cluster-name> --zone <zone> --project <project-id>
+```
+
+## 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).
+
+## Connect to local minikube cluster
+
+If you are doing local development, you can use `minikube` as your
+local cluster. If `kubectl cluster-info` is not showing `minikube` as the current
+cluster, use `kubectl config set-cluster minikube` to set the active cluster.
diff --git a/doc/install/kubernetes/preparation/eks.md b/doc/install/kubernetes/preparation/eks.md
new file mode 100644
index 00000000000..c40177c4302
--- /dev/null
+++ b/doc/install/kubernetes/preparation/eks.md
@@ -0,0 +1,44 @@
+# Running GitLab on EKS
+
+There are a few nuances to Amazon EKS which are important to be aware of, when deploying GitLab.
+
+## Persistent volume management
+
+There are two methods to manage volume claims on Kubernetes:
+1. Manually creating each persistent volume (recommended on EKS)
+1. Utilizing dynamic provisioning to automatically create the persistent volumes
+
+### Manual provisioning of volumes (Recommended)
+
+Manually creating the volumes allows you to control the zone of each volume, as well as all other details supported by the underlying storage.
+
+Follow our documentation on [manually creating persistent volumes](https://gitlab.com/charts/gitlab/blob/master/doc/installation/storage.md#manually-creating-static-volumes).
+
+### Dynamic provisioning of volumes
+
+Dynamic provisioning utilizes a Kubernetes provisioner, like `aws-ebs`, to automatically create persistent volumes to fulfill each claim.
+
+With EKS, there are a few important details to keep in mind:
+
+1. Clusters are required to span multiple AZ's
+1. Kubernetes volume provisioners create volumes across zones without regard to which pod they belong to. This leads to scenarios where a pod with multiple volumes being unable to start due to the volumes being in different zones.
+1. There is no default Storage Class.
+
+The easiest way to solve this and still utilize dynamic provisioning is to utilize, or create, a Storage Class that is locked to a specific zone.
+
+> **Note**: Restricting volumes to specific zone will cause GitLab and any other application using this Storage Class to only reside in that zone. For multiple zone support, utilize [manually provisioned volumes](#manual-provisioning-of-volumes).
+
+To create the storage class, download and edit Amazon EKS's [sample Storage Class](https://docs.aws.amazon.com/eks/latest/userguide/storage-classes.html) and add the following parameter:
+
+```yaml
+parameters:
+  zone: <desired-zone>
+```
+
+Then [specify the Storage Class](https://gitlab.com/charts/gitlab/blob/master/doc/installation/storage.md#using-a-custom-storage-class) name when deploying GitLab.
+
+## External access to GitLab
+
+By default, GitLab will an deploy an ingress which will create an associated Elastic Load Balancer. Since the DNS names of ELB's cannot be known ahead of time, it is difficult to utilize Let's Encrypt to automatically provision HTTPS certificates.
+
+We recommend [using your own certificates](https://gitlab.com/charts/gitlab/blob/master/doc/installation/tls.md#option-2-use-your-own-wildcard-certificate), and then mapping your desired DNS name to the created ELB using a CNAME record.
diff --git a/doc/install/kubernetes/preparation/networking.md b/doc/install/kubernetes/preparation/networking.md
new file mode 100644
index 00000000000..b157cf31aa9
--- /dev/null
+++ b/doc/install/kubernetes/preparation/networking.md
@@ -0,0 +1,36 @@
+# 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.
+
+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).
+
+To support the GitLab services and dynamic environments, a wildcard DNS entry is required which resolves to the external IP.
+
+## External IP
+
+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, to the Load Balancer.
+
+Set `global.hosts.externalIP` to this IP address when [deploying GitLab](../gitlab_chart.md#configuring-and-installing-gitlab).
+
+Then, create a [wildcard DNS record](#wildcard-dns-entry) which resolves to this IP address.
+
+### Creating an external IP on GCP
+
+When creating the external IP, it is critical to create it in the same region as your cluster. Otherwise, the IP address will fail to bind to the Load Balancer.
+
+1. Open the [web console](https://console.cloud.google.com)
+1. In the sidebar, browse to `VPC Network > External IP addresses`
+1. Click `Reserve static address`
+1. Choose `Regional` and select the region of your cluster
+1. Leave `Attached to` blank, as it will be automatically assigned during deployment
+
+## Wildcard DNS entry
+
+Now that an external IP address has been allocated, ensure that the wildcard DNS entry you would like to use resolves to this IP. Typically this would be an `A record` for `*`, resolving to the external IP above.
+
+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)
+
+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
new file mode 100644
index 00000000000..240893526d3
--- /dev/null
+++ b/doc/install/kubernetes/preparation/rbac.md
@@ -0,0 +1,16 @@
+# 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.
+
+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
+
+Try listing the current cluster roles, if it fails then `RBAC` is disabled
+
+This command will output `false` if `RBAC` is disabled and `true` otherwise
+
+`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
new file mode 100644
index 00000000000..c92f8258e41
--- /dev/null
+++ b/doc/install/kubernetes/preparation/tiller.md
@@ -0,0 +1,94 @@
+# 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`.
+
+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](#local-tiller) and avoid deploying it into the cluster. This should only be used when Tiller cannot be normally deployed.
+
+## Initialize Helm and Tiller
+
+Tiller is deployed into the cluster and interacts with the Kubernetes API to deploy your applications. If role based access control (RBAC) is enabled, Tiller will need to be [granted permissions](#preparing-for-helm-with-rbac) to allow it to talk to the Kubernetes API.
+
+If RBAC is not enabled, skip to [initalizing Helm](#initialize-helm).
+
+If you are not sure whether RBAC is enabled in your cluster, or to learn more, read through our [RBAC documentation](rbac.md).
+
+## Preparing for Helm with RBAC
+
+Helm's Tiller will need to be granted permissions to perform operations. These instructions grant cluster wide permissions, however for more advanced deployments [permissions can be restricted to a single namespace](https://docs.helm.sh/using_helm/#example-deploy-tiller-in-a-namespace-restricted-to-deploying-resources-only-in-that-namespace). To grant access to the cluster, we will create a new `tiller` service account and bind it to the `cluster-admin` role.
+
+Create a file `rbac-config.yaml` with the following contents:
+
+```yaml
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: tiller
+  namespace: kube-system
+---
+apiVersion: rbac.authorization.k8s.io/v1beta1
+kind: ClusterRoleBinding
+metadata:
+  name: tiller
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: cluster-admin
+subjects:
+  - kind: ServiceAccount
+    name: tiller
+    namespace: kube-system
+```
+
+Next we need to connect to the cluster and upload the RBAC config.
+
+### Upload the RBAC config
+
+Some clusters require authentication to use `kubectl` to create the Tiller roles.
+
+#### Upload the RBAC config as an admin user (GKE)
+
+For GKE, you need to grab the admin credentials:
+
+```
+gcloud container clusters describe <cluster-name> --zone <zone> --project <project-id> --format='value(masterAuth.password)'
+```
+
+This command will output the admin password. We need the password to authenticate with `kubectl` and create the role.
+
+```
+kubectl --username=admin --password=xxxxxxxxxxxxxx create -f rbac-config.yaml
+```
+
+#### Upload the RBAC config (Other clusters)
+
+For other clusters like Amazon EKS, you can directly upload the RBAC configuration.
+
+kubectl create -f rbac-config.yaml
+
+## Initialize Helm
+
+Deploy Helm Tiller with a service account
+
+```
+helm init --service-account tiller
+```
+
+If your cluster
+previously had Helm/Tiller installed, run the following to ensure that the deployed version of Tiller matches the local Helm version:
+
+```
+helm init --upgrade --service-account tiller
+```
+
+### Patching Helm Tiller for EKS
+
+Helm Tiller requires a flag to be enabled to work properly on EKS:
+
+`kubectl -n kube-system patch deployment tiller-deploy -p '{"spec": {"template": {"spec": {"automountServiceAccountToken": true}}}}'`
+
+[helm]: https://helm.sh
+[helm-using]: https://docs.helm.sh/using_helm
+[k8s-io]: https://kubernetes.io/
+[gcp-k8s]: https://console.cloud.google.com/kubernetes/list
diff --git a/doc/install/kubernetes/preparation/tools_installation.md b/doc/install/kubernetes/preparation/tools_installation.md
new file mode 100644
index 00000000000..210bc2f9e58
--- /dev/null
+++ b/doc/install/kubernetes/preparation/tools_installation.md
@@ -0,0 +1,19 @@
+# Installing kubectl and Helm on your computer
+
+In order to work with the GitLab Helm charts, `kubectl` and `helm` must be installed and configured on your computer.
+
+## Installing `kubectl`
+
+`kubectl` is the Kubernetes command line tool, which can be used to deploy settings to the cluster.
+
+Follow the [official documentation](https://kubernetes.io/docs/tasks/tools/install-kubectl/) for the most up to date instructions.
+
+## Installing `helm`
+
+Helm is a package management tool for Kubernetes, and is used to deploy charts.
+
+You can get Helm from the project's [releases page](https://github.com/kubernetes/helm/releases), or follow other options under the official documentation of [Installing Helm](https://docs.helm.sh/using_helm/#installing-helm).
+
+# Next steps
+
+Once installed, proceed to the next [installation step](../gitlab_chart.md#prerequisites).