diff options
Diffstat (limited to 'doc/user/clusters/agent/user_access.md')
| -rw-r--r-- | doc/user/clusters/agent/user_access.md | 58 |
1 files changed, 58 insertions, 0 deletions
diff --git a/doc/user/clusters/agent/user_access.md b/doc/user/clusters/agent/user_access.md index 7d6060fb44e..c0805b5e84a 100644 --- a/doc/user/clusters/agent/user_access.md +++ b/doc/user/clusters/agent/user_access.md @@ -141,6 +141,64 @@ subjects: 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](#configure-kubernetes-access) to allow GitLab users to access a cluster with the Kubernetes API. + +Use a [personal access token](../../profile/personal_access_tokens.md) +with the `k8s_proxy` scope to access the cluster via `kubectl`: + +1. Configure the agent with the [`user_access` entry](user_access.md). +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 gitlab --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. + + If needed, change `gitlab` to the name of your cluster. + 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>" + ``` + + If needed, change `gitlab-user` to your credentials name. + 1. Add the context to combine the cluster and the user: + + ```shell + kubectl config set-context gitlab-agent --cluster gitlab --user gitlab-user + ``` + + If needed, change the arguments to `cluster` and `user`. The arguments must match the cluster name and user from the previous steps. + + You can customize the context name. + 1. Activate the new context: + + ```shell + kubectl config use-context gitlab-agent + ``` + + If needed, change `gitlab-agent` to the context name you set in the last step. +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) |