1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
|
---
stage: Deploy
group: Environments
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
---
# Grant users Kubernetes access **(FREE ALL BETA)**
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390769) in GitLab 16.1, with [flags](../../../administration/feature_flags.md) named `environment_settings_to_graphql`, `kas_user_access`, `kas_user_access_project`, and `expose_authorized_cluster_agents`. This feature is in [Beta](../../../policy/experiment-beta-support.md#beta).
> - Feature flag `environment_settings_to_graphql` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124177) in GitLab 16.2.
> - Feature flags `kas_user_access`, `kas_user_access_project`, and `expose_authorized_cluster_agents` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/125835) 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](../../../administration/clusters/kas.md) 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:
```yaml
# .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:
```yaml
# .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](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)
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:
```yaml
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](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131144) 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:
1. On the left sidebar, select **Search or go to** and find your project.
1. 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.
1. Create a [personal access token](../../profile/personal_access_tokens.md) with the `k8s_proxy` scope. You need the access token to construct the full API token.
1. 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.
1. Add the GitLab KAS proxy cluster to the `kube config`:
```shell
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.
1. Use your numerical agent ID and personal access token to construct an API token:
```shell
kubectl config set-credentials <gitlab_user> --token "pat:<agent-id>:<token>"
```
1. Add the context to combine the cluster and the user:
```shell
kubectl config set-context <gitlab_agent> --cluster <cluster_name> --user <gitlab_user>
```
1. Activate the new context:
```shell
kubectl config use-context <gitlab_agent>
```
1. Check that the configuration works:
```shell
kubectl get nodes
```
The configured user can access your cluster with the Kubernetes API.
## Related topics
- [Architectural blueprint](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/kubernetes_user_access.md)
- [Dashboard for Kubernetes](https://gitlab.com/groups/gitlab-org/-/epics/2493)
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
Each scenario can be a third-level heading, for example `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->
|
