Kubectl Proxy: How to Start, Stop, Use & Troubleshoot (with Examples)

⇩ Download!

Priyansh Khodiyar

Author

Share with friends

This tutorial be helpful for beginners as well as experienced developers, it will equip you with all the knowledge you need to effectively utilize kubectl proxy in your Kubernetes workflow.

Let's roll!

What is Kubectl Proxy?

Kubectl proxy is a command-line tool that creates a proxy server between your local machine and a Kubernetes cluster. It does so by establishing a secure connection, allowing you to access Kubernetes services and resources without exposing them directly to the internet.

You must have heard the word 'proxy' during your university days, well it turns out, Kubernetes proxy is not that different.

With kubectl proxy, you can conveniently interact with APIs and debug applications running within the cluster.

In order to better understand 'kubectl proxy', let's use a code example using Minikube, a popular tool for running Kubernetes locally.

Also Read: Kubectl Cheat Sheet - A Complete List of Kubectl Commands with Examples

How to Setup Minikube?

Step 1:

Install Minikube on your local machine. Find installation instructions specific to your computer on the Minikube GitHub page.

Step 2:

Start Minikube by creating a local Kubernetes cluster. Open a terminal or command prompt and type the following:

minikube start

This will start a virtual machine that hosts the Kubernetes cluster.

Step 3:

Verify the cluster running status by executing the following command.

kubectl cluster-info

The above command will give the following output.

Kubernetes control plane is running at https://127.0.0.1:32768

Congrats, your Kubernetes cluster pane is running.

Now that you have set up a Kubernetes cluster using Minikube, let's see how to start the kubectl proxy.

Also Read: Kubectl Config Set-Context Tutorial

Starting Kubectl Proxy

Step 1:

Open a new terminal or command prompt window.

Step 2:

Run the following command to start the kubectl proxy:

kubectl proxy

Let's look at its output.

Starting to serve on 127.0.0.1:8001

The kubectl proxy starts a proxy server on your local machine, listening on port 8001.

Additional Notes on Kubectl Proxy

• The default port used by kubectl proxy is 8001, but you can specify a different port by using the --port flag when starting the proxy. For example, you can run kubectl proxy --port=8888 to use port 8888.

• By default, kubectl proxy only listens on the loopback interface (localhost), which means it can only be accessed from the same machine. If you want to make it accessible from external devices or other machines, use the --address flag. For example, kubectl proxy --address=0.0.0.0 allows access from external sources.

• Remember that kubectl proxy is mainly intended for development and debugging purposes. For production deployments, it is recommended to employ secure and controlled access methods like load balancers, Ingress controllers, or API gateways.

• To run kubectl proxy in the background and free up the terminal or command prompt for other tasks, you can append an ampersand (&) at the end of the command. For example, kubectl proxy & executes the proxy in the background.

How to Setup Google Kubernetes Engine (GKE)?

Step 1. Set up a Google Cloud Platform (GCP) account if you don't already have one.

Step 2. Install gcloud and authenticate with your GCP account. Find installation instructions on the Google Cloud SDK documentation.

Step 3. Create a GKE cluster using gcloud command. Run the following command:

gcloud container clusters create my-cluster --num-nodes=3 --zone=us-central1-a

This command creates a GKE cluster named "my-cluster" with three nodes in the "us-central1-a" zone.

Step 4. Verify cluster creation by executing the following command:

kubectl cluster-info

The output of the above command will be as follows:

Kubernetes control plane is running at https://...

This confirms that your GKE cluster is active.

Also Read: How to Work with Prometheus Operator in Kubernetes?

Using Services via Kubectl Proxy

Once you have the kubectl proxy running, you can easily access Kubernetes services using your local machine's browser or any HTTP client.

This provides a convenient way to interact with the services without the need to expose them directly to the internet.

To access a service through the kubectl proxy, simply follow these steps.

Step 1: First, determine the name and port of the service you wish to access. You can obtain a list of available services in your cluster by executing the following command.

kubectl get services

Step 2: Open your web browser and enter the following URL.

http://localhost:<port>/

Replace <port> with the actual port number of the service you want to access. In our example, the URL would be http://localhost:8080/.

The browser sends the request to the kubectl proxy, which forwards it to the corresponding service in the Kubernetes cluster. The response is then returned back to your browser.

You should now be able to interact with the service as if it were running locally on your machine.

Services via Kubectl Proxy: Additional Notes

