Skip to content

GitLab

Install the GitLab Agent (FREE)

  • Moved from GitLab Premium to GitLab Free in 14.5.
  • Introduced multi-arch images in GitLab 14.8. The first multi-arch release is v14.8.1. It supports AMD64 and ARM64 architectures.

To connect a cluster to GitLab, you need to install the GitLab Agent onto your cluster.

Prerequisites

Installation steps

To install the GitLab Agent on your cluster:

  1. Define a configuration repository.
  2. Register the Agent with GitLab.
  3. Install the Agent onto the cluster.

Watch a GitLab 14.2 walking-through video with this process.

When you complete the installation process, you can view your Agent's status and activity information. You can also configure it to your needs.

Define a configuration repository

  • Introduced in GitLab 13.7, the Agent manifest configuration can be added to multiple directories (or subdirectories) of its repository.
  • Group authorization was introduced in GitLab 14.3.

To create an Agent, you need a GitLab repository to hold its configuration file. If you already have a repository holding your cluster's manifest files, you can use it to store your Agent's configuration file and sync them with no further steps.

Create the Agent's configuration file

To create an Agent, go to the repository where you want to store it and add the Agent's configuration file under:

.gitlab/agents/<agent-name>/config.yaml

You don't have to add any content to this file at the moment you create it. The fact that the file exists tells GitLab that this is an Agent. You can edit it later to configure the Agent.

When creating this file, pay special attention to:

  • The Agent's naming format.
  • The file extension: use the .yaml extension (config.yaml). The .yml extension is not recognized.

Register the Agent with GitLab

Introduced in GitLab 14.1, you can create a new Agent record directly from the GitLab UI.

Now that you've created your Agent's configuration file, register it with GitLab. When you register the Agent, GitLab generates a token that you need for installing the Agent onto your cluster.

In GitLab, go to the project where you added your Agent's configuration file and:

  1. Ensure that GitLab CI/CD is enabled in your project.
  2. From your project's sidebar, select Infrastructure > Kubernetes clusters.
  3. Select Actions.
  4. From the Select an Agent dropdown list, select the Agent you want to register and select Register an Agent.
  5. GitLab generates a registration token for this Agent. Securely store this secret token, as you need it to install the Agent onto your cluster and to update the Agent to another version.
  6. Copy the command under Recommended installation method. You need it to install the Agent onto your cluster through the one-liner installation method.

Install the Agent onto the cluster

To connect your cluster to GitLab, install the registered Agent onto your cluster. To install it, you can use either:

You can use the one-liner installation for trying to use the Agent for the first time, to do internal setups with high trust, and to quickly get started. For long-term production usage, you may want to use the advanced installation method to benefit from more configuration options.

One-liner installation

The one-liner installation is the simplest process, but you need Docker installed locally. If you don't have it, you can either install it or opt to the advanced installation method.

To install the Agent on your cluster using the one-liner installation:

  1. In your computer, open the terminal and connect to your cluster.
  2. Run the command you copied when registering your cluster in the previous step.

Optionally, you can customize the one-liner installation command.

Customize the one-liner installation

The one-liner command generated by GitLab:

  • Creates a namespace for the deployment (gitlab-kubernetes-agent).
  • Sets up a service account with cluster-admin rights (see how to restrict this service account).
  • Creates a Secret resource for the Agent's registration token.
  • Creates a Deployment resource for the agentk pod.

You can edit these parameters according to your needs to customize the one-liner installation command at the command line. To find all available options, run in your terminal:

docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --help

WARNING: --agent-version stable can be used to refer to the latest stable release at the time when the command runs. It's fine for testing purposes but for production please make sure to specify a matching version explicitly.

Advanced installation

For advanced installation options, use the kpt installation method.

Customize the permissions for the agentk service account

The GitLab Agent allows you to fully own your cluster and grant GitLab the permissions you want. Still, to facilitate the process, by default the generated manifests provide cluster-admin rights to the Agent.

You can restrict the Agent's access rights using Kustomize overlays. An example is commented out in the kpt package you retrieved as part of the installation.

