Using the GitLab kas chart

The kas sub-chart provides a configurable deployment of the GitLab agent server (KAS). The agent server is a component you install together with GitLab. It is required to manage the GitLab agent for Kubernetes.

This chart depends on access to the GitLab API and the Gitaly Servers. When you enable this chart, an Ingress is deployed.

To consume minimal resources, the kas container uses a distroless image. The deployed services are exposed by an Ingress, which uses WebSocket proxying for communication. This proxy allows long-lived connections with the external component, agentk. agentk is the Kubernetes cluster-side agent counterpart.

The route to access the service depends on your Ingress configuration.

For more information, see the GitLab agent for Kubernetes architecture.

Disable the agent server

The GitLab agent server (kas) is enabled by default. To disable it on your GitLab instance, set the Helm property global.kas.enabled to false.

For example:

helm upgrade --install kas --set global.kas.enabled=false

Specify an Ingress

When you use the chart’s Ingress with the default configuration, the service for the agent server is reachable on a subdomain. For example, for global.hosts.domain: example.com, the agent server is reachable at kas.example.com.

The KAS Ingress can use a different domain than the global.hosts.domain.

Set global.hosts.kas.name, for example:

global.hosts.kas.name: kas.my-other-domain.com

This example uses kas.my-other-domain.com as the host for the KAS Ingress alone. The rest of the services (including GitLab, Registry, MinIO, etc.) use the domain specified in global.hosts.domain.

Installation command line options

You can pass these parameters to the helm install command by using the --set flags.

ParameterDefaultDescription
annotations{}Pod annotations.
common.labels{}Supplemental labels that are applied to all objects created by this chart.
containerSecurityContext.runAsUser65532Override container securityContext under which the container is started
extraContainers List of extra containers to include.
extraEnv List of extra environment variables to expose
extraEnvFrom List of extra environment variables from other data sources to expose
init.containerSecurityContext{}init container securityContext overrides
image.repositoryregistry.gitlab.com/gitlab-org/build/cng/gitlab-kasImage repository.
image.tagv13.7.0Image tag.
hpa.behavior{scaleDown: {stabilizationWindowSeconds: 300 }}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.targetTypeAverageValueSet the autoscaling CPU target type, must be either Utilization or AverageValue.
hpa.cpu.targetAverageValue100mSet 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
ingress.enabled true if global.kas.enabled=true You can use kas.ingress.enabled to explicitly turn it on or off. If not set, you can optionally use global.ingress.enabled for the same purpose.
ingress.apiVersion Value to use in the apiVersion field.
ingress.annotations{}Ingress annotations.
ingress.tls{}Ingress TLS configuration.
ingress.agentPath/Ingress path for the agent API endpoint.
ingress.k8sApiPath/k8s-proxyIngress path for Kubernetes API endpoint.
metrics.enabledtrueIf a metrics endpoint should be made available for scraping.
metrics.path/metricsMetrics endpoint path.
metrics.serviceMonitor.enabledfalseIf a ServiceMonitor should be created to enable Prometheus Operator to manage the metrics scraping. Enabling 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.
maxReplicas10HPA maxReplicas.
maxUnavailable1HPA maxUnavailable.
minReplicas2HPA maxReplicas.
nodeSelector Define a nodeSelector for the Pods of this Deployment, if present.
observability.port8151Observability endpoint port. Used for metrics and probe endpoints.
observability.livenessProbe.path/livenessURI for the liveness probe endpoint. This value has to match the observability.liveness_probe.url_path value from the KAS service configuration.
observability.readinessProbe.path/readinessURI for the readiness probe endpoint. This value has to match the observability.readiness_probe.url_path value from the KAS service configuration.
serviceAccount.annotations{}Service account annotations.
podLabels{}Supplemental Pod labels. Not used for selectors.
serviceLabels{}Supplemental service labels.
common.labels Supplemental labels that are applied to all objects created by this chart.
redis.enabledtrueAllows opting-out of using Redis for KAS features. Warnings: Redis will become a hard dependency soon, so this key is already deprecated.
resources.requests.cpu75mGitLab Exporter minimum CPU.
resources.requests.memory100MGitLab Exporter minimum memory.
service.externalPort8150External port (for agentk connections).
service.internalPort8150Internal port (for agentk connections).
service.apiInternalPort8153Internal port for the internal API (for GitLab backend).
service.loadBalancerIPnilA custom load balancer IP when service.type is LoadBalancer.
service.loadBalancerSourceRangesnilA list of custom load balancer source ranges when service.type is LoadBalancer.
service.kubernetesApiPort8154External port to expose proxied Kubernetes API on.
service.privateApiPort8155Internal port to expose kas’ private API on (for kas -> kas communication).
privateApi.secretAutogeneratedThe name of the secret to use for authenticating with the database.
privateApi.keyAutogeneratedThe name of the key in privateApi.secret to use.
privateApi.tls.enabledfalse DEPRECATED: use global.kas.tls.enabled. Enable kas pods to communicate with each other using TLS.
privateApi.tls.secretNamenil DEPRECATED: use global.kas.tls.secretName. Name of the Kubernetes TLS secret which contains the certificate and its associated key. Required if privateApi.tls is true.
global.kas.service.apiExternalPort8153External port for the internal API (for GitLab backend).
service.typeClusterIPService type.
tolerations[]Toleration labels for pod assignment.
customConfig{}When given, merges the default kas configuration with these values giving precedence to those defined here.
deployment.minReadySeconds0Minimum number of seconds that must pass before a kas pod is considered ready.
deployment.strategy{}Allows one to configure the update strategy utilized by the deployment.
deployment.terminationGracePeriodSeconds300How much time in seconds a Pod is allowed to spend shutting down after receiving SIGTERM.
priorityClassName  Priority class assigned to pods.