• If you're using a graphical HTTP client like [Postman] or [cURL], you can make requests to the service by specifying the proxy URL. For example, with cURL: curl http://localhost:<port>/

• If the service requires authentication or uses HTTPS, you may need to provide additional headers or use the HTTPS version of the URL. Refer to the service's documentation for specific instructions.

• Remember to keep the kubectl proxy running in the terminal or command prompt window to maintain the proxy server connection while accessing services.

Exploring APIs with Kubectl Proxy

One of the powerful features of kubectl proxy is its ability to allow you to explore and interact with Kubernetes APIs using a user-friendly interface.

This can be helpful for understanding the available resources, retrieving information, and even making modifications if allowed.

To explore Kubernetes APIs using kubectl proxy, follow these steps.

Step 1. Ensure that the kubectl proxy is running.

Step 2. Open your web browser and enter the following URL: http://localhost:8001/api/

This URL points to the base API endpoint exposed by the kubectl proxy. It provides an overview of the available Kubernetes API versions.

The browser sends the request to the kubectl proxy, which forwards it to the Kubernetes API server running in your cluster. The response is then returned back to your browser.

Step 3. Explore the available API versions by clicking on the links displayed on the web page. Each API version represents a set of resources and functionalities provided by the Kubernetes cluster.

For example, you can click on the v1 link to access the core v1 API resources, such as Pods, Services, Deployments, and more. Further navigation will reveal specific endpoints and resources under each API version.

Step 4. Click on specific resources or endpoints to view more detailed information about them. This can include attributes, status, metadata, and other relevant details.

For instance, clicking on the pods link under the v1 API version will display a list of all Pods running in your Kubernetes cluster.

Clicking on a specific Pod will show detailed information about that Pod, such as its status, labels, and more.

You can explore different resources and endpoints to get insights into the Kubernetes cluster's state and configuration.

Additional Notes: APIs with Kubectl Proxy

• You can also make HTTP requests to specific API endpoints using tools like cURL or Postman by specifying the appropriate URL with the kubectl proxy. For example:

curl http://localhost:8001/api/v1/namespaces/default/pods

• This command retrieves a list of Pods in the default Kubernetes namespace by making a direct request to the Kubernetes API server through the kubectl proxy.

• Be cautious when interacting with APIs using the kubectl proxy, as some operations can have a significant impact on your cluster.

Also Read: How to Manage K8s Cluster using Kubeadm

Securing Kubectl Proxy: Enabling Authentication and Authorization

Here are some important considerations for securing the kubectl proxy:

1.Enable authentication by configuring the Kubernetes API server.

2.Enable authorization using Role-Based Access Control (RBAC).

Kubernetes provides various authentication and authorization mechanisms, some of which are:

• Token-based Authentication: Users authenticate using a bearer token associated with their Kubernetes user account.

• Client Certificates: Users authenticate using TLS client certificates.

• OpenID Connect (OIDC): Users authenticate using an external OIDC provider, such as Google or Azure AD.

• Service Account Tokens: Pods and services within the cluster can authenticate as service accounts.

Kubectl Proxy Security: Additional Notes

• When deploying Kubernetes clusters in production environments, it's recommended to use secure access methods like load balancers, Ingress controllers, or API gateways, which provide additional security features and granular control over access.

• Remember that securing the kubectl proxy is just one aspect of overall Kubernetes cluster security. It's crucial to follow best practices for securing other components like the API server, etcd, and worker nodes.

Also Read: Top 13 Heroku Alternatives to Use in 2023

How to Stop Kubectl Proxy?

In the terminal or command prompt where the kubectl proxy is running, press Ctrl + C to interrupt/stop the running process.

If you started the kubectl proxy in the background by appending an ampersand (&) to the command (kubectl proxy &), you can stop the proxy by finding its process ID (PID) and then sending a termination signal to it.

ps aux | grep "kubectl proxy"

Look for the line that contains the kubectl proxy process and note the corresponding PID. Then, use the kill command to send the termination signal:

kill <pid>

How to Configure Kubectl Proxy in settings.yaml File?

Here's how to configure the proxy settings in the settings.yaml file.

Step 1. Locate the kubectl configuration directory. The default location for the configuration directory is:

• Linux: $HOME/.kube/

• macOS: $HOME/.kube/

• Windows: %USERPROFILE%/.kube/

Step 2. Open the config file in a text editor in your OS.

