• Configure Host settings
  • hostSuffix
• Configure Ingress settings
  • global.ingress.configureCertmanager
• GitLab Version
• Configure PostgreSQL settings
• Configure Redis settings
• Configure Grafana integration
• Configure Registry settings
• Configure Gitaly settings
  • Gitaly hosts
    • Internal
    • External
    • Mixed
  • authToken
  • Deprecated Gitaly settings
  • TLS settings
• Configure MinIO settings
• Configure appConfig settings
  • General application settings
    • defaultProjectsFeatures
  • Gravatar/Libravatar settings
  • Hooking Analytics services to the GitLab instance
  • LFS, Artifacts, Uploads, Packages, and External MR diffs
    • connection
    • when (only for External MR Diffs)
  • Incoming email settings
  • LDAP
    • Disable LDAP web sign in
    • Using a custom CA or self signed LDAP certificates
  • OmniAuth
    • providers
  • Pseudonymizer settings
    • configMap
    • connection
  • Cron jobs related settings
• Configure Rails settings
  • Bootsnap Cache
• Configure GitLab Shell
• Configure Unicorn
  • workerTimeout
• Custom Certificate Authorities
• Application Resource
• Busybox image

Configure Charts using Globals

To reduce configuration duplication when installing our wrapper Helm chart, several configuration settings are available to be set in the global section of values.yml. These global settings are used across several charts, while all other settings are scoped within their chart. See the Helm documentation on globals for more information on how the global variables work.

• Hosts
• Ingress
• GitLab Version
• PostgreSQL
• Redis
• Grafana
• Registry
• Gitaly
• MinIO
• appConfig
• Rails
• GitLab Shell
• Unicorn
• Custom Certificate Authorities
• Application Resource
• Busybox image

Configure Host settings

The GitLab global host settings are located under the global.hosts key.

global:
  hosts:
    domain: example.com
    hostSuffix: staging
    https: false
    externalIP:
    gitlab:
      name: gitlab.example.com
      https: false
    registry:
      name: registry.example.com
      https: false
    minio:
      name: minio.example.com
      https: false

hostSuffix

The hostSuffix is appended to the subdomain when assembling a hostname using the base domain, but is not used for hosts that have their own name set.

Defaults to being unset. If set, the suffix is appended to the subdomain with a hyphen. The example below would result in using external hostnames like gitlab-staging.example.com and registry-staging.example.com:

global:
  hosts:
    domain: example.com
    hostSuffix: staging

Configure Ingress settings

The GitLab global host settings for Ingress are located under the global.ingress key:

global.ingress.configureCertmanager

Global setting that controls the automatic configuration of cert-manager for Ingress objects. If true, relies on certmanager-issuer.email being set.

If false and global.ingress.tls.secretName is not set, this will activate automatic self-signed certificate generation, which creates a wildcard certificate for all Ingress objects.

• gitlab.unicorn.ingress.tls.secretName
• registry.ingress.tls.secretName
• minio.ingress.tls.secretName
• global.ingress.annotations

GitLab Version

The GitLab version used in the default image tag for the charts can be changed using the global.gitlabVersion key:

--set global.gitlabVersion=11.0.1

This impacts the default image tag used in the unicorn, sidekiq, and migration charts. Note that the gitaly, gitlab-shell and gitlab-runner image tags should be separately updated to versions compatible with the GitLab version.

Configure PostgreSQL settings

The GitLab global PostgreSQL settings are located under the global.psql key. For more details, see the documentation within the Unicorn chart.

global:
  psql:
    host: db.example.com
    # serviceName:
    port: 5432
    preparedStatements: false
    pool: 10
    password:
      secret: gitlab-postgres
      key: psql-password

If you want to connect GitLab with a PostgreSQL database over mutual TLS, create a secret containing the client key, client certificate and server certificate authority as different secret keys. Then describe the secret’s structure using the global.psql.ssl mapping.

global:
  psql:
    host: db.example.com
    # ... further settings like in the previous example ...
    ssl:
      secret: db-example-ssl-secrets # Name of the secret
      clientKey: key.pem             # Secret key of the certificate's key
      clientCertificate: cert.pem    # Secret key storing the certificate
      serverCA: server-ca.pem        # Secret key containing the CA for the database server

