Secrets
GitLab requires a variety of secrets to operate:
GitLab Components:
- Registry authentication certificates
- SSH Host Keys and Certificates for GitLab Shell
- Passwords for individual GitLab services
Optional External Services:
- SMTP server
- LDAP
- OmniAuth
- IMAP for incoming emails (via mail_room service)
- IMAP for service desk emails (via mail_room service)
- S/MIME certificate
Any secret not provided manually will be automatically generated with a random value. Automatic generation of HTTPS certificates is provided by Let’s Encrypt.
To utilize autogenerated secrets continue to next steps.
To specify your own secrets, proceed to manual secret creation.
Manual secret creation (optional)
Use gitlab
as the release name if you followed previous steps in this
documentation.
- TLS certificates
- Registry authentication certificates
- Registry sensitive notification headers
- SSH Host Keys
- Passwords:
- External Services
Registry authentication certificates
Communication between GitLab and Registry happens behind an Ingress so it is sufficient in most cases to use self-signed certificates for this communication. If this traffic is exposed over a network, you should generate publicly valid certificates.
In the example below, we assume that we require self-signed certificates.
Generate a certificate-key pair:
mkdir -p certs
openssl req -new -newkey rsa:4096 -subj "/CN=gitlab-issuer" -nodes -x509 -keyout certs/registry-example-com.key -out certs/registry-example-com.crt
Create a secret containing these certificates.
We will create registry-auth.key
and registry-auth.crt
keys inside the
<name>-registry-secret
secret. Replace <name>
with the name of the release.
kubectl create secret generic <name>-registry-secret --from-file=registry-auth.key=certs/registry-example-com.key --from-file=registry-auth.crt=certs/registry-example-com.crt
This secret is referenced by the global.registry.certificate.secret
setting.
Registry sensitive notification headers
Check documentation regarding configuring Registry notifications for more details.
The secret content should be a list of items, even if it contains a single item. If the content is just a string, the charts WILL NOT convert it to a list as needed.
Consider the example where registry-authorization-header
secret with value
RandomFooBar
is created.
kubectl create secret generic registry-authorization-header --from-literal="value=[RandomFooBar]"
By default, the key used within the secret is “value”. However, users can use a
different key, but must ensure that it’s specified as key
under the header map
item.
SSH Host Keys
Generate the OpenSSH certificate-key pairs:
mkdir -p hostKeys
ssh-keygen -t rsa -f hostKeys/ssh_host_rsa_key -N ""
ssh-keygen -t dsa -f hostKeys/ssh_host_dsa_key -N ""
ssh-keygen -t ecdsa -f hostKeys/ssh_host_ecdsa_key -N ""
ssh-keygen -t ed25519 -f hostKeys/ssh_host_ed25519_key -N ""
Create the secret containing these certificates. Replace <name>
with the name
of the release.
kubectl create secret generic <name>-gitlab-shell-host-keys --from-file hostKeys
This secret is referenced by the global.shell.hostKeys.secret
setting.
Initial Enterprise license
Create a Kubernetes secret for storing the Enterprise license for the GitLab instance.
Replace <name>
with the name of the release.
kubectl create secret generic <name>-gitlab-license --from-file=license=/tmp/license.gitlab
Then use --set global.gitlab.license.secret=<name>-gitlab-license
to
inject the license into your configuration.
You can also use the global.gitlab.license.key
option to change the default
license
key pointing to the license in the license secret.
Initial root password
Create a Kubernetes secret for storing the initial root password. The password
should be at least 6 characters long. Replace <name>
with the name of the
release.
kubectl create secret generic <name>-gitlab-initial-root-password --from-literal=password=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 32)
Redis password
Generate a random 64 character alpha-numeric password for Redis. Replace
<name>
with the name of the release.
kubectl create secret generic <name>-redis-secret --from-literal=secret=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 64)
If deploying with an already existing Redis cluster, please use the password for accessing the Redis cluster that has been base64 encoded instead of a randomly generated one.
GitLab Shell secret
Generate a random 64 character alpha-numeric secret for GitLab Shell. Replace
<name>
with the name of the release.
kubectl create secret generic <name>-gitlab-shell-secret --from-literal=secret=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 64)
This secret is referenced by the global.shell.authToken.secret
setting.
Gitaly secret
Generate a random 64 character alpha-numeric token for Gitaly. Replace <name>
with the name of the release.
kubectl create secret generic <name>-gitaly-secret --from-literal=token=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 64)
This secret is referenced by the global.gitaly.authToken.secret
setting.
GitLab Rails secret
Replace <name>
with the name of the release.
cat << EOF > secrets.yml
production:
secret_key_base: $(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 128)
otp_key_base: $(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 128)
db_key_base: $(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 128)
openid_connect_signing_key: |
$(openssl genrsa 2048 | awk '{print " " $0}')
ci_jwt_signing_key: |
$(openssl genrsa 2048 | awk '{print " " $0}')
EOF
kubectl create secret generic <name>-rails-secret --from-file=secrets.yml
This secret is referenced by the global.railsSecrets.secret
setting.
GitLab Workhorse secret
Generate the workhorse secret. This must have a length of 32 characters and
base64-encoded. Replace <name>
with the name of the release.
kubectl create secret generic <name>-gitlab-workhorse-secret --from-literal=shared_secret=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 32 | base64)
This secret is referenced by the global.workhorse.key
setting.
GitLab Runner secret
Replace <name>
with the name of the release.
kubectl create secret generic <name>-gitlab-runner-secret --from-literal=runner-registration-token=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 64)
MinIO secret
Generate a set of random 20 & 64 character alpha-numeric keys for MinIO.
Replace <name>
with the name of the release.
kubectl create secret generic <name>-minio-secret --from-literal=accesskey=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 20) --from-literal=secretkey=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 64)
This secret is referenced by the global.minio.credentials.secret
setting.
PostgreSQL password
Generate a random 64 character alpha-numeric password. Replace <name>
with
the name of the release.
kubectl create secret generic <name>-postgresql-password \
--from-literal=postgresql-password=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 64) \
--from-literal=postgresql-postgres-password=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 64)
Grafana password
If configuring Grafana integration, generate a random 64 character alpha-numeric password.
generate_secret_if_needed "gitlab-grafana-initial-password" --from-literal=password=$(gen_random 'a-zA-Z0-9' 64)
Registry HTTP secret
Generate a random 64 character alpha-numeric key shared by all registry pods.
Replace <name>
with the name of the release.
kubectl create secret generic <name>-registry-httpsecret --from-literal=secret=$(head -c 512 /dev/urandom | LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 64 | base64)
External services
Some charts have further secrets to enable functionality that can not be automatically generated.
OmniAuth
In order to enable the use of OmniAuth Providers with the deployed GitLab, please follow the instructions in the Globals chart
LDAP Password
If you need password authentication to connect with your LDAP server, you must store the password in a Kubernetes secret.
kubectl create secret generic ldap-main-password --from-literal=password=yourpasswordhere
Then use --set global.appConfig.ldap.servers.main.password.secret=ldap-main-password
to
inject the password into your configuration.
Secret
name, not the actual password when configuring the Helm property.SMTP password
If you are using an SMTP server that requires authentication, store the password in a Kubernetes secret.
kubectl create secret generic smtp-password --from-literal=password=yourpasswordhere
Then use --set global.smtp.password.secret=smtp-password
in your Helm command.
Secret
name, not the actual password when configuring the Helm property.IMAP password for incoming emails
To let GitLab have access to incoming emails store the password of the IMAP account in a Kubernetes secret.
kubectl create secret generic incoming-email-password --from-literal=password=yourpasswordhere
Then use --set global.appConfig.incomingEmail.password.secret=incoming-email-password
in your Helm command along with other required settings as specified in the docs.
Secret
name, not the actual password when configuring the Helm property.IMAP password for service desk emails
To let GitLab have access to service_desk emails store the password of the IMAP account in a Kubernetes secret.
kubectl create secret generic service-desk-email-password --from-literal=password=yourpasswordhere
Then use --set global.appConfig.serviceDeskEmail.password.secret=service-desk-email-password
in your Helm command along with other required settings as specified in the docs.
Secret
name, not the actual password when configuring the Helm property.S/MIME Certificate
Outgoing email messages can be digitally signed using the S/MIME standard. The S/MIME certificate needs to be stored in a Kubernetes secret as a TLS type secret.
kubectl create secret tls smime-certificate --key=file.key --cert file.crt
If there is an existing secret as a opaque type, then the global.email.smime.keyName
and global.email.smime.certName
values will need to be adjusted for
the specific secret.
S/MIME settings can be set through the values.yaml
file or on the command
line. Use --set global.email.smime.enabled=true
to enable S/MIME and
--set global.email.smime.secretName=smime-certificate
to specify the
secret that contains the S/MIME certificate.
Next steps
Once all secrets have been generated and stored, you can proceed deploying GitLab.