Installing the agent for Kubernetes
Offering: GitLab.com, Self-managed, GitLab Dedicated
- 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. - Introduced ARM architecture support in GitLab 14.9.
To connect a Kubernetes cluster to GitLab, you must install an agent in your cluster.
Prerequisites
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.
Then it is available by default at
wss://gitlab.example.com/-/kubernetes-agent/
. On GitLab.com, the agent server is available atwss://kas.gitlab.com
.
Installation steps
To install the agent in your cluster:
- Create an agent configuration file.
- Register the agent with GitLab.
- Install the agent in your cluster.
Watch a GitLab 14.2 walk-through of this process.
Create an agent configuration file
- Introduced in GitLab 13.7, the agent configuration file can be added to multiple directories (or subdirectories) of the repository.
- Group authorization was introduced in GitLab 14.3.
For configuration settings, the agent uses a YAML file in the GitLab project. You must create this file if:
- You use a GitOps workflow.
- You use a GitLab CI/CD workflow and want to authorize a different project to use the agent.
- You allow specific project or group members to access Kubernetes.
To create an agent configuration file:
-
Choose a name for your agent. The agent name follows the DNS label standard from RFC 1123. The name must:
- Be unique in the project.
- Contain at most 63 characters.
- Contain only lowercase alphanumeric characters or
-
. - Start with an alphanumeric character.
- End with an alphanumeric character.
-
In the repository, in the default branch, create an agent configuration file at the root:
.gitlab/agents/<agent-name>/config.yaml
You can leave the file blank for now, and configure it later.
Register the agent with GitLab
- Introduced in GitLab 14.1, you can create a new agent record directly from the GitLab UI.
- Introduced in GitLab 14.9, the agent can be registered without creating an agent configuration file.
certificate_based_clusters
changed the Actions menu to focus on the agent rather than certificates. The flag is enabled on GitLab.com, GitLab Dedicated, and self-managed.Prerequisites:
- For a GitLab CI/CD workflow, ensure that GitLab CI/CD is not disabled.
You must register an agent before you can install the agent in your cluster. To register an agent:
- On the left sidebar, select Search or go to and find your project. If you have an agent configuration file, it must be in this project. Your cluster manifest files should also be in this project.
- Select Operate > Kubernetes clusters.
- Select Connect a cluster (agent).
- If you want to create a configuration with CI/CD defaults, type a name.
- 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. You need this token to install the agent in your cluster.
Securely store the agent access token. A bad actor can use this token to access source code in the agent’s configuration project, access source code in any public project on the GitLab instance, or even, under very specific conditions, obtain a Kubernetes manifest. - 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.
Install the agent in the cluster
- 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:
- Install the agent with Helm.
- Or, follow the advanced installation method.
If you do not know which one to choose, we recommend starting with Helm.
Install the agent with Helm
cluster-admin
rights. You should not use this on production systems. To deploy to a production system, follow the instructions in Customize the Helm installation to create a service account with the minimum permissions required for your deployment and specify that during installation.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 you registered your agent with GitLab. The command should look like:
helm repo add gitlab https://charts.gitlab.io helm repo update helm upgrade --install test gitlab/gitlab-agent \ --namespace gitlab-agent-test \ --create-namespace \ --set image.tag=<current agentk version> \ --set config.token=<your_token> \ --set config.kasAddress=<address_to_GitLab_KAS_instance>
- Optional. Customize the Helm installation. If you install the agent on a production system, you should customize the Helm installation to restrict the permissions of the service account. See How to deploy the GitLab Agent for Kubernetes with limited permissions.
Customize the Helm installation
By default, the Helm installation command generated by GitLab:
- Creates a namespace
gitlab-agent
for the deployment (--namespace gitlab-agent
). You can skip creating the namespace by omitting the--create-namespace
flag. - Sets up a service account for the agent and assigns it the
cluster-admin
role. You can:- Skip creating the service account by adding
--set serviceAccount.create=false
to thehelm install
command. In this case, you must setserviceAccount.name
to a pre-existing service account. - Customise the role assigned to the service account by adding
--set rbac.useExistingRole <your role name>
to thehelm install
command. In this case, you should have a pre-created role with restricted permissions that can be used by the service account. - Skip role assignment altogether by adding
--set rbac.create=false
to yourhelm install
command. In this case, you must createClusterRoleBinding
manually.
- Skip creating the service account by adding
- Creates a
Secret
resource 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
Deployment
resource for theagentk
pod.
To see the full list of customizations available, see the Helm chart’s README.
Use the agent when KAS is behind a self-signed certificate
When KAS is behind a self-signed certificate,
you can set the value of config.kasCaCert
to the certificate. For example:
helm upgrade --install gitlab-agent gitlab/gitlab-agent \
--set-file config.kasCaCert=my-custom-ca.pem
In this example, my-custom-ca.pem
is the path to a local file that contains
the CA certificate used by KAS. The certificate is automatically stored in a
config map and mounted in the agentk
pod.
If KAS is installed with the GitLab chart, and the chart is configured to provide
an auto-generated self-signed wildcard certificate, you can extract the CA certificate from the RELEASE-wildcard-tls-ca
secret.
Use the agent behind an HTTP proxy
- Introduced in GitLab 15.0, the GitLab agent Helm chart supports setting environment variables.
To configure an HTTP proxy when using the Helm chart, you can use the environment variables HTTP_PROXY
, HTTPS_PROXY
,
and NO_PROXY
. Upper and lowercase are both acceptable.
You can set these variables by using the extraEnv
value, as a list of objects with keys name
and value
.
For example, to set only the environment variable HTTPS_PROXY
to the value https://example.com/proxy
, you can run:
helm upgrade --install gitlab-agent gitlab/gitlab-agent \
--set extraEnv[0].name=HTTPS_PROXY \
--set extraEnv[0].value=https://example.com/proxy \
...
HTTP_PROXY
or the HTTPS_PROXY
environment variable is set,
and the domain DNS can’t be resolved.Advanced installation method
GitLab also provides a KPT package for the agent. This method provides greater flexibility, but is only recommended for advanced users.
Configure your agent
To configure your agent, add content to the config.yaml
file:
- For a GitOps workflow, view the configuration reference.
- For a GitLab CI/CD workflow, authorize the agent to access your projects. Then
add
kubectl
commands to your.gitlab-ci.yml
file.
Install multiple agents in your cluster
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, for example,
second-gitlab-agent
:helm upgrade --install second-gitlab-agent gitlab/gitlab-agent ...
-
Or, install the agent in a different namespace, for example,
different-namespace
:helm upgrade --install gitlab-agent gitlab/gitlab-agent \ --namespace different-namespace \ ...
Example projects
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
Updates and version compatibility
- 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 and next minor versions are 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 or v14.10.x version of the agent is also supported. See the release page of the GitLab agent.
Update the agent version
--reuse-values
, you should specify all needed values.
If you use --reuse-values
, you might miss new defaults or use deprecated values.
To retrieve previous --set
arguments, use helm get values <release name>
.
You can save the values to a file with helm get values gitlab-agent > agent.yaml
, and pass the file to Helm with -f
:
helm upgrade gitlab-agent gitlab/gitlab-agent -f agent.yaml
. This safely replaces the behavior of --reuse-values
.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 \
To set a specific version, you can override the image.tag
value. For example, to install version v14.9.1
, run:
helm upgrade gitlab-agent gitlab/gitlab-agent \
--namespace gitlab-agent \
--set image.tag=v14.9.1
The Helm chart is updated separately from the agent for Kubernetes, and might occasionally lag behind the latest version of the agent. If you run helm repo update
and don’t specify an image tag, your agent runs the version specified in the chart.
To use the latest release of the agent for Kubernetes, set the image tag to match the most recent agent image.
Uninstall the agent
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