To create restricted permissions:

  1. Copy the cluster directory.
  2. Edit the kustomization.yaml and components/* files based on your requirements.
  3. Run kustomize build <your copied directory> | kubectl apply -f - to apply your configuration.

The above setup allows you to regularly update from the upstream package using kpt pkg update gitlab-agent --strategy resource-merge and maintain your customizations at the same time.

Configure the Agent

When successfully installed, you can configure the Agent by editing its configuration file. When you update the configuration file, GitLab transmits the information to the cluster automatically without downtime.

View your Agents

The version of installed agentk shown on the Agent tab introduced in GitLab 14.8. If you have at least the Developer role, you can access the Agent's configuration repository and view the Agent's list:

  1. On the left sidebar, select Infrastructure > Kubernetes clusters.
  2. Select Agent tab to view clusters connected to GitLab through the Agent.

On this page, you can view:

  • All the registered Agents for the current project.
  • The connection status.
  • The version of agentk installed on your cluster.
  • The path to each Agent's configuration file.

Furthermore, if you select one of the Agents on your list, you can view its activity information.

View the Agent's activity information

Introduced in GitLab 14.6.

The activity logs help you to identify problems and get the information you need for troubleshooting. You can see events from a week before the current date. To access an Agent's activity:

  1. In your Agent's repository, go to the Agents list as described above.
  2. Select the Agent you want to see the activity.

The activity list includes:

  • Agent registration events: when a new token is created.
  • Connection events: when an Agent is successfully connected to a cluster.

Note that the connection status is logged when you connect an Agent for the first time or after more than an hour of inactivity.

To check what else is planned for the Agent's UI and provide feedback, see the related epic.

View vulnerabilities in cluster images (ULTIMATE)

Introduced in GitLab 14.8 with a flag named cluster_vulnerabilities. Enabled by default.

Users with at least the Developer role can view cluster vulnerabilities. You can access them through the vulnerability report or in your cluster's image through the following process:

  1. Configure cluster image scanning to your build process.
  2. Go to your Agent's configuration repository.
  3. On the left sidebar, select Infrastructure > Kubernetes clusters.
  4. Select the Agent tab.
  5. Select the Agent you want to see the vulnerabilities for.

Cluster Agent security tab UI

Create multiple Agents

You can create and install multiple Agents using the same process documented above. Give each Agent's configuration file a unique name and you're good to go. You can create multiple Agents, for example:

  • To reach your cluster from different projects.
  • To connect multiple clusters to GitLab.

Update the Agent version

Introduced in GitLab 14.8, GitLab warns you on the Agent's list page to update the Agent version installed on your cluster.

To update the Agent's version on your cluster, you need to re-run the installation command with a newer --agent-version. Make sure to specify the other required parameters: --kas-address, --namespace, and --agent-token. You can find the available agentk versions in the container registry.

If you don't have access to your Agent's token, you can retrieve it from your cluster:

  1. On your computer, open the terminal and connect to your cluster.

  2. To retrieve the namespace, run:

    kubectl get namespaces

  3. To retrieve the secret, run:

    kubectl -n <namespace> get secrets

  4. To retrieve the token, run:

    kubectl -n <namespace> get secret <secret-name> --template={{.data.token}} | base64 --decode

Example projects

The following example projects can help you get started with the Agent.

Upgrades and version compatibility

The Agent is comprised of two major components: agentk and kas. As we provide kas installers built into the various GitLab installation methods, the required kas version corresponds to the GitLab major.minor (X.Y) versions.

At the same time, agentk and kas can differ by 1 minor version in either direction. For example, agentk 14.4 supports kas 14.3, 14.4, and 14.5 (regardless of the patch).

A feature introduced in a given GitLab minor version might work with other agentk or kas versions. To make sure that it works, use at least the same agentk and kas minor version. For example, if your GitLab version is 14.2, use at least agentk 14.2 and kas 14.2.

We recommend upgrading your kas installations together with GitLab instances' upgrades, and to upgrade the agentk installations after upgrading GitLab.

The available agentk and kas versions can be found in the container registry.