How does kubectl know which cluster to talk to?
Quick Answer
kubectl reads connection details — the API server's address, the credentials to authenticate with, and which cluster/user/namespace combination (a "context") is currently active — from a kubeconfig file, by default at `~/.kube/config`. You can define multiple clusters and contexts in one kubeconfig file and switch between them with `kubectl config use-context`, or point kubectl at a different file entirely via the `KUBECONFIG` environment variable or the `--kubeconfig` flag.
Detailed Answer
The kubeconfig file
By default, kubectl reads ~/.kube/config, a YAML file with three related sections:
apiVersion: v1
kind: Config
clusters:
- name: prod-cluster
cluster:
server: https://prod-api.example.com
certificate-authority-data: <base64-encoded CA cert>
- name: staging-cluster
cluster:
server: https://staging-api.example.com
...
users:
- name: alice
user:
client-certificate-data: <base64-encoded cert>
client-key-data: <base64-encoded key>
contexts:
- name: prod
context:
cluster: prod-cluster
user: alice
namespace: production
- name: staging
context:
cluster: staging-cluster
user: alice
namespace: default
current-context: staging
clusters— where each cluster's API server lives, and how to verify its identity (the cluster's CA certificate).users— credentials for authenticating as a specific identity (a client certificate, a bearer token, or a command that generates one dynamically, e.g., for cloud-provider IAM-based auth).contexts— a named combination of a cluster + a user + (optionally) a default namespace, letting you bundle "which cluster, as whom, in which namespace" into one switchable unit.
Switching contexts
kubectl config get-contexts # list all available contexts
kubectl config use-context prod # switch the active context
kubectl config current-context # show which one is active
Every kubectl command uses whichever context is currently active, unless overridden per-command with --context=<name>. Accidentally running a command against the wrong active context (a classic "meant to hit staging, actually hit prod" incident) is a well-known operational risk — many teams use shell prompt integrations or wrapper tools that visibly display the current context to reduce this risk.
Overriding the config file location
export KUBECONFIG=/path/to/other-config.yaml
kubectl --kubeconfig=/path/to/other-config.yaml get pods
KUBECONFIG can also point to multiple colon-separated files, which kubectl merges together — useful for combining a base config with cluster-specific credential files generated by different tools (a cloud provider's CLI, a CI pipeline's service account setup).
How managed cloud clusters populate this automatically
Cloud provider CLIs typically offer a command that fetches cluster connection details and merges an appropriate entry into your kubeconfig automatically — e.g., aws eks update-kubeconfig, gcloud container clusters get-credentials, az aks get-credentials — so you rarely hand-write these files for a real cluster; you generate them via the provider's tooling and then just manage which context is active.