gitlab_chart.md 6.74 KB
Newer Older
1
# GitLab Helm Chart
2
> **Note:** The chart is currently **beta**, if you encounter any problems please [open an issue](https://gitlab.com/charts/gitlab/issues/new).
3

4
For more information on available GitLab Helm Charts, please see our [overview](index.md#chart-overview).
5

6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34
## 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).
Joshua Lambert's avatar
Joshua Lambert committed
35
1. A Kubernetes cluster, version 1.8 or higher. 6vCPU and 16GB of RAM is recommended.
36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66
  * [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/
Joshua Lambert's avatar
Joshua Lambert committed
67
helm update
68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83
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

Mike Lewis's avatar
Mike Lewis committed
84
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`.
85 86 87

If you manually created the secret for initial root password, you
can use that to sign in as `root` user. If not, Gitlab automatically
88 89
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`
Joshua Lambert's avatar
Joshua Lambert committed
90
if you used the command above).
91 92

```
93
kubectl get secret <name>-gitlab-initial-root-password -ojsonpath={.data.password} | base64 --decode
94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137
```

## 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