Use Port Forwarding to Access Applications in a Cluster

فهرست فصل‌ها دانلود آرشیوناشر

Kubernetes Docs · نسخهٔ f284a9e7c87f · CC BY 4.0 برای مستندات و مجوزهای همراه

<!-- overview -->

This page shows how to use kubectl port-forward to connect to a MongoDB server running in a Kubernetes cluster. This type of connection can be useful for database debugging.

{{% heading "prerequisites" %}}

  • {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
  • Install MongoDB Shell.

<!-- steps -->

Creating MongoDB deployment and service

  1. Create a Deployment that runs MongoDB:
shell
   kubectl apply -f https://k8s.io/examples/application/mongodb/mongo-deployment.yaml

The output of a successful command verifies that the deployment was created:

text
   deployment.apps/mongo created

View the pod status to check that it is ready:

shell
   kubectl get pods

The output displays the pod created:

text
   NAME                     READY   STATUS    RESTARTS   AGE
   mongo-75f59d57f4-4nd6q   1/1     Running   0          2m4s

View the Deployment's status:

shell
   kubectl get deployment

The output displays that the Deployment was created:

text
   NAME    READY   UP-TO-DATE   AVAILABLE   AGE
   mongo   1/1     1            1           2m21s

The Deployment automatically manages a ReplicaSet. View the ReplicaSet status using:

shell
   kubectl get replicaset

The output displays that the ReplicaSet was created:

text
   NAME               DESIRED   CURRENT   READY   AGE
   mongo-75f59d57f4   1         1         1       3m12s
  1. Create a Service to expose MongoDB on the network:
shell
   kubectl apply -f https://k8s.io/examples/application/mongodb/mongo-service.yaml

The output of a successful command verifies that the Service was created:

text
   service/mongo created

Check the Service created:

shell
   kubectl get service mongo

The output displays the service created:

text
   NAME    TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)     AGE
   mongo   ClusterIP   10.96.41.183   <none>        27017/TCP   11s
  1. Verify that the MongoDB server is running in the Pod, and listening on port 27017:
shell
   # Change mongo-75f59d57f4-4nd6q to the name of the Pod
   kubectl get pod mongo-75f59d57f4-4nd6q --template='{{(index (index .spec.containers 0).ports 0).containerPort}}{{"\n"}}'

The output displays the port for MongoDB in that Pod:

text
   27017

27017 is the official TCP port for MongoDB.

Forward a local port to a port on the Pod

  1. kubectl port-forward allows using resource name, such as a pod name, to select a matching pod to port forward to.
shell
   # Change mongo-75f59d57f4-4nd6q to the name of the Pod
   kubectl port-forward mongo-75f59d57f4-4nd6q 28015:27017

which is the same as

shell
   kubectl port-forward pods/mongo-75f59d57f4-4nd6q 28015:27017

or

shell
   kubectl port-forward deployment/mongo 28015:27017

or

shell
   kubectl port-forward replicaset/mongo-75f59d57f4 28015:27017

or

shell
   kubectl port-forward service/mongo 28015:27017

Any of the above commands works. The output is similar to this:

text
   Forwarding from 127.0.0.1:28015 -> 27017
   Forwarding from [::1]:28015 -> 27017

{{< note >}} kubectl port-forward does not return. To continue with the exercises, you will need to open another terminal. {{< /note >}}

  1. Start the MongoDB command line interface:
shell
   mongosh --port 28015
  1. At the MongoDB command line prompt, enter the ping command:
text
   db.runCommand( { ping: 1 } )

A successful ping request returns:

text
   { ok: 1 }

Optionally let _kubectl_ choose the local port {#let-kubectl-choose-local-port}

If you don't need a specific local port, you can let kubectl choose and allocate the local port and thus relieve you from having to manage local port conflicts, with the slightly simpler syntax:

shell
kubectl port-forward deployment/mongo :27017

The kubectl tool finds a local port number that is not in use (avoiding low ports numbers, because these might be used by other applications). The output is similar to:

text
Forwarding from 127.0.0.1:63753 -> 27017
Forwarding from [::1]:63753 -> 27017

<!-- discussion -->

Discussion

Connections made to local port 28015 are forwarded to port 27017 of the Pod that is running the MongoDB server. With this connection in place, you can use your local workstation to debug the database that is running in the Pod.

{{< note >}} kubectl port-forward is implemented for TCP ports only. The support for UDP protocol is tracked in issue 47862. {{< /note >}}

Authorization and security considerations

Access to kubectl port-forward is controlled by Kubernetes authorization mechanisms like {{< glossary_tooltip text="Role-Based Access Control (RBAC)" term_id="rbac" >}}. Authorization is enforced by the Kubernetes API server, not by the kubectl client.

To use kubectl port-forward, a user must have permission to access the target resource (for example, a Pod or Service) and the portforward subresource. Typical required permissions include get on pods and create on pods/portforward.

Cluster administrators should carefully restrict these permissions, as port-forwarding can provide direct network access to workloads and may bypass network-level controls.

{{% heading "whatsnext" %}}

Learn more about kubectl port-forward.