• Configure Kubernetes access
• Configure access with user impersonation
  • User impersonation workflow
  • RBAC authorization
• Access a cluster with the Kubernetes API
• Related topics

Grant users Kubernetes access

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

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

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:

1. On the left sidebar, select Search or go to and find your project.
2. 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.
3. Create a personal access token with the k8s_proxy scope. You need the access token to construct the full API token.
4. 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>
      

5. Check that the configuration works:

    kubectl get nodes
   

The configured user can access your cluster with the Kubernetes API.

Related topics

• Architectural blueprint
• Dashboard for Kubernetes