Connecting to a database or message broker running in OpenShift

Updated 21 September 2020

Here’s a tip that will help you speed up your cloud-native development for OpenShift.

You’re busy adding some database persistence to your application….

update disco set more_cowbell = '1'

But if your database is running inside OpenShift, then how do you talk to it from your dev workstation? You don’t want to have to redeploy your application to OpenShift every time you make a tiny code change. That would be a bit tedious.

So how do you save time by developing and running your application locally, while it connects to a database running inside OpenShift?

Fortunately OpenShift has a feature called port forwarding which helps you do this.

What’s port forwarding?

Port forwarding is another way to expose an application outside OpenShift. It’s not the usual way to expose an application to the outside world. It’s just a temporary solution. You might use port forwarding when:

You’re developing your client application, and you need to connect it up to a database or message broker for tests, but you don’t want to have to run those components locally. So you port-forward to your database running in the OpenShift cluster.
You’re debugging an issue: you want to be able to make requests to a pod in the cluster, without having to expose it to everyone.

So it’s a nice tool to have in your OpenShift development and debugging toolkit.

Using port forwarding to connect to a database - the steps

So here’s how to connect from your local workstation to a service – like a database or a message broker – running inside OpenShift.

Here’s how you do it:

Identify the pod and port you want to connect to

First, you need to find the application you want to connect to, which is running inside OpenShift.

You need to look for the pod to connect to and get its name.

You can use the web console to do this. go to Workloads → Pods (or Applications → Pods in OpenShift 3.x). Here, I’m viewing details of my MongoDB pod:

Or, you can use the oc command line tool to get the name, using oc get pod:
Set up port forwarding for each pod

Then, for each app you want to connect to, use the oc port-forward command, to create a local port forwarder.

This sets up a proxy on your machine, so that all requests to localhost on a port of your choice, will be forwarded to a port on a pod in OpenShift.
How to know which port to forward?

You need to know which port to forward. To check the ports your Pod exposes, you can view the Pod definition in the OpenShift web console or do oc describe pod from the command line. Some typical ports are:
- Port 27017 for MongoDB
- Port 61616 for ActiveMQ.
- Port 80 for HTTP servers.
Use this command to create a port forwarder:
```
oc port-forward <pod name> <local port>:<remote port>
```
So for example, in my example, I would use:
```
oc port-forward mongodb-1-xdqzq 27019:27017
```
This creates a local proxy on port 27019, so that when I make a request to localhost:27019, it will be forwarded directly to my MongoDB pod in OpenShift, port 27017.

The port-forwarder will keep running until you quit by pressing Ctrl+C.

If you’re running Linux, you can background this command by adding & at the end, and then later use the fg command to bring it to the foreground.
Run your application and override its config to connect to localhost

Finally, run your application, and override your app’s configuration, so that it makes a request to the port-forwarder, instead of the real database.

For example, in this case I would update my database host to localhost, and the database port config to 27019.

How do you do this exactly? It depends on which language and framework you’re using. But you will probably need to edit your application’s configuration file, set an environment variable, or provide a command line argument to your app.

Just make sure that you override your app’s database host and database port configuration.
Example - with Spring Boot

Since I’m a Spring Boot kind of a guy, I’m using Spring Boot as an example. If I have an application.properties file that looks like this:
```
spring.data.mongodb.host=mydatabaseserver
spring.data.mongodb.port=27017
```
Then, I can run my Spring Boot 2.x app like this, using the Spring Boot Maven Plugin’s run.arguments option to override my MongoDB connection settings, passing in localhost port 27019:
```
mvn clean spring-boot:run \
  -Drun.arguments=--spring.data.mongodb.host=localhost,--spring.data.mongodb.port=27019
```
Or, if you are using Spring Boot 1.x, you can do it like this:
```
mvn clean spring-boot:run \
  -Dspring.data.mongodb.host=localhost \
  -Dspring.data.mongodb.port=27019
```
Now my application will run locally, but it will connect to my database running inside OpenShift.

That’s the basic gist. You can use port forwarding to expose a database in OpenShift, for local development.

Then, you can just repeat the same steps for any other services that you need to connect to.

For example, you might need to also connect to an ActiveMQ message broker, a cache like Redis, or maybe a microservice.

Port-forwarding is just one trick I like to use to help speed things up when developing or debugging.

So even if your database and message brokers are deployed in OpenShift, now can still develop and test locally, using port forwarding.

Go give it a try!

What’s port forwarding?

Using port forwarding to connect to a database - the steps

Identify the pod and port you want to connect to

Set up port forwarding for each pod

Run your application and override its config to connect to localhost

Comments