debian-mirror-gitlab/doc/user/clusters/agent/install/index.md

stage	group	info
Configure	Configure	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments

Installing the agent for Kubernetes (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.
• 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:
  • Google Kubernetes Engine (GKE)
  • Amazon Elastic Kubernetes Service (EKS)
  • Digital Ocean
• On self-managed GitLab instances, a GitLab administrator must set up the agent server. On GitLab.com, the agent server is available at wss://kas.gitlab.com.

Installation steps

To install the agent in your cluster:

1. Register the agent with GitLab.
2. Install the agent in your cluster.

Watch a GitLab 14.2 walk-through of this process.

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.

You must register an agent with GitLab.

Prerequisites:

• For a GitLab CI/CD workflow, ensure that GitLab CI/CD is enabled.

To register an agent with GitLab:

1. On the top bar, select Menu > Projects and find your project.
2. From the left sidebar, select Infrastructure > Kubernetes clusters.
3. Select Actions.
4. From the Select an agent dropdown list:
   • 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.
5. Select Register an agent.
6. 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.
7. 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.

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.

You can use an agent configuration file to specify details about your implementation. Creating a file is optional but is needed if:

• You use a GitOps workflow and you want a more advanced configuration.
• You use a GitLab CI/CD workflow. In that workflow, you must authorize the agent.

To create an agent configuration file, go to the GitLab project. In the repository, create a file called config.yaml at this path:

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

• Ensure the agent name follows the naming convention.
• Ensure the filename has the .yaml file extension (config.yaml). The .yml extension is not accepted.
• Add content to the config.yaml file:
  • For a GitOps workflow, view the configuration reference for details.
  • For a GitLab CI/CD workflow, you can leave the file blank for now.

The agent bootstraps with the GitLab installation URL and an access token, and you provide the rest of the configuration in your repository, following Infrastructure as Code (IaaC) best practices.

Install the agent in the cluster

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

• The one-liner installation method.
• The advanced installation method.

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 a 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

By default, the one-liner command generated by GitLab:

• Creates a namespace for the deployment (gitlab-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 access token.
• Creates a Deployment resource for the agentk pod.

You can edit these parameters to customize the one-liner installation command. To view all available options, open a terminal and run this command:

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

Usage:
  cli generate [flags]

Flags:
      --agent-token string     Access token registered for agent
      --agent-version string   Version of the agentk image to use (default "v14.8.1")
  -h, --help                   help for generate
      --kas-address string     GitLab agent server for Kubernetes address
      --name-prefix string     The prefix to use for names of Kubernetes objects
      --namespace string       Kubernetes namespace to create resources in (default "gitlab-agent")
      --no-rbac                Do not include corresponding Roles and RoleBindings for the agent service account

WARNING: Use --agent-version stable to refer to the latest stable release at the time when the command runs. For production, however, you should explicitly specify a matching version.

Advanced installation

For advanced installation options, use the kpt installation method.

Customize the permissions for the agentk service account

You own your cluster and can grant GitLab the permissions you want. By default, however, the generated manifests provide cluster-admin rights to the agent.

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

To restrict 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.

Update the advanced installation base layer

Now you can update from the upstream package by using kpt pkg update gitlab-agent --strategy resource-merge. When the advanced installation setup changes, you will not need to change your custom overlays.

Install multiple agents in your cluster

For total separation between teams, you might need to run multiple agentk instances in your cluster. You might want multiple agents so you can restrict RBAC for every agentk deployment.

To install multiple agents, follow the advanced installation steps a second time and:

1. Change the agent name and create a new configuration file.
2. Register the new agent. You receive a new access token. Each token should be used only with one agent.
3. Change the namespace or prefix you use for the installation.

You should also change the RBAC for the installed agentk.

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

Upgrades and version compatibility

The agent has two major components: agentk and kas. GitLab provides 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 ensure 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 are available in the Container Registry.

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, re-run the installation command with a newer --agent-version. Make sure to specify the other required parameters: --kas-address, --namespace, and --agent-token. The available agentk versions are in the Container Registry.

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

1. Open a 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 access token, run:

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