Enable TLS communication

Version history
  • The gitlab.kas.privateApi.tls.enabled and gitlab.kas.privateApi.tls.secretName attributes were deprecated in GitLab 15.8, and will be removed in GitLab 17.0. Enable TLS via the global KAS attribute instead.

Enable TLS communication between your kas pods and other GitLab chart components, through the global KAS attribute.

Enable TLS communication through the gitlab.kas.privateApi attributes (deprecated)

caution
The gitlab.kas.privateApi.tls.enabled and gitlab.kas.privateApi.tls.secretName attributes were deprecated in GitLab 15.8, and will be removed in GitLab 17.0. Enable TLS via the global KAS attribute instead.

Prerequisites:

  • Use GitLab 15.5.1 or later. You can set your GitLab version with global.gitlabVersion: <version>. If you need to force an image update after an initial deployment, also set global.image.pullPolicy: Always.
  1. Create the certificate authority and certificates that your kas pods will trust.
  2. Configure your chart to use the trusted certificates.
  3. Optional. Configure Redis for TLS.

To configure kas to use the certificates you created, set the following values.

ValueDescription
global.certificates.customCAsShares your CA with your GitLab components.
global.appConfig.gitlab_kas.internalUrlEnables grpcs communication between the GitLab Webservice and kas.
gitlab.kas.privateApi.tls.enabledMounts the certificates volume and enables TLS communication between kas pods.
gitlab.kas.privateApi.tls.secretNameSpecifies which Kubernetes TLS secret stores your certificates.
gitlab.kas.customConfigConfigures kas to expose its ports by using grpcs.
gitlab.kas.ingressConfigures kas Ingress to verify the proxied SSL certificate.

For example, you could use this values.yaml file to deploy your chart:

   .internal-ca: &internal-ca gitlab-internal-tls-ca # The secret name you used to share your TLS CA.
   .internal-tls: &internal-tls gitlab-internal-tls # The secret name you used to share your TLS certificate.

   global:
     certificates:
       customCAs:
       - secret: *internal-ca
     hosts:
       domain: gitlab.example.com # Your gitlab domain
     appConfig:
       gitlab_kas:
         internalUrl: "grpcs://RELEASE-kas.NAMESPACE.svc:8153" # Replace RELEASE and NAMESPACE with your chart's release and namespace

   gitlab:
     kas:
       privateApi:
         tls:
           enabled: true
           secretName: *internal-tls
       customConfig:
         api:
           listen:
             certificate_file: /etc/kas/tls.crt
             key_file: /etc/kas/tls.key
         agent:
           listen:
             certificate_file: /etc/kas/tls.crt
             key_file: /etc/kas/tls.key
           kubernetes_api:
             listen:
               certificate_file: /etc/kas/tls.crt
               key_file: /etc/kas/tls.key
       ingress:
         annotations:
           nginx.ingress.kubernetes.io/backend-protocol: https
           nginx.ingress.kubernetes.io/proxy-ssl-name: RELEASE-kas.NAMESPACE.svc # Replace RELEASE and NAMESPACE with your chart's release and namespace
           nginx.ingress.kubernetes.io/proxy-ssl-secret: NAMESPACE/CA-SECRET-NAME # Replace NAMESPACE and CA-SECRET-NAME with your chart's namespace and CA secret name. The same you used for &internal-ca.
           nginx.ingress.kubernetes.io/proxy-ssl-verify: on

Test the kas chart

To install the chart:

  1. Create your own Kubernetes cluster.
  2. Check out the merge request’s working branch.
  3. Install (or upgrade) GitLab with kas enabled by default from your local chart branch:

    helm upgrade --force --install gitlab . \
      --timeout 600s \
      --set global.hosts.domain=your.domain.com \
      --set global.hosts.externalIP=XYZ.XYZ.XYZ.XYZ \
      --set certmanager-issuer.email=your@email.com
    
  4. Use the GDK to run the process to configure and use the GitLab agent for Kubernetes: (You can also follow the steps to configure and use the agent manually.)

    1. From your GDK GitLab repository, move into the QA folder: cd qa.
    2. Run the following command to run the QA test:

      GITLAB_USERNAME=$ROOT_USER
      GITLAB_PASSWORD=$ROOT_PASSWORD
      GITLAB_ADMIN_USERNAME=$ROOT_USER
      GITLAB_ADMIN_PASSWORD=$ROOT_PASSWORD
      bundle exec bin/qa Test::Instance::All https://your.gitlab.domain/ -- --tag orchestrated --tag quarantine qa/specs/features/ee/api/7_configure/kubernetes/kubernetes_agent_spec.rb
      

      You can also customize the agentk version to install with an environment variable: GITLAB_AGENTK_VERSION=v13.7.1