Kubernetes: kubeconfig for every cluster you can reach
How to get kubectl, k9s, Helm, Lens and any other kubeconfig-based tool
working against all Kubernetes clusters Teleport grants you, with one command, from any
network. Covers what the command does, when to re-run it, and how to keep the generated
contexts in their own file.
1. Why go through Teleport for Kubernetes
Every better.care Kubernetes cluster runs a Teleport kube agent. The agent joins the Teleport cluster from inside Kubernetes, so:
-
You never need cloud-provider credentials or a place on an API-server IP allowlist. Office, home, VPN or hotel — same access.
-
Your Kubernetes identity is your Teleport user and roles; the platform team maps them to Kubernetes groups per cluster. Access is audited and
kubectl execsessions are recorded. -
Credentials are your short-lived Teleport cert. Nothing long-lived is stored in kubeconfig.
Which clusters you see is decided by the teleport_access label on each kube agent and
the roles you hold — exactly like SSH nodes (see the label section).
2. The one command: tsh kube login --all
tsh kube login <cluster> adds a kubeconfig context for one cluster. --all does it for
every cluster your roles allow — the same list tsh kube ls prints — in one go:
tsh login --proxy=teleport.better.care:443 --user=<your-username> # if not already logged in
tsh kube login --all
Afterwards kubectl config get-contexts lists one context per cluster, named
teleport.better.care-<cluster> by default, and plain tooling works:
kubectl --context teleport.better.care-<cluster> get nodes
kubectl config use-context teleport.better.care-<cluster>
k9s # pick the context with :ctx
2.1. What it actually writes
Each context points at the Teleport proxy (teleport.better.care:443) and uses tsh as an
exec credential plugin:
users:
- name: teleport.better.care-<cluster>
user:
exec:
command: /usr/local/bin/tsh
args: [kube, credentials, --kube-cluster=<cluster>, --teleport-cluster=teleport.better.care, --proxy=teleport.better.care:443]
So every kubectl call asks tsh for a credential, which it mints from your current
Teleport cert. Nothing needs to keep running in the background, unlike the Teleport Connect
"local proxy" which only serves the terminal tab it was started from.
2.2. Shorter context names (optional)
The default names are long. --set-context-name takes a template:
tsh kube login --all --set-context-name '{{.KubeName}}' # -> <cluster>, <other-cluster>, ...
tsh kube login --all --set-context-name 'tp-{{.KubeName}}' # -> tp-<cluster>, ...
Use a prefix if you also keep direct cloud contexts in the same kubeconfig (a cloud-provider context with the same short name would otherwise collide with the Teleport one).
3. When to run it (and re-run it)
| Situation | What to do |
|---|---|
First time on a laptop, or a fresh |
|
You were granted access to a new cluster, or a new cluster was enrolled |
Re-run |
|
Your Teleport cert expired (see |
You lost access to a cluster |
The context remains in your kubeconfig but every call is refused. Re-run
|
A cluster was renamed or re-enrolled |
Re-run |
You switched laptops |
Install Teleport Connect and |
--all covers the Teleport cluster you are logged in to. Leaf clusters currently host
no Kubernetes clusters at better.care; if that changes, add --cluster=<leaf>.
|
4. Keep Teleport contexts in their own file (recommended)
kubeconfig has no Include directive, but kubectl merges every file named in the
KUBECONFIG environment variable (colon-separated), and tsh writes into whatever
KUBECONFIG points at. That gives a clean split: ~/.kube/config stays yours,
~/.kube/teleport is fully generated and disposable.
Add to ~/.zshrc (or your shell profile):
export KUBECONFIG="$HOME/.kube/config:$HOME/.kube/teleport"
# regenerate Teleport kube contexts into their own file
tsh-kube() {
tsh status >/dev/null 2>&1 || tsh login --proxy=teleport.better.care:443
KUBECONFIG="$HOME/.kube/teleport" tsh kube login --all --set-context-name '{{.KubeName}}' \
&& echo "kube contexts: $(kubectl --kubeconfig "$HOME/.kube/teleport" config get-contexts -o name | wc -l | tr -d ' ')"
}
Then tsh-kube (re)builds the Teleport file, and every tool sees both files merged.
Two merge rules to keep in mind:
-
The first file in
KUBECONFIGownscurrent-contextand receiveskubectl config set-*writes. Keep~/.kube/configfirst. -
If two files define the same context name, the first one wins. Prefix the Teleport contexts (or keep the default long names) if you also have direct cloud contexts.
To start over: rm ~/.kube/teleport && tsh-kube.
5. Teleport Connect and kubeconfig
Teleport Connect’s Connect button on a Kubernetes cluster starts a local proxy and sets
KUBECONFIG to a per-cluster file under ~/Library/Application Support/Teleport Connect/
in the terminal tab it opens. That is fine for a quick kubectl, but the file disappears
when the proxy is closed and is invisible to other terminals, IDEs and k9s. For everyday
work use tsh kube login --all as above; both can coexist.
6. Troubleshooting
-
tsh kube lsis empty — your roles grant no Kubernetes clusters. Ask the platform team; the relevant role has to include the cluster’steleport_accesslabel. -
Unable to connect to the server: getting credentials: exec: executable tsh failed—tshis not onPATHfor the tool calling it (common in IDEs launched from the Dock, which don’t read your shell profile). The kubeconfig stores the absolute pathtshhad when you rantsh kube login; re-run it from a terminal wheretsh versionworks, or installtshin PATH from the Teleport Connect menu (see Setup). -
error: You must be logged in to the server (Unauthorized)— Teleport cert expired or your Kubernetes groups changed.tsh login, then retry; if it persists,tsh kube login --alland checktsh statusshowsKubernetes: enabled. -
k9sdoesn’t show a new cluster — it reads kubeconfig at start-up. Restart it, or use:ctxafter re-runningtsh kube login --all. -
kubectl uses the wrong cluster after a re-run —
tsh kube loginsetscurrent-contextto the last cluster it wrote. Pin it withkubectl config use-context <name>or always pass--context.