Using the GitLab Unicorn Chart

The unicorn sub-chart provides the GitLab Rails webserver with two Unicorn workers per pod. (The minimum necessary for a single pod to be able to serve any web request in GitLab)

Currently the container used in the chart also includes a copy of GitLab Workhorse, which we haven’t split out yet.

Requirements

This chart depends on Redis, PostgreSQL, Gitaly, and Registry services, either as part of the complete GitLab chart or provided as external services reachable from the Kubernetes cluster this chart is deployed onto.

Configuration

The unicorn chart is configured as follows: Global Settings, Ingress Settings, External Services, and Chart Settings.

Installation command line options

The table below contains all the possible chart configurations that can be supplied to the helm install command using the --set flags.

ParameterDefaultDescription
annotations Pod annotations
deployment.livenessProbe.initialDelaySeconds20Delay before liveness probe is initiated
deployment.livenessProbe.periodSeconds60How often to perform the liveness probe
deployment.livenessProbe.timeoutSeconds30When the liveness probe times out
deployment.livenessProbe.successThreshold1Minimum consecutive successes for the liveness probe to be considered successful after having failed
deployment.livenessProbe.failureThreshold3Minimum consecutive failures for the liveness probe to be considered failed after having succeeded
deployment.readinessProbe.initialDelaySeconds0Delay before readiness probe is initiated
deployment.readinessProbe.periodSeconds10How often to perform the readiness probe
deployment.readinessProbe.timeoutSeconds2When the readiness probe times out
deployment.readinessProbe.successThreshold1Minimum consecutive successes for the readiness probe to be considered successful after having failed
deployment.readinessProbe.failureThreshold3Minimum consecutive failures for the readiness probe to be considered failed after having succeeded
enabledtrueUnicorn enabled flag
extraContainers List of extra containers to include
extraInitContainers List of extra init containers to include
extras.google_analytics_idnilGoogle Analytics Id for frontend
extraVolumeMounts List of extra volumes mountes to do
extraVolumes List of extra volumes to create
gitlab.unicorn.workhorse.imageregistry.gitlab.com/gitlab-org/build/cng/gitlab-workhorse-eeWorkhorse image repository
gitlab.unicorn.workhorse.tag Workhorse image tag
hpa.targetAverageValue1Set the autoscaling target value
image.pullPolicyAlwaysUnicorn image pull policy
image.pullSecrets Secrets for the image repository
image.repositoryregistry.gitlab.com/gitlab-org/build/cng/gitlab-unicorn-eeUnicorn image repository
image.tag Unicorn image tag
init.imagebusyboxinitContainer image
init.taglatestinitContainer image tag
memory.min400The minimum memory threshold (in megabytes) for the Unicorn worker killer
memory.max650The maximum memory threshold (in megabytes) for the Unicorn worker killer
metrics.enabledtrueToggle Prometheus metrics exporter
minio.bucketgit-lfsName of storage bucket, when using MinIO
minio.port9000Port for MinIO service
minio.serviceNameminio-svcName of MinIO service
monitoring.ipWhitelist[0.0.0.0/0]List of IPs to whitelist for the monitoring endpoints
monitoring.exporter.enabledfalseEnable webserver to expose Prometheus metrics
monitoring.exporter.port8083Port number to use for the metrics exporter
psql.password.keypsql-passwordKey to psql password in psql secret
psql.password.secretgitlab-postgrespsql secret name
rack_attack.git_basic_auth{}See GitLab documentation for details
redis.serviceNameredisRedis service name
registry.api.port5000Registry port
registry.api.protocolhttpRegistry protocol
registry.api.serviceNameregistryRegistry service name
registry.enabledtrueAdd/Remove registry link in all projects menu
registry.tokenIssuergitlab-issuerRegistry token issuer
replicaCount1Unicorn number of replicas
resources.requests.cpu200mUnicorn minimum cpu
resources.requests.memory1.4GUnicorn minimum memory
service.externalPort8080Unicorn exposed port
service.internalPort8080Unicorn internal port
service.nameunicornUnicorn service name
service.typeClusterIPUnicorn service type
service.workhorseExternalPort8181Workhorse exposed port
service.workhorseInternalPort8181Workhorse internal port
shell.authToken.keysecretKey to shell token in shell secret
shell.authToken.secretgitlab-shell-secretShell token secret
shell.portnilPort number to use in SSH URLs generated by UI
shutdown.blackoutSeconds10Number of seconds to keep Unicorn running after receiving shutdown
tolerations[]Toleration labels for pod assignment
trusted_proxies[]See GitLab documentation for details
workerProcesses2Unicorn number of workers
workerTimeout60Unicorn worker timeout
workhorse.livenessProbe.initialDelaySeconds20Delay before liveness probe is initiated
workhorse.livenessProbe.periodSeconds60How often to perform the liveness probe
workhorse.livenessProbe.timeoutSeconds30When the liveness probe times out
workhorse.livenessProbe.successThreshold1Minimum consecutive successes for the liveness probe to be considered successful after having failed
workhorse.livenessProbe.failureThreshold3Minimum consecutive failures for the liveness probe to be considered failed after having succeeded
workhorse.readinessProbe.initialDelaySeconds0Delay before readiness probe is initiated
workhorse.readinessProbe.periodSeconds10How often to perform the readiness probe
workhorse.readinessProbe.timeoutSeconds2When the readiness probe times out
workhorse.readinessProbe.successThreshold1Minimum consecutive successes for the readiness probe to be considered successful after having failed
workhorse.readinessProbe.failureThreshold3Minimum consecutive failures for the readiness probe to be considered failed after having succeeded

