Understanding kubectl port-forward (with examples)

Introduction

kubectl port-forward is a powerful command used within the Kubernetes ecosystem to help developers access services from their local machine. This command simplifies a great deal of development and debugging processes by allowing direct interaction with applications as if they were running on a local port. It works by forwarding one or more local ports to a pod running on a Kubernetes cluster.

In this tutorial, we’ll explore the kubectl port-forward command through several examples that increase in complexity. By the end, you will have a solid understanding of how to use this tool in your own development workflow.

Prerequisites

• Access to a Kubernetes cluster
• kubectl installed and configured to communicate with your cluster
• Basic understanding of Kubernetes Pods and Services

Basic Usage

To get started, let’s consider the most straightforward usage of kubectl port-forward:

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

This command forwards traffic from your local machine’s port 8080 to port 80 of the pod named my-pod. After running this command, you should be able to access the application by visiting http://localhost:8080 on your browser.

Forwarding to a Service

Instead of forwarding to a pod, you can also forward to services within the cluster:

kubectl port-forward svc/my-service 8080:80

With this command, any local traffic on port 8080 will be forwarded to the my-service on port 80.

Multiple Port Forward

You might need to forward more than one port, which can also be achieved through kubectl port-forward. Here’s an example:

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

This forwards local ports 8080 and 8443 to the respective ports 80 and 443 on the my-pod.

Forwarding a Range of Ports

port-forward also allows for ranges of ports:

kubectl port-forward pod/my-pod 8000-8010:80-90

In this example, a range of local ports (8000 to 8010) is forwarded to the corresponding range (80 to 90) on the pod.

Using with a Deployment

When we want to forward ports to a deployment, we can first determine one of the pods:

kubectl get pods --selector=app=my-app-deploymentkubectl port-forward pod/my-app-pod-123 8080:80

This will select a pod generated by the my-app-deployment and forward the specified ports accordingly.

Specifying a Namespace

When your pod or service is in a different namespace, include it in your command:

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

This forwards port 8080 of your local machine to port 80 of the pod my-pod within my-namespace.

Accessing from Other Machines

If you need the forwarded port to be accessible from other machines, you can have kubectl listen on all interfaces:

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

This command will bind to all network interfaces, not just localhost, making the forwarded port available across the network.

Conclusion

As we have seen, kubectl port-forward can be a very flexible and handy tool when working with applications running within a Kubernetes cluster. It enables local development and debugging workflows, and with practice, you can use it to streamline your development process even further. Whether it’s for simple single-port forwarding or more advanced use cases, kubectl port-forward helps bridge the gap between your local environment and the distant Kubernetes clusters.