May 14, 2024

How to use kubectl proxy

Learn how kubectl proxy exposes the Kubernetes API locally, when it helps, and what alternatives to use for application access.

kubectl proxy is a local tunnel to the Kubernetes API server. It is useful for debugging API access and exploring cluster resources from your machine. It is not an ingress strategy, and it is not how users should reach production services.

Use it when you need a quick, authenticated path to the API. Reach for port forwarding, services, or ingress when the problem is application traffic.

What is Kubectl Proxy?

A Kubernetes cluster is designed to be isolated from external access by default. Services in the cluster can easily make requests of other services in the cluster, but for an external service to communicate with the cluster resources, it needs to pass through authentication and authorization steps. This ensures that no external entity can access or modify your cluster's internal resources.

To expose internal services, you can add or create type: NodePort or type: LoadBalancer. But what if you want to access the resources through your development environment? What if you want to ping a server hosted in your Kubernetes cluster from your laptop to test whether it returns the correct response?

Typically, you'd generate a token to communicate with the Kubernetes API server and attach it to every request you send to your cluster. However, this is a very cumbersome process. And if you have multiple local processes that need to send requests to the cluster, it gets more complicated.

The kubectl proxy command makes this process more convenient while maintaining the secure architecture of Kubernetes clusters. It creates a communication channel between your local machine and your Kubernetes API server by reading the cluster configuration and credentials from your kube-config file. You can then use the local port exposed by kubectl to relay requests to your cluster without having to provide security credentials with each request.

How does Kubectl Proxy work?

Here's how you can use the kubectl proxy command:

kubectl proxy --port=8080

>> Starting to serve on 127.0.0.1:8080

A proxy has been started, and now you can directly access the Kubernetes API by sending requests to http://127.0.0.1:8080/api. Here's a curl command to fetch the details of a pod named "nginx":

curl http://localhost:8080/api/v1/namespaces/default/pods/nginx

Exploring Kubectl Proxy in detail

The kubectl proxy command offers a few options:

• address: This option helps you to change the IP address of the exposed proxy. Its default value is 127.0.0.1 (i.e. localhost)

kubectl proxy --address="127.0.0.1"

• port: You've already seen this in the example command we used above. It enables you to choose which port the proxy will be exposed from. If you do not provide this option, port 8001 will be used for exposing the proxy.

kubectl proxy --port=81

• api-prefix: This option allows you to add a prefix to the API route for the Kubernetes API server.

kubectl proxy --api-prefix=/something/# Now you can send requests to http://localhost:8001/something/api instead of the usual http://localhost:8001/api

Alternatives to Kubectl Proxy

If kubectl proxy does not meet your requirements, there are a few alternatives that might come in handy:

• hostNetwork: If you want to expose the applications in a pod to all devices connected to your host network, you can set hostNetwork: true for them. However, each pod may be shut down and restarted in a different node. This can change its base IP address, so it might not be the best solution for you. This solution is useful only when a direct connection to the host network is needed.
• hostPort: This option is applicable to containers only. You can expose an individual container's port on the host IP address by adding hostPort: 8080 to the container node in your pod's definition. This method, however, has the same shortcoming as the previous one - on each restart of the pod, the base IP address might change, so you can't rely on it for longer durations. Ales Nosek does a great job of explaining these two options on his blog.
• NodePort: This is another method you can use to expose services from your Kubernetes cluster. Creating a service of type: NodePort and setting a nodePort value for it opens up the set port on all nodes of the cluster for public access. Any requests received by the ports are forwarded directly to the service. You can read more about it here.

Final thoughts

kubectl proxy is a debugging tool for local API access. It is useful, narrow, and easy to misuse if you confuse it with application exposure. Keep it in the toolbox, but do not build workflows around it.

For day-to-day ML work, Polyaxon users should rarely need direct API proxying. The platform surfaces workload status, logs, artifacts, and controls without making every user poke the Kubernetes API.