Configure Redis settings

The GitLab global Redis settings are located under the global.redis key. For more details on these settings, see the documentation within the Unicorn chart.

global:
  redis:
    host: redis.example.com
    # serviceName:
    port: 6379
    sentinels:
      - host: sentinel1.example.com
        port: 26379
      - host: sentinel2.example.com
        port: 26379
    password:
      enabled: true
      secret: gitlab-redis-secret
      key: redis-password

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.install=false. The Secret containing the Redis password will need to be manually created before deploying the GitLab chart.

Configure Grafana integration

The GitLab global Grafana settings are located under global.grafana. At this time, the only setting available is global.grafana.enabled.

When set to true, the GitLab chart will deploy the Grafana chart, expose it under /-/grafana of the GitLab Ingress, and pre-configure it with a secure random password. The generated password can be found in the Secret named gitlab-grafana-initial-root-password.

The GitLab chart connects to the deployed Prometheus instance.

Configure Registry settings

The global Registry settings are located under the global.registry key. For more details on these settings, see the documentation within the registry chart.

global:
  registry:
    bucket: registry
    certificate:
    httpSecret:

Configure Gitaly settings

The global Gitaly settings are located under the global.gitaly key.

global:
  gitaly:
    internal:
      names:
        - default
        - default2
    external:
      - name: node1
        hostname: node1.example.com
        port: 8075
    authToken:
      secret: gitaly-secret
      key: token
    tls:
      enabled: true
      secretName: gitlab-gitaly-tls

Gitaly hosts

Gitaly is a service that provides high-level RPC access to Git repositories, which handles all Git calls made by GitLab.

Administrators can chose to use Gitaly nodes in the following ways:

• Internal to the chart, as part of a StatefulSet via the Gitaly chart.
• External to the chart, as external pets.
• Mixed environment using both internal and external nodes.

See Repository Storage Paths documentation for details on managing which nodes will be used for new projects.

Internal

The internal key currently consists of only one key, names, which is a list of storage names to be managed by the chart. For each listed name, in logical order, one pod will be spawned, named ${releaseName}-gitaly-${ordinal}, where ordinal is the index within the names list. If dynamic provisioning is enabled, the PersistentVolumeClaim will match.

This list defaults to ['default'], which provides for 1 pod related to one storage path.

A sample configuration of multiple internal nodes can be found in the examples folder.

External

The external key provides a configuration for Gitaly nodes external to the cluster. Each item of this list has 3 keys:

• name: The name of the storage.
• hostname: The host of Gitaly services.
• port: (optional) The port number to reach the host on. Defaults to 8075.

We provide an advanced configuration guide for using an external Gitaly service. You can also find sample configuration of multiple external services in the examples folder.

Mixed

It is possible to use both internal and external Gitaly nodes, but be aware that:

• There must always be a node named default, which Internal provides by default.
• External nodes will be populated first, then Internal.

A sample configuration of mixed internal and external nodes can be found in the examples folder.

authToken

The authToken attribute for Gitaly has two sub keys:

• secret defines the name of the Kubernetes Secret to pull from.
• key defines the name of the key in the above secret that contains the authToken.

Deprecated Gitaly settings

TLS settings

Configuring Gitaly over TLS is detailed in the Gitaly chart’s documentation.

Configure MinIO settings

The GitLab global MinIO settings are located under the global.minio key. For more details on these settings, see the documentation within the MinIO chart.

global:
  minio:
    enabled: true
    credentials: {}

Configure appConfig settings

The Unicorn, Sidekiq, and Gitaly charts share multiple settings, which are configured with the global.appConfig key.

