gitlab-org--gitlab-foss/doc/development/agent/identity.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/#designated-technical-writers

Kubernetes Agent identity and authentication (PREMIUM ONLY)

This page uses the word agent to describe the concept of the GitLab Kubernetes Agent. The program that implements the concept is called agentk. Read the architecture page for more information.

Agent identity and name

In a GitLab installation, each agent must have a unique, immutable name. This name must be unique in the project the agent is attached to, and this name must follow the DNS label standard from RFC 1123. The name must:

• Contain at most 63 characters.
• Contain only lowercase alphanumeric characters or -.
• Start with an alphanumeric character.
• End with an alphanumeric character.

Kubernetes uses the same naming restriction for some names.

The regex for names is: /\A[a-z0-9]([-a-z0-9]*[a-z0-9])?\z/.

Multiple agents in a cluster

A Kubernetes cluster may have 0 or more agents running in it. Each agent likely has a different configuration. Some may enable features A and B, and some may enable features B and C. This flexibility enables different groups of people to use different features of the agent in the same cluster.

For example, Priyanka (Platform Engineer) may want to use cluster-wide features of the agent, while Sasha (Software Developer) uses the agent that only has access to a particular namespace.

Each agent is likely running using a ServiceAccount, a distinct Kubernetes identity, with a distinct set of permissions attached to it. These permissions enable the agent administrator to follow the principle of least privilege and minimize the permissions each particular agent needs.

Kubernetes Agent authentication

When adding a new agent, GitLab provides the user with a bearer access token. The agent uses this token to authenticate with GitLab. This token is a random string and does not encode any information in it, but it is secret and must be treated with care. Store it as a Secret in Kubernetes.

Each agent can have 0 or more tokens in a GitLab database. Having several valid tokens helps you rotate tokens without needing to re-register an agent. Each token record in the database has the following fields:

• Agent identity it belongs to.
• Token value. Encrypted at rest.
• Creation time.
• Who created it.
• Revocation flag to mark token as revoked.
• Revocation time.
• Who revoked it.
• A text field to store any comments the administrator may want to make about the token for future self.

Tokens can be managed by users with maintainer and higher level of permissions.

Tokens are immutable, and only the following fields can be updated:

• Revocation flag. Can only be updated to true once, but immutable after that.
• Revocation time. Set to the current time when revocation flag is set, but immutable after that.
• Comments field. Can be updated any number of times, including after the token has been revoked.

The agent sends its token, along with each request, to GitLab to authenticate itself. For each request, GitLab checks the token's validity:

• Does the token exist in the database?
• Has the token been revoked?

This information may be cached for some time to reduce load on the database.

Kubernetes Agent authorization

GitLab provides the following information in its response for a given Agent access token:

• Agent configuration Git repository. (The agent doesn't support per-folder authorization.)
• Agent name.