Skip to main content
← Back to blog
How to Use kubectl port-forward for Secure Application Access in Kubernetes
4 min read

How to Use kubectl port-forward for Secure Application Access in Kubernetes

CICube banner
The GitHub Actions dashboard helps you spot bottlenecks and optimize your CI pipeline with actionable insights.
Live Demo

Introduction​

In most scenarios, Kubernetes services are running inside a cluster, and accessing internal applications directly during the development or debugging process is hard to achieve. Port forwarding allows you to connect a local port with a specific port inside a pod running in the cluster. This enables access to an internal service-like database without exposing it publicly. This can be very useful for debugging, testing APIs, or generally inspecting services.

Prerequisites​

Before detailing the usage of kubectl port-forward, ensure the following is the case:

  • You have a working Kubernetes cluster (v1.10 or later).
  • The kubectl command-line tool is configured for your cluster.
  • PostgreSQL client installed on your local machine.

Example: Connecting to a PostgreSQL Server in Kubernetes​

Suppose there is a running PostgreSQL server in your Kubernetes cluster, and you want to connect to it from your local machine for some debugging or testing.

1. Create the PostgreSQL Deployment:​

You can do this by creating a deployment of PostgreSQL either by writing a YAML file or by just running:

kubectl apply -f https://k8s.io/examples/application/postgresql/postgres-deployment.yaml

2. Check Pod Status:​

Make sure PostgreSQL pod is up and running:

kubectl get pods

3. Expose the PostgreSQL Service:​

Create a service to expose PostgreSQL on the cluster network:

kubectl apply -f https://k8s.io/examples/application/postgresql/postgres-service.yaml

Monitoring GitHub Actions Workflows

CICube is a GitHub Actions monitoring tool that provides you with detailed insights into your workflows to further optimize your CI/CD pipeline. With CICube, you will be able to track your workflow runs, understand where the bottlenecks are, and tease out the best from your build times. Go to cicube.io now and create a free account to better optimize your GitHub Actions workflows!

CICube GitHub Actions Workflow Duration Monitoring

Check status of the service:

kubectl get service postgres

4. Forward the Local Port:​

Now use kubectl port-forward to forward your local machine's port to the PostgreSQL pod's port. For PostgreSQL, the default port is 5432.

kubectl port-forward service/postgres 5433:5432

This command will forward your local port 5433 to the 5432 port of the PostgreSQL service inside the cluster, so you can reach your PostgreSQL locally.

5. Connect to PostgreSQL:​

Once that's done, connect from your local PostgreSQL client:

psql -h localhost -p 5433 -U <your-username> -d <your-database>

6. Run a Simple Query:​

Verify the connection by running a light SQL query, such as:

SELECT version();

How Does kubectl port-forward Work?​

This is achieved through the use of the kubectl port-forward command via the Kubernetes API server, establishing a secure tunnel between your local machine and the Kubernetes pod. It ensures that the traffic to the local port is forwarded securely to the correct pod's port so that you can work with services as if they were running locally inside the cluster.

Use Cases for kubectl port-forward​

  • Application debugging: Connect to applications running in pods for debugging without exposing them to outside world.
  • Database Access: To be able to access or manipulate databases, such as PostgreSQL, directly from a developer's machine.
  • Testing Web Applications: You can forward ports so that web applications running in Kubernetes pods are accessible locally.
  • Forward all API ports: This will test internal services from inside your machine.

Best Practices​

  • Production Use One important guideline is that a connection should not be forwarded in a production environment unless the connection is secured.
  • Limit Exposure: Always bind to localhost unless there is an explicit need to expose services to the outside world.
  • Secure Authentication: Strong authentication is applied to sensitive services, such as databases.

Conclusion​

kubectl port-forward helps developers and DevOps engineers to work with a Kubernetes cluster in an easy and secure way. That is very useful for internal service access, such as PostgreSQL, without exposing them to the public. Whether debugging, using APIs for testing, or database access, port forwarding allows you to interact with services as if they were running locally. These tools are very handy during development. However, using them in production is highly cautionary because of the unintended exposure.