- Agent identity and name
- Multiple agents in a cluster
- Kubernetes Agent authentication
- Kubernetes Agent authorization
- Create an agent
This page uses the word
agent to describe the concept of the
GitLab Kubernetes Agent. The program that implements the concept is called
for more information.
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 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.
Each agent is likely running using a
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.
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
Tokens are immutable, and only the following fields can be updated:
- Revocation flag. Can only be updated to
trueonce, 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.
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.
You can create an agent by following the user documentation, or via Rails console:
project = ::Project.find_by_full_path("path-to/your-configuration-project") # agent-name should be the same as specified above in the config.yaml agent = ::Clusters::Agent.create(name: "<agent-name>", project: project) token = ::Clusters::AgentToken.create(agent: agent) token.token # this will print out the token you need to use on the next step