Skip to content
Snippets Groups Projects
Commit f6d5c72f authored by Achilleas Pipinellis's avatar Achilleas Pipinellis
Browse files

Merge branch 'helm-documentation' into 'master' 

Kubernetes Helm Chart Install docs

See merge request !11139

Former-commit-id: 914a0bbd
parents 1bbf1a81 a84879bb
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
doc/install/README.md
+ 2
− 0
View file @ f6d5c72f
@@ -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.
 
doc/install/kubernetes/gitlab_chart.md 0 → 100644
+ 436
− 0
View file @ f6d5c72f
# 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
doc/install/kubernetes/gitlab_runner_chart.md 0 → 100644
+ 175
− 0
View file @ f6d5c72f
# 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`.
doc/install/kubernetes/index.md 0 → 100644
+ 44
− 0
View file @ f6d5c72f
# 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
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment