The Toolbox Pod is used to execute periodic housekeeping tasks within
the GitLab application. These tasks include backups, Sidekiq maintenance,
and Rake tasks.
Configuration
The following configuration settings are the default settings provided by the
Toolbox chart:
List of extra environment variables from other data sources to expose
Configuring backups
Information concerning configuring backups in the
backup and restore documentation. Additional
information about the technical implementation of how the backups are
performed can be found in the
backup and restore architecture documentation.]
Persistence configuration
The persistent stores for backups and restorations are configured separately.
Please review the following considerations when configuring GitLab for
backup and restore operations.
Backups use the
backups.cron.persistence.*
properties and restorations
use the
persistence.*
properties. Further descriptions concerning the
configuration of a persistence store will use just the final property key
(e.g.
.enabled
or
.size
) and the appropriate prefix will need to be
added.
The persistence stores are disabled by default, thus
.enabled
needs to
be set to
true
for a backup or restoration of any appreciable size.
In addition, either
.storageClass
needs to be specified for a PersistentVolume
to be created by Kubernetes or a PersistentVolume needs to be manually created.
If
.storageClass
is specified as ‘-‘, then the PersistentVolume will be
created using the default StorageClass
as specified in the Kubernetes cluster.
If the PersistentVolume is created manually, then the volume can be specified
using the
.volumeName
property or by using the selector
.matchLables
/
.matchExpressions
properties.
In most cases the default value of
.accessMode
will provide adequate
controls for only Toolbox accessing the PersistentVolumes. Please consult
the documentation for the CSI driver installed in the Kubernetes cluster to
ensure that the setting is correct.
Backup considerations
A backup operation needs an amount of disk space to hold the individual
components that are being backed up before they are written to the backup
object store. The amount of disk space depends on the following factors:
Number of projects and the amount of data stored under each project
Size of the PostgresSQL database (issues, MRs, etc.)
Size of each object store backend
Once the rough size has been determined, the
backups.cron.persistence.size
property can be set so that backups can commence.
Restore considerations
During the restoration of a backup, the backup needs to be extracted to disk
before the files are replaced on the running instance. The size of this
restoration disk space is controlled by the
persistence.size
property. Be
mindful that as the size of the GitLab installation grows the size of the
restoration disk space also needs to grow accordingly. In most cases the
size of the restoration disk space should be the same size as the backup
disk space.
Toolbox included tools
The Toolbox container contains useful GitLab tools such as Rails console,
Rake tasks, etc. These commands allow one to check the status of the database
migrations, execute Rake tasks for administrative tasks, interact with
the Rails console:
# locate the Toolbox pod kubectl get pods -lapp=toolbox
# Launch a shell inside the pod kubectl exec-it <Toolbox pod name> -- bash
# open Rails console gitlab-rails console -e production
# execute a Rake task gitlab-rake gitlab:env:info
Using the GitLab Webservice chart | GitLab
Requirements
Configuration
Installation command line options
Chart configuration examples
extraEnv
extraEnvFrom
image.pullSecrets
tolerations
annotations
strategy
TLS
gitlab-workhorse
webservice
Using the Community Edition of this chart
Global settings
Deployments settings
Deployments Ingress
Ingress settings
annotations
proxyBodySize
Resources
Memory requests/limits
External Services
Redis
PostgreSQL
Gitaly
MinIO
Registry
Chart settings
Metrics
GitLab Shell
WebServer options
Configuring the
networkpolicy
Example Network Policy
LoadBalancer Service
Using the GitLab Webservice chart
The
webservice
sub-chart provides the GitLab Rails webserver with two Webservice workers
per pod. (The minimum necessary for a single pod to be able to serve any web request in GitLab)
The pods of this chart make use of two containers:
gitlab-workhorse
and
webservice
.
GitLab Workhorse listens on
port
8181
, and should
always
be the destination for inbound traffic to the pod.
The
webservice
houses the GitLab Rails codebase,
listens on
8080
, and is accessible for metrics collection purposes.
webservice
should never recieve normal traffic directly.
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
webservice
chart is configured as follows: Global settings,
Deployments 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.
Parameter
Default
Description
annotations
Pod annotations
podLabels
Supplemental Pod labels. Will not be used for selectors.
common.labels
Supplemental labels that are applied to all objects created by this chart.
deployment.terminationGracePeriodSeconds
30
Seconds that Kubernetes will wait for a pod to exit, note this must be longer than
shutdown.blackoutSeconds
deployment.livenessProbe.initialDelaySeconds
20
Delay before liveness probe is initiated
deployment.livenessProbe.periodSeconds
60
How often to perform the liveness probe
deployment.livenessProbe.timeoutSeconds
30
When the liveness probe times out
deployment.livenessProbe.successThreshold
1
Minimum consecutive successes for the liveness probe to be considered successful after having failed
deployment.livenessProbe.failureThreshold
3
Minimum consecutive failures for the liveness probe to be considered failed after having succeeded
deployment.readinessProbe.initialDelaySeconds
0
Delay before readiness probe is initiated
deployment.readinessProbe.periodSeconds
10
How often to perform the readiness probe
deployment.readinessProbe.timeoutSeconds
2
When the readiness probe times out
deployment.readinessProbe.successThreshold
1
Minimum consecutive successes for the readiness probe to be considered successful after having failed
deployment.readinessProbe.failureThreshold
3
Minimum consecutive failures for the readiness probe to be considered failed after having succeeded
deployment.strategy
{}
Allows one to configure the update strategy used by the deployment. When not provided, the cluster default is used.
enabled
true
Webservice enabled flag
extraContainers
List of extra containers to include
extraInitContainers
List of extra init containers to include
extras.google_analytics_id
nil
Google Analytics ID for frontend
extraVolumeMounts
List of extra volumes mounts to do
extraVolumes
List of extra volumes to create
extraEnv
List of extra environment variables to expose
extraEnvFrom
List of extra environment variables from other data sources to expose
Behavior contains the specifications for up- and downscaling behavior (requires
autoscaling/v2beta2
or higher)
hpa.customMetrics
[]
Custom metrics contains the specifications for which to use to calculate the desired replica count (overrides the default use of Average CPU Utilization configured in
targetAverageUtilization
)
hpa.cpu.targetType
AverageValue
Set the autoscaling CPU target type, must be either
Utilization
or
AverageValue
hpa.cpu.targetAverageValue
1
Set the autoscaling CPU target value
hpa.cpu.targetAverageUtilization
Set the autoscaling CPU target utilization
hpa.memory.targetType
Set the autoscaling memory target type, must be either
Utilization
or
AverageValue
hpa.memory.targetAverageValue
Set the autoscaling memory target value
hpa.memory.targetAverageUtilization
Set the autoscaling memory target utilization
hpa.targetAverageValue
DEPRECATED
Set the autoscaling CPU target value
sshHostKeys.mount
false
Whether to mount the GitLab Shell secret containing the public SSH keys.
If a metrics endpoint should be made available for scraping
metrics.port
8083
Metrics endpoint port
metrics.path
/metrics
Metrics endpoint path
metrics.serviceMonitor.enabled
false
If a ServiceMonitor should be created to enable Prometheus Operator to manage the metrics scraping, note that enabling this removes the
prometheus.io
scrape annotations
metrics.serviceMonitor.additionalLabels
{}
Additional labels to add to the ServiceMonitor
metrics.serviceMonitor.endpointConfig
{}
Additional endpoint configuration for the ServiceMonitor
metrics.annotations
DEPRECATED
Set explicit metrics annotations. Replaced by template content.
metrics.tls.enabled
false
TLS enabled for the metrics/web_exporter endpoint
metrics.tls.secretName
{Release.Name}-webservice-metrics-tls
Secret for the metrics/web_exporter endpoint TLS cert and key
minio.bucket
git-lfs
Name of storage bucket, when using MinIO
minio.port
9000
Port for MinIO service
minio.serviceName
minio-svc
Name of MinIO service
monitoring.ipWhitelist
[0.0.0.0/0]
List of IPs to whitelist for the monitoring endpoints
monitoring.exporter.enabled
false
Enable webserver to expose Prometheus metrics, this is overridden by
metrics.enabled
if the metrics port is set to the monitoring exporter port
monitoring.exporter.port
8083
Port number to use for the metrics exporter
psql.password.key
psql-password
Key to psql password in psql secret
psql.password.secret
gitlab-postgres
psql secret name
psql.port
Set PostgreSQL server port. Takes precedence over
global.psql.port
puma.disableWorkerKiller
true
Disables Puma worker memory killer
puma.workerMaxMemory
The maximum memory (in megabytes) for the Puma worker killer
puma.threads.min
4
The minimum amount of Puma threads
puma.threads.max
4
The maximum amount of Puma threads
rack_attack.git_basic_auth
{}
See GitLab documentation for details
redis.serviceName
redis
Redis service name
registry.api.port
5000
Registry port
registry.api.protocol
http
Registry protocol
registry.api.serviceName
registry
Registry service name
registry.enabled
true
Add/Remove registry link in all projects menu
registry.tokenIssuer
gitlab-issuer
Registry token issuer
replicaCount
1
Webservice number of replicas
resources.requests.cpu
300m
Webservice minimum CPU
resources.requests.memory
1.5G
Webservice minimum memory
service.externalPort
8080
Webservice exposed port
securityContext.fsGroup
1000
Group ID under which the pod should be started
securityContext.runAsUser
1000
User ID under which the pod should be started
serviceLabels
{}
Supplemental service labels
service.internalPort
8080
Webservice internal port
service.type
ClusterIP
Webservice service type
service.workhorseExternalPort
8181
Workhorse exposed port
service.workhorseInternalPort
8181
Workhorse internal port
service.loadBalancerIP
IP address to assign to LoadBalancer (if supported by cloud provider)
service.loadBalancerSourceRanges
List of IP CIDRs allowed access to LoadBalancer (if supported) Required for service.type = LoadBalancer
shell.authToken.key
secret
Key to shell token in shell secret
shell.authToken.secret
{Release.Name}-gitlab-shell-secret
Shell token secret
shell.port
nil
Port number to use in SSH URLs generated by UI
shutdown.blackoutSeconds
10
Number of seconds to keep Webservice running after receiving shutdown, note this must shorter than
deployment.terminationGracePeriodSeconds
tls.enabled
false
Webservice TLS enabled
tls.secretName
{Release.Name}-webservice-tls
Webservice TLS secrets.
secretName
must point to a Kubernetes TLS secret.
tolerations
[]
Toleration labels for pod assignment
trusted_proxies
[]
See GitLab documentation for details
workhorse.logFormat
json
Logging format. Valid formats:
json
,
structured
,
text
workerProcesses
2
Webservice number of workers
workhorse.keywatcher
true
Subscribe workhorse to Redis. This is
required
by any deployment servicing request to
/api/*
, but can be safely disabled for other deployments
workhorse.shutdownTimeout
global.webservice.workerTimeout + 1
(seconds)
Time to wait for all Web requests to clear from Workhorse. Examples:
1min
,
65s
.
workhorse.trustedCIDRsForPropagation
A list of CIDR blocks that can be trusted for propagating a correlation ID. The
-propagateCorrelationID
option must also be used in
workhorse.extraArgs
for this to work. See the Workhorse documentation for more details.
workhorse.trustedCIDRsForXForwardedFor
A list of CIDR blocks that can be used to resolve the actual client IP via the
X-Forwarded-For
HTTP header. This is used with
workhorse.trustedCIDRsForPropagation
. See the Workhorse documentation for more details.
workhorse.livenessProbe.initialDelaySeconds
20
Delay before liveness probe is initiated
workhorse.livenessProbe.periodSeconds
60
How often to perform the liveness probe
workhorse.livenessProbe.timeoutSeconds
30
When the liveness probe times out
workhorse.livenessProbe.successThreshold
1
Minimum consecutive successes for the liveness probe to be considered successful after having failed
workhorse.livenessProbe.failureThreshold
3
Minimum consecutive failures for the liveness probe to be considered failed after having succeeded
workhorse.monitoring.exporter.enabled
false
Enable workhorse to expose Prometheus metrics, this is overridden by
workhorse.metrics.enabled
workhorse.monitoring.exporter.port
9229
Port number to use for workhorse Prometheus metrics
workhorse.monitoring.exporter.tls.enabled
false
When set to
true
, enables TLS on metrics endpoint. It requires TLS to be enabled for Workhorse.
workhorse.metrics.enabled
true
If a workhorse metrics endpoint should be made available for scraping
workhorse.metrics.port
8083
Workhorse metrics endpoint port
workhorse.metrics.path
/metrics
Workhorse metrics endpoint path
workhorse.metrics.serviceMonitor.enabled
false
If a ServiceMonitor should be created to enable Prometheus Operator to manage the Workhorse metrics scraping
workhorse.metrics.serviceMonitor.additionalLabels
{}
Additional labels to add to the Workhorse ServiceMonitor
workhorse.metrics.serviceMonitor.endpointConfig
{}
Additional endpoint configuration for the Workhorse ServiceMonitor
workhorse.readinessProbe.initialDelaySeconds
0
Delay before readiness probe is initiated
workhorse.readinessProbe.periodSeconds
10
How often to perform the readiness probe
workhorse.readinessProbe.timeoutSeconds
2
When the readiness probe times out
workhorse.readinessProbe.successThreshold
1
Minimum consecutive successes for the readiness probe to be considered successful after having failed
workhorse.readinessProbe.failureThreshold
3
Minimum consecutive failures for the readiness probe to be considered failed after having succeeded
workhorse.imageScaler.maxProcs
2
The maximum number of image scaling processes that may run concurrently
workhorse.imageScaler.maxFileSizeBytes
250000
The maximum file size in bytes for images to be processed by the scaler
workhorse.tls.verify
true
When set to
true
forces NGINX Ingress to verify the TLS certificate of Workhorse. For custom CA you need to set
workhorse.tls.caSecretName
as well. Must be set to
false
for self-signed certificates.
workhorse.tls.secretName
{Release.Name}-workhorse-tls
The name of the TLS Secret that contains the TLS key and certificate pair. This is required when Workhorse TLS is enabled.
workhorse.tls.caSecretName
The name of the Secret that contains the CA certificate. This
is not
a TLS Secret, and must have only
ca.crt
key. This is used for TLS verification by NGINX.
webServer
puma
Selects web server (Webservice/Puma) that would be used for request handling
priorityClassName
""
Allow configuring pods
priorityClassName
, this is used to control pod priority in case of eviction
Chart configuration examples
extraEnv
extraEnv
allows you to expose additional environment variables in all containers in the pods.
deployment.strategy
allows you to change the deployment update strategy. It defines how the pods will be recreated when deployment is updated. When not provided, the cluster default is used.
For example, if you don’t want to create extra pods when the rolling update starts and change max unavailable pods to 50%:
You can also change the type of update strategy to
Recreate
, but be careful as it will kill all pods before scheduling new ones, and the web UI will be unavailable until the new pods are started. In this case, you don’t need to define
rollingUpdate
, only
type
:
deployment: strategy: type:Recreate
For more details, see the Kubernetes documentation.
TLS
A Webservice pod runs two containers:
gitlab-workhorse
webservice
gitlab-workhorse
Workhorse supports TLS for both web and metrics endpoints. This will secure the
communication between Workhorse and other components, in particular
nginx-ingress
,
gitlab-shell
, and
gitaly
. The TLS certificate should include the Workhorse
Service host name (e.g.
RELEASE-webservice-default.default.svc
) in the Common
Name (CN) or Subject Alternate Name (SAN).
Note that multiple deployments of Webservice can exist,
so you need to prepare the TLS certificate for different service names. This
can be achieved by either multiple SAN or wildcard certificate.
Once the TLS certificate is generated, create a Kubernetes TLS Secret for it. You also need to create
another Secret that only contains the CA certificate of the TLS certificate
with
ca.crt
key.
The TLS can be enabled for
gitlab-workhorse
container by setting
global.workhorse.tls.enabled
to
true
. You can pass custom Secret names to
gitlab.webservice.workhorse.tls.secretName
and
global.certificates.customCAs
accordingly.
When
gitlab.webservice.workhorse.tls.verify
is
true
(it is by default), you
also need to pass the CA certificate Secret name to
gitlab.webservice.workhorse.tls.caSecretName
.
This is necessary for self-signed certificates and custom CA. This Secret is used
by NGINX to verify the TLS certificate of Workhorse.
TLS can be enabled on metrics endpoints for
gitlab-workhorse
container by setting
gitlab.webservice.workhorse.monitoring.tls.enabled
to
true
. Note that TLS on
metrics endpoint is only available when TLS is enabled for Workhorse. The metrics
listener uses the same TLS certificate that is specified by
gitlab.webservice.workhorse.tls.secretName
.
webservice
The primary use case for enabling TLS is to provide encryption via HTTPS
for scraping Prometheus metrics.
For this reason, the TLS certificate should include the Webservice
hostname (ex:
RELEASE-webservice-default.default.svc
) in the Common
Name (CN) or Subject Alternate Name (SAN).
The Prometheus server bundled with the chart does not yet
support scraping of HTTPS endpoints.
TLS can be enabled on the
webservice
container by the settings
gitlab.webservice.tls.enabled
:
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-webservice-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.
Deployments settings
This chart has the ability to create multiple Deployment objects and their related
resources. This feature allows requests to the GitLab application to be distributed between multiple sets of Pods using path based routing.
The keys of this Map (
default
in this example) are the “name” for each.
default
will have a Deployment, Service, HorizontalPodAutoscaler, PodDisruptionBudget, and
optional Ingress created with
RELEASE-webservice-default
.
Any property not provided will inherit from the
gitlab-webservice
chart defaults.
Each
deployments
entry will inherit from chart-wide Ingress settings. Any value presented here will override those provided there. Outside of
path
, all settings are identical to those.
The
path
property is directly populated into the Ingress’s
path
property, and allows one to control URI paths which are directed to each service. In the example above,
default
acts as the catch-all path, and
api
received all traffic under
/api
You can disable a given Deployment from having an associated Ingress resource created by setting
path
to empty. See below, where
internal-api
will never receive external traffic.
These annotations will be used for every Ingress. For example:
ingress.annotations."nginx\.ingress\.kubernetes\.io/enable-access-log"=true
.
ingress.configureCertmanager
Boolean
Toggles Ingress annotation
cert-manager.io/issuer
. For more information see the TLS requirement for GitLab Pages.
ingress.enabled
Boolean
false
Setting that controls whether to create Ingress objects for services that support them. When
false
, the
global.ingress.enabled
setting value is used.
ingress.proxyBodySize
String
512m
See Below.
ingress.tls.enabled
Boolean
true
When set to
false
, you disable TLS for GitLab Webservice. 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.secretName
String
(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.
ingress.tls.smardcardSecretName
String
(empty)
The name of the Kubernetes TLS SEcret that contains a valid certificate and key for the GitLab smartcard URL if enabled. When not set, the
global.ingress.tls.secretName
value is used instead.
annotations
annotations
is used to set annotations on the Webservice Ingress.
We set one annotation by default:
nginx.ingress.kubernetes.io/service-upstream: "true"
.
This helps balance traffic to the Webservice pods more evenly by telling NGINX to directly
contact the Service itself as the upstream. For more information, see the
NGINX docs.
proxyBodySize
is used to set the NGINX proxy maximum body size. This is commonly
required to allow a larger Docker image than the default.
It is equivalent to the
nginx['client_max_body_size']
configuration in an
Omnibus installation.
As an alternative option,
you can set the body size with either of the following two parameters too:
Each pod spawns an amount of workers equal to
workerProcesses
, who each use
some baseline amount of memory. We recommend:
A minimum of 1.25GB per worker (
requests.memory
)
A maximum of 1.5GB per worker, plus 1GB for the primary (
limits.memory
)
Note that required resources are dependent on the workload generated by users
and may change in the future based on changes or upgrades in the GitLab application.
The hostname of the Registry server to use. This can be omitted in lieu of
api.serviceName
.
api.port
Integer
5000
The port on which to connect to the Registry API.
api.protocol
String
The protocol Webservice should use to reach the Registry API.
api.serviceName
String
registry
The 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.key
String
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.secret
String
The name of the Kubernetes Secret that houses the certificate bundle to be used to verify the tokens created by the GitLab instance(s).
host
String
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.
port
Integer
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
.
tokenIssuer
String
gitlab-issuer
The 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 Webservice Pods.
Name
Type
Default
Description
replicaCount
Integer
1
The number of Webservice instances to create in the deployment.
workerProcesses
Integer
2
The number of Webservice 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.
Metrics
Metrics can be enabled with the
metrics.enabled
value and use the GitLab
monitoring exporter to expose a metrics port. Pods are either given Prometheus
annotations or if
metrics.serviceMonitor.enabled
is
true
a Prometheus
Operator ServiceMonitor is created. Metrics can alternativly be scraped from
the
/-/metrics
endpoint, but this requires GitLab Prometheus metrics
to be enabled in the Admin area. The GitLab Workhorse metrics can also be
exposed via
workhorse.metrics.enabled
but these can’t be collected using the
Prometheus annotations so either require
workhorse.metrics.serviceMonitor.enabled
to be
true
or external Prometheus
configuration.
GitLab Shell
GitLab Shell uses an Auth Token in its communication with Webservice. Share the token
with GitLab Shell and Webservice using a shared Secret.
Defines the name of the key in the secret (below) that contains the authToken.
authToken.secret
String
Defines the name of the Kubernetes
Secret
to pull from.
port
Integer
22
The port number to use in the generation of SSH URLs within the GitLab UI. Controlled by
global.shell.port
.
WebServer options
Current version of chart supports Puma web server.
Puma unique options:
Name
Type
Default
Description
puma.workerMaxMemory
Integer
The maximum memory (in megabytes) for the Puma worker killer
puma.threads.min
Integer
4
The minimum amount of Puma threads
puma.threads.max
Integer
4
The maximum amount of Puma threads
Configuring the
networkpolicy
This section controls the
NetworkPolicy.
This configuration is optional and is used to limit Egress and Ingress of the
Pods to specific endpoints.
Name
Type
Default
Description
enabled
Boolean
false
This setting enables the
NetworkPolicy
ingress.enabled
Boolean
false
When set to
true
, the
Ingress
network policy will be activated. This will block all Ingress connections unless rules are specified.
ingress.rules
Array
[]
Rules for the Ingress policy, for details see https://kubernetes.io/docs/concepts/services-networking/network-policies/#the-networkpolicy-resource and the example below
egress.enabled
Boolean
false
When set to
true
, the
Egress
network policy will be activated. This will block all egress connections unless rules are specified.
egress.rules
Array
[]
Rules for the egress policy, these for details see https://kubernetes.io/docs/concepts/services-networking/network-policies/#the-networkpolicy-resource and the example below
Example Network Policy
The webservice service requires Ingress connections for only the Prometheus
exporter if enabled and traffic coming from the NGINX Ingress, and normally
requires Egress connections to various places. This examples adds the following
network policy:
All Ingress requests from the network on TCP
10.0.0.0/8
port 8080 are allowed for metrics exporting and NGINX Ingress
All Egress requests to the network on UDP
10.0.0.0/8
port 53 are allowed for DNS
All Egress requests to the network on TCP
10.0.0.0/8
port 5432 are allowed for PostgreSQL
All Egress requests to the network on TCP
10.0.0.0/8
port 6379 are allowed for Redis
All Egress requests to the network on TCP
10.0.0.0/8
port 8075 are allowed for Gitaly
Other Egress requests to the local network on
10.0.0.0/8
are restricted
Egress requests outside of the
10.0.0.0/8
are allowed
Note the example provided is only an example and may not be complete
Note that the Webservice requires outbound connectivity to the public internet
for images on external object storage
If the
service.type
is set to
LoadBalancer
, you can optionally specify
service.loadBalancerIP
to create
the
LoadBalancer
with a user-specified IP (if your cloud provider supports it).
When the
service.type
is set to
LoadBalancer
you must also set
service.loadBalancerSourceRanges
to restrict
the CIDR ranges that can access the
LoadBalancer
(if your cloud provider supports it).
This is currently required due to an issue where metric ports are exposed.
Additional information about the
LoadBalancer
service type can be found in
the Kubernetes documentation
LFS, Artifacts, Uploads, Packages, External MR diffs, and Dependency Proxy
connection
when (only for External MR Diffs)
cdn (only for CI Artifacts)
Incoming email settings
KAS settings
Custom secret
Custom URLs
External KAS
Suggested Reviewers settings
Custom secret
LDAP
Disable LDAP web sign in
Using a custom CA or self signed LDAP certificates
OmniAuth
providers
connection
Cron jobs related settings
Sentry settings
gitlab_docs settings
Smartcard Authentication settings
Sidekiq routing rules settings
Configure Rails settings
Configure Workhorse settings
Bootsnap Cache
Configure GitLab Shell
Port
TCP proxy protocol
Configure GitLab Pages
Configure Webservice
workerTimeout
Custom Certificate Authorities
Application Resource
Busybox image
Service Accounts
Annotations
Node Selector
Labels
Common Labels
Pod
Service
Tracing
extraEnv
extraEnvFrom
Configure OAuth settings
Kerberos
Dedicated port for Kerberos
LDAP custom allowed realms
Outgoing email
Platform
Affinity
Pod Priority and Preemption
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.yaml
.
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
Praefect
MinIO
appConfig
Rails
Workhorse
GitLab Shell
Pages
Webservice
Custom Certificate Authorities
Application Resource
Busybox image
Service Accounts
Annotations
Tracing
extraEnv
extraEnvFrom
OAuth
Kerberos
Outgoing email
Platform
Affinity
Configure Host settings
The GitLab global host settings are located under the
global.hosts
key.
The base domain. GitLab and Registry will be exposed on the subdomain of this setting. This defaults to
example.com
, but is not used for hosts that have their
name
property configured. See the
gitlab.name
,
minio.name
, and
registry.name
sections below.
externalIP
nil
Set the external IP address that will be claimed from the provider. This will be templated into the NGINX chart, in place of the more complex
nginx.service.loadBalancerIP
.
https
Boolean
true
If set to true, you will need to ensure the NGINX chart has access to the certificates. In cases where you have TLS-termination in front of your Ingresses, you probably want to look at
global.ingress.tls.enabled
. Set to false for external URLs to use
http://
instead of
https
.
hostSuffix
String
See Below.
gitlab.https
Boolean
false
If
hosts.https
or
gitlab.https
are
true
, the GitLab external URL will use
https://
instead of
http://
.
gitlab.name
String
The hostname for GitLab. If set, this hostname is used, regardless of the
global.hosts.domain
and
global.hosts.hostSuffix
settings.
gitlab.hostnameOverride
String
Override the hostname used in Ingress configuration of the Webservice. Useful if GitLab has to be reachable behind a WAF that rewrites the Hostname to an internal hostname (e.g.:
gitlab.example.com
–>
gitlab.cluster.local
).
gitlab.serviceName
String
webservice
The name of the
service
which is operating the GitLab server. The chart will template the hostname of the service (and current
.Release.Name
) to create the proper internal serviceName.
gitlab.servicePort
String
workhorse
The named port of the
service
where the GitLab server can be reached.
minio.https
Boolean
false
If
hosts.https
or
minio.https
are
true
, the MinIO external URL will use
https://
instead of
http://
.
minio.name
String
minio
The hostname for MinIO. If set, this hostname is used, regardless of the
global.hosts.domain
and
global.hosts.hostSuffix
settings.
minio.serviceName
String
minio
The name of the
service
which is operating the MinIO server. The chart will template the hostname of the service (and current
.Release.Name
) to create the proper internal serviceName.
minio.servicePort
String
minio
The named port of the
service
where the MinIO server can be reached.
registry.https
Boolean
false
If
hosts.https
or
registry.https
are
true
, the Registry external URL will use
https://
instead of
http://
.
registry.name
String
registry
The hostname for Registry. If set, this hostname is used, regardless of the
global.hosts.domain
and
global.hosts.hostSuffix
settings.
registry.serviceName
String
registry
The name of the
service
which is operating the Registry server. The chart will template the hostname of the service (and current
.Release.Name
) to create the proper internal serviceName.
registry.servicePort
String
registry
The named port of the
service
where the Registry server can be reached.
smartcard.name
String
smartcard
The hostname for smartcard authentication. If set, this hostname is used, regardless of the
global.hosts.domain
and
global.hosts.hostSuffix
settings.
kas.name
String
kas
The hostname for the KAS. If set, this hostname is used, regardless of the
global.hosts.domain
and
global.hosts.hostSuffix
settings.
kas.https
Boolean
false
If
hosts.https
or
kas.https
are
true
, the KAS external URL will use
wss://
instead of
ws://
.
pages.name
String
pages
The hostname for GitLab Pages. If set, this hostname is used, regardless of the
global.hosts.domain
and
global.hosts.hostSuffix
settings.
pages.https
String
If
global.pages.https
or
global.hosts.pages.https
or
global.hosts.https
are
true
, then URL for GitLab Pages in the Project settings UI will use
https://
instead of
http://
.
ssh
String
The hostname for cloning repositories over SSH. If set, this hostname is used, regardless of the
global.hosts.domain
and
global.hosts.hostSuffix
settings.
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
:
The GitLab global host settings for HPA are located under the
global.hpa
key:
Name
Type
Default
Description
apiVersion
String
API version to use in the HorizontalPodAutoscaler object definitions.
Configure PodDisruptionBudget settings
The GitLab global host settings for PDB are located under the
global.pdb
key:
Name
Type
Default
Description
apiVersion
String
API version to use in the PodDisruptionBudget object definitions.
Configure CronJob settings
The GitLab global host settings for CronJobs are located under the
global.batch.cronJob
key:
Name
Type
Default
Description
apiVersion
String
API version to use in the CronJob object definitions.
Configure Ingress settings
The GitLab global host settings for Ingress are located under the
global.ingress
key:
Name
Type
Default
Description
apiVersion
String
API version to use in the Ingress object definitions.
annotations.*annotation-key*
String
Where
annotation-key
is a string that will be used with the value as an annotation on every Ingress. For Example:
global.ingress.annotations."nginx\.ingress\.kubernetes\.io/enable-access-log"=true
. No global annotations are provided by default.
configureCertmanager
Boolean
true
See below.
class
String
gitlab-nginx
Global setting that controls
kubernetes.io/ingress.class
annotation or
spec.IngressClassName
in
Ingress
resources. Set to
none
to disable, or
""
for empty. Note: for
none
or
""
, set
nginx-ingress.enabled=false
to prevent the charts from deploying unnecessary Ingress resources.
enabled
Boolean
true
Global setting that controls whether to create Ingress objects for services that support them.
tls.enabled
Boolean
true
When set to
false
, this disables TLS in GitLab. This is useful for cases in which you cannot use TLS termination of Ingresses, such as when you have a TLS-terminating proxy before the Ingress Controller. If you want to disable https completely, this should be set to
false
together with
global.hosts.https
.
tls.secretName
String
The name of the Kubernetes TLS Secret that contains a
wildcard
certificate and key for the domain used in
global.hosts.domain
.
path
String
/
Default for
path
entries in Ingress objects
pathType
String
Prefix
A Path Type allows you to specify how a path should be matched. Our current default is
Prefix
but you can use
ImplementationSpecific
or
Exact
depending on your use case.
provider
String
nginx
Global setting that defines the Ingress provider to use.
nginx
is used as the default provider.
Sample configurations for various cloud providers
can be found in the examples folder.
AWS
GKE
Ingress Path
This chart employs
global.ingress.path
as a means to assist those users that need to alter the definition of
path
entries for their Ingress objects.
Many users have no need for this setting, and
should not configure it
.
For those users who need to have their
path
definitions end in
/*
to match their load balancer / proxy behaviors, such as when using
ingress.class: gce
in GCP,
ingress.class: alb
in AWS, or another such provider.
This setting ensures that all
path
entries in Ingress resources throughout this chart are rendered with this.
The only exception is when populating the
gitlab/webservice
deployments settings, where
path
must be specified.
Cloud provider LoadBalancers
Various cloud providers’ LoadBalancer implementations have an impact on configuration of the Ingress resources and NGINX controller deployed as part of this chart. The next table provides examples.
Provider
Layer
Example snippet
AWS
4
aws/elb-layer4-loadbalancer
AWS
7
aws/elb-layer7-loadbalancer
AWS
7
aws/alb-full
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.
If you wish to use an external
cert-manager
, you must provide the following:
gitlab.webservice.ingress.tls.secretName
registry.ingress.tls.secretName
minio.ingress.tls.secretName
global.ingress.annotations
GitLab Version
This value should only used for development purposes, or by explicit request of GitLab support. Please avoid using this value
on production environments and set the version as described
in Deploy using Helm
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
webservice
,
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.
Adding suffix to all image tags
If you wish to add a suffix to the name of all images used in the Helm chart, you can use the
global.image.tagSuffix
key.
An example of this use case might be if you wish to use fips compliant container images from GitLab, which are all built
with the
-fips
extension to the image tag.
--set global.image.tagSuffix="-fips"
Configure PostgreSQL settings
The GitLab global PostgreSQL settings are located under the
global.psql
key.
The hostname of the PostgreSQL server with the database to use. This can be omitted if using PostgreSQL deployed by this chart.
serviceName
String
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.
database
String
gitlabhq_production
The name of the database to use on the PostgreSQL server.
password.useSecret
Boolean
true
Controls whether the password for PostgreSQL is read from a secret or file.
password.file
String
Defines the path to the file that contains the password for PostgreSQL. Ignored if
password.useSecret
is true
password.key
String
The
password.key
attribute for PostgreSQL defines the name of the key in the secret (below) that contains the password. Ignored if
password.useSecret
is false.
password.secret
String
The
password.secret
attribute for PostgreSQL defines the name of the Kubernetes
Secret
to pull from. Ignored if
password.useSecret
is false.
port
Integer
5432
The port on which to connect to the PostgreSQL server.
username
String
gitlab
The username with which to authenticate to the database.
preparedStatements
Boolean
false
If prepared statements should be used when communicating with the PostgreSQL server.
databaseTasks
Boolean
true
If GitLab should perform database tasks for a given database. Automatically disabled when sharing host/port/database match
main
.
connectTimeout
Integer
The number of seconds to wait for a database connection.
keepalives
Integer
Controls whether client-side TCP keepalives are used (1, meaning on, 0, meaning off).
keepalivesIdle
Integer
The number of seconds of inactivity after which TCP should send a keepalive message to the server. A value of zero uses the system default.
keepalivesInterval
Integer
The number of seconds after which a TCP keepalive message that is not acknowledged by the server should be retransmitted. A value of zero uses the system default.
keepalivesCount
Integer
The number of TCP keepalives that can be lost before the client’s connection to the server is considered dead. A value of zero uses the system default.
tcpUserTimeout
Integer
The number of milliseconds that transmitted data may remain unacknowledged before a connection is forcibly closed. A value of zero uses the system default.
applicationName
String
The name of the application connecting to the database. Set to a blank string (
""
) to disable. By default, this will be set to the name of the running process (e.g.
sidekiq
,
puma
).
PostgreSQL per chart
In some complex deployments, it may be desired to configure different parts of
this chart with different configurations for PostgreSQL. As of
v4.2.0
, all
properties available within
global.psql
can be set on a per-chart basis,
for example
gitlab.sidekiq.psql
. The local settings will override global values
when supplied, inheriting any
not present
from
global.psql
, with the exception
of
psql.load_balancing
.
PostgreSQL load balancing will
never
inherit
from the global, by design.
PostgreSQL SSL
SSL support is mutual TLS only.
See issue #2034
and issue #1817.
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: ssl: secret:db-example-ssl-secrets# Name of the secret clientCertificate:cert.pem# Secret key storing the certificate clientKey:key.pem# Secret key of the certificate's key serverCA:server-ca.pem# Secret key containing the CA for the database server
Name
Type
Default
Description
secret
String
Name of the Kubernetes
Secret
containing the following keys
clientCertificate
String
Name of the key within the
Secret
containing the client certificate.
clientKey
String
Name of the key within the
Secret
containing the client certificate’s key file.
serverCA
String
Name of the key within the
Secret
containing the certificate authority for the server.
You may also need to set
extraEnv
values to export environment values to point to the correct keys.
Configuration of service discovery can be more complex. For a complete
details of this configuration, the parameters and their associated
behaviors, see Service Discovery
in the GitLab Administration documentation.
Further tuning is also available, in regards to the
handling of stale reads.
The GitLab Administration documentation covers these items in detail,
and those properties can be added directly under
load_balancing
.
global: psql: load_balancing: max_replication_difference:# See documentation max_replication_lag_time:# See documentation replica_check_interval:# See documentation
Configure Redis settings
The GitLab global Redis settings are located under the
global.redis
key.
By default we use an single, non-replicated Redis instance. If desired, a
highly available Redis can be deployed instead. To install an HA Redis
cluster one needs to set
redis.cluster.enabled=true
when the GitLab
chart is installed.
You can bring an external Redis instance by setting
redis.install=false
, and
following our advanced documentation for
configuration.
The hostname of the Redis server with the database to use. This can be omitted in lieu of
serviceName
.
serviceName
String
redis
The 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.
port
Integer
6379
The port on which to connect to the Redis server.
password.enabled
Boolean
true
The
password.enabled
provides a toggle for using a password with the Redis instance.
password.key
String
The
password.key
attribute for Redis defines the name of the key in the secret (below) that contains the password.
password.secret
String
The
password.secret
attribute for Redis defines the name of the Kubernetes
Secret
to pull from.
scheme
String
redis
The URI scheme to be used to generate Redis URLs. Valid values are
redis
,
rediss
, and
tcp
. If using
rediss
(SSL encrypted connection) scheme, the certificate used by the server should be a part of the system’s trusted chains. This can be done by adding them to the custom certificate authorities list.
Configure Redis chart-specific settings
Settings to configure the Redis chart
directly are located under the
redis
key:
Refer to the full list of settings
for more information.
Redis Sentinel support
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 Kubernetes Secret containing the Redis password will need to be manually created
before deploying the GitLab chart.
The installation of an HA Redis cluster from the GitLab chart does not
support using sentinels. If sentinel support is desired, a Redis cluster
needs to be created separately from the GitLab chart install. This can be
done inside or outside the Kubernetes cluster.
An issue to track the
supporting of sentinels in a GitLab deployed Redis cluster has
been created for tracking purposes.
The
host
attribute needs to be set to the cluster name as specified in the
sentinel.conf
.
sentinels.[].host
String
The hostname of Redis Sentinel server for a Redis HA setup.
sentinels.[].port
Integer
26379
The port on which to connect to the Redis Sentinel server.
All the prior Redis attributes in the general configure Redis settings
continue to apply with the Sentinel support unless re-specified in the table above.
Multiple Redis support
The GitLab chart includes support for running with separate Redis instances
for different persistence classes, currently:
Instance
Purpose
cache
Store cached data
queues
Store Sidekiq background jobs
sharedState
Store various persistent data such as distributed locks
actioncable
Pub/Sub queue backend for ActionCable
traceChunks
Store job traces temporarily
rateLimiting
Store rate-limiting usage for RackAttack and Application Limits
sessions
Store user session data
Any number of the instances may be specified. Any instances not specified
will be handled by the primary Redis instance specified
by
global.redis.host
or use the deployed Redis instance from the chart.
For example:
The following table describes the attributes for each dictionary of the
Redis instances.
Name
Type
Default
Description
.host
String
The hostname of the Redis server with the database to use.
.port
Integer
6379
The port on which to connect to the Redis server.
.password.enabled
Boolean
true
The
password.enabled
provides a toggle for using a password with the Redis instance.
.password.key
String
The
password.key
attribute for Redis defines the name of the key in the secret (below) that contains the password.
.password.secret
String
The
password.secret
attribute for Redis defines the name of the Kubernetes
Secret
to pull from.
The primary Redis definition is required as there are additional persistence
classes that have not been separated.
Each instance definition may also use Redis Sentinel support. Sentinel
configurations
are not shared
and needs to be specified for each
instance that uses Sentinels. Please refer to the Sentinel configuration
for the attributes that are used to configure Sentinel servers.
Specifying secure Redis scheme (SSL)
In order to connect to Redis using SSL, the
rediss
(note the double
s
) scheme parameter is required:
Some Redis services such as Google Cloud Memorystore do not make use of passwords and the associated
AUTH
command. The use and requirement for a password can be disabled via the following configuration setting:
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/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
bucket
,
certificate
,
httpSecret
, and
notificationSecret
settings, see the documentation within the registry chart.
notifications
This setting is used to configure
Registry notifications.
It takes in a map (following upstream specification), but with an added feature
of providing sensitive headers as Kubernetes secrets. For example, consider the
following snippet where the Authorization header contains sensitive data while
other headers contain regular data:
In this example, the header
X-Random-Config
is a regular header and its value
can be provided in plaintext in the
values.yaml
file or via
--set
flag.
However, the header
Authorization
is a sensitive one, so mounting it from a
Kubernetes secret is preferred. For details regarding the structure of the
secret, refer the secrets documentation
Configure Gitaly settings
The global Gitaly settings are located under the
global.gitaly
key.
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.
If
gitaly.host
is provided,
gitaly.internal
and
gitaly.external
properties will
be ignored
.
See the deprecated Gitaly settings.
The Gitaly authentication token is expected to be identical for
all Gitaly services at this time, internal or external. Ensure these are aligned.
See issue #1992 for further details.
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.
Manual scaling of this item is required, by adding or removing entries in
gitaly.internal.names
. When scaling down, any repository that has not been moved
to another node will become unavailable. Since the Gitaly chart is a
StatefulSet
,
dynamically provisioned disks
will not
be reclaimed. This means the data disks
will persist, and the data on them can be accessed when the set is scaled up again
by re-adding a node to the
names
list.
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.
An entry with
name: default
is required.
hostname
: The host of Gitaly services.
port
: (optional) The port number to reach the host on. Defaults to
8075
.
tlsEnabled
: (optional) Override
global.gitaly.tls.enabled
for this particular entry.
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.
You may use an external Praefect
to provide highly available Gitaly services. Configuration of the two is
interchangeable, as from the viewpoint of the clients, there is no difference.
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.
All Gitaly nodes
must
share the same authentication token.
Deprecated Gitaly settings
Name
Type
Default
Description
host
(deprecated)
String
The hostname of the Gitaly server to use. This can be omitted in lieu of
serviceName
. If this setting is used, it will override any values of
internal
or
external
.
port
(deprecated)
Integer
8075
The port on which to connect to the Gitaly server.
serviceName
(deprecated)
String
The name of the
service
which is operating the Gitaly server. 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 Gitaly as a part of the overall GitLab chart.
TLS settings
Configuring Gitaly to serve via TLS is detailed in the Gitaly chart’s documentation.
Configure Praefect settings
The global Praefect settings are located under the
global.praefect
key.
Praefect is disabled by default. When enabled with no extra settings, 3 Gitaly replicas will be created, and the Praefect database will need to be manually created on the default PostgreSQL instance.
Enable Praefect
To enable Praefect with default settings, set
global.praefect.enabled=true
.
See the Praefect documentation for details on how to operate a Gitaly cluster using Praefect.
The list of desired virtual storages (each backed by a Gitaly StatefulSet)
dbSecret.secret
String
The name of the secret to use for authenticating with the database
dbSecret.key
String
The name of the key in
dbSecret.secret
to use
psql.host
String
The hostname of the database server to use (when using an external database)
psql.port
String
The port number of the database server (when using an external database)
psql.user
String
praefect
The database user to use
psql.dbName
String
praefect
The name of the database to use
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 Webservice, Sidekiq, and
Gitaly charts share multiple settings, which are configured
with the
global.appConfig
key.
The
appConfig
settings that can be used to tweak the general properties of the Rails
application are described below:
Name
Type
Default
Description
cdnHost
String
(empty)
Sets a base URL for a CDN to serve static assets (for example,
https://mycdnsubdomain.fictional-cdn.com
).
contentSecurityPolicy
Struct
See below.
enableUsagePing
Boolean
true
A flag to disable the usage ping support.
enableSeatLink
Boolean
true
A flag to disable the seat link support.
enableImpersonation
nil
A flag to disable user impersonation by Administrators.
applicationSettingsCacheSeconds
Integer
60
An interval value (in seconds) to invalidate the application settings cache.
usernameChangingEnabled
Boolean
true
A flag to decide if users are allowed to change their username.
issueClosingPattern
String
(empty)
Pattern to close issues automatically.
defaultTheme
Integer
Numeric ID of the default theme for the GitLab instance. It takes a number, denoting the ID of the theme.
defaultProjectsFeatures.*feature*
Boolean
true
See below.
webHookTimeout
Integer
Waiting time in seconds before a hook is deemed to have failed.
Content Security Policy
Setting a Content Security Policy (CSP) can help thwart JavaScript cross-site
scripting (XSS) attacks. See GitLab documentation for configuration details. Content Security Policy Documentation
GitLab automatically provides secure default values for the CSP.
Improperly configuring the CSP rules could prevent GitLab from working properly.
Before rolling out a policy, you may also want to change report_only to true to
test the configuration.
defaultProjectsFeatures
Flags to decide if new projects should be created with the respective features by
default. All flags default to
true
.
By default, the charts work with Gravatar avatar service available at gravatar.com.
However, a custom Libravatar service can also be used if needed:
Name
Type
Default
Description
gravatar.plainURL
String
(empty)
HTTP URL to Libravatar instance (instead of using gravatar.com).
gravatar.sslUrl
String
(empty)
HTTPS URL to Libravatar instance (instead of using gravatar.com).
Hooking Analytics services to the GitLab instance
Settings to configure Analytics services like Google Analytics and Matomo are defined
under the
extra
key below
appConfig
:
Name
Type
Default
Description
extra.googleAnalyticsId
String
(empty)
Tracking ID for Google Analytics.
extra.matomoSiteId
String
(empty)
Matomo Site ID.
extra.matomoUrl
String
(empty)
Matomo URL.
extra.matomoDisableCookies
Boolean
(empty)
Disable Matomo cookies (corresponds to
disableCookies
in the Matomo script)
extra.oneTrustId
String
(empty)
OneTrust ID.
extra.googleTagManagerNonceId
String
(empty)
Google Tag Manager ID.
extra.bizible
Boolean
false
Set to true to enable Bizible script
Consolidated object storage
In addition to the following section that describes how to configure individual settings
for object storage, we’ve added a consolidated object storage configuration to ease the use
of shared configuration for these items. Making use of
object_store
, you can configure a
connection
once, and it will be used for any and all object storage backed features that
are not individually configured with a
connection
property.
Enable proxy of all downloads via GitLab, in place of direct downloads from the
bucket
.
storage_options
String
{}
See below.
connection
String
{}
See below.
The property structure is shared, and all properties here can be overridden by the individual
items below. The
connection
property structure is identical.
Notice:
The
bucket
,
enabled
, and
proxy_download
properties are the only properties that must be
configured on a per-item level (
global.appConfig.artifacts.bucket
, …) if you wish to
deviate from the default values.
When using the
AWS
provider for the connection (which is any
S3 compatible provider such as the included MinIO), GitLab Workhorse can offload
all storage related uploads. This will automatically be enabled for you, when
using this consolidated configuration.
Specify buckets
Each object type should be stored in different buckets.
By default, GitLab uses these bucket names for each type:
Object type
Bucket Name
CI artifacts
gitlab-artifacts
Git LFS
git-lfs
Packages
gitlab-packages
Uploads
gitlab-uploads
External merge request diffs
gitlab-mr-diffs
Terraform State
gitlab-terraform-state
CI Secure Files
gitlab-ci-secure-files
Dependency Proxy
gitlab-dependency-proxy
Pages
gitlab-pages
You can use these defaults or configure the bucket names:
The
storage_options
are used to configure
S3 Server Side Encryption.
Setting a default encryption on an S3 bucket is the easiest way to
enable encryption, but you may want to
set a bucket policy to ensure only encrypted objects are uploaded.
To do this, you must configure GitLab to send the proper encryption headers
in the
storage_options
configuration section:
Setting
Description
server_side_encryption
Encryption mode (
AES256
or
aws:kms
)
server_side_encryption_kms_key_id
Amazon Resource Name. Only needed when
aws:kms
is used in
server_side_encryption
. See the Amazon documentation on using KMS encryption
LFS, Artifacts, Uploads, Packages, External MR diffs, and Dependency Proxy
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.
Defaults to
true
for LFS, artifacts, uploads, and packages
Enable the use of these features with object storage.
proxy_download
Boolean
true
Enable proxy of all downloads via GitLab, in place of direct downloads from the
bucket
.
bucket
String
Various
Name of the bucket to use from object storage provider. Default will be
git-lfs
,
gitlab-artifacts
,
gitlab-uploads
, or
gitlab-packages
, depending on the service.
connection
String
{}
See below.
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
rails.azurerm.yaml
Once a YAML file containing the contents of the
connection
has been created, use
this file to create the secret in Kubernetes.
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.
cdn (only for CI Artifacts)
artifacts
setting has an additional key
cdn
to configure Google CDN in front of a Google Cloud Storage bucket.
Incoming email settings
The incoming email settings are explained in the command line options page.
KAS settings
Custom secret
One can optionally customize the KAS
secret
name as well as
key
, either by
using Helm’s
--set variable
option:
The GitLab backend can be made aware of an external KAS server (i.e. not
managed by the chart) by explicitly enabling it and configuring the required
URLs. You can do so using Helm’s
--set variable
option:
If you’d like to customize the secret value, refer to the secrets documentation.
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 the GitLab 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' base:'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:
Commas are considered special characters
within Helm
--set
items. Be sure to escape commas in values such as
bind_dn
:
--set global.appConfig.ldap.servers.main.bind_dn='cn=administrator\,cn=Users\,dc=domain\,dc=net'
.
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:
Ensure that the custom CA/Self-Signed certificate is created as a Secret or ConfigMap in the cluster/namespace:
# Configure a custom CA from a Secret --set global.certificates.customCAs[0].secret=my-custom-ca-secret
# Or from a ConfigMap --set global.certificates.customCAs[0].configMap=my-custom-ca-configmap
# Configure the LDAP integration to trust the custom CA --set global.appConfig.ldap.servers.main.ca_file=/etc/ssl/certs/ca-cert-unique_name.pem
This will ensure that the CA certificate is mounted in the relevant pods at
/etc/ssl/certs/ca-cert-unique_name.pem
and specifies its use in the LDAP configuration.
See Custom Certificate Authorities for more info.
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.
Allows users to log in with the specified providers without two factor authentication. Can be set to
true
,
false
, or an array of providers. See Bypassing two factor authentication.
allowSingleSignOn
Array
['saml']
Enable the automatic creation of accounts when signing in with OmniAuth. Input the name of the OmniAuth Provider.
autoLinkLdapUser
Boolean
false
Can be used if you have LDAP / ActiveDirectory integration enabled. When enabled, users automatically created through OmniAuth will be linked to their LDAP entry as well.
autoLinkSamlUser
Boolean
false
Can be used if you have SAML integration enabled. When enabled, users automatically created through OmniAuth will be linked to their SAML entry as well.
autoLinkUser
Allows users authenticating via an OmniAuth provider to be automatically linked to a current GitLab user if their emails match. Can be set to
true
,
false
, or an array of providers.
autoSignInWithProvider
nil
Single provider name allowed to automatically sign in. This should match the name of the provider, such as
saml
or
google_oauth2
.
blockAutoCreatedUsers
Boolean
true
If
true
auto created users will be blocked by default and will have to be unblocked by an administrator before they are able to sign in.
enabled
Boolean
false
Enable / disable the use of OmniAuth with GitLab.
externalProviders
[]
You can define which OmniAuth providers you want to be
external
, so that all users
creating accounts, or logging in via these providers
will be unable to access internal projects. You will need to use the full name of the provider, like
google_oauth2
for Google. See Configure OmniAuth Providers as External.
providers
[]
See below.
syncProfileAttributes
['email']
List of profile attributes to sync from the provider upon login. See Keep OmniAuth user profiles up to date for options.
syncProfileFromProvider
[]
List of provider names that GitLab should automatically sync profile information from. Entries should match the name of the provider, such as
saml
or
google_oauth2
. See Keep OmniAuth user profiles up to date.
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.
Due to the complexity of using
--set
arguments, a user may wish to use a YAML snippet,
passed to
helm
with
-f omniauth.yaml
.
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:
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
cron_jobs
and
ee_cron_jobs
sections in the sample
gitlab.yml
for more job examples.
These settings are shared between Sidekiq, Webservice (for showing tooltips in UI)
and Toolbox (for debugging purposes) pods.
Hostname to use for smartcard authentication. By default, the provided or computed smartcard hostname is used.
sanExtensions
Boolean
false
Enable the use of SAN extensions to match users with certificates.
requiredForGitAccess
Boolean
false
Require browser session with smartcard sign-in for Git access.
Sidekiq routing rules settings
GitLab supports routing a job from a worker to a desired queue before it is
scheduled. Sidekiq clients match a job against a configured list of routing
rules. Rules are evaluated from first to last, and as soon as a match for a
given worker is found, the processing for that worker is stopped (first match wins). If
the worker doesn’t match any rule, it falls back the queue name generated from
the worker name.
By default, the routing rules are not configured (or denoted with an empty
array), all the jobs are routed to the queue generated from the worker name.
The routing rules list is an ordered array of tuples of query and
corresponding queue:
The query is following the
worker matching query syntax.
The
<queue_name>
must match a valid Sidekiq queue name
sidekiq.pods[].queues
defined under
sidekiq.pods
. If the queue name
is
nil
, or an empty string, the worker is routed to the queue generated
by the name of the worker instead.
The query supports wildcard matching
*
, which matches all workers. As a
result, the wildcard query must stay at the end of the list or the later rules
are ignored:
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
Configure Workhorse settings
Several components of the GitLab suite speak to the APIs via GitLab Workhorse. This is currently a part of the Webservice chart. These settings are consumed by all charts that need to contact GitLab Workhorse, providing an easy access to set them globally vs individually.
Name of service to direct internal API traffic to. Do not include the Release name, as it will be templated in. Should match an entry in
gitlab.webservice.deployments
. See
gitlab/webservice
chart
scheme
String
http
Scheme of the API endpoint
host
String
Fully qualified hostname or IP address of an API endpoint. Overrides the presence of
serviceName
.
port
Integer
8181
Port number of associated API server.
tls.enabled
Boolean
false
When set to
true
, enables TLS support for Workhorse.
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.
See authToken in the GitLab Shell chart specific documentation.
hostKeys
See hostKeys in the GitLab Shell chart specific documentation.
tcp.proxyProtocol
Boolean
false
See TCP proxy protocol below for specific documentation.
Port
You can control the port used by the Ingress to pass SSH traffic, as well as the port used
in SSH URLs provided from GitLab via
global.shell.port
. This is reflected in the
port on which the service listens, as well as the SSH clone URLs provided in project UI.
global: shell: port:32022
You can combine
global.shell.port
and
nginx-ingress.controller.service.type=NodePort
to set a NodePort for the NGINX controller Service object. Note that if
nginx-ingress.controller.service.nodePorts.gitlab-shell
is set, it will
override
global.shell.port
when setting the NodePort for NGINX.
global: shell: port:32022
nginx-ingress: controller: service: type:NodePort
TCP proxy protocol
You can enable handling proxy protocol on the SSH Ingress to properly handle a connection from an upstream proxy that adds the proxy protocol header.
By doing so, this will prevent SSH from receiving the additional headers and not break SSH.
One common environment where one needs to enable handling of proxy protocol is when using AWS with an ELB handling the inbound connections to the cluster. You can consult the AWS layer 4 loadbalancer example to properly set it up.
Decides whether to install GitLab Pages chart in the cluster
accessControl
Boolean
False
Enables GitLab Pages Access Control
path
String
/srv/gitlab/shared/pages
Path where Pages deployment related files to be stored. Note: Unused by default, since object storage is used.
host
String
Pages root domain.
port
String
Port to be used to construct Pages URLs in UI. If left unset, default value of 80 or 443 is set based on HTTPS situation of Pages.
https
Boolean
True
Whether GitLab UI should show HTTPS URLs for Pages or not. Has precedence over
global.hosts.pages.https
and
global.hosts.https
. Set to True by default.
externalHttp
List
[]
List of IP addresses through which HTTP requests reach Pages daemon. For supporting custom domains.
externalHttps
List
[]
List of IP addresses through which HTTPS requests reach Pages daemon. For supporting custom domains.
artifactsServer
Boolean
True
Enable viewing artifacts in GitLab Pages.
objectStore.enabled
Boolean
True
Enable using object storage for Pages.
objectStore.bucket
String
gitlab-pages
Bucket to be used to store content related to Pages
objectStore.connection.secret
String
Secret containing connection details for object storage.
objectStore.connection.key
String
Key within the connection secret where connection details are stored.
localStore.enabled
Boolean
False
Enable using local storage for content related to Pages (as opposed to objectStore)
localStore.path
String
/srv/gitlab/shared/pages
Path where pages files will be stored; only used if localStore is set to true.
apiSecret.secret
String
Secret containing 32 bit API key in Base64 encoded form.
apiSecret.key
String
Key within the API key secret where the API key is stored.
Configure Webservice
The global Webservice settings (that are used by other charts also) are located
under the
global.webservice
key.
global: webservice: workerTimeout:60
workerTimeout
Configure the request timeout (in seconds) after which a Webservice worker process
is killed by the Webservice master process. The default value is 60 seconds.
Custom Certificate Authorities
These settings do not affect charts from outside of this repository, via
requirements.yaml
.
Some users may need to add custom certificate authorities, such as when using internally
issued SSL certificates for TLS services. To provide this functionality, we provide
a mechanism for injecting these custom root certificate authorities into the application through Secrets or ConfigMaps.
To create a Secret or ConfigMap:
# Create a Secret from a certificate file kubectl create secret generic secret-custom-ca --from-file=unique_name=/path/to/cert
# Create a ConfigMap from a certificate file kubectl create configmap cm-custom-ca --from-file=unique_name=/path/to/cert
To configure a Secret or ConfigMap, or both, specify them in globals:
global: certificates: customCAs: -secret:secret-custom-CAs# Mount all keys of a Secret -secret:secret-custom-CAs# Mount only the specified keys of a Secret keys: -unique_name -configMap:cm-custom-CAs# Mount all keys of a ConfigMap -configMap:cm-custom-CAs# Mount only the specified keys of a ConfigMap keys: -unique_name_1 -unique_name_2
You can provide any number of Secrets or ConfigMaps, each containing any number of keys that hold
PEM-encoded CA certificates. These are configured as entries under
global.certificates.customCAs
.
All keys are mounted unless
keys:
is provided with a list of specific keys to be mounted. All mounted keys across all Secrets and ConfigMaps must be unique.
The Secrets and ConfigMaps can be named in any fashion, but they
must not
contain key names that collide.
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.
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.
Service Accounts
GitLab Helm charts allow for the pods to run using custom Service Accounts.
This is configured with the following settings in
global.serviceAccount
:
global: serviceAccount: enabled:false create:true annotations:{} ## Name to be used for serviceAccount, otherwise defaults to chart fullname # name:
Setting
global.serviceAccount.enabled
to
true
will create a custom service account for each deployment.
Setting
global.serviceAccount.create
to
false
will disable automatic service account creation.
Setting
global.serviceAccount.name
will use that name in the deployment for either auto-generated or manually created service accounts.
Annotations
Custom annotations can be applied to Deployment, Service, and Ingress objects.
Custom
nodeSelector
s can be applied to all components globally. Any global defaults
can also be overridden on each subchart individually.
global: nodeSelector: disktype:ssd
Note
: charts that are maintained externally do not respect the
global.nodeSelector
at this time and may need to be configured separately based on available chart values.
This includes Prometheus, cert-manager, Redis, etc.
Labels
Common Labels
Labels can be applied to nearly all objects that are created by various objects
by using the configuration
common.labels
. This can be applied under the
global
key, or under a specific charts’ configuration. Example:
With the above example configuration, nearly all components deployed by the Helm
chart will be provided the label set
environment: production
. All components
of the GitLab Shell chart will receive the label set
foo: bar
. Some charts
allow for additional nesting. For example, the Sidekiq and Webservices charts
allow for additional deployments depending on your configuration needs:
In the above example, all components associated with the
pod-0
Sidekiq
deployment will also recieve the label set
baz: bat
. Refer to the Sidekiq and
Webservice charts for additional details.
Some charts that we depend on are excluded from this label configuration. Only
the GitLab component sub-charts will receive these
extra labels.
Pod
Custom labels can be applied to various Deployments and Jobs. These labels are
supplementary to existing or preconfigured labels constructed by this Helm
chart. These supplementary labels will
not
be utilized for
matchSelectors
.
global: pod: labels: environment:production
Service
Custom labels can be applied to services. These labels are
supplementary to existing or preconfigured labels constructed by this Helm
chart.
global: service: labels: environment:production
Tracing
GitLab Helm charts support tracing, and you can configure it with:
global.tracing.connection.string
is used to configure where tracing spans would be sent. You can read more about that in GitLab tracing documentation
global.tracing.urlTemplate
is used as a template for tracing info URL rendering in GitLab performance bar.
extraEnv
extraEnv
allows you to expose additional environment variables in all containers in the pods
that are deployed via GitLab charts (
charts/gitlab/charts
). Extra environment variables set at
the global level will be merged into those provided at the chart level, with precedence given
to those provided at the chart level.
extraEnvFrom
allows you to expose additional environment variables from other data sources in all containers in the pods. Extra environment variables can be set up at
global
level (
global.extraEnvFrom
), GitLab chart top level (
extraEnvFrom
) or sub-chart level (
<subchart_name>.extraEnvFrom
).
The implementation does not support re-using a value name with different content types. You can override the same name with similar content, but no not mix sources like
secretKeyRef
,
configMapKeyRef
, etc.
Configure OAuth settings
OAuth integration is configured out-of-the box for services which support it.
The services specified in
global.oauth
are automatically registered as OAuth
client applications in GitLab during deployment. By default this list includes
GitLab Pages, if access control is enabled.
Name of the secret with OAuth credentials for the service.
appIdKey
String
Key in the secret under which App ID of service is stored. Default value being set is
appid
.
appSecretKey
String
Key in the secret under which App Secret of service is stored. Default value being set is
appsecret
.
redirectUri
String
URI to which user should be redirected after successful authorization.
authScope
String
api
Scope used for authentication with GitLab API.
Check the secrets documentation for more details on the secret.
Kerberos
To configure the Kerberos integration in the GitLab Helm chart, you must provide a secret in the
global.appConfig.kerberos.keytab.secret
setting containing a Kerberos keytab with a service principal for your GitLab host. Your Kerberos administrators can help with creating a keytab file if you don’t have one.
You can create a secret using the following snippet (assuming that you are installing the chart in the
gitlab
namespace and
gitlab.keytab
is the keytab file containing the service principal):
Kerberos integration for Git is enabled by setting
global.appConfig.kerberos.enabled=true
. This will also add the
kerberos
provider to the list of enabled OmniAuth providers for ticket-based authentication in the browser.
If left as
false
the Helm chart will still mount the
keytab
in the toolbox, Sidekiq, and webservice Pods, which can be used with manually configured OmniAuth settings for Kerberos.
You can provide a Kerberos client configuration in
global.appConfig.kerberos.krb5Config
.
Check the Kerberos documentation for more details.
Dedicated port for Kerberos
GitLab supports the use of a dedicated port for Kerberos negotiation when using the HTTP protocol for Git operations to workaround a limitation in Git falling back to Basic Authentication when presented with the
negotiate
headers in the authentication exchange.
Use of the dedicated port is currently required when using GitLab CI/CD - as the GitLab Runner helper relies on in-URL credentials to clone from GitLab.
This can be enabled with the
global.appConfig.kerberos.dedicatedPort
settings:
This enables an additional clone URL in the GitLab UI that is dedicated for Kerberos negotiation. The
https: true
setting is for URL generation only, and doesn’t expose any additional TLS configuration. TLS is terminated and configured in the Ingress for GitLab.
Due to a current limitation with our fork of the
nginx-ingress
Helm chart - specifying a
dedicatedPort
will not currently expose the port for use in the chart’s
nginx-ingress
controller. Cluster operators will need to expose this port themselves. Follow this charts issue for more details and potential workarounds.
LDAP custom allowed realms
The
global.appConfig.kerberos.simpleLdapLinkingAllowedRealms
can be used to specify a set of domains used to link LDAP and Kerberos identities together when a user’s LDAP DN does not match the user’s Kerberos realm. See the Custom allowed realms section in the Kerberos integration documentation for additional details.
Outgoing email
Outgoing email configuration is available via
global.smtp.*
,
global.appConfig.microsoft_graph_mailer.*
and
global.email.*
.
More information on the available configuration options is available in the
outgoing email documentation.
More detailed examples can be found in the
Omnibus SMTP settings documentation.
Platform
The
platform
key is reserved for specific features targeting a specific
platform like GKE or EKS.
Affinity
Affinity configuration is available via
global.antiAffinity
and
global.affinity
.
Affinity allows you to constrain which nodes your pod is eligible to be scheduled on, based on node labels or labels of pods that are already running on a node. This allow spread pods across the cluster or select specific nodes, ensuring more resilience in case of a failing node.
soft
: Define a
preferredDuringSchedulingIgnoredDuringExecution
anti-affinity where the Kubernetes scheduler will try to enforce the rule but will not guarantee the result.
hard
: Defined a
requiredDuringSchedulingIgnoredDuringExecution
anti-affinity where the rule
must
be met for a pod to be scheduled onto a node.
global.affinity.podAntiAffinity.topologyKey
define a node attribute used two divide them into logical zone. Most common
topologyKey
values are :
kubernetes.io/hostname
topology.kubernetes.io/zone
topology.kubernetes.io/region
Kubernetes references on Inter-pod affinity and anti-affinity
Pod Priority and Preemption
Pod priorities can be configured either via
global.priorityClassName
or per sub-chart via
priorityClassName
.
Setting pod priority allows you to tell the scheduler to evict lower priority pods to make scheduling of pendings pods possible.
This chart is based on
stable/minio
version
0.4.3
,
and inherits most settings from there.
Design Choices
Design choices related to the upstream chart
can be found in the project’s README.
GitLab chose to alter that chart in order to simplify configuration of the secrets,
and to remove all use of secrets in environment variables. GitLab added
initContainer
s
to control the population of secrets into the
config.json
, and a chart-wide
enabled
flag.
This chart makes use of only one secret:
global.minio.credentials.secret
: A global secret containing the
accesskey
and
secretkey
values that will be used for authentication to the bucket(s).
Configuration
We will describe all the major sections of the configuration below. When configuring
from the parent chart, these values will be:
They 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, MinIO is enabled out of the box, but is not recommended for production use.
When you are ready to disable it, run
--set global.minio.enabled: false
.
Configure the initContainer
While rarely altered, the
initContainer
behaviors can be changed via the following items:
The initContainer image settings are just as with a normal image configuration.
By default, chart-local values are left empty, and the global settings
global.busybox.image.repository
and
global.busybox.image.tag
will be used to
populate initContainer image. If chart-local values are specified, they get
used instead of the global setting’s values.
initContainer script
The initContainer is passed the following items:
The secret containing authentication items mounted in
/config
, usually
accesskey
and
secretkey
.
The ConfigMap containing the
config.json
template, and
configure
containing a
script to be executed with
sh
, mounted in
/config
.
An
emptyDir
mounted at
/minio
that will be passed to the daemon’s container.
The initContainer is expected to populate
/minio/config.json
with a completed configuration,
using
/config/configure
script. When the
minio-config
container has completed
that task, the
/minio
directory will be passed to the
minio
container, and used
to provide the
config.json
to the MinIO server.
Configuring the Ingress
These settings control the MinIO Ingress.
Name
Type
Default
Description
apiVersion
String
Value to use in the
apiVersion
field.
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.
configureCertmanager
Boolean
Toggles Ingress annotation
cert-manager.io/issuer
. For more information see the TLS requirement for GitLab Pages.
tls.enabled
Boolean
true
When set to
false
, you disable TLS for MinIO. This is mainly useful when you cannot use TLS termination at Ingress-level, like when you have a TLS-terminating proxy before the Ingress Controller.
tls.secretName
String
The name of the Kubernetes TLS Secret that contains a valid certificate and key for the MinIO URL. When not set, the
global.ingress.tls.secretName
is used instead.
Configuring the image
The
image
,
imageTag
and
imagePullPolicy
defaults are
documented upstream.
Persistence
This chart provisions a
PersistentVolumeClaim
and mounts a corresponding persistent
volume to default location
/export
. You’ll need physical storage available in the
Kubernetes cluster for this to work. If you’d rather use
emptyDir
, disable
PersistentVolumeClaim
by:
persistence.enabled: false
.
The behaviors for
persistence
are documented upstream.
When
volumeName
is provided, the
PersistentVolumeClaim
will use the provided
PersistentVolume
by name, in place of creating a
PersistentVolume
dynamically. This overrides the upstream behavior.
matchLabels
Map
true
Accepts a Map of label names and label values to match against when choosing a volume to bind. This is used in the
PersistentVolumeClaim
selector
section. See the volumes documentation.
matchExpressions
Array
Accepts an array of label condition objects to match against when choosing a volume to bind. This is used in the
PersistentVolumeClaim
selector
section. See the volumes documentation.
defaultBuckets
defaultBuckets
provides a mechanism to automatically create buckets on the MinIO
pod at
installation
. This property contains an array of items, each with up to three
properties:
name
,
policy
, and
purge
.
The name of the bucket that is created. The provided value should conform to AWS bucket naming rules, meaning that it should be compliant with DNS and contain only the characters a-z, 0-9, and – (hyphen) in strings between 3 and 63 characters in length. The
name
property is
required
for all entries.
policy
none
The value of
policy
controls the access policy of the bucket on MinIO. The
policy
property is not required, and the default value is
none
. In regards to
anonymous
access, possible values are:
none
(no anonymous access),
download
(anonymous read-only access),
upload
(anonymous write-only access) or
public
(anonymous read/write access).
purge
Boolean
The
purge
property is provided as a means to cause any existing bucket to be removed with force, at installation time. This only comes into play when using a pre-existing
PersistentVolume
for the volumeName property of persistence. If you make use of a dynamically created
PersistentVolume
, this will have no valuable effect as it only happens at chart installation and there will be no data in the
PersistentVolume
that was just created. This property is not required, but you may specify this property with a value of
true
in order to cause a bucket to purged with force
mc rm -r --force
.
Security Context
These options allow control over which
user
and/or
group
is used to start the pod.
For in-depth information about security context, please refer to the official
Kubernetes documentation.
Service Type and Port
These are documented upstream,
and the key summary is:
## Expose the MinIO service to be accessed from outside the cluster (LoadBalancer service). ## or access it from within the cluster (ClusterIP service). Set the service type and the port to serve it. ## ref: http://kubernetes.io/docs/user-guide/services/ ## serviceType:LoadBalancer servicePort:9000
The chart does not expect to be of the
type: NodePort
, so
do not
set it as such.
Upstream items
The upstream documentation
for the following also applies completely to this chart:
resources
nodeSelector
minioConfig
Further explanation of the
minioConfig
settings can be found in the
MinIO notify documentation.
This includes details on publishing notifications when Bucket Objects are accessed or changed.
Our fork of the NGINX chart was pulled from GitHub.
Adjustments to the NGINX fork
The following adjustments were made to the NGINX fork:
tcp-configmap.yaml
: is optional depending on new
tcpExternalConfig
setting
Ability to use a templated TCP ConfigMap name from another chart
controller-configmap-tcp.yaml
:
.metadata.name
is a template
ingress-nginx.tcp-configmap
controller-deployment.yaml
:
.spec.template.spec.containers[0].args
uses
ingress-nginx.tcp-configmap
template for ConfigMap name
GitLab chart overrides
ingress-nginx.tcp-configmap
so that
gitlab/gitlab-org/charts/gitlab-shell
can configure its TCP service
Ability to use a templated Ingress name based on the release name
Replace
controller.service.loadBalancerIP
with
global.hosts.externalIP
Added support to add common labels through
common.labels
configuration option
controller-deployment.yaml
:
Add
podlabels
and
global.pod.labels
to
.spec.template.metadata.labels
default-backend-deployment.yaml
:
Add
podlabels
and
global.pod.labels
to
.spec.template.metadata.labels
Disable NGINX’s default nodeSelectors.
Added support for PDB
maxUnavailable
.
Remove NGINX’s
isControllerTagValid
helper in
charts/nginx-ingress/templates/_helpers.tpl
The check had not been updated since it was implemented in 2020.
As part of #3383, we need to refer to a tag that will contain
ubi
,
meaning that the
semverCompare
would not work as expected anyway.
Added support for autoscaling/v2beta2 and autoscaling/v2 APIs in HPAs and
extended HPA settings to support memory and custom metrics, as well as
behavior configuration.
Added conditional support for API version of PodDisruptionBudget.
Add the following booleans to enable/disable GitLab Shell (SSH access) independently for the external and internal (if enabled with
controller.service.internal.enabled
) services:
controller.service.enableShell
.
controller.service.internal.enableShell
.
(follows the exisiting chart pattern of
controller.service.enableHttp(s)
)