doc/user/clusters/agent/user_access.md
{{< details >}}
{{< /details >}}
{{< history >}}
environment_settings_to_graphql, kas_user_access, kas_user_access_project, and expose_authorized_cluster_agents. This feature is in beta.environment_settings_to_graphql removed in GitLab 16.2.kas_user_access, kas_user_access_project, and expose_authorized_cluster_agents removed in GitLab 16.2.user_access parameter access_as was made optional in GitLab 18.3. Defaults to agent impersonation.{{< /history >}}
As an administrator of Kubernetes clusters in an organization, you can grant Kubernetes access to members of a specific project or group.
Granting access also activates the Dashboard for Kubernetes for a project or group.
For GitLab Self-Managed instances, make sure you either:
gitlab.com and KAS on kas.gitlab.com.Configure access when you want to grant users access to a Kubernetes cluster.
Prerequisites:
To configure access:
In the agent configuration file, define a user_access keyword with the following parameters:
projects: A list of projects whose members should have access. You can authorize up to 500 projects.groups: A list of groups whose members should have access. You can authorize up to 500 groups. It grants access to the group and all its descendants.access_as: For access with agent identity, the value is { agent: {...} }.Authorized projects and groups must have the same top-level group or user namespace as the agent's configuration project, unless the instance level authorization application setting is enabled.
After you configure access, requests are forwarded to the API server using the agent service account. For example:
# .gitlab/agents/my-agent/config.yaml
user_access:
access_as:
agent: {}
projects:
- id: group-1/project-1
- id: group-2/project-2
groups:
- id: group-2
- id: group-3/subgroup
{{< details >}}
{{< /details >}}
You can grant access to a Kubernetes cluster and transform requests into impersonation requests for authenticated users.
Prerequisites:
To configure access with user impersonation:
In the agent configuration file, define a user_access keyword with the following parameters:
projects: A list of projects whose members should have access.groups: A list of groups whose members should have access.access_as: For user impersonation, the value is { user: {...} }.After you configure access, requests are transformed into impersonation requests for authenticated users.
The installed agentk impersonates the given users as follows:
UserName is gitlab:user:<username>Groups is:
gitlab:user: Common to all requests coming from GitLab users.gitlab:project_role:<project_id>:<role> for each role in each authorized project.gitlab:group_role:<group_id>:<role> for each role in each authorized group.Extra carries additional information about the request:
agent.gitlab.com/id: The agent ID.agent.gitlab.com/username: The username of the GitLab user.agent.gitlab.com/config_project_id: The agent configuration project ID.agent.gitlab.com/access_type: One of personal_access_token or session_cookie. Ultimate only.Only projects and groups directly listed in the under user_access in the configuration
file are impersonated. For example:
# .gitlab/agents/my-agent/config.yaml
user_access:
access_as:
user: {}
projects:
- id: group-1/project-1 # group_id=1, project_id=1
- id: group-2/project-2 # group_id=2, project_id=2
groups:
- id: group-2 # group_id=2
- id: group-3/subgroup # group_id=3, group_id=4
In this configuration:
group-1, they receive
only the Kubernetes RBAC groups gitlab:project_role:1:<role>.group-2, they receive both Kubernetes RBAC groups:
gitlab:project_role:2:<role>,gitlab:group_role:2:<role>.Impersonated requests require ClusterRoleBinding or RoleBinding to identify the resource permissions
inside Kubernetes. See RBAC authorization
for the appropriate configuration.
For example, if you allow maintainers in awesome-org/deployment project (ID: 123) to read the Kubernetes workloads,
you must add a ClusterRoleBinding resource to your Kubernetes configuration:
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: my-cluster-role-binding
roleRef:
name: view
kind: ClusterRole
apiGroup: rbac.authorization.k8s.io
subjects:
- name: gitlab:project_role:123:maintainer
kind: Group
{{< history >}}
{{< /history >}}
You can configure an agent to allow GitLab users to access a cluster with the Kubernetes API.
Prerequisites:
user_access entry.You can use the GitLab CLI glab to create or update
a Kubernetes configuration file to access the agent Kubernetes API.
Use glab cluster agent commands to manage cluster connections:
glab cluster agent list --repo '<group>/<project>'
# If your current working directory is the Git repository of the project with the agent, you can omit the --repo option:
glab cluster agent list
kubeconfig:glab cluster agent update-kubeconfig --repo '<group>/<project>' --agent '<agent-id>' --use-context
kubectl or your preferred Kubernetes tooling:kubectl get nodes
The update-kubeconfig command sets glab cluster agent get-token as a
credential plugin
for Kubernetes tools to retrieve a token. The get-token command creates and
returns a personal access token that is valid until the end of the current day.
Kubernetes tools cache the token until it expires, the API returns an authorization error, or the process exits. Expect all subsequent calls to your Kubernetes tooling to create a new token.
The glab cluster agent update-kubeconfig command supports a number of command line flags. You can view all supported flags with glab cluster agent update-kubeconfig --help.
Some examples:
# When the current working directory is the Git repository where the agent is registered the --repo / -R flag can be omitted
glab cluster agent update-kubeconfig --agent '<agent-id>'
# When the --use-context option is specified the `current-context` of the kubeconfig file is changed to the agent context
glab cluster agent update-kubeconfig --agent '<agent-id>' --use-context
# The --kubeconfig flag can be used to specify an alternative kubeconfig path
glab cluster agent update-kubeconfig --agent '<agent-id>' --kubeconfig ~/gitlab.kubeconfig
You can configure access to a Kubernetes cluster using a long-lived personal access token:
In the top bar, select Search or go to and find your project.
Select Operate > Kubernetes clusters and retrieve the numerical ID of the agent you want to access. You need the ID to construct the full API token.
Create a personal access token with the k8s_proxy scope. You need the access token to construct the full API token.
Construct kubeconfig entries to access the cluster:
Make sure that the proper kubeconfig is selected.
For example, you can set the KUBECONFIG environment variable.
Add the GitLab KAS proxy cluster to the kubeconfig:
kubectl config set-cluster <cluster_name> --server "https://kas.gitlab.com/k8s-proxy"
The server argument points to the KAS address of your GitLab instance.
On GitLab.com, this is https://kas.gitlab.com/k8s-proxy.
You can get the KAS address of your instance when you register an agent.
Use your numerical agent ID and personal access token to construct an API token:
kubectl config set-credentials <gitlab_user> --token "pat:<agent-id>:<token>"
Add the context to combine the cluster and the user:
kubectl config set-context <gitlab_agent> --cluster <cluster_name> --user <gitlab_user>
Activate the new context:
kubectl config use-context <gitlab_agent>
Check that the configuration works:
kubectl get nodes
The configured user can access your cluster with the Kubernetes API.