global:
  appConfig:
    enableUsagePing: true
    enableSeatLink: true
    enableImpersonation: true
    defaultCanCreateGroup: true
    usernameChangingEnabled: true
    issueClosingPattern:
    defaultTheme:
    defaultProjectsFeatures:
      issues: true
      mergeRequests: true
      wiki: true
      snippets: true
      builds: true
      containerRegistry: true
    webhookTimeout:
    gravatar:
      plainUrl:
      sslUrl:
    extra:
      googleAnalyticsId:
      piwikUrl:
      piwikSiteId:
    lfs:
      enabled: true
      proxy_download: true
      bucket: git-lfs
      connection: {}
    artifacts:
      enabled: true
      proxy_download: true
      bucket: gitlab-artifacts
      connection: {}
    uploads:
      enabled: true
      proxy_download: true
      bucket: gitlab-uploads
      connection: {}
    packages:
      enabled: true
      proxy_download: true
      bucket: gitlab-packages
      connection: {}
    externalDiffs:
      enabled:
      when:
      proxy_download: true
      bucket: gitlab-mr-diffs
      connection: {}
    terraformState:
      enabled: false
      bucket: gitlab-terraform-state
      connection: {}
    backups:
      bucket: gitlab-backups
    incomingEmail:
      enabled: false
      address: ""
      host: "imap.gmail.com"
      port: 993
      ssl: true
      startTls: false
      user: ""
      password:
        secret:
        key: password
      mailbox: inbox
      idleTimeout: 60
    pseudonymizer:
      configMap:
      bucket: gitlab-pseudo
      connection: {}
    cron_jobs: {}

General application settings

The appConfig settings that can be used to tweak the general properties of the Rails application are described below:

defaultProjectsFeatures

Flags to decide if new projects should be created with the respective features by default. All flags default to true.

defaultProjectsFeatures:
  issues: true
  mergeRequests: true
  wiki: true
  snippets: true
  builds: true
  containerRegistry: true

Gravatar/Libravatar settings

By default, the charts work with Gravatar avatar service available at gravatar.com. However, a custom Libravatar service can also be used if needed:

Hooking Analytics services to the GitLab instance

Settings to configure Analytics services like Google Analytics and Piwik are defined under the extra key below appConfig:

LFS, Artifacts, Uploads, Packages, and External MR diffs

Details on these settings are below. Documentation is not repeated individually, as they are structurally identical aside from the default value of the bucket property.

  enabled: true
  proxy_download: true
  bucket:
  connection:
    secret:
    key:

connection

The connection property has been transitioned to a Kubernetes Secret. The contents of this secret should be a YAML formatted file. Defaults to {} and will be ignored if global.minio.enabled is true.

This property has two sub-keys: secret and key.

• secret is the name of a Kubernetes Secret. This value is required to use external object storage.
• key is the name of the key in the secret which houses the YAML block. Defaults to connection.

Valid configuration keys can be found in the GitLab Job Artifacts Administration documentation. This matches to Fog, and is different between provider modules.

Examples for AWS and Google providers can be found in examples/objectstorage.

• rails.s3.yaml
• rails.gcs.yaml

Once a YAML file containing the contents of the connection has been created, use this file to create the secret in Kubernetes.

kubectl create secret generic gitlab-rails-storage \
    --from-file=connection=rails.yaml

when (only for External MR Diffs)

externalDiffs setting has an additional key when to conditionally store specific diffs on object storage. This setting is left empty by default in the Charts, for a default value to be assigned by the Rails code.

Incoming email settings

The incoming email settings are explained in the command line options page.

LDAP

The ldap.servers setting allows for the configuration of LDAP user authentication. It is presented as a map, which will be translated into the appropriate LDAP servers configuration in gitlab.yml, as with an installation from source.

Configuring passwords can be done by supplying a secret which holds the password. This password will then be injected into GitLab’s configuration at runtime.

An example configuration snippet:

ldap:
  preventSignin: false
  servers:
    # 'main' is the GitLab 'provider ID' of this LDAP server
    main:
      label: 'LDAP'
      host: '_your_ldap_server'
      port: 636
      uid: 'sAMAccountName'
      bind_dn: 'cn=administrator,cn=Users,dc=domain,dc=net'
      password:
        secret: my-ldap-password-secret
        key: the-key-containing-the-password

Example --set configuration items, when using the global chart:

--set global.appConfig.ldap.servers.main.label='LDAP' \
--set global.appConfig.ldap.servers.main.host='your_ldap_server' \
--set global.appConfig.ldap.servers.main.port='636' \
--set global.appConfig.ldap.servers.main.uid='sAMAccountName' \
--set global.appConfig.ldap.servers.main.bind_dn='cn=administrator\,cn=Users\,dc=domain\,dc=net'
--set global.appConfig.ldap.servers.main.password.secret='my-ldap-password-secret'
--set global.appConfig.ldap.servers.main.password.key='the-key-containing-the-password'

