1
2
3
4
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
35
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
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
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
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
|
# GitLab-Omnibus Helm Chart
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).
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 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:
- A [GitLab Omnibus](https://docs.gitlab.com/omnibus/) Pod, including Mattermost, Container Registry, and Prometheus
- An auto-scaling [GitLab Runner](https://docs.gitlab.com/runner/) using the Kubernetes executor
- [Redis](https://github.com/kubernetes/charts/tree/master/stable/redis)
- [PostgreSQL](https://github.com/kubernetes/charts/tree/master/stable/postgresql)
- [NGINX Ingress](https://github.com/kubernetes/charts/tree/master/stable/nginx-ingress)
- Persistent Volume Claims for Data, Registry, Postgres, and Redis
## Limitations
[High Availability](../../administration/high_availability/README.md) and
[Geo](https://docs.gitlab.com/ee/administration/geo/replication/index.html) are not supported.
## 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
- [Persistent Volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) provisioner support in the underlying infrastructure
- A [wildcard DNS entry](#networking-prerequisites), which resolves to the external IP address
- 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 requirements
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.
#### 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. 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.
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:
```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.
For production deployments of GitLab, we strongly recommend using a
[external IP](#external-ip).
## Configuring and Installing GitLab
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/gitlab-omnibus/blob/master/values.yaml).
### Choosing a different GitLab release version
The version of GitLab installed is based on the `gitlab` setting (see [section](#choosing-gitlab-edition) above), and
the value of the corresponding helm setting: `gitlabCEImage` or `gitabEEImage`.
```yaml
gitlab: CE
gitlabCEImage: gitlab/gitlab-ce:9.5.2-ce.0
gitlabEEImage: gitlab/gitlab-ee:9.5.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.
### Persistent storage
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.
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:
```yaml
redisImage: redis:3.2.10
redisDedicatedStorage: true
redisStorageSize: 5Gi
postgresImage: postgres:9.6.3
# If you disable postgresDedicatedStorage, you should consider bumping up gitlabRailsStorageSize
postgresDedicatedStorage: true
postgresStorageSize: 30Gi
gitlabRailsStorageSize: 30Gi
gitlabRegistryStorageSize: 30Gi
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).
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: **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:
```bash
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:
```bash
helm install --name gitlab -f values.yaml gitlab/gitlab-omnibus
```
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
```
## Updating GitLab using the Helm Chart
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
```
Once your GitLab Chart is installed, configuration changes and chart updates
should be done using `helm upgrade`:
```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 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
```
You can also upgrade and specify these options via the command line:
```bash
helm upgrade gitlab --set gitlab=ee,gitlabEEImage=gitlab/gitlab-ee:9.5.5-ee.0 gitlab/gitlab-omnibus
```
## Uninstalling GitLab using the Helm Chart
To uninstall the GitLab Chart, run the following:
```bash
helm delete --purge gitlab
```
## Troubleshooting
### 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`.
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
|
