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.
You need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. It is recommended to run this tutorial on a cluster with at least two nodes that are not acting as control plane hosts. If you do not already have a cluster, you can create one by using minikube or you can use one of these Kubernetes playgrounds:
Your Kubernetes server must be at or later than version v1.10. To check the version, enterkubectl version
. Install MongoDB Shell.
Create a Deployment that runs MongoDB:
kubectl apply -f https://k8s.io/examples/application/mongodb/mongo-deployment.yaml
The output of a successful command verifies that the deployment was created:
deployment.apps/mongo created
View the pod status to check that it is ready:
kubectl get pods
The output displays the pod created:
NAME READY STATUS RESTARTS AGE
mongo-75f59d57f4-4nd6q 1/1 Running 0 2m4s
View the Deployment's status:
kubectl get deployment
The output displays that the Deployment was created:
NAME READY UP-TO-DATE AVAILABLE AGE
mongo 1/1 1 1 2m21s
The Deployment automatically manages a ReplicaSet. View the ReplicaSet status using:
kubectl get replicaset
The output displays that the ReplicaSet was created:
NAME DESIRED CURRENT READY AGE
mongo-75f59d57f4 1 1 1 3m12s
Create a Service to expose MongoDB on the network:
kubectl apply -f https://k8s.io/examples/application/mongodb/mongo-service.yaml
The output of a successful command verifies that the Service was created:
service/mongo created
Check the Service created:
kubectl get service mongo
The output displays the service created:
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
mongo ClusterIP 10.96.41.183 <none> 27017/TCP 11s
Verify that the MongoDB server is running in the Pod, and listening on port 27017:
# 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:
27017
(this is the TCP port allocated to MongoDB on the internet).
kubectl port-forward
allows using resource name, such as a pod name, to select a matching pod to port forward to.
# Change mongo-75f59d57f4-4nd6q to the name of the Pod
kubectl port-forward mongo-75f59d57f4-4nd6q 28015:27017
which is the same as
kubectl port-forward pods/mongo-75f59d57f4-4nd6q 28015:27017
or
kubectl port-forward deployment/mongo 28015:27017
or
kubectl port-forward replicaset/mongo-75f59d57f4 28015:27017
or
kubectl port-forward service/mongo 28015:27017
Any of the above commands works. The output is similar to this:
Forwarding from 127.0.0.1:28015 -> 27017
Forwarding from [::1]:28015 -> 27017
kubectl port-forward
does not return. To continue with the exercises, you will need to open another terminal. Start the MongoDB command line interface:
mongosh --port 28015
At the MongoDB command line prompt, enter the ping
command:
db.runCommand( { ping: 1 } )
A successful ping request returns:
{ ok: 1 }
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:
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:
Forwarding from 127.0.0.1:63753 -> 27017
Forwarding from [::1]:63753 -> 27017
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.
kubectl port-forward
is implemented for TCP ports only. The support for UDP protocol is tracked in issue 47862. Learn more about kubectl port-forward.
© 2022 The Kubernetes Authors
Documentation Distributed under CC BY 4.0.
https://kubernetes.io/docs/tasks/access-application-cluster/port-forward-access-application-cluster/