Creating an RDS Proxy

To manage connections for a specified set of DB instances, you can create a proxy. You can associate a proxy with an RDS for MariaDB, RDS for Microsoft SQL Server, RDS for MySQL, or RDS for PostgreSQL DB instance.

AWS Management Console

To create a proxy

1. Sign in to the AWS Management Console and open the Amazon RDS console at https://console.aws.amazon.com/rds/.

2. In the navigation pane, choose Proxies.

3. Choose Create proxy.

4. Choose all the settings for your proxy.

   For Proxy configuration, provide information for the following:

   • Engine family. This setting determines which database network protocol the proxy recognizes when it interprets network traffic to and from the database. For RDS for MariaDB or RDS for MySQL, choose MariaDB and MySQL. For RDS for PostgreSQL, choose PostgreSQL. For RDS for SQL Server, choose SQL Server.

   • Proxy identifier. Specify a name of that is unique within your AWS account ID and current AWS Region.

   • Idle client connection timeout. Choose a time period that a client connection can be idle before the proxy closes it. The default is 1,800 seconds (30 minutes). A client connection is considered idle when the application doesn't submit a new request within the specified time after the previous request completed. The underlying database connection stays open and is returned to the connection pool. Thus, it's available to be reused for new client connections.

     To have the proxy proactively remove stale connections, lower the idle client connection timeout. When the workload is spiking, to save the cost of establishing connections, increase the idle client connection timeout."

   For Target group configuration, provide information for the following:

   • Database. Choose one RDS DB instance to access through this proxy. The list only includes DB instances and clusters with compatible database engines, engine versions, and other settings. If the list is empty, create a new DB instance or cluster that's compatible with RDS Proxy. To do so, follow the procedure in Creating an Amazon RDS DB instance. Then try creating the proxy again.

   • Connection pool maximum connections. Specify a value from 1 through 100. This setting represents the percentage of the max_connections value that RDS Proxy can use for its connections. If you only intend to use one proxy with this DB instance or cluster, you can set this value to 100. For details about how RDS Proxy uses this setting, see MaxConnectionsPercent.

   • Session pinning filters. (Optional) This option allows you to force RDS Proxy to not pin for certain types of detected session states. This circumvents the default safety measures for multiplexing database connections across client connections. Currently, the setting isn't supported for PostgreSQL. The only choice is EXCLUDE_VARIABLE_SETS.

     Enabling this setting can cause session variables of one connection to impact other connections. This can cause errors or correctness issues if your queries depend on session variable values set outside of the current transaction. Consider using this option after verifying it is safe for your applications to share database connections across client connections.

     The following patterns can be considered safe:

     • SET statements where there is no change to the effective session variable value, i.e., there is no change to the session variable.

     • You change the session variable value and execute a statement in the same transaction.

     For more information, see Avoiding pinning an RDS Proxy.

   • Connection borrow timeout. In some cases, you might expect the proxy to sometimes use all available database connections. In such cases, you can specify how long the proxy waits for a database connection to become available before returning a timeout error. You can specify a period up to a maximum of five minutes. This setting only applies when the proxy has the maximum number of connections open and all connections are already in use.

   • Initialization query. (Optional) Add an initialization query, or modify the current one. You can specify one or more SQL statements for the proxy to run when opening each new database connection. The setting is typically used with SET statements to make sure that each connection has identical settings. Make sure that the query you add is valid. To include multiple variables in a single SET statement, use comma separators. For example:

     SET variable1=value1, variable2=value2

     For multiple statements, use semicolons as the separator.

   For Authentication, provide information for the following:

   • IAM role. Choose an IAM role that has permission to access the Secrets Manager secrets that you chose earlier. Or, you can create a new IAM role from the AWS Management Console.

   • Secrets Manager secrets. Choose at least one Secrets Manager secret that contains database user credentials that allow the proxy to access the RDS DB instance.

   • Client authentication type. Choose the type of authentication the proxy uses for connections from clients. Your choice applies to all Secrets Manager secrets that you associate with this proxy. If you need to specify a different client authentication type for each secret, then create your proxy by using the AWS CLI or the API instead.

   • IAM authentication. Choose whether to require, allow, or disallow IAM authentication for connections to your proxy. The allow option is only valid for proxies for RDS for SQL Server. Your choice applies to all Secrets Manager secrets that you associate with this proxy. If you need to specify a different IAM authentication for each secret, create your proxy by using the AWS CLI or the API instead.

   For Connectivity, provide information for the following:

   • Require Transport Layer Security. Choose this setting if you want the proxy to enforce TLS/SSL for all client connections. For an encrypted or unencrypted connection to a proxy, the proxy uses the same encryption setting when it makes a connection to the underlying database.

   • Subnets. This field is prepopulated with all the subnets associated with your VPC. You can remove any subnets that you don't need for this proxy. You must leave at least two subnets.

   Provide additional connectivity configuration:

   • VPC security group. Choose an existing VPC security group. Or, you can create a new security group from the AWS Management Console. You must configure the Inbound rules to allow your applications to access the proxy. You must also configure the Outbound rules to allow traffic from your DB targets.

     Note

     This security group must allow connections from the proxy to the database. The same security group is used for ingress from your applications to the proxy, and for egress from the proxy to the database. For example, suppose that you use the same security group for your database and your proxy. In this case, make sure that you specify that resources in that security group can communicate with other resources in the same security group.

     When using a shared VPC, you can't use the default security group for the VPC, or one that belongs to another account. Choose a security group that belongs to your account. If one doesn't exist, create one. For more information about this limitation, see Work with shared VPCs.

     RDS deploys a proxy over multiple Availability Zones to ensure high availability. To enable cross-AZ communication for such a proxy, the network access control list (ACL) for your proxy subnet must allow engine port specific egress and all ports to ingress. For more information about network ACLs, see Control traffic to subnets using network ACLs. If the network ACL for your proxy and target are identical, you must add a TCP protocol ingress rule where the Source is set to the VPC CIDR. You must also add an engine port specific TCP protocol egress rule where the Destination is set to the VPC CIDR.

   (Optional) Provide advanced configuration:

   • Enable enhanced logging. You can enable this setting to troubleshoot proxy compatibility or performance issues.

     When this setting is enabled, RDS Proxy includes detailed information about proxy performance in its logs. This information helps you to debug issues involving SQL behavior or the performance and scalability of the proxy connections. Thus, only enable this setting for debugging and when you have security measures in place to safeguard any sensitive information that appears in the logs.

     To minimize overhead associated with your proxy, RDS Proxy automatically turns this setting off 24 hours after you enable it. Enable it temporarily to troubleshoot a specific issue.

