In certain scenarios (i.e. offline environments), you may want to bring your own images rather than pulling them down from the Internet. This requires specifying your own Docker image registry/repository for each of the charts that make up the GitLab release.
Default image format
Our default format for the image in most cases includes the full path to the image, excluding the tag:
The end result will be repo.example.com/image:custom-tag.
Example values file
There is an example values file that demonstrates how to configure a custom Docker registry/repository and tag. You can copy relevant sections of this file for your own releases.
Some of the charts (especially third party charts) sometimes have slightly different conventions for specifying the image registry/repository and tag. You can find documentation for third party charts on the Artifact Hub.
We’ll make use of the Omnibus GitLab package for Ubuntu. This package provides versions of the services that are guaranteed to be compatible with the charts’ services.
Create VM with Omnibus GitLab
Create a VM on your provider of choice, or locally. This was tested with VirtualBox, KVM, and Bhyve. Ensure that the instance is reachable from the cluster.
Install Ubuntu Server onto the VM that you have created. Ensure that openssh-server is installed, and that all packages are up to date. Configure networking and a hostname. Make note of the hostname/IP, and ensure it is both resolvable and reachable from your Kubernetes cluster. Be sure firewall policies are in place to allow traffic.
Follow the installation instructions for Omnibus GitLab. When you perform the package installation, do not provide the EXTERNAL_URL= value. We do not want automatic configuration to occur, as we’ll provide a very specific configuration in the next step.
Configure Omnibus GitLab
Create a minimal gitlab.rb file to be placed at /etc/gitlab/gitlab.rb. Be very explicit about what is enabled on this node, use the contents below.
DB_ENCODED_PASSWORD encoded value of DB_PASSWORD. Can be generated by replacing DB_USERNAME and DB_PASSWORD with real values in: echo -n 'DB_PASSSWORDDB_USERNAME' | md5sum - | cut -d' ' -f1
AUTH_CIDR_ADDRESS configure the CIDRs for MD5 authentication, should be the smallest possible subnets of your cluster or it’s gateway. For minikube, this value is 192.168.100.0/12
# Change the address below if you do not want PG to listen on all available addresses postgresql['listen_address']='0.0.0.0' # Set to approximately 1/4 of available RAM. postgresql['shared_buffers']="512MB" # This password is: `echo -n '${password}${username}' | md5sum - | cut -d' ' -f1` # The default username is `gitlab` postgresql['sql_user_password']="DB_ENCODED_PASSWORD" # Configure the CIDRs for MD5 authentication postgresql['md5_auth_cidr_addresses']=['AUTH_CIDR_ADDRESSES'] # Configure the CIDRs for trusted authentication (passwordless) postgresql['trust_auth_cidr_addresses']=['127.0.0.1/24']
After creating gitlab.rb, we’ll reconfigure the package with gitlab-ctl reconfigure. Once the task has completed, check the running processes with gitlab-ctl status. The output should appear as such:
The pg_trgm and btree_gist extensions. If you don’t provide an account with the Superuser flag to GitLab, ensure these extensions are loaded prior to proceeding with the database installation.
Networking prerequisites:
Ensure that the database is reachable from the cluster. Be sure that your firewall policies allow traffic.
If you plan to use PostgreSQL as a load balancing cluster and Kubernetes DNS for service discovery, when you install the bitnami/postgresql chart, use --set slave.service.clusterIP=None. This setting configures the PostgreSQL secondary service as a headless service to allow DNS A records to be created for each secondary instance.
The instructions here make use of the Omnibus GitLab package for Ubuntu. This package provides versions of the services that are guaranteed to be compatible with the charts’ services.
Create VM with Omnibus GitLab
Create a VM on your provider of choice, or locally. This was tested with VirtualBox, KVM, and Bhyve. Ensure that the instance is reachable from the cluster.
Install Ubuntu Server onto the VM that you have created. Ensure that openssh-server is installed, and that all packages are up to date. Configure networking and a hostname. Make note of the hostname/IP, and ensure it is both resolvable and reachable from your Kubernetes cluster. Be sure firewall policies are in place to allow traffic.
Follow the installation instructions for Omnibus GitLab. When you perform the package installation, do not provide the EXTERNAL_URL= value. We do not want automatic configuration to occur, as we’ll provide a very specific configuration in the next step.
Configure Omnibus GitLab
Create a minimal gitlab.rb file to be placed at /etc/gitlab/gitlab.rb. Be very explicit about what’s enabled on this node, using the following contents based on the documentation for running Gitaly on its own server.
# Avoid running unnecessary services on the Gitaly server postgresql['enable']=false redis['enable']=false nginx['enable']=false puma['enable']=false sidekiq['enable']=false gitlab_workhorse['enable']=false grafana['enable']=false gitlab_exporter['enable']=false gitlab_kas['enable']=false
# If you run a seperate monitoring node you can disable these services prometheus['enable']=false alertmanager['enable']=false
# If you don't run a seperate monitoring node you can # Enable Prometheus access & disable these extra services # This makes Prometheus listen on all interfaces. You must use firewalls to restrict access to this address/port. # prometheus['listen_address'] = '0.0.0.0:9090' # prometheus['monitor_kubernetes'] = false
# If you don't want to run monitoring services uncomment the following (not recommended) # node_exporter['enable'] = false
# Prevent database connections during 'gitlab-ctl reconfigure' gitlab_rails['auto_migrate']=false
# Configure the gitlab-shell API callback URL. Without this, `git push` will # fail. This can be your 'front door' GitLab URL or an internal load # balancer. gitlab_rails['internal_api_url']='GITLAB_URL' gitlab_shell['secret_token']='SHELL_TOKEN'
# Make Gitaly accept connections on all network interfaces. You must use # firewalls to restrict access to this address/port. # Comment out following line if you only want to support TLS connections gitaly['listen_addr']="0.0.0.0:8075"
# Authentication token to ensure only authorized servers can communicate with # Gitaly server gitaly['auth_token']='AUTH_TOKEN'
# To use TLS for Gitaly you need to add gitaly['tls_listen_addr']="0.0.0.0:8076" gitaly['certificate_path']="path/to/cert.pem" gitaly['key_path']="path/to/key.pem"
After creating gitlab.rb, reconfigure the package with gitlab-ctl reconfigure. Once the task has completed, check the running processes with gitlab-ctl status. The output should appear as such:
global.gitaly.authToken.key: The key within the secret, which contains the token content.
The external Gitaly services will make use of their own instances of GitLab Shell. Depending your implementation, you can configure those with the secrets from this chart, or you can configure this chart’s secrets with the content from a predefined source.
If your implementation uses multiple Gitaly nodes external to these charts, you can define multiple hosts as well. The syntax is slightly different, as to allow the complexity required.
An example values file is provided, which shows the appropriate set of configuration. The content of this values file is not interpreted correctly via --set arguments, so should be passed to Helm with the -f / --values flag.
Connecting to external Gitaly over TLS
If your external Gitaly server listens over TLS port, you can make your GitLab instance communicate with it over TLS. To do this, you have to
Create a Kubernetes secret containing the certificate of the Gitaly server
kubectl create secret generic gitlab-gitaly-tls-certificate --from-file=gitaly-tls.crt=<path to certificate>
Add the certificate of external Gitaly server to the list of custom Certificate Authorities In the values file, specify the following
You can choose any valid secret name and key for this, but make sure the key is unique across all the secrets specified in customCAs to avoid collision since all keys within the secrets will be mounted. You do not need to provide the key for the certificate, as this is the client side.