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

Short description

When you use RDS Proxy to connect to RDS DB instances or Aurora DB instances, your connection might fail for the following reasons:

• Your security group rules for the DB instance or for the RDS Proxy prevent the connection.
• You connected from outside a virtual private cloud (VPC).
  Note: RDS Proxy only works in a VPC.
• Your DB instance doesn't accept the connection because of a modification or because the instance is in a non-available state.
• You used incorrect authentication credentials for the native username and password mode.
• You used AWS Identity and Access Management (IAM) database authentication. However, you didn't authorize the client's associated IAM user or role to connect with RDS Proxy.

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

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 the connection with usernames and passwords. For more information, see Configuring IAM authentication for RDS Proxy.

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

You can use RDS Proxy only in a VPC that isn't publicly accessible.

Note: Your DB instance can be publicly accessible.

If you connect from outside a private network, then your connection times out. To troubleshoot VPC connection issues, take one of the following actions:

• If the client is from the same VPC, then confirm that your RDS Proxy's security group allows connections from the client on the default port. For MySQL, the default port is 3306. For PostgreSQL, the default port is 5432. To allow the required traffic, add rules to the security group that you associate with the VPC.
• If the client is from a different 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 an SSH tunnel as an intermediate host.
  Note: This allows you to connect to the RDS Proxy within the same VPC.

Confirm that RDS Proxy can connect with the DB instance

To manage the connection pool, RDS Proxy must establish a connection with your DB instance. To connect, RDS Proxy uses the username and password that you store in AWS Secrets Manager. Make sure that the credentials are valid and can connect to the DB instance as any other client.

Check whether your DB instance's security group allows traffic from the RDS Proxy. Identify both the DB instance and RDS Proxy security groups. 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. To allow connections from the RDS Proxy, include the following inbound rules for the DB instance:

• Set the protocol to TCP.
• Set the port range to the port where the DB engine runs on the RDS DB instance.
• Set the source to the common security group.

If the RDS Proxy and DB instance use different security groups, then mention the RDS Proxy's security group in the DB instance security group's inbound rules. To allow connections from the RDS Proxy, include the following inbound rules for the DB instance:

• Set the protocol to TCP.
• Set the port range to the port where the DB engine runs on the RDS DB instance.
• Set the source to the security group of the RDS Proxy.

Make sure that the RDS Proxy security group's outbound rule allows the required traffic. The security group must include the following outbound rules:

• Set the protocol to TCP.
• Set the port range to the port where the DB engine runs on the RDS DB instance.
• Set the destination to the security group of the DB instance.
  Note: If you set the RDS Proxy security group's outbound rule to ALL --- 0.0.0.0/0, then you don't have to explicitly add the security group.

Confirm that the IAM role that you associate with the RDS Proxy has the following attributes:

• The IAM role has the trust policy for rds.amazonaws.com.
• The IAM policy has access to call the secretsmanager:GetSecretValue action on the secret.
• The IAM policy has access to call the kms:Decrypt action on the AWS Key Management Service (AWS KMS) key that encrypted the secret.
  Note: You can view the details of the AWS KMS key that Secrets Manager uses in the AWS KMS console.

Example IAM 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: Replace account_id with your AWS account ID, secret_name with your secret, region with your AWS Region, and key_id with your key ID. You must use the AWS KMS key ID in the Resource section.

If you still experience connection issues, then run the describe-db-proxy-targets AWS CLI command:

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

Note: Replace DB_PROXY_NAME with your RDS Proxy name.

In the output, review the State, Reason, and Description fields of the TargetHealth structure for information about the connection health of the RDS Proxy target.

For more information, see Verifying connectivity for a proxy.

Note: RDS Proxy uses AWS Security Token Service (AWS STS) to assume the role and connect to the database. Make sure that you activate AWS STS in your Region.

For an Amazon RDS for PostgreSQL DB instance, RDS Proxy requires the postgres database to perform health checks. To create the postgres database, run the following commands:

CREATE DATABASE postgres;
GRANT CONNECT ON DATABASE postgres TO rdsproxyadmin;

Confirm that the DB instance accepts connections

Confirm that your DB instance is in the AVAILABLE state. To view the status of your DB instance, see the following documentation:

• Viewing Amazon RDS DB instance status
• Viewing DB instance status in an Aurora cluster

If your target DB instance isn't available, then the AvailabilityPercentage RDS Proxy shows values of less than 100.

Associate your IAM user and role with a client that has the required permissions

Note: If you activate IAM database authentication on your RDS Proxy, then you must complete this step.

The client must generate a token to authorize the connection request. To do this, the IAM user and IAM role that you associate with this client must have the rds-db:connect IAM policy. Also, make sure to use the RDS Proxy ID in the Amazon Resource Name (ARN) for the Resource attribute. Example Resource attribute:

"Resource": "arn:aws:rds-db:region:account_id:dbuser:prx-ABCDEFGHIJKL01234/db_user"

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

Review the RDS Proxy logs

Activate Enhanced Logging for RDS Proxy to view detailed information about the SQL statements to understand your authentication issues. It's a best practice to only activate Enhanced Logging to debug because the logs add to performance overhead. To minimize overhead, RDS Proxy automatically deactivates this setting 24 hours after you turn it on.

Related information

Amazon RDS Proxy