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 exec sessions 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 ~/.kube

tsh login, then tsh kube login --all.

You were granted access to a new cluster, or a new cluster was enrolled

Re-run tsh kube login --all. Existing contexts are updated in place, new ones added. Nothing appears in kubectl for a cluster until you do this.

kubectl says error: You must be logged in to the server or tsh prints access denied / certificate expired

Your Teleport cert expired (see tsh status). Run tsh login again. The contexts stay valid; nothing to regenerate.

You lost access to a cluster

The context remains in your kubeconfig but every call is refused. Re-run tsh kube login --all to refresh the set, and delete the stale context with kubectl config delete-context <name>.

A cluster was renamed or re-enrolled

Re-run tsh kube login --all; delete the old context by hand.

You switched laptops

Install Teleport Connect and tsh (see Setup), tsh login, tsh kube login --all. There is nothing to copy over.

--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>.

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 KUBECONFIG owns current-context and receives kubectl config set-* writes. Keep ~/.kube/config first.

  • 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 ls is empty — your roles grant no Kubernetes clusters. Ask the platform team; the relevant role has to include the cluster’s teleport_access label.

  • Unable to connect to the server: getting credentials: exec: executable tsh failed — tsh is not on PATH for the tool calling it (common in IDEs launched from the Dock, which don’t read your shell profile). The kubeconfig stores the absolute path tsh had when you ran tsh kube login; re-run it from a terminal where tsh version works, or install tsh in 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 --all and check tsh status shows Kubernetes: enabled.

  • k9s doesn’t show a new cluster — it reads kubeconfig at start-up. Restart it, or use :ctx after re-running tsh kube login --all.

  • kubectl uses the wrong cluster after a re-run — tsh kube login sets current-context to the last cluster it wrote. Pin it with kubectl config use-context <name> or always pass --context.