kubectl proxy: Usage, Options & Common CI Errors
Expose the Kubernetes API on localhost with auth handled for you.
kubectl proxy runs a local HTTP proxy that forwards to the API server, injecting your credentials so plain curl can hit the raw API. In CI it is handy for scripting against API endpoints that kubectl does not wrap.
What it does
kubectl proxy listens on 127.0.0.1:8001 by default and proxies every request to the API server using your kubeconfig auth. --port changes the port, --address the bind interface, and --api-prefix the path root. It runs in the foreground until interrupted.
Common usage
kubectl proxy --port=8001 &
curl -s http://localhost:8001/api/v1/namespaces/default/pods
curl -s http://localhost:8001/healthz
kill %1 # tear the proxy downCommon errors in CI
Like port-forward, proxy backgrounds with a readiness race: curl immediately after starting it can hit "connection refused" before the listener is up - poll http://localhost:8001/healthz until it answers before the real requests, and always kill the process in a trap so the step does not hang. "address already in use" means a prior proxy on the same port leaked from an earlier step; pick a unique port or clean up. By default proxy binds only to localhost, so a request from another container or host fails until you set --address and --accept-hosts, which you should do cautiously.
Using this in CI
A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods
# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info
# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes