diff options
Diffstat (limited to 'doc/development/agent/identity.md')
| -rw-r--r-- | doc/development/agent/identity.md | 107 |
1 files changed, 5 insertions, 102 deletions
diff --git a/doc/development/agent/identity.md b/doc/development/agent/identity.md index 83af4318de9..67084a6d995 100644 --- a/doc/development/agent/identity.md +++ b/doc/development/agent/identity.md @@ -1,106 +1,9 @@ --- -stage: Configure -group: Configure -info: 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 +redirect_to: 'https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/identity_and_auth.md' +remove_date: '2022-06-24' --- -# Kubernetes Agent identity and authentication **(PREMIUM SELF)** +This file was moved to [another location](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/identity_and_auth.md). -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](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md) -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](https://tools.ietf.org/html/rfc1123). -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](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-label-names) -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)](https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/#priyanka-platform-engineer) -may want to use cluster-wide features of the agent, while -[Sasha (Software Developer)](https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/#sasha-software-developer) -uses the agent that only has access to a particular namespace. - -Each agent is likely running using a -[`ServiceAccount`](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/), -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](https://en.wikipedia.org/wiki/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](../../user/permissions.md). - -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. - -## Create an agent - -You can create an agent by following the [user documentation](../../user/clusters/agent/index.md#create-an-agent-record-in-gitlab), or via Rails console: - -```ruby -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 -``` +<!-- This redirect file can be deleted after <2022-06-24>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> |