Chart configuration examples

image.pullSecrets

pullSecrets allows you to authenticate to a private registry to pull images for a pod.

Additional details about private registries and their authentication methods can be found in the Kubernetes documentation.

Below is an example use of pullSecrets:

image:
  repository: my.unicorn.repository
  pullPolicy: Always
  pullSecrets:
  - name: my-secret-name
  - name: my-secondary-secret-name

tolerations

tolerations allow you schedule pods on tainted worker nodes

Below is an example use of tolerations:

tolerations:
- key: "node_label"
  operator: "Equal"
  value: "true"
  effect: "NoSchedule"
- key: "node_label"
  operator: "Equal"
  value: "true"
  effect: "NoExecute"

annotations

annotations allows you to add annotations to the Unicorn pods. For example:

annotations:
  kubernetes.io/example-annotation: annotation-value

Using the Community Edition of this chart

By default, the Helm charts use the Enterprise Edition of GitLab. If desired, you can use the Community Edition instead. Learn more about the differences between the two.

In order to use the Community Edition, set image.repository to registry.gitlab.com/gitlab-org/build/cng/gitlab-unicorn-ce and workhorse.image to registry.gitlab.com/gitlab-org/build/cng/gitlab-workhorse-ce.

Global Settings

We share some common global settings among our charts. See the Globals Documentation for common configuration options, such as GitLab and Registry hostnames.

Ingress Settings

NameTypeDefaultDescription
ingress.annotations.*annotation-key*String(empty)annotation-key is a string that will be used with the value as an annotation on every Ingress. For example: ingress.annotations."nginx\.ingress\.kubernetes\.io/enable-access-log"=true.
ingress.enabledBooleanfalseSetting that controls whether to create Ingress objects for services that support them. When false, the global.ingress.enabled setting value is used.
ingress.proxyBodySizeString512mSee Below.
ingress.tls.enabledBooleantrueWhen set to false, you disable TLS for GitLab Unicorn. This is mainly useful for cases in which you cannot use TLS termination at Ingress-level, like when you have a TLS-terminating proxy before the Ingress Controller.
ingress.tls.secretNameString(empty)The name of the Kubernetes TLS Secret that contains a valid certificate and key for the GitLab url. When not set, the global.ingress.tls.secretName value is used instead.

proxyBodySize

proxyBodySize is used to set the NGINX proxy maximum body size. This is commonly required to allow a larger docker image than the default. As an alternative option, you can set the body size with either of the following two parameters too:

  • gitlab.unicorn.ingress.annotations."nginx\.ingress\.kubernetes\.io/proxy-body-size"
  • global.ingress.annotations."nginx\.ingress\.kubernetes\.io/proxy-body-size"

Memory

Memory thresholds for the unicorn-worker-killer can be customized using the memory.min and memory.max chart values. While the default values are sane, you can increase (or lower) these values to fine-tune them for your environment or troubleshoot performance issues.

External Services

Redis

redis:
  host: redis.example.com
  serviceName: redis
  port: 6379
  sentinels:
    - host: sentinel1.example.com
      port: 26379
  password:
    enabled: true
    secret: gitlab-redis
    key: redis-password
NameTypeDefaultDescription
hostString The hostname of the Redis server with the database to use. This can be omitted in lieu of serviceName. If using Redis Sentinels, the host attribute needs to be set to the cluster name as specified in the sentinel.conf.
serviceNameStringredisThe name of the service which is operating the Redis database. If this is present, and host is not, the chart will template the hostname of the service (and current .Release.Name) in place of the host value. This is convenient when using Redis as a part of the overall GitLab chart.
portInteger6379The port on which to connect to the Redis server.
password.keyString The password.key attribute for Redis defines the name of the key in the secret (below) that contains the password.
password.secretString The password.secret attribute for Redis defines the name of the Kubernetes Secret to pull from.
password.enabledBooltrueThe password.enabled provides a toggle for using a password with the Redis instance.
sentinels.[].hostString The hostname of Redis Sentinel server for a Redis HA setup.
sentinels.[].portInteger26379The port on which to connect to the Redis Sentinel server.

