- Installation steps
- Install multiple agents in your cluster
- Example projects
- Updates and version compatibility
- Uninstall the agent
To connect a Kubernetes cluster to GitLab, you must install an agent in your cluster.
Before you can install the agent in your cluster, you need:
- An existing Kubernetes cluster. If you don’t have a cluster, you can create one on a cloud provider, like:
- On self-managed GitLab instances, a GitLab administrator must set up the agent server.
On GitLab.com, the agent server is available at
To install the agent in your cluster:
Watch a GitLab 14.2 walk-through of this process.
You must register an agent with GitLab.
To register an agent with GitLab:
- On the top bar, select Menu > Projects and find your project.
- From the left sidebar, select Infrastructure > Kubernetes clusters.
- Select Connect a cluster (agent).
- If you want to create a configuration with CI/CD defaults, type a name for the agent.
- If you already have an agent configuration file, select it from the list.
- Select Register an agent.
- GitLab generates an access token for the agent. Securely store this token. You need it to install the agent in your cluster and to update the agent to another version.
- Copy the command under Recommended installation method. You need it when you use the one-liner installation method to install the agent in your cluster.
The agent is configured through a configuration file. This file is optional. Without a configuration file, you can still use the CI/CD workflow in the project where the agent is registered.
You need a configuration file if:
- You want to use a GitOps workflow.
- You want to authorize a different project to use the agent for a GitLab CI/CD workflow.
To create an agent configuration file, go to the GitLab project. In the repository, create a file called
config.yaml at this path:
- Ensure the agent name follows the naming convention.
- Ensure the filename has the
.yamlfile extension (
.ymlextension is not accepted.
- Add content to the
- For a GitOps workflow, view the configuration reference for details.
- For a GitLab CI/CD workflow, you can leave the file blank for now.
Introduced in GitLab 14.10, GitLab recommends using Helm to install the agent.
To connect your cluster to GitLab, install the registered agent in your cluster. You can either:
If you do not know which one to choose, we recommend starting with Helm.
To install the agent on your cluster using Helm:
- Install Helm
- In your computer, open a terminal and connect to your cluster.
- Run the command you copied when registering your agent with GitLab.
Optionally, you can customize the Helm installation.
By default, the Helm installation command generated by GitLab:
- Creates a namespace
gitlab-agentfor the deployment (
--namespace gitlab-agent). You can skip creating the namespace by omitting the
- Sets up a service account for the agent with
cluster-adminrights. You can:
- Skip creating the service account by adding
--set serviceAccount.create=falseto the
helm installcommand. In this case, you must set
serviceAccount.nameto a pre-existing service account.
- Skip creating the RBAC permissions by adding
--set rbac.create=falseto the
helm installcommand. In this case, you must bring your own RBAC permissions for the agent. Otherwise, it has no permissions at all.
- Skip creating the service account by adding
- Creates a
Secretresource for the agent’s access token. To instead bring your own secret with a token, omit the token (
--set token=...) and instead use
--set config.secretName=<your secret name>.
- Creates a
Deploymentresource for the
To see the full list of customizations available, see the Helm chart’s default values file.
GitLab also provides a KPT package for the agent. This method provides greater flexibility, but is only recommended for advanced users.
To install a second agent in your cluster, you can follow the previous steps a second time. To avoid resource name collisions within the cluster, you must either:
Use a different release name for the agent, e.g.
helm upgrade --install second-gitlab-agent gitlab/gitlab-agent ...
Or, install the agent in a different namespace, e.g.
helm upgrade --install gitlab-agent gitlab/gitlab-agent \ --namespace different-namespace \ ...
The following example projects can help you get started with the agent.
- Configuration repository with minimal manifests
- Distinct application and manifest repository example
- Auto DevOps setup that uses the CI/CD workflow
- Cluster management project template example that uses the CI/CD workflow
Introduced in GitLab 14.8, GitLab warns you on the agent’s list page to update the agent version installed on your cluster.
For the best experience, the version of the agent installed in your cluster should match the GitLab major and minor version. The previous minor version is also supported. For example, if your GitLab version is v14.9.4 (major version 14, minor version 9), then versions v14.9.0 and v14.9.1 of the agent are ideal, but any v14.8.x version of the agent is also supported. See this page of releases of the GitLab agent.
To update the agent to the latest version, you can run:
helm repo update helm upgrade --install gitlab-agent gitlab/gitlab-agent \ --namespace gitlab-agent \ --reuse-values
To set a specific version, you can override the
image.tag value. For example, to install version
helm upgrade gitlab-agent gitlab/gitlab-agent \ --namespace gitlab-agent \ --reuse-values \ --set image.tag=v14.9.1
If you installed the agent with Helm, then you can also uninstall with Helm. For example, if the release and namespace are both called
gitlab-agent, then you can uninstall the agent using the following command:
helm uninstall gitlab-agent \ --namespace gitlab-agent