Relay (KAS) is the server that agents for Kubernetes installed in clusters connect to. While Relay is not set up, the “Connect a Kubernetes cluster” dialog on the “Kubernetes clusters” page of a project shows the message “Your instance doesn’t have the GitLab Relay (KAS) set up. Ask a Deckhouse Code Administrator to install it.” in place of the agent registration form.

Enabling Relay

On the Linux package and in Omnibus Docker, Relay is part of the package and runs by default. In the Helm Chart, Relay is not deployed until it is enabled in the values.

  • Linux package
  • Omnibus Docker
  • Helm Chart

Relay runs as the gitlab-kas service and needs no setting. To turn it off, set in /etc/gitlab/gitlab.rb:

gitlab_kas['enable'] = false

Apply the change:

sudo gitlab-ctl reconfigure

Relay runs as the gitlab-kas service inside the container and needs no setting. To turn it off, add gitlab_kas['enable'] = false to /srv/code/config/gitlab.rb on the host and apply the change:

docker exec code gitlab-ctl reconfigure

A key set in GITLAB_OMNIBUS_CONFIG takes effect only when the container is recreated with the same volumes. Both places are described on the Configuration page of the authentication section.

Enable Relay in values.yaml:

global:
  kas:
    enabled: true

Apply the values to the release:

helm upgrade code oci://<CHART_REGISTRY>/code \
  --version <CHART_VERSION> \
  -n code \
  -f values.yaml

Connection address

Agents connect to Relay over WebSocket at its external address.

  • Linux package
  • Omnibus Docker
  • Helm Chart

By default, Relay answers on the instance address under the /-/kubernetes-agent/ path. With external_url 'https://code.example.com', the address of Relay is wss://code.example.com/-/kubernetes-agent/; with an http instance address, the scheme is ws.

To serve Relay on a host of its own, set it in /etc/gitlab/gitlab.rb:

gitlab_kas_external_url 'wss://kas.example.com/'

The address takes the ws or wss scheme only. For a wss address, place the certificate and the key of the host in /etc/gitlab/ssl/kas.example.com.crt and /etc/gitlab/ssl/kas.example.com.key, and create a DNS record for kas.example.com that points at the server. When Let’s Encrypt is enabled and these files do not exist, the Relay host is added to the Let’s Encrypt certificate of the instance. Then run sudo gitlab-ctl reconfigure.

The address is set by the same keys as on the Linux package, written in /srv/code/config/gitlab.rb on the host. With the volumes from the quick start, the certificate and the key of a separate Relay host are placed in /srv/code/config/ssl/ on the host. The change takes effect after docker exec code gitlab-ctl reconfigure; a key set in GITLAB_OMNIBUS_CONFIG takes effect only when the container is recreated.

Relay answers on a host of its own, kas.<domain>, where <domain> is global.hosts.domain. Another name is set in global.hosts.kas.name. Create a DNS record for this host that points at the same address as the web interface.

In the certManager mode of global.codeHelm.ingress.tls.mode, the chart issues the certificate of the host into the Secret code-kas-tls. In the manual mode, the Relay host uses the Secret named in gitlab.kas.ingress.tls.secretName, or the Secret named in global.ingress.tls.secretName when the first value is empty; the certificate in that Secret covers the Relay host name. The values are described in Advanced configuration.

Checking Relay

On the “Admin” → “Instance overview” → “Dashboard” page, the “Components” block shows the “GitLab KAS” line with the Relay version. The line is absent while Relay is turned off. The value “Unknown” means that the instance has not received the version from Relay.

Check the state of Relay:

  • Linux package
  • Omnibus Docker
  • Helm Chart
sudo gitlab-ctl status gitlab-kas
sudo gitlab-ctl tail gitlab-kas

The service logs are in /var/log/gitlab/gitlab-kas/.

docker exec code gitlab-ctl status gitlab-kas
docker exec code gitlab-ctl tail gitlab-kas
d8 k -n code get pods -l app=kas

Instance-level agent authorization

The ci_access section of the agent configuration file .gitlab/agents/<AGENT_NAME>/config.yaml in the agent’s project, where <AGENT_NAME> is the name of the agent, names the projects and groups whose CI/CD jobs can use the agent; each list takes up to 500 entries. By default, the section can name projects and groups under the top-level group of the agent’s project; when the agent’s project is in a personal namespace, only the projects of that namespace. With instance-level authorization, the section can name projects and groups under any top-level group, and its instance key authorizes the agent for every project of the instance.

  1. Go to “Admin” → “Settings” → “General”.
  2. Expand the “GitLab Agent for Kubernetes” section.
  3. Select the “Enable instance level authorization” checkbox.
  4. Click “Save changes”.

Agents for Kubernetes

The agent for Kubernetes (agentk) runs in a cluster and connects it to Relay. The user who registers the agent or the Deckhouse Code administrator deploys it in the cluster; the installations of Deckhouse Code do not deploy agents.

After the agent is registered, the “Connect a Kubernetes cluster” dialog shows the helm upgrade --install command that installs the agent from the gitlab/gitlab-agent chart. Deckhouse Code provides the agent image registry.deckhouse.ru/deckhouse/ee/packages/code/images/agentk. To install the agent from it, add the --set image.repository line to the command from the dialog:

helm repo add gitlab https://charts.gitlab.io
helm repo update
helm upgrade --install <AGENT_NAME> gitlab/gitlab-agent \
    --namespace gitlab-agent-<AGENT_NAME> \
    --create-namespace \
    --set image.repository=registry.deckhouse.ru/deckhouse/ee/packages/code/images/agentk \
    --set image.tag=v<VERSION> \
    --set config.token=<TOKEN> \
    --set config.kasAddress=<RELAY_ADDRESS>

The values <AGENT_NAME>, <VERSION>, <TOKEN> and <RELAY_ADDRESS> come from the command in the dialog.

←
Administration / Advanced search
Administration / Backup and restore
→