kubectl-proxy

Run a proxy using the default settings on port 8001 and listen on localhost

$ kubectl proxy

$ kubectl proxy [[-w|--www]] [path/to/static_dir] [[-P|--www-prefix]] [/static_prefix/] --api-prefix [/api_subset/]

$ kubectl proxy --api-prefix [/custom_prefix/]

$ kubectl proxy [[-p|--port]] [port] [[-w|--www]] [path/to/static_dir]

$ kubectl proxy [[-p|--port]] 0

$ kubectl proxy [[-u|--unix-socket]] [path/to/socket]

$ kubectl proxy --address 0.0.0.0 --accept-hosts '.*'

$ kubectl proxy --accept-paths '^/api/v1/namespaces/default/.*' --reject-paths '^/api/.*/pods/.*/exec'

kubectl proxy [--port=PORT] [--accept-hosts=REGEXP] [--address=ADDRESS] [--disable-filter=BOOL] [--keepalive=DURATION] [--www=DIR] [--www-prefix=PREFIX] [flags]

-p, --port=PORT
    The local port on which to run the proxy. Defaults to 8001. Set to 0 to pick a random available port.

--address=ADDRESS
    The IP address or hostname for the proxy to listen on. Defaults to 127.0.0.1 (localhost). Use 0.0.0.0 to listen on all network interfaces.

--accept-hosts=REGEXP
    A regular expression for hosts that the proxy should accept. Requests from hosts not matching this pattern will be rejected.

--append-slash=true|false
    If true, all request paths will automatically end with a '/'. Defaults to true.

--api-prefix=PATH
    The prefix for API calls to Kubernetes. Defaults to '/'. Useful for routing.

--disable-filter=true|false
    If true, disable API filtering. This will allow the proxy to serve all API paths, including raw data. Defaults to false.

--keepalive=DURATION
    Keepalive duration for the HTTP server in a format like '1h', '30m', or '60s'. Defaults to 0s (no keepalive).

--www=DIR
    Path to serve static files from a local directory or a resource file with the format 'filename:resource'.

--www-prefix=PATH
    The URL path prefix at which to serve static files specified by --www. Defaults to '/static/'.

--kubeconfig=PATH
    Path to the kubeconfig file to use for authentication and cluster details. (Global kubectl flag)

--context=NAME
    The name of the kubeconfig context to use. (Global kubectl flag)

--server=URL
    The address and port of the Kubernetes API server. Overrides the value in kubeconfig. (Global kubectl flag)

--namespace=NAME
    If present, the namespace scope for this command. (Global kubectl flag)

The kubectl proxy command creates a local HTTP proxy that allows direct, authenticated access to the Kubernetes API server from your local machine. It simplifies interaction with the cluster's REST API by handling authentication and basic routing, making it appear as if the API server is running locally on a specified port (default 8001).

This command is primarily used for several purposes: testing and debugging local applications that need to interact with the Kubernetes API, accessing the Kubernetes dashboard, or other web-based UIs that connect through the API. It eliminates the need for applications to manage their own authentication tokens or certificates, as kubectl proxy leverages your existing kubeconfig setup.

It acts as a reverse proxy, forwarding requests from your local machine to the Kubernetes API server and then returning the responses. While convenient for development and internal tools, it's generally not recommended for production exposure due to its basic security model and single-point-of-failure nature.

The kubectl proxy command provides unauthenticated access from the local machine to the Kubernetes API server. Anyone with access to the machine running the proxy can access the cluster's API endpoints via the proxy without further authentication.

While you can restrict accepted hosts with --accept-hosts and the listening address with --address, caution should be exercised, especially when binding to '0.0.0.0' or running on a public server. It is not designed to be a secure, production-grade API gateway or ingress solution.

Start proxy on default port 8001:
kubectl proxy

Start proxy on a specific port:
kubectl proxy --port=8080

Start proxy listening on all interfaces (caution!):
kubectl proxy --address=0.0.0.0

Accessing API endpoints through the proxy:
Once the proxy is running, you can access the Kubernetes API at http://localhost:8001/api/v1/. For example, to list all pods in a specific namespace:
curl http://localhost:8001/api/v1/namespaces/default/pods

Serving local static content along with API:
kubectl proxy --www='./static_files' --www-prefix='/ui/'
This would serve files from the local 'static_files' directory at http://localhost:8001/ui/.

By default, kubectl proxy listens only on localhost (127.0.0.1), limiting access to the machine where it is running. This is generally safe for personal use.

If you change the --address to 0.0.0.0, the proxy will listen on all available network interfaces, making it accessible from other machines on the network. This significantly increases the security risk as any client that can reach the proxy's IP and port can then access your Kubernetes cluster API.

The --accept-hosts flag provides a layer of defense, allowing you to specify a regular expression for the 'Host' header of incoming requests. Only requests with a matching 'Host' header will be processed. For example, --accept-hosts='^localhost$,^192.168.1.100$' would only allow requests from localhost or a specific IP address.

The kubectl proxy command has been an integral part of the Kubernetes CLI (kubectl) since its early versions, offering a foundational method for developers and administrators to interact with the Kubernetes API server locally. Its core functionality has remained largely consistent, reflecting its stable and essential role in the Kubernetes ecosystem for local development, debugging, and dashboard access. It was designed to leverage existing kubeconfig authentication, simplifying access to the cluster's resources without complex manual setup.

kubectl port-forward(1), kubectl get(1), kubectl config(1), curl(1)