Install the GitLab Agent (FREE)

Moved from GitLab Premium to GitLab Free in 14.5.

To get started with the Agent, install it in your cluster.

Prerequisites (SELF)

• An existing Kubernetes cluster.
• On self-managed GitLab instances, a GitLab administrator needs to set up the GitLab Agent Server (KAS).

Installation steps

To install the Agent in your cluster:

1. Define a configuration repository.
2. Register an agent with GitLab.
3. Install the agent into the cluster.

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

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 the configuration file.

After installed, when you update the configuration file, GitLab transmits the information to the cluster automatically without downtime.

In your repository, add the Agent configuration file under:

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

Make sure that <agent-name> conforms to the Agent's naming format.

WARNING: The agent is only recognized if you use .yaml extension for the config.yaml file. The extension .yml is not recognized.

You don't have to add any content to this file when you create it. The fact that the file exists tells GitLab that this is an agent configuration file and enables the CI/CD tunnel. Later on, you can use this file to configure the agent by setting up parameters such as:

• Groups and projects that can access the agent via the CI/CD Tunnel.
• Manifest projects to synchronize.
• The address of the hubble-relay for the Network Security policy integrations.

To see all the settings available, read the Agent configuration repository documentation.

Register an agent with GitLab

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

Next, create a GitLab Rails Agent record to associate it with the configuration repository project. Creating this record also creates a Secret needed to configure the Agent in subsequent steps.

In GitLab:

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, select the agent you want to connect and select Register an agent to access the installation form.
5. The form reveals your registration token. Securely store this secret token as you cannot view it again.
6. Copy the command under Recommended installation method.

Install the agent into the cluster

In your computer:

1. Open your local terminal and connect to your cluster.
2. Run the command you copied when registering your cluster in the previous step.

See the following sections to learn about customizing the installation.

Simple installation method

The command provided by GitLab does the following things:

• Creates a namespace for the deployment (gitlab-kubernetes-agent).
• Sets up a service account with cluster-admin rights. Read more on how you can restrict this service account.
• Creates a Secret resource for the agent registration token.
• Creates a Deployment resource for the agentk pod.

The one-liner installer can be customized at the command line. To find out the various options the above Docker container supports, run:

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 method

For more advanced configurations, we recommend to use the kpt based installation method.

Otherwise, follow the manual installation steps described below.

Customize the permissions for the agentk service account

The GitLab Agent for Kubernetes allows you to fully own your cluster and requires only the permissions you give. Still, for easy getting started, by default the generated manifests provide cluster-admin rights to the agent.

As part of the advanced installation method, you can restrict the agent 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.

Example projects

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

• Configuration repository
• This basic GitOps example deploys NGINX: Manifest repository

View installed Agents

Users with at least the Developer can access the user interface for the Agent at Infrastructure > Kubernetes clusters, under the Agent tab. This page lists all registered agents for the current project, and the configuration directory for each agent:

Additional management interfaces are planned for the GitLab Agent. Provide more feedback in the related epic.

View Agent activity information

Introduced in GitLab 14.6.

Users with at least the Developer can view the Agent's activity events. 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. Go to your agent's configuration repository.
2. From the sidebar, select Infrastructure > Kubernetes clusters.
3. Select the Agent tab.
4. Select the agent you want to see the activity.

You can see the following events on the activity list:

• Agent registration:
  • 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.

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.