Connect to a database from your computer

This guide shows you how to connect to a database via localhost on a specific port.

Reference implementation

See how RDS bastion is configured in pirates-iac.

Things to consider

The database will be accessible by anyone who can log in to the AWS account.

If you choose to omit the optional step involving the setup of VPC endpoints, it's important to understand the implications. When you run the ok forward command, as outlined in this guide, it initiates an ECS task running Nginx. This setup allows the container to access your database. However, it also grants Nginx access to the entire internet, denoted by the CIDR block 0.0.0.0/0. You should consider the security implications of this, but as a general guideline, you should not run this in production.

Before you begin

You have followed the setup guide and have a working environment
You have a database in a private subnet
You have an ECS cluster in a private subnet

Step 1: Configure

Add RDS bastion package to your environment
repo-iac/environments/dev
```
ok pkg add rds-bastion
```
Update configuration
repo-iac/environments/dev/_config/rds-bastion.yml
```
StackName: "rds-bastion"
UseVPCEndpoints: false
```

Install and apply the package

repo-iac/environments/dev

ok pkg install rds-bastion
cd rds-bastion
terraform init
terraform apply

Step 2: Enhance container security with VPC endpoints (optional)

To enhance the security of your container and prevent it from accessing the internet directly, you can utilize VPC endpoints.

Before you begin

Ensure you have set up VPC endpoints. For guidance, refer to setting up networking.
Make sure you have a suitable container image in your private ECR registry. For details on setting this up, see Create and use ECR pull through cache rules.

Once you have the VPC endpoints set up and your container image in place, the next step is to enable VPC endpoint support in your Terraform configuration.

Open _config/rds-bastion.tf.
Modify the file by setting the UseVPCEndpoints variable to true.
Apply the configuration

repo-iac/environments/dev

ok pkg install rds-bastion
cd rds-bastion
terraform init
terraform apply

Step 3: Connect to database

Run the ok forward command to start the port forwarding session.
```
ok forward
```
You will be presented a list of Task Definitions which is applicable for port forwarding. Select the one you want to use using the arrow keys and press enter.
```
> ssm-pf-my-bastion-task-definition
> ssm-pf-another-bastion-task-definition
```
Now a new ECS task will be started. This usually takes 20 to 30 seconds.
Next you will be presented a list of all the RDS instances in your environment. Select the one you want to port forward to using the arrow keys and press enter.
```
> my-team-db.c7d1xxxi7fm.eu-west-1.rds.amazonaws.com
> some-other-db.c7d1xxxi7fm.eu-west-1.rds.amazonaws.com
```
Last step is to enter the ports you want to forward to and expose locally for the forwarded database.

Now the database is port forwarded and you can connect to it using the forwarded ports.

LOCAL_PORT=4812 # or replace this with the port you entered in step 4
psql --host=localhost --port=$LOCAL_PORT --username=db_username --password --dbname=postgres

When you are done, press Ctrl+C to stop the port forwarding session.

If you don't stop the port forwarding session manually, it will be stopped automatically by the Lambda function after some time of inactivity.

builds/ directory

What is the builds directory?

terraform apply will create a directory called builds. This should be committed to your IaC repository. If not, future runs of terraform apply will always detect a change. Sometimes terraform plan/apply will report a change even though the code has not changed. This is due to the hash changing and it is normal expected behavior.