5. Choose Create Proxy.

AWS CLI

To create a proxy by using the AWS CLI, call the create-db-proxy command with the following required parameters:

• --db-proxy-name

• --engine-family

• --role-arn

• --auth

• --vpc-subnet-ids

The --engine-family value is case-sensitive.

Example

For Linux, macOS, or Unix:

aws rds create-db-proxy \
    --db-proxy-name proxy_name \
    --engine-family { MYSQL | POSTGRESQL | SQLSERVER } \
    --auth ProxyAuthenticationConfig_JSON_string \
    --role-arn iam_role \
    --vpc-subnet-ids space_separated_list \
    [--vpc-security-group-ids space_separated_list] \
    [--require-tls | --no-require-tls] \
    [--idle-client-timeout value] \
    [--debug-logging | --no-debug-logging] \
    [--tags comma_separated_list]

For Windows:

aws rds create-db-proxy ^
    --db-proxy-name proxy_name ^
    --engine-family { MYSQL | POSTGRESQL | SQLSERVER } ^
    --auth ProxyAuthenticationConfig_JSON_string ^
    --role-arn iam_role ^
    --vpc-subnet-ids space_separated_list ^
    [--vpc-security-group-ids space_separated_list] ^
    [--require-tls | --no-require-tls] ^
    [--idle-client-timeout value] ^
    [--debug-logging | --no-debug-logging] ^
    [--tags comma_separated_list]

The following is an example of the JSON value for the --auth option. This example 
 applies a different client authentication type to each secret.

[
  {
    "Description": "proxy description 1",
    "AuthScheme": "SECRETS",
    "SecretArn": "arn:aws:secretsmanager:us-west-2:123456789123:secret/1234abcd-12ab-34cd-56ef-1234567890ab",
    "IAMAuth": "DISABLED",
    "ClientPasswordAuthType": "POSTGRES_SCRAM_SHA_256"
  },
  
  {
    "Description": "proxy description 2",
    "AuthScheme": "SECRETS",
    "SecretArn": "arn:aws:secretsmanager:us-west-2:111122223333:secret/1234abcd-12ab-34cd-56ef-1234567890cd",
    "IAMAuth": "DISABLED",
    "ClientPasswordAuthType": "POSTGRES_MD5"
    
  },
  
  {
    "Description": "proxy description 3",
    "AuthScheme": "SECRETS",
    "SecretArn": "arn:aws:secretsmanager:us-west-2:111122221111:secret/1234abcd-12ab-34cd-56ef-1234567890ef",
    "IAMAuth": "REQUIRED"
  }
  
]

Tip

If you don't already know the subnet IDs to use for the --vpc-subnet-ids parameter, see Setting up network prerequisites for RDS Proxy for examples of how to find them.

Note

The security group must allow access to the database the proxy connects to. The same security group is used for ingress from your applications to the proxy, and for egress from the proxy to the database. For example, suppose that you use the same security group for your database and your proxy. In this case, make sure that you specify that resources in that security group can communicate with other resources in the same security group.

When using a shared VPC, you can't use the default security group for the VPC, or one that belongs to another account. Choose a security group that belongs to your account. If one doesn't exist, create one. For more information about this limitation, see Work with shared VPCs.

To create the right associations for the proxy, you also use the register-db-proxy-targets command. Specify the target group name default. RDS Proxy automatically creates a target group with this name when you create each proxy.

aws rds register-db-proxy-targets
    --db-proxy-name value
    [--target-group-name target_group_name]
    [--db-instance-identifiers space_separated_list]  # rds db instances, or
    [--db-cluster-identifiers cluster_id]        # rds db cluster (all instances)

RDS API

To create an RDS proxy, call the Amazon RDS API operation CreateDBProxy. You pass a parameter with the AuthConfig data structure.

RDS Proxy automatically creates a target group named default when you create each proxy. You associate an RDS DB instance with the target group by calling the function RegisterDBProxyTargets.