User Access & Kubeconfig

## What a kubeconfig is A **kubeconfig** is the YAML file that tells `kubectl` (and any client built on client-go) **where** the Kubernetes API server is and **who** to be when talking to it. Its top level is `apiVersion: v1` and `kind: Config`. It is not a Kubernetes object stored in the cluster: it lives on the client machine, by default at `~/.kube/config`. Because it usually carries a credential, it should be handled like a password. ## The three lists and the pointer A kubeconfig holds three named lists plus one pointer: | Section | Each entry holds | Example name | |---|---|---| | `clusters` | `server` (the API server URL) and the CA that signed the API server's serving certificate (`certificate-authority` or `certificate-authority-data`) | `spot-mix-38` | | `users` | a credential, typically `client-certificate-data` + `client-key-data`, a bearer `token`, or an `exec` block that runs a credential plugin | `fraud-dev` | | `contexts` | a reference to one cluster, one user and, optionally, a default `namespace` | `fraud-rules-prod` | | `current-context` | the name of the context used when nothing else is specified | `fraud-rules-prod` | Key points about the `users` list: - A "user" here is only a **local label for a credential**. Kubernetes has no User object; the username the API server records comes from the credential (a certificate's subject, a token's claims), not from this label. - The same credential can be reused by several contexts, for example one context per namespace. - A context does not grant anything. Permissions still come from RBAC bindings on the cluster side. ## How kubectl picks a file and a context `kubectl` resolves its configuration in this order: 1. If the `--kubeconfig` flag is given, that single file is used and nothing is merged. 2. Otherwise, if the `KUBECONFIG` environment variable is set, every file in its list (colon-separated on Linux and macOS, semicolon-separated on Windows) is loaded and **merged**. 3. Otherwise, `~/.kube/config` is used. Merging follows a **first-file-wins** rule: the first file that defines a given cluster, user or context name wins, and that entry is taken whole from that file; a later file's fields are never blended into it. `current-context` is likewise taken from the first file that sets it. Once the merged config exists, the context is chosen: `--context` if given, otherwise `current-context`. The flags `--cluster`, `--user` and `--namespace` override individual parts of that context for one command. ## Everyday commands ```bash kubectl config get-contexts kubectl config use-context fraud-rules-prod kubectl config set-context --current --namespace=fraud-rules kubectl config view --minify kubectl auth whoami ``` - `get-contexts` lists contexts and marks the current one with `*`. - `use-context` rewrites `current-context` in the file (it changes state for every later command). - `set-context --current --namespace` changes only the default namespace of the active context. - `view --minify` shows only what the current context uses; `--raw` would print the secret data too, and `--flatten` inlines referenced files so the result is portable. - `kubectl auth whoami` asks the API server, through a SelfSubjectReview, which username and groups it actually derived from your credential; this is the fastest way to confirm what the context really authenticates as. ## What a users entry can hold The `user` block of an entry normally carries one way of proving identity (client-go rejects a bearer token combined with basic auth), and the choice decides how access is issued and revoked: - **`client-certificate-data` and `client-key-data`**: an X.509 certificate signed by a CA the API server trusts. Simple and needs nothing else, but long-lived and not revocable. - **`token`**: a static bearer token pasted into the file. It is common for ServiceAccount tokens used by automation and a poor fit for people, because anyone who copies the file becomes you. - **`exec`**: a command that `kubectl` runs to fetch a short-lived credential, typically from an OIDC identity provider. The file then contains no secret at all, only instructions for getting one. Paths such as `client-certificate` and `client-key` can replace the `-data` fields when the material lives in separate files. ## Common failure modes - **Wrong cluster, right name.** Two teams' files both define a context called `prod`; with `KUBECONFIG` merging, whichever file is listed first silently wins. - **Shared admin file.** Copying one kubeconfig to many people makes every action look like one identity and makes revocation impossible without breaking everyone. - **Relative paths.** `client-certificate` and `certificate-authority` paths are resolved relative to the kubeconfig file itself, so moving the file breaks them; the `-data` variants, or `--flatten`, avoid that. - **Accidental production commands.** Because `use-context` is sticky, many teams prefer per-command `--context` in scripts, or a separate `KUBECONFIG` per shell.