kubectl proxy

When to Use kubectl proxy

kubectl proxy creates an HTTP proxy to the Kubernetes API server that handles authentication automatically. It is the simplest way to explore the Kubernetes REST API, access the dashboard, and develop custom tools that interact with the API without managing authentication tokens.

Starting the Proxy

# Start on default port 8001
kubectl proxy
# Starting to serve on 127.0.0.1:8001

# Start on a custom port
kubectl proxy --port=9090

# Run in background
kubectl proxy &

The proxy listens on localhost only by default, which is secure for local development. It uses your kubeconfig credentials to authenticate all requests to the API server.

Exploring the API

With the proxy running, you can explore the entire Kubernetes API using curl or a browser:

# List API versions
curl http://localhost:8001/api

# List API groups
curl http://localhost:8001/apis

# List all pods in default namespace
curl http://localhost:8001/api/v1/namespaces/default/pods

# Get a specific pod
curl http://localhost:8001/api/v1/namespaces/default/pods/my-pod

# List deployments in all namespaces
curl http://localhost:8001/apis/apps/v1/deployments

# Get a specific deployment
curl http://localhost:8001/apis/apps/v1/namespaces/default/deployments/my-app

# Watch for changes (server-sent events)
curl http://localhost:8001/api/v1/namespaces/default/pods?watch=true

API Discovery

The proxy is excellent for discovering available API resources and their paths:

# See all available resource types
curl http://localhost:8001/api/v1 | jq '.resources[].name'

# See resources in apps/v1
curl http://localhost:8001/apis/apps/v1 | jq '.resources[].name'

# Check if a CRD resource exists
curl http://localhost:8001/apis/cert-manager.io/v1 | jq '.resources[].name'

# Get the OpenAPI spec
curl http://localhost:8001/openapi/v2 > openapi-spec.json

Creating and Modifying Resources

The proxy supports all HTTP methods, allowing full CRUD operations:

# Create a namespace
curl -X POST http://localhost:8001/api/v1/namespaces \
  -H "Content-Type: application/json" \
  -d '{"apiVersion":"v1","kind":"Namespace","metadata":{"name":"test"}}'

# Patch a deployment
curl -X PATCH http://localhost:8001/apis/apps/v1/namespaces/default/deployments/my-app \
  -H "Content-Type: application/strategic-merge-patch+json" \
  -d '{"spec":{"replicas":3}}'

# Delete a pod
curl -X DELETE http://localhost:8001/api/v1/namespaces/default/pods/my-pod

Accessing Services Through the Proxy

The proxy can access services through the API server's service proxy feature:

# Access a service through the API server proxy
curl http://localhost:8001/api/v1/namespaces/monitoring/services/grafana:3000/proxy/

# Access the Kubernetes dashboard
curl http://localhost:8001/api/v1/namespaces/kubernetes-dashboard/services/https:kubernetes-dashboard:/proxy/

This feature proxies traffic through the API server to the service, which is different from kubectl port-forward that creates a direct tunnel.

Security Considerations

The proxy authenticates using your kubeconfig, so it has full access to whatever your RBAC roles allow:

# Restrict the proxy to read-only paths
kubectl proxy --accept-paths='^/api/v1/(pods|services|namespaces)$'

# Reject destructive paths
kubectl proxy --reject-paths='^/api/.*/pods/.*/exec'

Never expose the proxy to the network without restrictions. Running with --address=0.0.0.0 opens the full API to anyone who can reach the machine. If you must expose it, use --accept-paths and --reject-paths to limit access.

Development Use Cases

The proxy is commonly used in development workflows:

# Develop a custom dashboard that queries the API
# The proxy handles auth so your frontend can call the API directly

# Test webhook configurations
# Use the proxy to inspect admission webhook payloads

# Debug custom controllers
# Monitor the API server's behavior for specific resource changes
curl "http://localhost:8001/api/v1/namespaces/default/events?watch=true"

Best Practices

Use the proxy for local development and API exploration. Always restrict the listening address and paths when exposing to others. Never use the proxy as a production access mechanism. For programmatic API access in production, use proper service accounts and in-cluster authentication. Remember that the proxy runs with your personal credentials, so any request through it is attributed to your user.