Why can't I connect to my Amazon RDS DB or Amazon Aurora DB instance using RDS Proxy?

Short description

You might experience connection failures with RDS Proxy for multiple reasons. The following issues are common causes for RDS Proxy connection failures, even when RDS Proxy is in the Available state:

• Security group rules, either at the DB instance or at the RDS Proxy, prevent the connection.
• RDS Proxy works only within a virtual private cloud (VPC), so connections from outside the private network fail.
• The DB instance doesn't accept the connection because of modification or because it's in a non-available state.
• For native user name and password mode: you used incorrect authentication credentials.
• For AWS Identity and Access Management (IAM) DB authentication: the IAM user or role that's associated with the client isn't authorized to connect with RDS Proxy.

Resolution

Note: If you use RDS Proxy with an RDS DB instance or Aurora DB cluster that uses IAM authentication, then all users must authenticate their connections. Make sure that all users who connect through a proxy authenticate their connection with user names and passwords. See Setting up IAM policies for more information about IAM support in RDS Proxy.

Check that the client can reach RDS Proxy within the private network of a VPC

RDS Proxy can be used only within a VPC, and can't be publicly accessible (although the DB instance can be). If you connect from outside a private network, then your connection times out. Note the following attributes for connecting within a VPC:

• If the client is from the same VPC, then check that your RDS Proxy's security group allows connections from the client on the default port. The default ports are 3306 for MySQL and 5432 for PostgreSQL. Add rules to the security group associated with the VPC to allow the required traffic.
• If the client is from another VPC, then use VPC peering. To manage the traffic from the other VPC, review the security group and route tables.
• If your client is from a corporate network, then use AWS Direct Connect or AWS Site-to-Site VPN to connect directly to the VPC.
• If your client must connect through the public internet, then use SSH tunneling as an intermediate host. This allows you to connect into the RDS Proxy within the same VPC.

Check that RDS Proxy can connect with the DB instance

To manage the connection pool, RDS Proxy must establish a connection with your DB instance. This connection uses the user name and password that's stored in the AWS Secrets Manager. Use the following best practices to make sure that RDS Proxy can connect with your DB instance:

• Check that the credentials in the Secrets Manager are valid and can connect to the DB instance.
• Make sure that your DB instance's security group allows traffic from the RDS Proxy. To do this, first determine the security group of the DB instance and RDS Proxy.

If the RDS Proxy and DB instance use the same security group, then verify that the security group's inheritance rule is in the inbound rules:

Inbound rules for the RDS instance in order to allow connections from RDS proxy:
Protocol : TCP
Port Range : Port on which the DB engine is running on the RDS instance
Source : Common security group (for self referencing the security group)

If they use different security groups, then mention the RDS Proxy's security group in the inbound rule of the DB instance's security group:

Inbound rules for the RDS instance in order to allow connections from RDS proxy:
Protocol : TCP
Port range : Port on which the DB engine is running on the DB instance
Source : Security group of RDS Proxy

The RDS Proxy initiates the connection to manage the pool. Therefore, you must allow outbound traffic to reach the DB instance. To do this, RDS Proxy security group must allow the required traffic in its outbound rule:

Protocol : TCP
Port range : Port on which the DB engine is running on the RDS instance
Destination : Security group of DB instance

Note: If you already have the following outbound rules attached to the security group of the RDS Proxy, then there is no need to explicitly add the security group. 
Outbound rules: ALL --- 0.0.0.0/0

• Check that the IAM role associated with the RDS Proxy can fetch and use the credentials that are required for connections:

The IAM role must have the trust policy for rds.amazonaws.com.

The IAM policy must have access to call the secretsmanager:GetSecretValue action on the secret.

The IAM policy must have access to call the kms:Decrypt action on the AWS Key Management Service (AWS KMS) key that encrypted the secret. You can get the details of the KMS key that's used by Secrets Manager from the AWS KMS console. Note that the KMS key ID must be used for the Resource section. See the following example policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "secretsmanager:GetSecretValue",
      "Resource": [
        "arn:aws:secretsmanager:region:account_id:secret:secret_name"
      ]
    },
    {
      "Effect": "Allow",
      "Action": "kms:Decrypt",
      "Resource": "arn:aws:kms:region:account_id:key/key_id",
      "Condition": {
        "StringEquals": {
          "kms:ViaService": "secretsmanager.region.amazonaws.com"
        }
      }
    }
  ]
}

Note: Be sure to replace account_id, secret_name, region, account_id, and key_id with your relevant values.

• For more information on what might prevent the proxy from connecting to the DB instance, run the describe-db-proxy-targets command. Then, review the TargetHealth structure in the output. Review the State, Reason, and Description fields for more information on the connection health of the RDS Proxy target:

aws rds describe-db-proxy-targets --db-proxy-name $DB_PROXY_NAME

For more information, see Verifying connectivity for a proxy.

Check that the DB instance currently accepts connections

Review the current status of your DB instance and confirm that it's in the AVAILABLE state. For more information on reviewing the status of your DB instance, see the Amazon RDS and Aurora documentation for DB instance status.

Check that the IAM user/role is associated with a client with required permissions

Note: This step is required only if you activated IAM DB Authentication on your RDS Proxy.

The client must generate a token to authorize the connection request. To do this, the IAM user and IAM role that's associated with this client must have the rds-db:connect IAM policy. Also, make sure to use the RDS Proxy ID in the ARN for the Resources attribute in the policy:

"Resource": "arn:aws:rds-db:us-east-2:1234567890:dbuser:prx-ABCDEFGHIJKL01234/db_user"

For more information, see Creating and using an IAM policy for IAM database access.

Review the RDS Proxy logs

Turn on the Enhanced Logging feature of RDS Proxy. Logging gives detailed information about the SQL statements. These logs are a useful resource to help you understand certain authentication issues. Because this adds to performance overhead, it's a best practice to turn them on only for debugging. To minimize overhead, RDS Proxy automatically turns this setting off 24 hours after you turn it on.

Related information

Using Amazon RDS Proxy

Set up shared database connections with Amazon RDS Proxy