Start your free 14-day ContainIQ trial

Using Kubectl Proxy | Tutorial

In this guide, we explain to readers the use case for the Kubectl Proxy command and show readers how to use effectively.

September 8, 2022
Kumar Harsh
Software Developer

Kubernetes is among the most popular container orchestration frameworks on the market today. It enables you to deploy containerized applications in clusters and scale them as needed. Most Kubernetes users rely on <terminal inline>kubectl<terminal inline>, an open-source CLI, to interact with their Kubernetes setup.

This guide will show you how to use the <terminal inline>kubectl proxy<terminal inline> command to communicate with your cluster’s API server without having to pass through authentication and authorization every time.

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 <terminal inline>type: NodePort<terminal inline> or <terminal inline>type: LoadBalancer<terminal inline>. 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 <terminal inline>kubectl proxy<terminal inline> 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 <terminal inline>kubectl proxy<terminal inline> command:

kubectl proxy --port=8080

You’ll receive a similar output:

Starting to serve on

A proxy has been started, and now you can directly access the Kubernetes API by sending requests to <terminal inline><terminal inline>. 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 <terminal inline>kubectl proxy<terminal inline> command offers a few options:

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

kubectl proxy --address=""
  • 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 <terminal inline>8001<terminal inline> 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 <terminal inline>kubectl proxy<terminal inline> 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 <terminal inline>hostNetwork: true<terminal inline> 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 <terminal inline>hostPort: 8080<terminal inline> 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 K8s cluster. Creating a service of <terminal inline>type: NodePort<terminal inline> and setting a <terminal inline>nodePort<terminal inline> 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

You’ll often need to access the Kubernetes API on your cluster from your dev machine. The <terminal inline>kubectl proxy<terminal inline> command is meant to help you do just that as simply as possible. In this guide, we demonstrated how to use the command and shared some alternative methods.

Start your free 14-day ContainIQ trial
Start Free TrialBook a Demo
No card required
Kumar Harsh
Software Developer

Kumar is a software developer and technical author. He has written for a number of software companies including LogRocket and Career Karma. Kumar previously worked for Goldman Sachs as a Summer Analyst. He is currently pursuing a Bachelor of Technology in Computer Science at the National Institute of Technology, Patna.