How does kubectl know which cluster to talk to?
Quick Answer
kubectl reads connection details from a kubeconfig file, by default at ~/.kube/config: the API server's address, the credentials to authenticate with, and which cluster/user/namespace combination (a "context") is currently active. 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, for example for cloud-provider IAM-based auth.contexts— a named combination of a cluster + a user + an optional 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, like a cloud provider's CLI or 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 — aws eks update-kubeconfig, gcloud container clusters get-credentials, az aks get-credentials. 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.