• 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
  • Extra Ingress
• 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
• Configuring KEDA

Using the GitLab Webservice chart

The webservice sub-chart provides the GitLab Rails webserver with two Webservice workers per pod, which is 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 receive 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.

Chart configuration examples

extraEnv

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

Below is an example use of extraEnv:

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
SOME_KEY=some_value
SOME_OTHER_KEY=some_other_value

extraEnvFrom

extraEnvFrom allows you to expose additional environment variables from other data sources in all containers in the pods. Subsequent variables can be overridden per deployment.

Below is an example use of extraEnvFrom:

extraEnvFrom:
  MY_NODE_NAME:
    fieldRef:
      fieldPath: spec.nodeName
  MY_CPU_REQUEST:
    resourceFieldRef:
      containerName: test-container
      resource: requests.cpu
  SECRET_THING:
    secretKeyRef:
      name: special-secret
      key: special_token
      # optional: boolean
deployments:
  default:
    extraEnvFrom:
      CONFIG_STRING:
        configMapKeyRef:
          name: useful-config
          key: some-string
          # optional: boolean

image.pullSecrets

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:

image:
  repository: my.webservice.repository
  pullPolicy: Always
  pullSecrets:
  - name: my-secret-name
  - name: my-secondary-secret-name

tolerations

tolerations allow you schedule pods on tainted worker nodes

Below is an example use of tolerations:

tolerations:
- key: "node_label"
  operator: "Equal"
  value: "true"
  effect: "NoSchedule"
- key: "node_label"
  operator: "Equal"
  value: "true"
  effect: "NoExecute"

annotations

annotations allows you to add annotations to the Webservice pods. For example:

annotations:
  kubernetes.io/example-annotation: annotation-value

strategy

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%:

deployment:
  strategy:
    rollingUpdate:
      maxSurge: 0
      maxUnavailable: 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.

global:
  workhorse:
    tls:
      enabled: true
  certificates:
    customCAs:
      - secret: gitlab-workhorse-ca
gitlab:
  webservice:
    workhorse:
      tls:
        verify: true
        # secretName: gitlab-workhorse-tls
        caSecretName: gitlab-workhorse-ca
      monitoring:
        exporter:
          enabled: true
          tls:
            enabled: true

TLS on the metrics endpoints of the gitlab-workhorse container is inherited from global.workhorse.tls.enabled. 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.

TLS certificates used for metrics endpoints may require additional considerations for the included subject alternative names (SANs), particularly if using the included Prometheus Helm chart. For more information, see Configure Prometheus to scrape TLS-enabled endpoints.

webservice

The primary use case for enabling TLS is to provide encryption via HTTPS for scraping Prometheus metrics.

For Prometheus to scrape the /metrics/ endpoint using HTTPS, additional configuration is required for the certificate’s CommonName attribute or a SubjectAlternativeName entry. See Configuring Prometheus to scrape TLS-enabled endpoints for those requirements.

TLS can be enabled on the webservice container by the settings gitlab.webservice.tls.enabled:

gitlab:
  webservice:
    tls:
      enabled: true
      # secretName: gitlab-webservice-tls

secretName must point to a Kubernetes TLS secret. For example, to create a TLS secret with a local certificate and key:

kubectl create secret tls <secret name> --cert=path/to/puma.crt --key=path/to/puma.key

Using the Community Edition of this chart

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.

deployments:
  default:
    ingress:
      path: # Does not inherit or default. Leave blank to disable Ingress.
      pathType: Prefix
      provider: nginx
      annotations:
        # inherits `ingress.anntoations`
      proxyConnectTimeout: # inherits `ingress.proxyConnectTimeout`
      proxyReadTimeout:    # inherits `ingress.proxyReadTimeout`
      proxyBodySize:       # inherits `ingress.proxyBodySize`
    deployment:
      annotations: # map
      labels: # map
      # inherits `deployment`
    pod:
      labels: # additional labels to .podLabels
      annotations: # map
        # inherit from .Values.annotations
    service:
      labels: # additional labels to .serviceLabels
      annotations: # additional annotations to .service.annotations
        # inherits `service.annotations`
    hpa:
      minReplicas: # defaults to .minReplicas
      maxReplicas: # defaults to .maxReplicas
      metrics: # optional replacement of HPA metrics definition
      # inherits `hpa`
    pdb:
      maxUnavailable: # inherits `maxUnavailable`
    resources: # `resources` for `webservice` container
      # inherits `resources`
    workhorse: # map
      # inherits `workhorse`
    extraEnv: #
      # inherits `extraEnv`
    extraEnvFrom: #
      # inherits `extraEnvFrom`
    puma: # map
      # inherits `puma`
    workerProcesses: # inherits `workerProcesses`
    shutdown:
      # inherits `shutdown`
    nodeSelector: # map
      # inherits `nodeSelector`
    tolerations: # array
      # inherits `tolerations`

