Kubernetes Helm Chart Install docs

4 files changed, 657 insertions, 0 deletions

diff --git a/doc/install/README.md b/doc/install/README.md
index 58cc7d312fd..3bf7923a9ee 100644
--- a/doc/install/README.md
+++ b/doc/install/README.md
@@ -20,6 +20,8 @@ the hardware requirements.
 - [Docker](https://docs.gitlab.com/omnibus/docker/) - Install GitLab using Docker.
 - [Installation on Google Cloud Platform](google_cloud_platform/index.md) - Install
   GitLab on Google Cloud Platform using our official image.
+- [Installing in Kubernetes](kubernetes/index.md) - Install GitLab into a Kubernetes
+  Cluster using our official Helm Chart Repository.
 - Testing only! [DigitalOcean and Docker Machine](digitaloceandocker.md) -
   Quickly test any version of GitLab on DigitalOcean using Docker Machine.
 
diff --git a/doc/install/kubernetes/gitlab_chart.md b/doc/install/kubernetes/gitlab_chart.md
new file mode 100644
index 00000000000..35d395af024
--- /dev/null
+++ b/doc/install/kubernetes/gitlab_chart.md
@@ -0,0 +1,436 @@
+# GitLab Helm Chart
+
+The `gitlab` Helm chart deploys GitLab into your Kubernetes cluster.
+
+This chart includes the following:
+
+- Deployment using the [gitlab-ce](https://hub.docker.com/r/gitlab/gitlab-ce) or [gitlab-ee](https://hub.docker.com/r/gitlab/gitlab-ee) container image
+- ConfigMap containing the `gitlab.rb` contents that configure [Omnibus GitLab](https://docs.gitlab.com/omnibus/settings/configuration.html#configuration-options)
+- Persistent Volume Claims for Data, Config, Logs, and Registry Storage
+- A Kubernetes service
+- Optional Redis deployment using the [Redis Chart](https://github.com/kubernetes/charts/tree/master/stable/redis) (defaults to enabled)
+- Optional PostgreSQL deployment using the [PostgreSQL Chart](https://github.com/kubernetes/charts/tree/master/stable/postgresql) (defaults to enabled)
+- Optional Ingress (defaults to disabled)
+
+## Prerequisites
+
+- _At least_ 3 GB of RAM available on your cluster, in chunks of 1 GB
+- Kubernetes 1.4+ with Beta APIs enabled
+- [Persistent Volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) provisioner support in the underlying infrastructure
+- The ability to point a DNS entry or URL at your GitLab install
+- The `kubectl` CLI installed locally and authenticated for the cluster
+- The Helm Client installed locally
+- The Helm Server (Tiller) already installed and running in the cluster, by running `helm init`
+- The GitLab Helm Repo [added to your Helm Client](index.md#add-the-gitlab-helm-repository)
+
+## Configuring GitLab
+
+Create a `values.yaml` file for your GitLab configuration. See the
+[Helm docs](https://github.com/kubernetes/helm/blob/master/docs/chart_template_guide/values_files.md)
+for information on how your values file will override the defaults.
+
+The default configuration can always be [found in the `values.yaml`](https://gitlab.com/charts/charts.gitlab.io/blob/master/charts/gitlab/values.yaml), in the chart repository.
+
+### Required configuration
+
+In order for GitLab to function, your config file **must** specify the following:
+
+- An `externalUrl` that GitLab will be reachable at.
+
+### Choosing GitLab Edition
+
+The Helm chart defaults to installing GitLab CE. This can be controlled by setting the `edition` variable in your values.
+
+Setting `edition` to GitLab Enterprise Edition (EE) in your `values.yaml`
+
+```yaml
+edition: EE
+
+externalUrl: 'http://gitlab.example.com'
+```
+
+### Choosing a different GitLab release version
+
+The version of GitLab installed is based on the `edition` setting (see [section](#choosing-gitlab-edition) above), and
+the value of the corresponding helm setting: `ceImage` or `eeImage`.
+
+```yaml
+## GitLab Edition
+## ref: https://about.gitlab.com/products/
+## - CE - Community Edition
+## - EE - Enterprise Edition - (requires license issued by GitLab Inc)
+##
+edition: CE
+
+## GitLab CE image
+## ref: https://hub.docker.com/r/gitlab/gitlab-ce/tags/
+##
+ceImage: gitlab/gitlab-ce:9.1.2-ce.0
+
+## GitLab EE image
+## ref: https://hub.docker.com/r/gitlab/gitlab-ee/tags/
+##
+eeImage: gitlab/gitlab-ee:9.1.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.
+
+
+### Custom Omnibus GitLab configuration
+
+In addition to the configuration options provided for GitLab in the Helm Chart, you can also pass any custom configuration
+that is valid for the [Omnibus GitLab Configuration](https://docs.gitlab.com/omnibus/settings/configuration.html).
+
+The setting to pass these values in is `omnibusConfigRuby`. It accepts any valid
+Ruby code that could used in the Omnibus `/etc/gitlab/gitlab.rb` file. In
+Kubernetes, the contents will be stored in a ConfigMap.
+
+Example setting:
+
+```yaml
+omnibusConfigRuby: |
+  unicorn['worker_processes'] = 2;
+  gitlab_rails['trusted_proxies'] = ["10.0.0.0/8","172.16.0.0/12","192.168.0.0/16"];
+```
+
+### Persistent storage
+
+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`, and each
+component allows you to optionally configure the `storageClass` variable so you
+can take advantage of faster drives on your cloud provider.
+
+Basic configuration:
+
+```yaml
+## Enable persistence using Persistent Volume Claims
+## ref: http://kubernetes.io/docs/user-guide/persistent-volumes/
+## ref: https://docs.gitlab.com/ce/install/requirements.html#storage
+##
+persistence:
+  ## This volume persists generated configuration files, keys, and certs.
+  ##
+  gitlabEtc:
+    enabled: true
+    size: 1Gi
+    ## If defined, volume.beta.kubernetes.io/storage-class: <storageClass>
+    ## Default: volume.alpha.kubernetes.io/storage-class: default
+    ##
+    # storageClass:
+    accessMode: ReadWriteOnce
+  ## This volume is used to store git data and other project files.
+  ## ref: https://docs.gitlab.com/omnibus/settings/configuration.html#storing-git-data-in-an-alternative-directory
+  ##
+  gitlabData:
+    enabled: true
+    size: 10Gi
+    ## If defined, volume.beta.kubernetes.io/storage-class: <storageClass>
+    ## Default: volume.alpha.kubernetes.io/storage-class: default
+    ##
+    # storageClass:
+    accessMode: ReadWriteOnce
+  gitlabRegistry:
+    enabled: true
+    size: 10Gi
+    ## If defined, volume.beta.kubernetes.io/storage-class: <storageClass>
+    ## Default: volume.alpha.kubernetes.io/storage-class: default
+    ##
+    # storageClass:
+
+  postgresql:
+    persistence:
+      # storageClass:
+      size: 10Gi
+  ## Configuration values for the Redis dependency.
+  ## ref: https://github.com/kubernetes/charts/blob/master/stable/redis/README.md
+  ##
+  redis:
+    persistence:
+      # storageClass:
+      size: 10Gi
+```
+
+>**Note:**
+You can make use of faster SSD drives by adding a [StorageClass] to your cluster
+and using the `storageClass` setting in the above config to the name of
+your new storage class.
+
+### Routing
+
+By default, the GitLab chart uses a service type of `LoadBalancer` which will
+result in the GitLab service being exposed externally using your cloud provider's
+load balancer.
+
+This field is configurable in your `values.yml` by setting the top-level
+`serviceType` field. See the [Service documentation][kube-srv] for more
+information on the possible values.
+
+#### Ingress routing
+
+Optionally, you can enable the Chart's ingress for use by an ingress controller
+deployed in your cluster.
+
+To enable the ingress, edit its section in your `values.yaml`:
+
+```yaml
+ingress:
+  ## If true, gitlab Ingress will be created
+  ##
+  enabled: true
+
+  ## gitlab Ingress hostnames
+  ## Must be provided if Ingress is enabled
+  ##
+  hosts:
+    - gitlab.example.com
+
+  ## gitlab Ingress annotations
+  ##
+  annotations:
+    kubernetes.io/ingress.class: nginx
+```
+
+You must also provide the list of hosts that the ingress will use. In order for
+you ingress controller to work with the GitLab Ingress, you will need to specify
+its class in an annotation.
+
+>**Note:**
+The Ingress alone doesn't expose GitLab externally. You need to have a Ingress controller setup to do that.
+Setting up an Ingress controller can be as simple as installing the `nginx-ingress` helm chart. But be sure
+to read the [documentation](https://github.com/kubernetes/charts/blob/master/stable/nginx-ingress/README.md)
+
+### External database
+
+You can configure the GitLab Helm chart to connect to an external PostgreSQL
+database.
+
+>**Note:**
+This is currently our recommended approach for a Production setup.
+
+To use an external database, in your `values.yaml`, disable the included
+PostgreSQL dependency, then configure access to your database:
+
+```yaml
+dbHost: "<reachable postgres hostname>"
+dbPassword: "<password for the user with access to the db>"
+dbUsername: "<user with read/write access to the database>"
+dbDatabase: "<database name on postgres to connect to for GitLab>"
+
+postgresql:
+  # Sets whether the PostgreSQL helm chart is used as a dependency
+  enabled: false
+```
+
+Be sure to check the GitLab documentation on how to
+[configure the external database](../requirements.md#postgresql-requirements)
+
+You can also configure the chart to use an external Redis server, but this is
+not required for basic production use:
+
+```yaml
+dbHost: "<reachable redis hostname>"
+dbPassword: "<password>"
+
+redis:
+  # Sets whether the Redis helm chart is used as a dependency
+  enabled: false
+```
+
+### Sending email
+
+By default, the GitLab container will not be able to send email from your cluster.
+In order to send email, you should configure SMTP settings in the
+`omnibusConfigRuby` section, as per the [GitLab Omnibus documentation](https://docs.gitlab.com/omnibus/settings/smtp.html).
+
+>**Note:**
+Some cloud providers restrict emails being sent out on SMTP, so you will have
+to use a SMTP service that is supported by your provider. See this
+[Google Cloud Platform page](https://cloud.google.com/compute/docs/tutorials/sending-mail/)
+as and example.
+
+Here is an example configuration for Mailgun SMTP support:
+
+```yaml
+omnibusConfigRuby: |
+  # This is example config of what you may already have in your omnibusConfigRuby object
+  unicorn['worker_processes'] = 2;
+  gitlab_rails['trusted_proxies'] = ["10.0.0.0/8","172.16.0.0/12","192.168.0.0/16"];
+
+  # SMTP settings
+  gitlab_rails['smtp_enable'] = true
+  gitlab_rails['smtp_address'] = "smtp.mailgun.org"
+  gitlab_rails['smtp_port'] = 2525 # High port needed for Google Cloud
+  gitlab_rails['smtp_authentication'] = "plain"
+  gitlab_rails['smtp_enable_starttls_auto'] = false
+  gitlab_rails['smtp_user_name'] = "postmaster@mg.your-mail-domain"
+  gitlab_rails['smtp_password'] = "you-password"
+  gitlab_rails['smtp_domain'] = "mg.your-mail-domain"
+```
+
+### HTTPS configuration
+
+To setup HTTPS access to your GitLab server, first you need to configure the
+chart to use the [ingress](#ingress-routing).
+
+GitLab's config should be updated to support [proxied SSL](https://docs.gitlab.com/omnibus/settings/nginx.html#supporting-proxied-ssl).
+
+In addition to having a Ingress Controller deployed and the basic ingress
+settings configured, you will also need to specify in the ingress settings
+which hosts to use HTTPS for.
+
+Make sure `externalUrl` now includes `https://` instead of `http://` in its
+value, and update the `omnibusConfigRuby` section:
+
+```yaml
+externalUrl: 'https://gitlab.example.com'
+
+omnibusConfigRuby: |
+  # This is example config of what you may already have in your omnibusConfigRuby object
+  unicorn['worker_processes'] = 2;
+  gitlab_rails['trusted_proxies'] = ["10.0.0.0/8","172.16.0.0/12","192.168.0.0/16"];
+
+  # These are the settings needed to support proxied SSL
+  nginx['listen_port'] = 80
+  nginx['listen_https'] = false
+  nginx['proxy_set_headers'] = {
+    "X-Forwarded-Proto" => "https",
+    "X-Forwarded-Ssl" => "on"
+  }
+
+ingress:
+  enabled: true
+  annotations:
+   kubernetes.io/ingress.class: nginx
+   # kubernetes.io/tls-acme: 'true' Annotation used for letsencrypt support
+
+  hosts:
+    - gitlab.example.com
+
+    ## gitlab Ingress TLS configuration
+    ## Secrets must be created in the namespace, and is not done for you in this chart
+    ##
+    tls:
+      - secretName: gitlab-tls
+        hosts:
+          - gitlab.example.com
+```
+
+You will need to create the named secret in your cluster, specifying the private
+and public certificate pair using the format outlined in the
+[ingress documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls).
+
+Alternatively, you can use the `kubernetes.io/tls-acme` annotation, and install
+the `kube-lego` chart to your cluster to have Let's Encrypt issue your
+certificate. See the [kube-lego documentation](https://github.com/kubernetes/charts/blob/master/stable/kube-lego/README.md)
+for more information.
+
+### Enabling the GitLab Container Registry
+
+The GitLab Registry is disabled by default but can be enabled by providing an
+external URL for it in the configuration. In order for the Registry to be easily
+used by GitLab CI and your Kubernetes cluster, you will need to set it up with
+a TLS certificate, so these examples will include the ingress settings for that
+as well. See the [HTTPS Configuration section](#https-configuration)
+for more explanation on some of these settings.
+
+Example config:
+
+```yaml
+externalUrl: 'https://gitlab.example.com'
+
+omnibusConfigRuby: |
+  # This is example config of what you may already have in your omnibusConfigRuby object
+  unicorn['worker_processes'] = 2;
+  gitlab_rails['trusted_proxies'] = ["10.0.0.0/8","172.16.0.0/12","192.168.0.0/16"];
+
+  registry_external_url 'https://registry.example.com';
+
+  # These are the settings needed to support proxied SSL
+  nginx['listen_port'] = 80
+  nginx['listen_https'] = false
+  nginx['proxy_set_headers'] = {
+    "X-Forwarded-Proto" => "https",
+    "X-Forwarded-Ssl" => "on"
+  }
+  registry_nginx['listen_port'] = 80
+  registry_nginx['listen_https'] = false
+  registry_nginx['proxy_set_headers'] = {
+    "X-Forwarded-Proto" => "https",
+    "X-Forwarded-Ssl" => "on"
+  }
+
+ingress:
+  enabled: true
+  annotations:
+   kubernetes.io/ingress.class: nginx
+   # kubernetes.io/tls-acme: 'true' Annotation used for letsencrypt support
+
+  hosts:
+    - gitlab.example.com
+    - registry.example.com
+
+    ## gitlab Ingress TLS configuration
+    ## Secrets must be created in the namespace, and is not done for you in this chart
+    ##
+    tls:
+      - secretName: gitlab-tls
+        hosts:
+          - gitlab.example.com
+          - registry.example.com
+```
+
+## Installing GitLab using the Helm Chart
+
+Once you [have configured](#configuration) GitLab in your `values.yml` file,
+run the following:
+
+```bash
+helm install --namepace <NAMEPACE> --name gitlab -f <CONFIG_VALUES_FILE> gitlab/gitlab
+```
+
+where:
+
+- `<NAMESPACE>` is the Kubernetes namespace where you want to install GitLab.
+- `<CONFIG_VALUES_FILE>` is the path to values file containing your custom
+  configuration. See the [Configuration](#configuration) section to create it.
+
+## Updating GitLab using the Helm Chart
+
+Once your GitLab Chart is installed, configuration changes and chart updates
+should we done using `helm upgrade`
+
+```bash
+helm upgrade --namepace <NAMEPACE> -f <CONFIG_VALUES_FILE> <RELEASE-NAME> gitlab/gitlab
+```
+
+where:
+
+- `<NAMESPACE>` is the Kubernetes namespace where GitLab is installed.
+- `<CONFIG_VALUES_FILE>` is the path to values file containing your custom
+  [configuration] (#configuration).
+- `<RELEASE-NAME>` is the name you gave the chart when installing it.
+  In the [Install section](#installing) we called it `gitlab`.
+
+## Uninstalling GitLab using the Helm Chart
+
+To uninstall the GitLab Chart, run the following:
+
+```bash
+helm delete --namespace <NAMESPACE> <RELEASE-NAME>
+```
+
+where:
+
+- `<NAMESPACE>` is the Kubernetes namespace where GitLab is installed.
+- `<RELEASE-NAME>` is the name you gave the chart when installing it.
+  In the [Install section](#installing) we called it `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/gitlab_runner_chart.md b/doc/install/kubernetes/gitlab_runner_chart.md
new file mode 100644
index 00000000000..dbd9ae3f70c
--- /dev/null
+++ b/doc/install/kubernetes/gitlab_runner_chart.md
@@ -0,0 +1,175 @@
+# GitLab Runner Helm Chart
+
+The `gitlab-runner` Helm chart deploys a GitLab Runner instance into your
+Kubernetes cluster.
+
+This chart configures the Runner to:
+
+- Run using the GitLab Runner [Kubernetes executor](https://docs.gitlab.com/runner/install/kubernetes.html)
+- For each new job it receives from [GitLab CI](https://about.gitlab.com/features/gitlab-ci-cd/), it will provision a
+  new pod within the specified namespace to run it.
+
+## Prerequisites
+
+- Your GitLab Server's API is reachable from the cluster
+- Kubernetes 1.4+ with Beta APIs enabled
+- The `kubectl` CLI installed locally and authenticated for the cluster
+- The Helm Client installed locally
+- The Helm Server (Tiller) already installed and running in the cluster, by running `helm init`
+- The GitLab Helm Repo added to your Helm Client. See [Adding GitLab Helm Repo](index.md#add-the-gitlab-helm-repository)
+
+## Configuring GitLab Runner using the Helm Chart
+
+Create a `values.yaml` file for your GitLab Runner configuration. See [Helm docs](https://github.com/kubernetes/helm/blob/master/docs/chart_template_guide/values_files.md)
+for information on how your values file will override the defaults.
+
+The default configuration can always be found in the [values.yaml](https://gitlab.com/charts/charts.gitlab.io/blob/master/charts/gitlab-runner/values.yaml) in the chart repository.
+
+### Required configuration
+
+In order for GitLab Runner to function, your config file **must** specify the following:
+
+ - `gitlabURL`  - the GitLab Server URL (with protocol) to register the runner against
+ - `runnerRegistrationToken` - The Registration Token for adding new Runners to the GitLab Server. This must be
+    retrieved from your GitLab Instance. See the [GitLab Runner Documentation](../../ci/runners/README.md#creating-and-registering-a-runner) for more information.
+
+### Other configuration
+
+The rest of the configuration is [documented in the `values.yaml`](https://gitlab.com/charts/charts.gitlab.io/blob/master/charts/gitlab-runner/values.yaml) in the chart repository.
+
+Here is a snippet of the important settings:
+
+```yaml
+## The GitLab Server URL (with protocol) that want to register the runner against
+## ref: https://docs.gitlab.com/runner/commands/README.html#gitlab-runner-register
+##
+gitlabURL: http://gitlab.your-domain.com/
+
+## The Registration Token for adding new Runners to the GitLab Server. This must
+## be retreived from your GitLab Instance.
+## ref: https://docs.gitlab.com/ce/ci/runners/README.html#creating-and-registering-a-runner
+##
+runnerRegistrationToken: ""
+
+## Configure the maximum number of concurrent jobs
+## ref: https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section
+##
+concurrent: 10
+
+## Defines in seconds how often to check GitLab for a new builds
+## ref: https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section
+##
+checkInterval: 30
+
+## Configuration for the Pods that that the runner launches for each new job
+##
+runners:
+  ## Default container image to use for builds when none is specified
+  ##
+  image: ubuntu:16.04
+
+  ## Run all containers with the privileged flag enabled
+  ## This will allow the docker:dind image to run if you need to run Docker
+  ## commands. Please read the docs before turning this on:
+  ## ref: https://docs.gitlab.com/runner/executors/kubernetes.html#using-docker-dind
+  ##
+  privileged: false
+
+  ## Namespace to run Kubernetes jobs in (defaults to 'default')
+  ##
+  # namespace:
+
+  ## Build Container specific configuration
+  ##
+  builds:
+    # cpuLimit: 200m
+    # memoryLimit: 256Mi
+    cpuRequests: 100m
+    memoryRequests: 128Mi
+
+  ## Service Container specific configuration
+  ##
+  services:
+    # cpuLimit: 200m
+    # memoryLimit: 256Mi
+    cpuRequests: 100m
+    memoryRequests: 128Mi
+
+  ## Helper Container specific configuration
+  ##
+  helpers:
+    # cpuLimit: 200m
+    # memoryLimit: 256Mi
+    cpuRequests: 100m
+    memoryRequests: 128Mi
+
+```
+
+### Running Docker-in-Docker containers with GitLab Runners
+
+See [Running Privileged Containers for the Runners](#running-privileged-containers-for-the-runners) for how to enable it,
+and the [GitLab CI Runner documentation](https://docs.gitlab.com/runner/executors/kubernetes.html#using-docker-in-your-builds) on running dind.
+
+### Running privileged containers for the Runners
+
+You can tell the GitLab Runner to run using privileged containers. You may need
+this enabled if you need to use the Docker executable within your GitLab CI jobs.
+
+This comes with several risks that you can read about in the
+[GitLab CI Runner documentation](https://docs.gitlab.com/runner/executors/kubernetes.html#using-docker-in-your-builds).
+
+If you are okay with the risks, and your GitLab CI Runner instance is registered
+against a specific project in GitLab that you trust the CI jobs of, you can
+enable privileged mode in `values.yaml`:
+
+```yaml
+runners:
+  ## Run all containers with the privileged flag enabled
+  ## This will allow the docker:dind image to run if you need to run Docker
+  ## commands. Please read the docs before turning this on:
+  ## ref: https://docs.gitlab.com/runner/executors/kubernetes.html#using-docker-dind
+  ##
+  privileged: true
+```
+
+## Installing GitLab Runner using the Helm Chart
+
+Once you [have configured](#configuration) GitLab Runner in your `values.yml` file,
+run the following:
+
+```bash
+helm install --namepace <NAMEPACE> --name gitlab-runner -f <CONFIG_VALUES_FILE> gitlab/gitlab-runner
+```
+
+- `<NAMESPACE>` is the Kubernetes namespace where you want to install the GitLab Runner.
+- `<CONFIG_VALUES_FILE>` is the path to values file containing your custom configuration. See the
+  [Configuration](#configuration) section to create it.
+
+## Updating GitLab Runner using the Helm Chart
+
+Once your GitLab Runner Chart is installed, configuration changes and chart updates should we done using `helm upgrade`
+
+```bash
+helm upgrade --namepace <NAMEPACE> -f <CONFIG_VALUES_FILE> <RELEASE-NAME> gitlab/gitlab-runner
+```
+
+Where:
+- `<NAMESPACE>` is the Kubernetes namespace where GitLab Runner is installed
+- `<CONFIG_VALUES_FILE>` is the path to values file containing your custom configuration. See the
+  [Configuration](#configuration) section to create it.
+- `<RELEASE-NAME>` is the name you gave the chart when installing it.
+  In the [Install section](#installing) we called it `gitlab-runner`.
+
+## Uninstalling GitLab Runner using the Helm Chart
+
+To uninstall the GitLab Runner Chart, run the following:
+
+```bash
+helm delete --namespace <NAMESPACE> <RELEASE-NAME>
+```
+
+where:
+
+- `<NAMESPACE>` is the Kubernetes namespace where GitLab Runner is installed
+- `<RELEASE-NAME>` is the name you gave the chart when installing it.
+  In the [Install section](#installing) we called it `gitlab-runner`.
diff --git a/doc/install/kubernetes/index.md b/doc/install/kubernetes/index.md
new file mode 100644
index 00000000000..db0430fc27b
--- /dev/null
+++ b/doc/install/kubernetes/index.md
@@ -0,0 +1,44 @@
+# Installing GitLab in Kubernetes
+
+The easiest method to deploy GitLab in [Kubernetes](https://kubernetes.io/) is
+to take advantage of the official GitLab 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.
+
+The GitLab Helm repository is located at https://charts.gitlab.io.
+You can report any issues related to GitLab's Helm Charts at
+https://gitlab.com/charts/charts.gitlab.io/issues.
+Contributions and improvements are also very welcome.
+
+## Prerequisites
+
+To use the charts, the Helm tool must be installed and initialized. The best
+place to start is by reviewing the [Helm Quick Start Guide][helm-quick].
+
+## Add the GitLab Helm repository
+
+Once Helm has been installed, the GitLab chart repository must be added:
+
+```bash
+helm repo add gitlab https://charts.gitlab.io
+```
+
+After adding the repository, Helm must be re-initialized:
+
+```bash
+helm init
+```
+
+## Using the GitLab Helm Charts
+
+GitLab makes available two Helm Charts, one for the GitLab server and another
+for the Runner. More detailed information on installing and configuring each
+Chart can be found below:
+
+- [Install GitLab](gitlab_chart.md)
+- [Install GitLab Runner](gitlab_runner_chart.md)
+
+[chart]: https://github.com/kubernetes/charts
+[helm-quick]: https://github.com/kubernetes/helm/blob/master/docs/quickstart.md
+[helm]: https://github.com/kubernetes/helm/blob/master/README.md