Grant users Kubernetes access (FREE ALL BETA)

Introduced in GitLab 16.1, with flags named environment_settings_to_graphql, kas_user_access, kas_user_access_project, and expose_authorized_cluster_agents. This feature is in Beta.

Feature flag environment_settings_to_graphql removed in GitLab 16.2.

Feature flags kas_user_access, kas_user_access_project, and expose_authorized_cluster_agents removed in GitLab 16.2.

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 self-managed instances, make sure you either:

Host your GitLab instance and KAS on the same domain.
Host KAS on a subdomain of GitLab. For example, GitLab on gitlab.com and KAS on kas.gitlab.com.

Configure Kubernetes access

Configure access when you want to grant users access to a Kubernetes cluster.

Prerequisites:

The agent for Kubernetes is installed in the Kubernetes cluster.
You must have the Developer role or higher.

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.
- groups: A list of groups whose members should have access.
- access_as: Required. For plain access, the value is { agent: {...} }.

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

Configure access with user impersonation (PREMIUM ALL)

You can grant access to a Kubernetes cluster and transform requests into impersonation requests for authenticated users.

Prerequisites:

The agent for Kubernetes is installed in the Kubernetes cluster.
You must have the Developer role or higher.

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: Required. For user impersonation, the value is { user: {...} }.

After you configure access, requests are transformed into impersonation requests for authenticated users.

User impersonation workflow

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, oidc_id_token, or session_cookie.

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:

If a user is a member of only group-1, they receive only the Kubernetes RBAC groups gitlab:project_role:1:<role>.
If a user is a member of group-2, they receive both Kubernetes RBAC groups:
- gitlab:project_role:2:<role>,
- gitlab:group_role:2:<role>.

RBAC authorization

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

Access a cluster with the Kubernetes API

Introduced in GitLab 16.4.

You can configure an agent to allow GitLab users to access a cluster with the Kubernetes API.

Prerequisite:

You have an agent configured with the user_access entry.

To grant Kubernetes API access:

On the left sidebar, 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 kube config entries to access the cluster:
1. Make sure that the proper kube config is selected. For example, you can set the KUBECONFIG environment variable.
2. Add the GitLab KAS proxy cluster to the kube config:
```
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.
3. 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>"
```
4. Add the context to combine the cluster and the user:
```
kubectl config set-context <gitlab_agent> --cluster <cluster_name> --user <gitlab_user>
```
5. 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.