---
title: "kubectl access"
description: "Sign in to a cluster with EZGH IAM, map users, bots and groups into Kubernetes, and control the public endpoint."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# kubectl access

`kubectl` signs in to a cluster with your EZGH identity. There are no cluster passwords or
certificates to hand out: each request is checked against IAM as it's made, so removing someone's
access takes effect on their next request.

## Set up kubectl

```sh
ezgh kubernetes update-kubeconfig kcl_3k9d0a1m2x7q
```

This adds the cluster to your kubeconfig (the first file in `KUBECONFIG`, else `~/.kube/config`) and
makes it the current context. Other clusters, users and contexts in the file are kept. The entry is named
`ezgh-kcl_3k9d0a1m2x7q`; `--alias` names it something else, and `--kubeconfig` writes another file.

The user in that entry runs `ezgh kubernetes token --cluster kcl_3k9d0a1m2x7q` whenever `kubectl` needs
a token, with the `ezgh` profile, organization and project you used. Each token lasts 15 minutes and
works only for that cluster. Tokens aren't written to disk.

Getting a token needs the IAM action `kubernetes.clusters.accessKubernetesApi` on the cluster, and an
[access entry](#access-entries) decides what you can do inside it.

## The endpoint

A cluster's endpoint has two names:

- **Public:** `endpoint.hostname`, reachable from the internet, limited to `publicAccessCidrs`. The
  default is `0.0.0.0/0`. It takes up to 40 IPv4 CIDRs, and an empty list closes the public endpoint.
- **Private:** `endpoint.privateHostname`, which resolves to the cluster's addresses in its subnet
  (`endpoint.privateAddresses`). Nodes use it, and so can anything in the VPC:

  ```sh
  ezgh kubernetes update-kubeconfig kcl_3k9d0a1m2x7q --private
  ```

Change who reaches the public endpoint, or close it:

```sh
ezgh kubernetes clusters update kcl_3k9d0a1m2x7q --public-access-cidr 203.0.113.0/24 --wait
ezgh kubernetes clusters update kcl_3k9d0a1m2x7q --no-public-access --wait
```

Every cluster has one public IPv4 address for its endpoint, whether or not the public endpoint is open.

## Access entries

An access entry gives an EZGH principal an identity inside the cluster. The principal is a user, a
bot, an EZGH SSO user or a group; a group's members are looked up on each request, so adding or
removing someone from the group takes effect at once.

An entry has:

- **Username:** `ezgh:` and the principal's ID (for a bot or an SSO user, its UUID), set for you.
- **Kubernetes groups:** group names for your own RoleBindings and ClusterRoleBindings. Names starting
  with `system:` or `ezgh:` are refused.
- **Access policies:** EZGH-managed bindings to Kubernetes' built-in roles, each for the whole cluster
  or for listed namespaces.

| Policy | Kubernetes role |
| --- | --- |
| `clusterAdmin` | `cluster-admin` |
| `admin` | `admin` |
| `edit` | `edit` |
| `view` | `view` |

```sh
# Ada can view everything, and edit in the shop namespace.
ezgh kubernetes access-entries create --cluster kcl_3k9d0a1m2x7q \
  --principal 0199a3c5-1e2f-7a31-9b4c-5d6e7f8091a2 --principal-type user \
  --policy view --policy edit:shop

# The platform group is in the Kubernetes group platform-admins, bound by your own RBAC.
ezgh kubernetes access-entries create --cluster kcl_3k9d0a1m2x7q \
  --principal grp_4k2m9x0a7qpe --kubernetes-group platform-admins
```

A user is named by their user ID, a bot by its `bot_` ID, an SSO user by its `usr_` ID, and a group by
its `grp_` ID ([CreateAccessEntry](/kubernetes-api/CreateAccessEntry/)). A principal has one entry per cluster.

The access policies are kept as RoleBindings and ClusterRoleBindings whose names start with `ezgh:`.
Don't create or change bindings with that prefix: EZGH replaces them.

Deleting an access entry, or removing `kubernetes.clusters.accessKubernetesApi` from the principal,
stops its `kubectl` requests on the next request.

### Creator access

Whoever creates a cluster gets an access entry with `clusterAdmin`, so they can use the cluster at once.
It's an ordinary entry, which you can change or delete. To create a cluster without it, pass
`--no-creator-access` (`bootstrapCreatorAccess: false`).

## CI and automation

A CI job signs in as a [bot](/iam/bots): give the bot `kubernetes.clusters.accessKubernetesApi` on the
cluster and an access entry, then sign `ezgh` in with a bot API key, or with an [OIDC API
key](/iam/github-actions) so no key is stored in CI. `ezgh kubernetes update-kubeconfig` and `kubectl`
then work as they do for a person.

Source: https://docs.ezghcloud.com/kubernetes/kubectl-access/index.mdx