Note: The current Redis Sentinel support only supports Sentinels that have been deployed separately from the GitLab chart. As a result, the Redis deployment through the GitLab chart should be disabled with redis.enabled=false and redis-ha.enabled=false. The Secret containing the Redis password will need to be manually created before deploying the GitLab chart.

PostgreSQL

psql:
  host: psql.example.com
  serviceName: pgbouncer
  port: 5432
  database: gitlabhq_production
  username: gitlab
  preparedStatements: false
  password:
    secret: gitlab-postgres
    key: psql-password
NameTypeDefaultDescription
hostString The hostname of the PostgreSQL server with the database to use. This can be omitted if postgresql.install=true (default non-production).
serviceNameString The name of the service which is operating the PostgreSQL database. If this is present, and host is not, the chart will template the hostname of the service in place of the host value.
databaseStringgitlabhq_productionThe name of the database to use on the PostgreSQL server.
password.keyString The password.key attribute for PostgreSQL defines the name of the key in the secret (below) that contains the password.
password.secretString The password.secret attribute for PostgreSQL defines the name of the Kubernetes Secret to pull from.
portInteger5432The port on which to connect to the PostgreSQL server.
usernameStringgitlabThe username with which to authenticate to the database.
preparedStatementsBoolfalseIf prepared statements should be used when communicating with the PostgreSQL server.

Gitaly

Gitaly is configured by global settings. Please see the Gitaly configuration documentation.

MinIO

minio:
  serviceName: 'minio-svc'
  port: 9000
NameTypeDefaultDescription
portInteger9000Port number to reach the MinIO Service on.
serviceNameStringminio-svcName of the Service that is exposed by the MinIO pod.

Registry

registry:
  host: registry.example.com
  port: 443
  api:
    protocol: http
    host: registry.example.com
    serviceName: registry
    port: 5000
  tokenIssuer: gitlab-issuer
  certificate:
    secret: gitlab-registry
    key: registry-auth.key
NameTypeDefaultDescription
api.hostString The hostname of the Registry server to use. This can be omitted in lieu of api.serviceName.
api.portInteger5000The port on which to connect to the Registry API.
api.protocolString The protocol Unicorn should use to reach the Registry API.
api.serviceNameStringregistryThe name of the service which is operating the Registry server. If this is present, and api.host is not, the chart will template the hostname of the service (and current .Release.Name) in place of the api.host value. This is convenient when using Registry as a part of the overall GitLab chart.
certificate.keyString The name of the key in the Secret which houses the certificate bundle that will be provided to the registry container as auth.token.rootcertbundle.
certificate.secretString The name of the Kubernetes Secret that houses the certificate bundle to be used to verify the tokens created by the GitLab instance(s).
hostString The external hostname to use for providing docker commands to users in the GitLab UI. Falls back to the value set in the registry.hostname template. Which determines the registry hostname based on the values set in global.hosts. See the Globals Documentation for more information.
portInteger The external port used in the hostname. Using port 80 or 443 will result in the URLs being formed with http/https. Other ports will all use http and append the port to the end of hostname, for example http://registry.example.com:8443.
tokenIssuerStringgitlab-issuerThe name of the auth token issuer. This must match the name used in the Registry’s configuration, as it incorporated into the token when it is sent. The default of gitlab-issuer is the same default we use in the Registry chart.

Chart Settings

The following values are used to configure the Unicorn Pods.

NameTypeDefaultDescription
replicaCountInteger1The number of Unicorn instances to create in the deployment.
workerProcessesInteger2The number of Unicorn workers to run per pod. You must have at least 2 workers available in your cluster in order for GitLab to function properly. Note that increasing the workerProcesses will increase the memory required by approximately 400MB per worker, so you should update the pod resources accordingly.
workerTimeoutInteger60The number of seconds a request can be pending before it times out.

metrics.enabled

By default, each pod exposes a metrics endpoint at /-/metrics. Metrics are only available when GitLab Prometheus metrics are enabled in the Admin area. When metrics are enabled, annotations are added to each pod allowing a Prometheus server to discover and scrape the exposed metrics.

GitLab Shell

GitLab Shell uses an Auth Token in its communication with Unicorn. Share the token with GitLab Shell and Unicorn using a shared Secret.

shell:
  authToken:
    secret: gitlab-shell-secret
    key: secret
  port:
NameTypeDefaultDescription
authToken.keyString Defines the name of the key in the secret (below) that contains the authToken.
authToken.secretString Defines the name of the Kubernetes Secret to pull from.
portInteger22The port number to use in the generation of SSH URLs within the GitLab UI. Controlled by global.shell.port.