Deployments Ingress

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.

webservice:
  deployments:
    default:
      ingress:
        path: /
   api:
     ingress:
       path: /api

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.

webservice:
  deployments:
    default:
      ingress:
        path: /
   api:
     ingress:
       path: /api
   internal-api:
     ingress:
       path:

Ingress settings

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.

To override this, set:

gitlab:
  webservice:
    ingress:
      annotations:
        nginx.ingress.kubernetes.io/service-upstream: "false"

proxyBodySize

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 a Linux package installation. As an alternative option, you can set the body size with either of the following two parameters too:

• gitlab.webservice.ingress.annotations."nginx\.ingress\.kubernetes\.io/proxy-body-size"
• global.ingress.annotations."nginx\.ingress\.kubernetes\.io/proxy-body-size"

Extra Ingress

An extra Ingress can be deployed by setting extraIngress.enabled=true. The Ingress is named as the default Ingress with the -extra suffix and supports the same settings as the default Ingress.

Resources

Memory requests/limits

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.

Default:

workerProcesses: 2
resources:
  requests:
    memory: 2.5G # = 2 * 1.25G
# limits:
#   memory: 4G   # = (2 * 1.5G) + 950M

With 4 workers configured:

workerProcesses: 4
resources:
  requests:
    memory: 5G   # = 4 * 1.25G
# limits:
#   memory: 7G   # = (4 * 1.5G) + 950M

External Services

Redis

The Redis documentation has been consolidated in the globals page. Please consult this page for the latest Redis configuration options.

PostgreSQL

The PostgreSQL documentation has been consolidated in the globals page. Please consult this page for the latest PostgreSQL configuration options.

Gitaly

Gitaly is configured by global settings. Please see the Gitaly configuration documentation.

MinIO

minio:
  serviceName: 'minio-svc'
  port: 9000

Registry

registry:
  host: registry.example.com
  port: 443
  api:
    protocol: http
    host: registry.example.com
    serviceName: registry
    port: 5000
  tokenIssuer: gitlab-issuer
  certificate:
    secret: gitlab-registry
    key: registry-auth.key

Chart settings

The following values are used to configure the Webservice Pods.

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.

shell:
  authToken:
    secret: gitlab-shell-secret
    key: secret
  port:

WebServer options

Current version of chart supports Puma web server.

Puma unique options:

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.

Example Network Policy

The webservice service requires Ingress connections for only the Prometheus exporter if enabled and traffic coming from the NGINX Ingress, and typically 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 Ingress requests to port 8181 are allowed for general service operation
• 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 the Webservice requires outbound connectivity to the public internet for images on external object storage

networkpolicy:
  enabled: true
  ingress:
    enabled: true
    rules:
      - from:
        - ipBlock:
            cidr: 10.0.0.0/8
        ports:
        - port: 8080
      - from:
        ports:
        - port: 8181
  egress:
    enabled: true
    rules:
      - to:
        - ipBlock:
            cidr: 10.0.0.0/8
        ports:
        - port: 53
          protocol: UDP
      - to:
        - ipBlock:
            cidr: 10.0.0.0/8
        ports:
        - port: 5432
          protocol: TCP
      - to:
        - ipBlock:
            cidr: 10.0.0.0/8
        ports:
        - port: 6379
          protocol: TCP
      - to:
        - ipBlock:
            cidr: 10.0.0.0/8
        ports:
        - port: 8075
          protocol: TCP
      - to:
        - ipBlock:
            cidr: 0.0.0.0/0
            except:
            - 10.0.0.0/8

LoadBalancer Service

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

service:
  type: LoadBalancer
  loadBalancerIP: 1.2.3.4
  loadBalancerSourceRanges:
  - 10.0.0.0/8

Configuring KEDA

This keda section enables the installation of KEDA ScaledObjects instead of regular HorizontalPodAutoscalers. This configuration is optional and can be used when there is a need for autoscaling based on custom or external metrics.

Most settings default to the values set in the hpa section where applicable.

If the following are true, CPU and memory triggers are added automatically based on the CPU and memory thresholds set in the hpa section:

• triggers is not set.
• The corresponding request.cpu.request or request.memory.request setting is also set to a non-zero value.

If no triggers are set, the ScaledObject is not created.

Refer to the KEDA documentation for more details about those settings.