/
Troubleshooting Docker Container Connections to AWS RDS

Troubleshooting Docker Container Connections to AWS RDS

Owned by Kraig Eisenman
Last updated: Mar 12, 2025
2 min read

Problem Description

Some users may encounter connection timeouts when Docker containers try to connect to AWS RDS instances. This typically manifests as timeout errors in application logs:

psql: error: connection to server at "[rds-endpoint]" ([ip-address]), port 5432 failed: Connection timed out Is the server running on that host and accepting TCP/IP connections?

This issue commonly occurs when Docker's network configuration prevents containers from properly establishing connections to external services.

Root Cause

The issue is related to IP masquerading (NAT) not being properly enabled for Docker containers, preventing them from connecting to external services like RDS databases.

Why IP Masquerading Is Necessary

Docker containers on a bridge network receive private IP addresses (typically in ranges like 192.168.0.0/24). For these containers to communicate with external services:

  1. IP masquerading is required to modify the source IP address of outgoing packets

  2. When a container sends traffic to an external service, the packet's source address must be changed from the container's private IP to the host's IP

  3. When the external service responds, the host receives the response and forwards it to the appropriate container

Without IP masquerading:

  • Packets from containers maintain their private source IP addresses when leaving the host

  • External services cannot route responses back to these private IPs

  • Connection attempts timeout because response packets never reach the container

Diagnosis Steps

  1. Verify that your host machine can connect to the RDS instance:

    telnet your-rds-endpoint.region.rds.amazonaws.com 5432

    If you see "Connected to...", then your host has network connectivity to RDS.

  2. Check your Docker daemon configuration:

    cat /etc/docker/daemon.json

  3. Inspect your Docker bridge network settings:

    sudo docker network inspect bridge

    Check if "com.docker.network.bridge.enable_ip_masquerade" is set to "false".

Solution

Enable IP masquerading in Docker by updating the daemon configuration:

  1. Edit the Docker daemon configuration:

    sudo nano /etc/docker/daemon.json

  2. Modify the configuration to enable IP masquerading:

    { "iptables": true, "ip-masq": true, "default-address-pools": [ { "base": "192.168.0.0/16", "size": 24 } ] }

  3. Save the file and restart Docker:

    sudo systemctl restart docker

  4. Restart your containers:

    sudo docker restart your-container-id

Verification

After implementing the solution, verify the connection:

  1. Restart your container

  2. Check the container logs for successful database connections

  3. For direct testing, you can exec into the container and try connecting to RDS:

    sudo docker exec -it your-container-id bash psql -h your-rds-endpoint.region.rds.amazonaws.com -U username -d dbname

Security Considerations

  • The "ip-masq": true setting is generally safe and ensures proper NAT for container traffic

  • This setting only affects how container traffic appears to external services and doesn't compromise container isolation

Related Documentation

Related content