Step 3. Look for the proxy section in the config file. If it doesn't exist, you can add it under the clusters section.

Here's what it will look like.

clusters:
- name: my-cluster
  ...
  proxy:
    httpProxy: http://proxy.example.com:8080
    httpsProxy: http://proxy.example.com:8080
    noProxy: localhost,127.0.0.1

• httpProxy: Specify the HTTP proxy URL, including the protocol (e.g., http://) and the proxy address with the port number.

• httpsProxy: Specify the HTTPS proxy URL, including the protocol (e.g., http://) and the proxy address with the port number.

• noProxy: Specify a comma-separated list of hostnames or IP addresses that should bypass the proxy.

Step 4. Save the config file.

After configuring the proxy settings in the settings.yaml file, now kubectl will use the updated proxy settings for communicating with the cluster.

How Does Kubectl Proxy Work?

If you have followed along till here, I believe you have a fair idea of what kubectl proxy does.

Here's how the kubectl proxy does it.

Step 1. When you run the kubectl proxy command, it starts a local HTTP server on your machine.

Step 2. The proxy server listens on a specific port (by default, 8001) on the localhost. It only accepts connections from the local machine, thus increasing security by limiting access to the proxy.

Step 3. The proxy server establishes a connection with the Kubernetes API server, which usually runs on a different machine or in a remote cluster.

Step 4. When you send an HTTP/HTTPS request to the proxy server, it forwards the request to the API server through a secured tunnel. The request is routed based on the provided path and specified method.

Step 5. The API server processes the request and returns the response to the proxy server.

Step 6. The proxy server then forwards the response back to your local machine, which can be accessed through the original HTTP/HTTPS request.

Also Read: Top 9 Kubernetes Distributions

Most Common Flags for Kubectl Proxy with Examples

Below are the most commonly used flags with the kubectl proxy.

--disable-filter

This kubectl proxy flag disables the filtering of non-resource URLs by the proxy server.

By default, the proxy filters out non-resource URLs to prevent potential security risks. Only use this flag if the need is to access non-resource URLs through the proxy.

kubectl proxy --disable-filter=true

--accept-hosts

Allows specific hostnames or IP ranges to bypass/evade the proxy. Useful when you don't want to include certain hosts from being proxied.

kubectl proxy --accept-hosts='localhost,example.com'

--reject-paths

This specifies a regex for rejecting certain paths.

kubectl proxy --reject-paths='^/metrics'

--api-prefix

This kubectl proxy specifies a prefix to be added to all proxied requests. This is especially useful when you want to proxy requests to an API prefix or path that is specified.

kubectl proxy --api-prefix='/api/v1'

--kubeconfig

This pecifies the path to the kubeconfig file that contains cluster information (authentication and configuration information).

Use this flag when you have multiple kubeconfig files or need to switch between different configurations.

kubectl proxy --kubeconfig=/path/to/kubeconfig

Also Read: Top 24 Kubernetes Best Practices

When to Use Kubectl Proxy?

Exploring Kubernetes APIs

APIs enable you to make HTTP/HTTPS requests to various API endpoints and retrieve information about resources, pods, deployments, namespaces, and many more.

Debugging and Troubleshooting

If you want to debug or troubleshoot issues in your Kubernetes cluster, use kubectl proxy for accessing and analyzing the cluster's APIs and resources.

Inspect logs, metrics, and other needy information using tools like good old `curl'.

Developing and Testing Applications

If you are a dev and you are developing applications that interact with Kubernetes APIs (pretty cool), kubectl proxy allows you to test and validate your application's behavior by making API requests directly from your local machine.

Bypassing Network Restrictions

In some network environments where direct access to the Kubernetes cluster's API server is restricted, kubectl proxy can help bypass those restrictions by establishing a local tunnel with the cluster.

Alternatives to Kubectl Proxy for Accessing Your Application in Cluster

Port Forwarding

Kubernetes supports port forwarding (of course it does), which allows you to forward a local port to a specific port on a pod within our cluster.

This helps you to access your application directly from your local machine.

kubectl port-forward pod/my-pod 8080:80

Ingress

If you have an Ingress controller set up in your cluster, you can use Ingress rules to expose your application externally, and what it means is, ingress allows you to define routing rules and access your application using a domain or a specific path.

Controllers like Nginx Ingress or Traefik can handle the traffic and route it to various other services within the cluster.

NodePort

The NodePort service type in Kubernetes allows you to expose your application on a static port on each node in the cluster.

What it means is that this makes your application accessible externally by accessing any node's IP address and the specified port.

ClusterIP

If you only need internal access to the cluster, the best thing to do is to expose your application using a ClusterIP service.

This allows other services within the cluster to access your application using the service's IP address and port.

Also Read: How to Set up Multiple Apps Using One Load Balancer in K8s?

Kubectl Port-Forward vs Kubectl Proxy

Both kubectl port-forward and kubectl proxy are commands provided by kubectl to facilitate accessing applications within a Kubernetes cluster, but they serve different purposes and have very different use cases.

Let's draw a comparison between kubectl port-forward and `kubectl proxy, shall we?

kubectl port-forward

Purpose: kubectl port-forward helps you to forward a local port on your machine to a specific port on a pod within the cluster. It can establish a direct network connection between your local machine and the pod you selected.

Use Case: Use kubectl port-forward when you want to access a particular pod or service within the cluster from your local machine. Commonly used for debugging, testing, or interacting with individual pods.

Example:

kubectl port-forward pod/my-pod 8080:80

The above command forwards local port 8080 to port 80 on the my-pod pod, allowing you to access the pod's application on http://localhost:8080.

kubectl proxy

Purpose: kubectl proxy creates a proxy server on your local machine that forwards HTTP/HTTPS requests to the Kubernetes API server running in the cluster. It enables you to access the Kubernetes API and resources through a local URL.

Use Case: Use kubectl proxy when you want to interact with the Kubernetes API server or access Kubernetes resources from your local machine. Commonly used for exploring APIs, retrieving information, or making API requests.

Example:

kubectl proxy --port=8001

This starts a proxy server on port 8001, allowing you to access Kubernetes APIs and resources through http://localhost:8001.

Also Read: How to Use Kubernetes Secrets?

Troubleshooting Kubectl Proxy

Time for some troubleshooting, let's see the common errors you might run into and related solutions.

1.Port Already in Use

If a port is already configured to be used elsewhere, stop that particular port from being used or use a different port address.

To use a different port, use the --port flag when starting the proxy:

kubectl proxy --port=8888

2.Connection Refused or Unable to Establish

It might happen that you are unable to connect to the proxy or received a "connection refused" error, chances are, there might be an issue with the proxy server or its configuration.

We have listed some scenarios for you to check, below:

• Make sure that the proxy is running on the expected port. By default, it runs on port 8001.

• Verify network and firewall settings. There should be no network restrictions or firewall rules that are blocking the connection to the proxy server.

• Is the Kubernetes cluster reachable? Check that your machine has connectivity to the Kubernetes cluster. Use kubectl cluster-info command to check the cluster's status.

3.Access Denied or Unauthorized

If you receive an error saying "access denied" or "unauthorized" when accessing a service or Kubernetes API through the kubectl proxy, it means a lack of proper permissions or authentication. If this is the case, the points below can help.

• Do you have the necessary permissions to access the required resources? Check with your cluster administrator or review your RBAC (Role-Based Access Control) configuration and see that your user or service account has the appropriate roles and permissions granted.

• Authenticate with the cluster. If your cluster requires authentication (which is likely the case), make sure you are providing the authentication credentials, such as bearer tokens, client certificates, or OIDC authentication tokens.

4.Proxy Server Hanging or not responsive

If the kubectl proxy becomes unresponsive or hangs while running, it may be due to reasons, like network issues, a large number of concurrent connections, or system resource constraints.

Follow these troubleshooting steps:

• Double-check your network connection to make sure that you have stable connectivity to the cluster.

• Restart the proxy. Stop the proxy using Ctrl + C and start it again.

• You might want to allocate more system resources or run the proxy on a machine with higher capabilities.

Kubectl Proxy: Final Words

Looks like we have reached the end of the article. What are you gonna do with all these learnings about kubectl proxy?

Break some pods?

This really was some long tutorial I must say, if you are reading this, chances are you now know a lot about Kubernetes proxies (not kube-proxy).

Use your newly found knowledge and build some awesome containers!

Share with friends

Written by Priyansh Khodiyar

TwitterLinkedIn

Priyansh is the founder of UnYAML and a software engineer with a passion for writing. He has good experience with writing and working around DevOps tools and technologies, APMs, Kubernetes APIs, etc and loves to share his knowledge with others.

Further Reading