Using the Container Registry

The registry sub-chart provides the Registry component to a complete cloud-native GitLab deployment on Kubernetes. This sub-chart makes use of the upstream registry container containing Docker Distribution. This chart is composed of 3 primary parts: Service, Deployment, and ConfigMap.

All configuration is handled according to the official Registry configuration documentation using /etc/docker/registry/config.yml variables provided to the Deployment populated from the ConfigMap. The ConfigMap overrides the upstream defaults, but is based on them. See below for more details:

Design Choices

A Kubernetes Deployment was chosen as the deployment method for this chart to allow for simple scaling of instances, while allowing for rolling updates.

This chart makes use of only two secrets:

  • global.registry.certificate.secret: A global secret that will contain the public certificate bundle to verify the authentication tokens provided by the associated GitLab instance(s). See documentation on using GitLab as an auth endpoint.
  • global.registry.httpSecret.secret: A global secret that will contain the shared secret between registry pods.


We will describe all the major sections of the configuration below. When configuring from the parent chart, these values will be:

    tag: '2.7.1'
    pullPolicy: IfoNtPresent
    type: ClusterIP
    name: registry
    secret: gitlab-registry
    key: registry-auth.crt
  replicas: 1
    key: storage
      enabled: false
    enabled: false
      enabled: true
      serviceName: redis

If you chose to deploy this chart as a standalone, remove the registry at the top level.

Installation command line options

Parameter Default Description
annotations   Pod annotations
authAutoRedirect true Auth auto-redirect (must be true for Windows clients to work)
authEndpoint Auth endpoint (only host and port)
certificate.secret gitlab-registry JWT certificate
compatiblity   Configuration of compatility settings
enabled true Enable registry flag
httpSecret   Https secret
image.pullPolicy   Pull policy for the registry image
image.pullSecrets   Secrets to use for image repository
image.repository registry Registry image
image.tag 2.7.1 Version of the image to use
init.image busybox initContainer image
init.tag latest initContainer image tag
minio.bucket global.registry.bucket Legacy registry bucket name
replicas 1 Number of replicas
tokenService container_registry JWT token service
tokenIssuer gitlab-issuer JWT token issuer

Chart configuration examples


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:

  repository: my.registry.repository
  tag: latest
  pullPolicy: Always
  - name: my-secret-name
  - name: my-secondary-secret-name


annotations allows you to add annotations to the registry pods.

Below is an example use of annotations

annotations: annotation-value

Enable the sub-chart

The way we’ve chosen to implement compartmentalized sub-charts includes the ability to disable the components that you may not want in a given deployment. For this reason, the first setting you should decide on is enabled.

By default, Registry is enabled out of the box. Should you wish to disable it, set enabled: false.

Configuring the image

This section details the settings for the container image used by this sub-chart’s Deployment. You can change the included version of the Registry and pullPolicy.

Default settings:

  • tag: '2.7.1'
  • pullPolicy: 'IfNotPresent'

Configuring the service

This section controls the name and type of the Service. These settings will be populated by values.yaml.

By default, the Service is configured as:

  • type: ClusterIP on, restricting access to the internal network of the Kubernetes cluster.
  • name: is set to registry.

Configuring the ingress

This section controls the registry ingress.

Name Type Default Description
annotations String   This field is an exact match to the standard annotations for Kubernetes Ingress.
enabled Boolean false Setting that controls whether to create ingress objects for services that support them. When false the global.ingress.enabled setting is used.
tls.enabled Boolean true When set to false, you disable TLS for the Registry subchart. 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.
tls.serviceName String redis The name of the Kubernetes TLS Secret that contains a valid certificate and key for the registry url. When not set, the global.ingress.tls.secretName is used instead. Defaults to not being set.

Defining the Registry Configuration

The following properties of this chart pertain to the configuration of the underlying registry container. Only the most critical values for integration with GitLab are exposed. For this integration, we make use of the auth.token.x settings of Docker Distribution, controlling authentication to the registry via JWT authentication tokens.


Field httpSecret is a map that contains two items: secret and key.

The content of the key this references correlates to the http.secret value of registry. This value should be populated with a cryptographically generated random string.

The shared-secrets job will automatically create this secret if not provided. It will be filled with a securely generated 128 character alpha-numeric string that is base64 encoded.

To create this secret manually:

kubectl create secret generic gitlab-registry-httpsecret --from-literal=secret=strongrandomstring


The authEndpoint field is a string, providing the URL to the GitLab instance(s) that the registry will authenticate to.

The value should include the protocol and hostname only. The chart template will automatically append the necessary request path. The resulting value will be populated to auth.token.realm inside the container. For example: authEndpoint: ""

By default this field is populated with the gitlab hostname configuration set by the Global Settings.


The certificate field is a map containing two items: secret and key.

secret is a string containing the name of the Kubernetes Secret that houses the certificate bundle to be used to verify the tokens created by the GitLab instance(s).

key is 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.

Default Example:

  secret: gitlab-registry
  key: registry-auth.crt


The compatibility field is a map relating directly to the configuration file’s compatiblity section.

Default contents:

    enabled: false


The schema1 section controls the compatibility of the service with version 1 of the Docker manifest schema. This setting is provide as a means of supporting Docker clients earlier than 1.10, after which schema v2 is used by default.

If you must support older verions of Docker clients, you can do so by setting registry.compatbility.schema1.enabled: true.


The replicas field is an integer, controlling the number of registry instances to create as a part of the set. This defaults to 1.


  key: storage

The storage field is a reference to a Kubernetes Secret and associated key. The content of this secret is taken directly from Registry Configuration: storage. Please refer to that documentation for more details.

Examples for AWS s3 and Google GCS drivers can be found in examples/objectstorage:

Place the contents of the storage block into the secret, and provide the following as items to the storage map:

  • secret: name of the Kubernetes Secret housing the YAML block.
  • key: name of the key in the secret to use. Defaults to storage.
  • extraKey: (optional) name of an extra key in the secret, which will be mounted to /etc/docker/registry/storage/${extraKey} within the container. This can be used to provide the keyfile for the gcs driver.
# Example using S3
kubectl create secret generic registry-storage \

# Example using GCS with JSON key
# - Note: ``
kubectl create secret generic registry-storage \
    --from-file=config=registry-storage.yaml \

If you chose to use the filesystem driver:

  • You will need to provide persistent volumes for this data.
  • replicas should be set to 1

For the sake of resiliency and simplicity, it is recommended to make use of an external service, such as s3, gcs, azure or other compatible Object Storage.

Note: The chart will populate delete.enabled: true into this configuration by default if not specified by the user. This keeps expected behavior in line with the default use of Minio, as well as the Omnibus GitLab. Any user provided value will supersede this default.