Disable LDAP web sign in

It can be useful to prevent using LDAP credentials through the web UI when an alternative such as SAML is preferred. This allows LDAP to be used for group sync, while also allowing your SAML identity provider to handle additional checks like custom 2FA.

When LDAP web sign in is disabled, users will not see a LDAP tab on the sign in page. This does not disable using LDAP credentials for Git access.

To disable the use of LDAP for web sign-in, set global.appConfig.ldap.preventSignin: true.

Using a custom CA or self signed LDAP certificates

If the LDAP server uses a custom CA or self-signed certificate, you must:

1. Ensure that the custom CA/Self-Signed certificate is created as a secret in the cluster/namespace:

   kubectl -n gitlab create secret generic my-custom-ca --from-file=my-custom-ca.pem
   

2. Then, specify:

   --set global.certificates.customCAs[0].secret=my-custom-ca.pem
   --set global.appConfig.ldap.servers.main.ca_file=/etc/ssl/certs/ca-cert-my-custom-ca.pem
   

This will ensure that the CA is mounted in the relevant pods under /etc/ssl/certs/ca-cert-my-custom-ca.pem and specifies its use in the LDAP configuration.

OmniAuth

GitLab can leverage OmniAuth to allow users to sign in using Twitter, GitHub, Google, and other popular services. Expanded documentation can be found in the OmniAuth documentation for GitLab.

omniauth:
  enabled: false
  autoSignInWithProvider:
  syncProfileFromProvider: []
  syncProfileAttributes: ['email']
  allowSingleSignOn: ['saml']
  blockAutoCreatedUsers: true
  autoLinkLdapUser: false
  autoLinkSamlUser: false
  externalProviders: []
  allowBypassTwoFactor: []
  providers: []
  # - secret: gitlab-google-oauth2
  #   key: provider

providers

providers is presented as an array of maps that are used to populate gitlab.yml as when installed from source. See GitLab documentation for the available selection of Supported Providers. Defaults to [].

This property has two sub-keys: secret and key:

• secret: (required) The name of a Kubernetes Secret containing the provider block.
• key: (optional) The name of the key in the Secret containing the provider block. Defaults to provider

The Secret for these entries contains YAML or JSON formatted blocks, as described in OmniAuth Providers. To create this secret, follow the appropriate instructions for retrieval of these items, and create a YAML or JSON file.

Example of configuration of Google OAuth2:

name: google_oauth2
label: Google
app_id: 'APP ID'
app_secret: 'APP SECRET'
args:
  access_type: offline
  approval_prompt: ''

This content can be saved as provider.yaml, and then a secret created from it:

kubectl create secret generic -n NAMESPACE SECRET_NAME --from-file=provider=provider.yaml

Once created, the providers are enabled by providing the maps in configuration, as shown below:

omniauth:
  providers:
    - secret: gitlab-google-oauth2
    - secret: gitlab-azure-oauth2
    - secret: gitlab-cas3

Example configuration --set items, when using the global chart:

--set global.appConfig.omniauth.providers[0].secret=gitlab-google-oauth2 \

Due to the complexity of using --set arguments, a user may wish to use a YAML snippet, passed to helm with -f omniauth.yaml.

Pseudonymizer settings

Use these settings to configure the Pseudonymizer service.

global:
  appConfig:
    pseudonymizer:
      configMap:
      bucket: gitlab-pseudo
      connection: {}

configMap

Name of the configMap containing a custom manifest file. Defaults to empty.

GitLab ships with a default manifest file for Pseudonymizer. Users can provide a custom one as a configMap.

First, create a configMap:

kubectl create configmap <name of the configmap> --from-file=pseudonymizer.yml=<path to pseudonymizer_config.yml>

Then pass the argument --set global.appConfig.pseudonymizer.configMap=<name of the configmap> to the helm install command to instruct GitLab to use this manifest instead of the default one.

connection

Details of the Kubernetes secret that contains the connection information for the object storage provider. The contents of this secret should be a YAML formatted file.

Defaults to {} and will be ignored if global.minio.enabled is true.

