Skip to main content

Accessing your RDS database

When you create an RDS instance using the RDS module, it is created inside a virtual private cloud (VPC), which will only accept network connections from within the kubernetes cluster. So, trying to connect to the RDS instance from your local machine will not work.

+--------------+      outside      \ /       inside           +--------------+
| Your machine | -------------------X-----------------------> | RDS instance |
+--------------+                   / \                        +--------------+
                               VPC Boundary

If you need to access your database from outside the cluster (e.g. from your own development machine, or to perform a bulk data import), you can do so via the following steps:

  1. Run a pod inside the cluster to forward network traffic to your RDS instance
  2. Tell kubernetes to forward traffic from your local machine to the new pod
  3. Access the database as if it were running on your local machine

So, the connection from your machine to the RDS instance works like this:

+--------------+             +---------------------+          +--------------+
| Your machine |------------>| Port forwarding pod |--------->| RDS instance |
+--------------+             +---------------------+          +--------------+

1. Run a port-forward pod

There are several docker images designed to forward network traffic, but you need one which does not run as root.

The cluster pod security policy (PSP) will prevent any images from running a process as the root user, so docker images which expect to do this will not work.

We will use ministryofjustice/port-forward for this example.

kubectl \
  -n [your namespace] \
  run port-forward-pod \
  --image=ministryofjustice/port-forward \
  --port=5432 \
  --env="REMOTE_HOST=[your database hostname]" \
  --env="LOCAL_PORT=5432" \
  --env="REMOTE_PORT=5432"

Use port 1433 for MS-SQL.

This creates a pod in your namespace, but without a deployment to manage it.

Manually-created pods (i.e. those which are not part of a deployment) block some cluster operations such as draining a node in order to replace it. For this reason, we have set up an automated process which will delete any such pods after 24 hours. If you need a port-forward pod to persist longer than this, please make it part of a deployment.

2. Forward local traffic to the port-forward-pod

Now you need to forward network traffic from a port on your local machine to the port-forward pod inside the cluster.

kubectl \
  -n [your namespace] \
  port-forward \
  port-forward-pod 5432:5432

Use port 1433 for MS-SQL.

You need to leave this running as long as you are accessing the database.

3. Access the database

Now you can connect to the database as if it were running locally, on your machine.

If you are exporting a database URL from your RDS kubernetes secret, it might have a value like this:

postgres://cpDvquXO5B:R1eDN0xEUnaH6Aqr@cloud-platform-df3589e0e7acba37.cdwm328dlye6.eu-west-2.rds.amazonaws.com:5432/dbdf3589e0e7acba37

For MS-SQL, use sqlcmd for MacOS and test with a command like

sqlcmd -S tcp:127.0.0.1,1433 -U $user -P $pass -Q 'select @@version'

You can use this URL to connect to your database via the port forward you have set up, but you need to replace the database hostname, (cloud-platform-df3589e0e7acba37.cdwm328dlye6.eu-west-2.rds.amazonaws.com in this example), with localhost.

So, if you were starting from the database URL above, the database connection command you will run on your local machine would be:

psql postgres://cpDvquXO5B:R1eDN0xEUnaH6Aqr@localhost:5432/dbdf3589e0e7acba37

If you are exporting the database credentials separately, the command would be something like this:

psql \
  --host localhost \
  --port 5432 \
  --dbname [your database name] \
  --username [your database username] \
  --password

(You will be prompted to enter the database password, which you should get (and then base64 decode) from your kubernetes secret)

4. Delete the port-forward pod

Please remember to delete the port-forwarding pod when you have finished.

kubectl delete pod port-forward-pod -n [your namespace]
This page was last reviewed on 23 August 2021. It needs to be reviewed again on 23 November 2021 .
This page was set to be reviewed before 23 November 2021. This might mean the content is out of date.