Using the GitLab Shell chart

The gitlab-shell sub-chart provides an SSH server configured for Git SSH access to GitLab.


This chart depends on access to the Workhorse services, either as part of the complete GitLab chart or provided as an external service reachable from the Kubernetes cluster this chart is deployed onto.

Design Choices

In order to easily support SSH replicas, and avoid using shared storage for the SSH authorized keys, we are using the SSH AuthorizedKeysCommand to authenticate against the GitLab authorized keys endpoint. As a result, we don’t persist or update the AuthorizedKeys file within these pods.


The gitlab-shell chart is configured in two parts: external services, and chart settings. The port exposed through Ingress is configured with, and defaults to 22. The Service’s external port is also controlled by

Installation command line options

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.
config.clientAliveInterval 0 Interval between keepalive pings on otherwise idle connections; the default value of 0 disables this ping
config.loginGraceTime 60 Specifies amount of time that the server will disconnect after if the user has not successfully logged in
config.maxStartups.full 100 SSHd refuse probability will increase linearly and all unauthenticated connection attempts would be refused when unauthenticated connections number will reach specified number
config.maxStartups.rate 30 SSHd will refuse connections with specified probability when there would be too many unauthenticated connections (optional)
config.maxStartups.start 10 SSHd will refuse connection attempts with some probability if there are currently more than the specified number of unauthenticated connections (optional)
config.proxyProtocol false Enable PROXY protocol support for the gitlab-sshd daemon
config.proxyPolicy "use" Specify policy for handling PROXY protocol. Value must be one of use, require, ignore, reject
config.proxyHeaderTimeout "500ms" The maximum duration gitlab-sshd will wait before giving up on reading the PROXY protocol header. Must include units: ms, s, or m.
config.ciphers [,,, aes128-ctr, aes192-ctr, aes256-ctr] Specify the ciphers allowed.
config.kexAlgorithms [curve25519-sha256,, ecdh-sha2-nistp256, ecdh-sha2-nistp384, ecdh-sha2-nistp521, diffie-hellman-group14-sha256, diffie-hellman-group14-sha1] Specifies the available KEX (Key Exchange) algorithms.
config.macs [,, hmac-sha2-256, hmac-sha2-512, hmac-sha1] Specifies the available MAC (message authentication code algorithms.
deployment.livenessProbe.initialDelaySeconds 10 Delay before liveness probe is initiated
deployment.livenessProbe.periodSeconds 10 How often to perform the liveness probe
deployment.livenessProbe.timeoutSeconds 3 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 10 Delay before readiness probe is initiated
deployment.readinessProbe.periodSeconds 5 How often to perform the readiness probe
deployment.readinessProbe.timeoutSeconds 3 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 2 Minimum consecutive failures for the readiness probe to be considered failed after having succeeded
deployment.strategy {} Allows one to configure the update strategy utilized by the deployment
deployment.terminationGracePeriodSeconds 30 Seconds that Kubernetes will wait for a pod to forcibly exit
enabled true Shell enable flag
extraContainers   List of extra containers to include
extraInitContainers   List of extra init containers to include
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
hpa.behaviour {scaleDown: {stabilizationWindowSeconds: 300 }} Behavior contains the specifications for up- and downscaling behavior (requires autoscaling/v2beta2 or higher)
hpa.targetAverageValue 100m Set the autoscaling target value
image.pullPolicy IfNotPresent Shell image pull policy
image.pullSecrets   Secrets for the image repository
image.repository Shell image repository
image.tag master Shell image tag
init.image.repository   initContainer image
init.image.tag   initContainer image tag
logging.format text Set to json for JSON-structured logs
logging.sshdLogLevel ERROR Log level for underlying SSH daemon
replicaCount 1 Shell replicas
serviceLabels {} Supplemental service labels
service.externalTrafficPolicy Cluster Shell service external traffic policy (Cluster or Local)
service.internalPort 2222 Shell internal port
service.nodePort   Sets shell nodePort if set gitlab-shell Shell service name
service.type ClusterIP Shell service type
service.loadBalancerIP   IP address to assign to LoadBalancer (if supported)
service.loadBalancerSourceRanges   List of IP CIDRs allowed access to LoadBalancer (if supported)
securityContext.fsGroup 1000 Group ID under which the pod should be started
securityContext.runAsUser 1000 User ID under which the pod should be started
sshDaemon openssh Selects which SSH daemon would be run, possible values (openssh, gitlab-sshd)
tolerations [] Toleration labels for pod assignment
workhorse.serviceName webservice Workhorse service name (by default, Workhorse is a part of the webservice Pods / Service)
metrics.enabled false If a metrics endpoint should be made available for scraping
metrics.port 9122 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 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.

Chart configuration examples


extraEnv allows you to expose additional environment variables in all containers in the pods.

Below is an example use of extraEnv:

  SOME_KEY: some_value
  SOME_OTHER_KEY: some_other_value

When the container is started, you can confirm that the environment variables are exposed:

env | grep SOME


extraEnvFrom allows you to expose additional environment variables from other data sources in all containers in the pods.

Below is an example use of extraEnvFrom:

      fieldPath: spec.nodeName
      containerName: test-container
      resource: requests.cpu
      name: special-secret
      key: special_token
      # optional: boolean
      name: useful-config
      key: some-string
      # optional: boolean


pullSecrets allows you to authenticate to a private registry to pull images for a pod.

Additional details about private registries and their authentication methods can be found in the Kubernetes documentation.

Below is an example use of pullSecrets:

  tag: latest
  pullPolicy: Always
  - name: my-secret-name
  - name: my-secondary-secret-name


deployment.livenessProbe and deployment.readinessProbe provide a mechanism to help control the termination of Pods under some scenarios.

Larger repositories benefit from tuning liveness and readiness probe times to match their typical long-running connections. Set readiness probe duration shorter than liveness probe duration to minimize potential interruptions during clone and push operations. Increase terminationGracePeriodSeconds and give these operations more time before the scheduler terminates the pod. Consider the example below as a starting point to tune GitLab Shell pods for increased stability and efficiency with larger repository workloads.