This property has two sub-keys: secret and key:

• secret is the name of a Kubernetes Secret. This value is required to use external object storage.
• key is the name of the key in the secret which houses the YAML block. Defaults to connection.

Examples for AWS (s3) and Google (GCS) providers can be found in examples/objectstorage:

• rails.s3.yaml
• rails.gcs.yaml

Once a YAML file containing the contents of the connection has been created, create the secret in Kubernetes:

kubectl create secret generic gitlab-rails-storage \
    --from-file=connection=rails.yaml

Cron jobs related settings

Sidekiq includes maintenance jobs that can be configured to run on a periodic basis using cron style schedules. A few examples are included below. See the sample gitlab.yml for more job examples.

These settings are shared between Sidekiq, Unicorn (for showing tooltips in UI) and task-runner (for debugging purposes) pods.

global:
  appConfig:
    cron_jobs:
      stuck_ci_jobs_worker:
        cron: "0 * * * *"
      pipeline_schedule_worker:
        cron: "19 * * * *"
      expire_build_artifacts_worker:
        cron: "50 * * * *"

Configure Rails settings

A large portion of the GitLab suite is based upon Rails. As such, many containers within this project operate with this stack. These settings apply to all of those containers, and provide an easy access method to setting them globally versus individually.

global:
  rails:
    bootsnap:
      enabled: true

Bootsnap Cache

Our Rails codebase makes use of Shopify’s Bootsnap Gem. Settings here are used to configure that behavior.

bootsnap.enabled controls the activation of this feature. It defaults to true.

Testing showed that enabling Bootsnap resulted in overall application performance boost. When a pre-compiled cache is available, some application containers see gains in excess of 33%. At this time, GitLab does not ship this pre-compiled cache with their containers, resulting in a gain of “only” 14%. There is a cost to this gain without the pre-compiled cache present, resulting in an intense spike of small IO at initial startup of each Pod. Due to this, we’ve exposed a method of disabling the use of Bootsnap in environments where this would be an issue.

When possible, we recommend leaving this enabled.

Configure GitLab Shell

There are several items for the global configuration of GitLab Shell chart.

global:
  shell:
    port:
    authToken: {}
    hostKeys: {}

Configure Unicorn

The global Unicorn settings (that are used by other charts also) are located under the global.unicorn key.

global:
  unicorn:
    workerTimeout: 60

workerTimeout

Configure the request timeout (in seconds) after which a Unicorn worker process is killed by the Unicorn master process. The default value is 60 seconds.

Custom Certificate Authorities

Some users may need to add custom certificate authorities, such as when using internally issued SSL certificates for TLS services. To provide this functionaliy, we provide a mechanism for injecting these custom root certificate authorities into the application via secrets.

global:
  certificates:
    customCAs:
      - secret: internal-cas
      - secret: other-custom-cas

A user can provide any number of secrets, each containing any number of keys that hold PEM encoded CA certificates. These are configured as entries under global.certificates.customCAs. All keys within the secret will be mounted, so all keys across all secrets must be unique.

To create a secret:

kubectl create secret generic custom-ca --from-file=unique_name=/path/to/cert

To configure the secret:

helm install gitlab gitlab/gitlab \
  --set global.certificates.customCAs[0].secret=custom-ca

Application Resource

GitLab can optionally include an Application resource, which can be created to identify the GitLab application within the cluster. Requires the Application CRD, version v1beta1, to already be deployed to the cluster.

To enable, set global.application.create to true:

global:
  application:
    create: true

Some environments, such as Google GKE Marketplace, do not allow the creation of ClusterRole resources. Set the following values to disable ClusterRole components in the Application Custom Resource Definition as well as the relevant charts packaged with Cloud Native GitLab.

global:
  application:
    allowClusterRoles: false
  operator:
     enabled: false
nginx:
  controller:
    scope:
      enabled: true
gitlab-runner:
  rbac:
    clusterWideAccess: false
certmanager:
  install: false

Busybox image

By default, GitLab Helm charts use busybox:latest for booting up various initContainers. This is controlled by the following settings

global:
  busybox:
    image:
      repository: busybox
      tag: latest

Many charts also provide init.image.repository and init.image.tag settings locally that can be used to override this global setting for that specific chart.