Share with friends
In this tutorial, we will dive deep into kubectl proxy, a powerful command-line tool for accessing and forwarding Kubernetes services and resources.
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 runkubectl 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
NAME
and PORT(S)
columns for the service you want to access. In this example, the service name is my-service
, and it's running on port 8080
.
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.
The proxy settings configured in the settings.yaml
file will be applied globally to all clusters defined in the file. If you only want to configure proxy settings specific to a particular cluster, you can create separate config
files for each cluster and then switch between them using the KUBECONFIG
environment variable or the --kubeconfig
flag when running kubectl
commands.
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