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.