# 开始使用 RDS 代理
<a name="rds-proxy-setup"></a>

使用以下页面中的信息来设置、管理 [Amazon RDS 代理](rds-proxy.md)以及设置相关的安全选项。这些安全选项控制哪些人可以访问每个代理，以及每个代理如何连接到数据库实例。

如果您不熟悉 RDS 代理，我们建议您按照我们展示页面的顺序进行操作。

**Topics**
+ [设置 RDS 代理的网络先决条件](rds-proxy-network-prereqs.md)
+ [设置 RDS 代理的数据库凭证](rds-proxy-secrets-arns.md)
+ [为 RDS 代理配置 IAM 身份验证](rds-proxy-iam-setup.md)
+ [为 Amazon RDS 创建代理](rds-proxy-creating.md)
+ [查看代理](rds-proxy-viewing.md)
+ [通过 RDS Proxy 连接到数据库](rds-proxy-connecting.md)

# 设置 RDS 代理的网络先决条件
<a name="rds-proxy-network-prereqs"></a>

 使用 RDS 代理需要您在 RDS 数据库实例和 RDS 代理之间拥有通用的虚拟私有云（VPC）。此 VPC 应至少有两个位于不同可用区中的子网。您的账户可以拥有这些子网，或与其他账户共享它们。有关 VPC 共享的信息，请参阅[使用共享 VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-sharing.html)。

要支持 IPv6，需要进行额外的网络配置：
+ **IPv6 端点网络类型** - 您的 VPC 和子网必须配置为支持 IPv6。这包括将 IPv6 CIDR 数据块分配给 VPC 和子网。
+ **双栈端点网络类型** – 您的 VPC 和子网必须支持 IPv4 和 IPv6 寻址。
+ **IPv6 目标连接网络类型** – 必须将数据库配置为双栈模式，才能支持来自代理的 IPv6 连接。

您的客户端应用程序资源（例如 Amazon EC2、Lambda 或 Amazon ECS）可以与代理位于同一 VPC 中。它们也可以位于与代理不同的 VPC 中。如果已成功连接到任何 RDS 数据库实例，则您已拥有所需的网络资源。

**Topics**
+ [获取有关您的子网的信息](#rds-proxy-network-prereqs.subnet-info)
+ [计划 IP 地址容量](#rds-proxy-network-prereqs.plan-ip-address)

## 获取有关您的子网的信息
<a name="rds-proxy-network-prereqs.subnet-info"></a>

要创建代理，必须提供代理在其中运行的子网和 VPC。以下 Linux 示例展示了检查 AWS 账户 拥有的 VPC 和子网的 AWS CLI 命令。尤其是，在使用 CLI 创建代理时，您可以将子网 ID 作为参数传递。

```
aws ec2 describe-vpcs
aws ec2 describe-internet-gateways
aws ec2 describe-subnets --query '*[].[VpcId,SubnetId]' --output text | sort
```

以下 Linux 示例展示了用于确定与特定 RDS 数据库实例对应的子网 ID 的 AWS CLI 命令。找到数据库实例的 VPC ID。检查 VPC 以查找其子网。以下 Linux 示例展示了操作步骤。

```
$ #From the DB instance, trace through the DBSubnetGroup and Subnets to find the subnet IDs.
$ aws rds describe-db-instances --db-instance-identifier my_instance_id --query '*[].[DBSubnetGroup]|[0]|[0]|[Subnets]|[0]|[*].SubnetIdentifier' --output text
```

```
subnet_id_1
subnet_id_2
subnet_id_3
...
```

```
$ #From the DB instance, find the VPC.
$ aws rds describe-db-instances --db-instance-identifier my_instance_id --query '*[].[DBSubnetGroup]|[0]|[0].VpcId' --output text
```

```
my_vpc_id
```

```
$ aws ec2 describe-subnets --filters Name=vpc-id,Values=my_vpc_id --query '*[].[SubnetId]' --output text
```

```
subnet_id_1
subnet_id_2
subnet_id_3
subnet_id_4
subnet_id_5
subnet_id_6
```

## 计划 IP 地址容量
<a name="rds-proxy-network-prereqs.plan-ip-address"></a>

RDS 代理会根据向它注册的数据库实例的大小和数量，视需要自动调整其容量。某些操作可能还需要更多代理容量，例如增加注册数据库的大小或内部 RDS 代理维护操作。在这些操作期间，您的代理可能需要更多 IP 地址来预调配额外的容量。这些额外的地址使您的代理可以在不影响工作负载的情况下进行扩展。您的子网中缺少可用的 IP 地址会阻止代理纵向扩展。这可能导致查询延迟更长或客户端连接故障。当您的子网中没有足够的可用 IP 地址时，RDS 会通过事件 `RDS-EVENT-0243` 通知您。有关此事件的信息，请参阅 [使用 RDS 代理事件使用 RDS Proxy 事件](rds-proxy.events.md)。

**注意**  
在 VPC 中，每个 RDS 代理消耗的 IP 地址不会超过 215 个。

根据数据库实例类大小，您应在子网中为代理保留以下最少可用的 IP 地址数。


|  数据库实例类  |  最少可用 IP 地址数  | 
| --- | --- | 
|  db.\$1.xlarge 或更小   |  10  | 
|  db.\$1.2xlarge   |  15  | 
|  db.\$1.4xlarge   |  25  | 
|  db.\$1.8xlarge   |  45  | 
|  db.\$1.12xlarge   |  60  | 
|  db.\$1.16xlarge   |  75  | 
|  db.\$1.24xlarge   |  110  | 

这些建议的 IP 地址数是针对仅具有默认端点的代理的估计数。具有更多端点或只读副本的代理可能需要更多可用的 IP 地址。对于每个其他端点，建议您另外预留三个 IP 地址。对于每个只读副本，建议您根据该只读副本的大小，保留表中指定的额外 IP 地址。

# 设置 RDS 代理的数据库凭证
<a name="rds-proxy-secrets-arns"></a>

Amazon RDS 中的 RDS 代理使用 AWS Secrets Manager 安全地存储和管理数据库凭证。您无需在应用程序中嵌入凭证，而是将代理与包含必要身份验证详细信息的 Secrets Manager 密钥相关联。您可以在 RDS 数据库实例上，为代理连接到的每个数据库用户账户分别创建 Secrets Manager 密钥。

或者，您可以将 RDS 代理配置为使用端到端 IAM 身份验证，这样就无需在 Secrets Manager 中存储数据库凭证。RDS 代理对客户端到代理和代理到数据库的连接都使用 IAM 身份验证。这提供了一个完全集成的基于 IAM 的身份验证解决方案，无需管理密钥或密码。有关添加新 IAM 数据库用户的信息，请参阅[使用 IAM 身份验证创建数据库账户](UsingWithRDS.IAMDBAuth.DBAccounts.md)。

**Topics**
+ [创建与 RDS 代理结合使用的密钥](#rds-proxy-secrets-create)

## 创建与 RDS 代理结合使用的密钥
<a name="rds-proxy-secrets-create"></a>

在创建代理之前，必须先创建至少一个用于存储数据库凭证的密钥。

### 控制台
<a name="rds-proxy-secrets-create-console"></a>

**创建密钥**

1. 通过 [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/) 打开 Secrets Manager 控制台。

1. 选择**存储新密钥**。

1. 选择 **Amazon RDS 数据库的凭证**。

1. 输入用户名和密码。您输入的凭证必须与关联的 RDS 数据库中存在的数据库用户的凭证相匹配。RDS 代理使用这些凭证代表应用程序对数据库进行身份验证和建立连接。

   如果不匹配，您可以更新密钥来与数据库密码匹配。在更新密钥之前，尝试使用该密钥通过代理进行连接会失败，但使用其它有效密钥的连接仍然有效。
**注意**  
对于 RDS For SQL Server，无论数据库实例排序规则设置如何，RDS 代理都需要在 Secrets Manager 中设置一个区分大小写的密钥。如果应用程序支持用户名使用不同的大小写，例如“Admin”和“admin”，则必须为每个用户名创建单独的密钥。RDS 代理不支持在客户端和代理之间进行不区分大小写的用户名身份验证。  
有关 SQL Server 中的排序规则的更多信息，请参阅 [Microsoft SQL Server](https://docs.microsoft.com/en-us/sql/relational-databases/collations/collation-and-unicode-support?view=sql-server-ver16) 文档。

1. 对于**数据库**，选择密钥将访问的 Amazon RDS 数据库。

1. 填写密钥的其它设置，然后选择**存储**。有关全面的说明，请参阅《AWS Secrets Manager User Guide》**中的 [Creating an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)。

### AWS CLI
<a name="rds-proxy-secrets-create-cli"></a>

通过 AWS CLI 创建代理时，请指定相应密钥的 Amazon 资源名称（ARN）。请为代理可以访问的所有数据库用户账户执行此操作。在 AWS 管理控制台 中，根据描述性名称选择密钥。
+ 要创建与 RDS 代理结合使用的 Secrets Manager 密钥，请使用 [create-secret](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/create-secret.html) 命令：

  ```
  aws secretsmanager create-secret \
    --name "secret_name" \
    --description "secret_description" \
    --region region_name \
    --secret-string '{"username":"db_user","password":"db_user_password"}'
  ```
+ 您也可以创建自定义密钥来加密 Secrets Manager 密钥。以下命令创建一个密钥示例。

  ```
  aws kms create-key --description "test-key" --policy '{
    "Id":"kms-policy",
    "Version": "2012-10-17",		 	 	 
    "Statement":
      [
        {
          "Sid":"Enable IAM User Permissions",
          "Effect":"Allow",
          "Principal":{"AWS":"arn:aws:iam::account_id:root"},
          "Action":"kms:*","Resource":"*"
        },
        {
          "Sid":"Allow access for Key Administrators",
          "Effect":"Allow",
          "Principal":
            {
              "AWS":
                ["$USER_ARN","arn:aws:iam:account_id::role/Admin"]
            },
          "Action":
            [
              "kms:Create*",
              "kms:Describe*",
              "kms:Enable*",
              "kms:List*",
              "kms:Put*",
              "kms:Update*",
              "kms:Revoke*",
              "kms:Disable*",
              "kms:Get*",
              "kms:Delete*",
              "kms:TagResource",
              "kms:UntagResource",
              "kms:ScheduleKeyDeletion",
              "kms:CancelKeyDeletion"
            ],
          "Resource":"*"
        },
        {
          "Sid":"Allow use of the key",
          "Effect":"Allow",
          "Principal":{"AWS":"$ROLE_ARN"},
          "Action":["kms:Decrypt","kms:DescribeKey"],
          "Resource":"*"
        }
      ]
  }'
  ```

 例如，以下命令为两个数据库用户创建 Secrets Manager 密钥：

```
aws secretsmanager create-secret \
  --name secret_name_1 --description "db admin user" \
  --secret-string '{"username":"admin","password":"choose_your_own_password"}'

aws secretsmanager create-secret \
  --name secret_name_2 --description "application user" \
  --secret-string '{"username":"app-user","password":"choose_your_own_password"}'
```

要创建使用自定义 AWS KMS 密钥加密的这些密钥，请使用以下命令：

```
aws secretsmanager create-secret \
  --name secret_name_1 --description "db admin user" \
  --secret-string '{"username":"admin","password":"choose_your_own_password"}' \
  --kms-key-id arn:aws:kms:us-east-2:account_id:key/key_id

aws secretsmanager create-secret \
  --name secret_name_2 --description "application user" \
  --secret-string '{"username":"app-user","password":"choose_your_own_password"}' \
  --kms-key-id arn:aws:kms:us-east-2:account_id:key/key_id
```

要查看您的 AWS 账户拥有的密钥，请使用 [list-secrets](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/list-secrets.html) 命令：

```
aws secretsmanager list-secrets
```

使用 CLI 创建代理时，将一个或多个密钥的 Amazon Resource Name (ARN) 传递给了 `--auth` 参数。以下示例展示了如何准备报告，其中仅包含 AWS 账户所拥有的每个密钥的名称和 ARN。此示例使用了 `--output table` 版本 2 中提供的 AWS CLI 参数。如果您使用的是 AWS CLI 版本 1，请改用 `--output text`。

```
aws secretsmanager list-secrets --query '*[].[Name,ARN]' --output table
```

要确认密钥包含格式正确的凭证，请使用 [get-secret-value](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/get-secret-value.html) 命令。将 `your_secret_name` 替换为密钥的短名称或 ARN。

```
aws secretsmanager get-secret-value --secret-id your_secret_name
```

输出包含一行 JSON 编码值，类似于以下内容：

```
...
"SecretString": "{\"username\":\"your_username\",\"password\":\"your_password\"}",
...
```

# 为 RDS 代理配置 IAM 身份验证
<a name="rds-proxy-iam-setup"></a>

要在 Amazon RDS 中为 RDS 代理设置 AWS Identity and Access Management（IAM）身份验证，请创建并配置用于授予必要权限的 IAM 策略。

本主题提供了为 RDS 代理配置 IAM 身份验证的步骤，包括创建所需的 IAM 策略并将其附加到 IAM 角色。

**提示**  
仅当您想创建自己的 IAM 角色时，才需要执行此过程。否则，RDS 可以在您设置代理时自动创建所需的角色，因此您可以跳过这些步骤。

## 先决条件
<a name="rds-proxy-iam-setup-prereqs"></a>

在为 RDS 代理设置 IAM 身份验证之前，请确保您具有以下各项：
+ **AWS Secrets Manager**：至少一个包含数据库凭证的存储密钥。有关创建密钥的说明，请参阅[设置 RDS 代理的数据库凭证](rds-proxy-secrets-arns.md)。

  如果您使用端到端 IAM 身份验证，则不需要这样做。
+ **IAM 权限**：具有在 AWS Secrets Manager 中创建和管理 IAM 策略、角色和密钥的权限的 IAM 角色或用户。

## 创建端到端 IAM 策略
<a name="rds-proxy-iam-setup-e2e-steps"></a>

使用端到端 IAM 身份验证时，RDS 代理使用 IAM 身份验证连接到您的数据库，而不是从 Secrets Manager 检索凭证。这需要为您的 IAM 角色配置您想要与代理一起使用的数据库账户的 `rds-db:connect` 权限。

要使用 IAM 对 RDS 代理进行数据库身份验证，请创建一个 IAM 角色，并附加授予必要数据库连接权限的策略。

### 控制台
<a name="rds-proxy-iam-e2e-console"></a>

**使用代理创建用于端到端 IAM 身份验证的角色**

1. 登录 AWS 管理控制台，然后通过以下网址打开 IAM 控制台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。

1. 为该角色创建权限策略。有关一般步骤，请参阅[创建 IAM 策略（控制台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html)。

   将此策略粘贴到 JSON 编辑器中，并进行以下更改：
   + 替换您自己的账户 ID。
   + 将 `us-east-2` 替换为代理必须位于的区域。
   + 用您想使用的 ID 和用户名替换数据库资源 ID 和用户名。RDS 实例和 Aurora clusters的资源 ID 格式有所不同。

   ```
   {
       "Version": "2012-10-17",		 	 	 
       "Statement": [
           {
               "Effect": "Allow",
               "Action": "rds-db:connect",
               "Resource": [
                   "arn:aws:rds-db:us-east-2:account_id:dbuser:db_instance_resource_id/db_user_name_1",
                   "arn:aws:rds-db:us-east-2:account_id:dbuser:db_instance_resource_id/db_user_name_2"
               ]
           }
       ]
   }
   ```

1. 创建角色并向其附加权限策略。有关一般步骤，请参阅[创建向 AWS 服务委派权限的角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html)。

   对于**可信实体类型**，选择 **AWS 服务**。在**用例**下，选择 **RDS**，然后为用例选择 **RDS - 向数据库添加角色**。

1. 对于**权限策略**，选择您创建的策略。

1. 对于**选择可信实体**，为该角色输入以下信任策略：

   ```
   {
     "Version": "2012-10-17",		 	 	 
     "Statement": [
       {
         "Sid": "",
         "Effect": "Allow",
         "Principal": {
           "Service": "rds.amazonaws.com"
         },
         "Action": "sts:AssumeRole"
       }
     ]
   }
   ```

### AWS CLI
<a name="rds-proxy-iam-e2e-cli"></a>

要使用 AWS CLI 创建角色，请发送以下请求：

```
aws iam create-role \
  --role-name my_e2e_iam_role_name \

  --assume-role-policy-document '{"Version":"2012-10-17",		 	 	 "Statement":[{"Effect":"Allow","Principal":{"Service":["rds.amazonaws.com"]},"Action":"sts:AssumeRole"}]}'
```

然后，将策略附加到该角色：

```
aws iam put-role-policy \
  --role-name my_e2e_iam_role_name \
  --policy-name e2e_iam_db_connect_policy \
  --policy-document '{

    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "rds-db:connect",
            "Resource": [
                "arn:aws:rds-db:us-east-2:account_id:dbuser:db_instance_resource_id/db_user_name_1",
                "arn:aws:rds-db:us-east-2:account_id:dbuser:db_instance_resource_id/db_user_name_2"
            ]
        }
    ]
}'
```

为端到端 IAM 身份验证配置 IAM 角色和权限后，即可创建 `DefaultAuthScheme` 设置为 `IAM_AUTH` 的代理。此代理使用 IAM 直接对数据库进行身份验证，无需使用 Secrets Manager 密钥。有关说明，请参阅[为 Amazon RDS 创建代理](rds-proxy-creating.md)。

使用端到端 IAM 身份验证时，请确保按照[使用 IAM 身份验证创建数据库账户](UsingWithRDS.IAMDBAuth.DBAccounts.md)中所述为数据库用户配置了 IAM 身份验证。

## 创建用于访问 Secrets Manager 的 IAM 策略
<a name="rds-proxy-iam-setup-steps"></a>

要支持 RDS 代理从 Secrets Manager 检索数据库凭证，请创建一个 IAM 角色，并使用授予必要权限的策略。

## 控制台
<a name="rds-proxy-iam-console"></a>

**创建用于访问您的密钥以便与代理一起使用的角色**

1. 登录 AWS 管理控制台，然后通过以下网址打开 IAM 控制台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。

1. 为该角色创建权限策略。有关一般步骤，请参阅[创建 IAM 策略（控制台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html)。

   将此策略粘贴到 JSON 编辑器中，并进行以下更改：
   + 替换您自己的账户 ID。
   + 将 `us-east-2` 替换为代理所在的区域。
   + 将密钥名称替换为您创建的名称。有关更多信息，请参阅 [Specifying KMS keys in IAM policy statements](https://docs.aws.amazon.com/kms/latest/developerguide/cmks-in-iam-policies.html)。
   + 将 KMS 密钥 ID 替换为您用于加密 Secrets Manager 密钥（默认密钥或您自己的密钥）的密钥 ID。

------
#### [ JSON ]

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Effect": "Allow",
               "Action": "secretsmanager:GetSecretValue",
               "Resource": [
                   "arn:aws:secretsmanager:us-east-2:111122223333:secret:secret_name_1",
                   "arn:aws:secretsmanager:us-east-2:111122223333:secret:secret_name_2"
               ]
           },
           {
               "Effect": "Allow",
               "Action": "kms:Decrypt",
               "Resource": "arn:aws:kms:us-east-2:111122223333:key/key_id",
               "Condition": {
                   "StringEquals": {
                       "kms:ViaService": "secretsmanager.us-east-2.amazonaws.com"
                   }
               }
           }
       ]
   }
   ```

------

1. 创建角色并向其附加权限策略。有关一般步骤，请参阅[创建向 AWS 服务委派权限的角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html)。

   对于**可信实体类型**，选择 **AWS 服务**。在**用例**下，选择 **RDS**，然后为用例选择 **RDS - 向数据库添加角色**。

1. 对于**权限策略**，选择您创建的策略。

1. 对于**选择可信实体**，为该角色输入以下信任策略：

------
#### [ JSON ]

****  

   ```
   {
     "Version":"2012-10-17",		 	 	 
     "Statement": [
       {
         "Sid": "",
         "Effect": "Allow",
         "Principal": {
           "Service": "rds.amazonaws.com"
         },
         "Action": "sts:AssumeRole"
       }
     ]
   }
   ```

------

## AWS CLI
<a name="rds-proxy-iam-cli"></a>

要使用 AWS CLI 创建角色，请发送以下请求：

```
aws iam create-role \
  --role-name my_role_name \
  --assume-role-policy-document '{"Version": "2012-10-17",		 	 	 "Statement":[{"Effect":"Allow","Principal":{"Service":["rds.amazonaws.com"]},"Action":"sts:AssumeRole"}]}'
```

然后，将策略附加到该角色：

```
aws iam put-role-policy \
  --role-name my_role_name \
  --policy-name secret_reader_policy \
  --policy-document '{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "secretsmanager:GetSecretValue",
            "Resource": [
                "arn:aws:secretsmanager:us-east-2:account_id:secret:secret_name_1",
                "arn:aws:secretsmanager:us-east-2:account_id:secret:secret_name_2"
            ]
        },
        {
            "Sid": "VisualEditor1",
            "Effect": "Allow",
            "Action": "kms:Decrypt",
            "Resource": "arn:aws:kms:us-east-2:account_id:key/key_id",
            "Condition": {
                "StringEquals": {
                    "kms:ViaService": "secretsmanager.us-east-2.amazonaws.com"
                }
            }
        }
    ]
}'
```

配置了 IAM 角色和权限后，您现在可以创建代理并将其与该角色关联。这可让代理安全地从 AWS Secrets Manager 中检索数据库凭证，并为您的应用程序启用 IAM 身份验证。有关说明，请参阅[为 Amazon RDS 创建代理](rds-proxy-creating.md)。

# 为 Amazon RDS 创建代理
<a name="rds-proxy-creating"></a>

您可以将代理与 RDS for MariaDB、RDS for Microsoft SQL Server、RDS for MySQL 或 RDS for PostgreSQL 数据库实例相关联。

## 控制台
<a name="rds-proxy-creating.console"></a>

**创建代理**

1. 登录 AWS 管理控制台 并通过以下网址打开 Amazon RDS 控制台：[https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/)。

1. 在导航窗格中，选择 **Proxies (代理)**。

1. 选择 **Create proxy (创建代理)**。

1. 为代理配置以下设置。    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/UserGuide/rds-proxy-creating.html)

1.  选择 **Create proxy (创建代理)**。

## AWS CLI
<a name="rds-proxy-creating.CLI"></a>

 要使用 AWS CLI 创建代理，请使用以下必需的参数调用 [create-db-proxy](https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-proxy.html) 命令：
+ `--db-proxy-name`
+ `--engine-family`
+ `--role-arn`
+ `--vpc-subnet-ids`

`--engine-family` 值区分大小写。

**Example**  
对于 Linux、macOS 或 Unix：  

```
aws rds create-db-proxy \
    --db-proxy-name proxy_name \
    --engine-family { MYSQL | POSTGRESQL | SQLSERVER } \
    --role-arn iam_role \
    --vpc-subnet-ids space_separated_list \
    [--default-auth-scheme { NONE | IAM_AUTH }] \
    [--auth ProxyAuthenticationConfig_JSON_string] \
    [--vpc-security-group-ids space_separated_list] \
    [--require-tls | --no-require-tls] \
    [--idle-client-timeout value] \
    [--debug-logging | --no-debug-logging] \
    [--endpoint-network-type { IPV4 | IPV6 | DUAL }] \
    [--target-connection-network-type { IPV4 | IPV6 }] \
    [--tags comma_separated_list]
```
对于：Windows  

```
aws rds create-db-proxy ^
    --db-proxy-name proxy_name ^
    --engine-family { MYSQL | POSTGRESQL | SQLSERVER } ^
    --role-arn iam_role ^
    --vpc-subnet-ids space_separated_list ^
    [--default-auth-scheme { NONE | IAM_AUTH }] ^
    [--auth ProxyAuthenticationConfig_JSON_string] ^
    [--vpc-security-group-ids space_separated_list] ^
    [--require-tls | --no-require-tls] ^
    [--idle-client-timeout value] ^
    [--debug-logging | --no-debug-logging] ^
    [--endpoint-network-type { IPV4 | IPV6 | DUAL }] ^
    [--target-connection-network-type { IPV4 | IPV6 }] ^
    [--tags comma_separated_list]
```

以下是 `--auth` 选项的 JSON 值的示例。此示例对每个密钥应用不同的客户端身份验证类型。

```
[
  {
    "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"
  }
  
]
```

`--endpoint-network-type` 参数指定客户端用于连接代理的代理端点的 IP 版本。有效值为：
+ `IPV4` – 代理端点仅使用 IPv4 地址（默认）。
+ `IPV6` – 代理端点仅使用 IPv6 地址。
+ `DUAL` – 代理端点支持 IPv4 和 IPv6 地址。

`--target-connection-network-type` 参数指定代理用于连接到目标数据库的 IP 版本。有效值为：
+ `IPV4` – 代理使用 IPv4 地址连接到数据库（默认）。
+ `IPV6` – 代理使用 IPv6 地址连接到数据库。

要使用 IPv6 或双栈端点网络类型，必须将您的 VPC 和子网配置为支持所选网络类型。要使用 IPv6 目标连接网络类型，您的数据库必须支持双栈模式。

**提示**  
 如果您尚不知道要用于 `--vpc-subnet-ids` 参数的子网 ID，请参阅 [设置 RDS 代理的网络先决条件](rds-proxy-network-prereqs.md) 获取有关如何查找它们的示例。

**注意**  
安全组必须允许访问代理连接到的数据库。同一安全组用于从应用程序到代理的入口以及从代理到数据库的出口。例如，假设您对数据库和代理使用同一安全组。在这种情况下，请确保您指定该安全组中的资源可以与同一安全组中的其他资源进行通信。  
使用共享 VPC 时，您不能使用 VPC 的默认安全组，也不能使用属于其他账户的安全组。选择属于您账户的安全组。如果不存在，请创建一个。有关此限制的详细信息，请参阅[使用共享 VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-sharing.html#vpc-share-limitations)。

 要为代理创建正确的关联，您还可以使用 [register-db-proxy-targets](https://docs.aws.amazon.com/cli/latest/reference/rds/register-db-proxy-targets.html) 命令。指定目标组名称 `default`。创建每个代理时，RDS 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
<a name="rds-proxy-creating.API"></a>

 要创建 RDS 代理，请调用 Amazon RDS API 操作 [CreateDBProxy](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateDBProxy.html)。传递具有 [AuthConfig](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_AuthConfig.html) 数据结构的参数。

 创建每个代理时，RDS Proxy 会自动创建一个名为 `default` 的目标组。通过调用函数 [RegisterDBProxyTargets](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_RegisterDBProxyTargets.html)，将 RDS 数据库实例与目标组关联。

**重要**  
当您选择 **IAM 身份验证**作为默认身份验证方案时：  
在代理成功连接之前，您必须在目标数据库实例或集群上启用 IAM 数据库身份验证。
如果选择**创建 IAM 角色**，则必须填写**用于 IAM 身份验证的数据库账户**字段。
如果选择现有 IAM 角色，则控制台不会自动更新具有数据库连接权限的角色。请检查该角色是否具有必要的 `rds-db:connect` 权限。

# 查看代理
<a name="rds-proxy-viewing"></a>

 创建一个或多个 RDS 代理后，您可以在 AWS 管理控制台、AWS CLI 或 RDS API 中查看和管理它们。您可以查看其配置详细信息，监控性能，并根据需要确定要修改或删除哪些代理。

要使数据库应用程序能够通过代理路由流量，必须在连接字符串中指定代理端点。

## 控制台
<a name="rds-proxy-viewing.console"></a>

**在控制台中查看代理**

1. 登录AWS 管理控制台并通过以下网址打开 Amazon RDS 控制台：[https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/)。

1. 在导航窗格中，选择 **Proxies (代理)**。

1. 选择代理名称以查看其详细信息。

1. 在详细信息页面上，**目标组**部分显示了代理与特定 RDS 数据库实例关联的方式。您可以导航到默认目标组页面，以便更深入地查看此关联，包括在创建代理期间定义的配置设置。这些设置包括最大连接百分比、连接借用超时、引擎系列和会话绑定筛选条件。

## CLI
<a name="rds-proxy-viewing.cli"></a>

 要使用 CLI 查看您的代理，请使用 [describe-db-proxies](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-proxies.html) 命令。默认情况下，该请求会返回由您的 AWS 账户拥有的所有代理。要查看单个代理的详细信息，请通过 `--db-proxy-name` 参数指定其名称。

```
aws rds describe-db-proxies [--db-proxy-name proxy_name]
```

 要查看与代理关联的其它信息，请使用以下命令。

```
aws rds describe-db-proxy-target-groups  --db-proxy-name proxy_name

aws rds describe-db-proxy-targets --db-proxy-name proxy_name
```

 使用以下命令序列查看有关与代理关联的内容的更多详细信息：

1.  要获取代理列表，请运行 [describe-db-proxies](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-proxies.html)。

1.  要显示连接参数（如代理可以使用的最大连接百分比），请运行 [describe-db-proxy-target-groups](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-proxy-target-groups.html) `--db-proxy-name`。使用代理的名称作为参数值。

1.  要查看与返回的目标组关联的 RDS 数据库实例的详细信息，请运行 [describe-db-proxy-targets](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-proxy-targets.html)。

## RDS API
<a name="rds-proxy-viewing.api"></a>

 要使用 RDS API 查看您的代理，请使用 [DescribeDBProxies](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DescribeDBProxies.html) 操作。该操作将返回 [DBProxy](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DBProxy.html) 数据类型的值。

 要查看代理连接设置的详细信息，请将此返回值中的代理标识符与 [DescribeDBProxyTargetGroups](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DescribeDBProxyTargetGroups.html) 操作一起使用。该操作将返回 [DBProxyTargetGroup](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DBProxyTargetGroup.html) 数据类型的值。

 要查看与代理关联的 RDS 实例或 Aurora 数据库集群，请使用 [DescribeDBProxyTargets](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DescribeDBProxyTargets.html) 操作。该操作将返回 [DBProxyTarget](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DBProxyTarget.html) 数据类型的值。

# 通过 RDS Proxy 连接到数据库
<a name="rds-proxy-connecting"></a>

通过代理或通过连接到数据库来连接到 RDS 数据库实例的方式通常是相同的。有关更多信息，请参阅 [代理终端节点概述](rds-proxy-endpoints.md#rds-proxy-endpoints-overview)。

**Topics**
+ [使用数据库凭证连接到数据库](#rds-proxy-connecting-native)
+ [使用 IAM 身份验证连接到数据库](#rds-proxy-connecting-iam)
+ [连接到 Microsoft SQL Server 的注意事项](#rds-proxy-connecting-sqlserver)
+ [连接到 PostgreSQL 的注意事项](#rds-proxy-connecting-postgresql)

## 使用数据库凭证连接到数据库
<a name="rds-proxy-connecting-native"></a>

 执行以下步骤，使用数据库凭证连接到代理：

1.  查找代理端点。在 AWS 管理控制台 中，您可以在相应代理的详细信息页面上找到端点。通过 AWS CLI，您可以使用 [describe-db-proxies](https://docs.aws.amazon.com/cli/latest/reference/rds/describe-db-proxies.html) 命令。下面的示例演示如何操作。

   ```
   # Add --output text to get output as a simple tab-separated list.
   $ aws rds describe-db-proxies --query '*[*].{DBProxyName:DBProxyName,Endpoint:Endpoint}'
   [
       [
           {
               "Endpoint": "the-proxy.proxy-demo.us-east-1.rds.amazonaws.com",
               "DBProxyName": "the-proxy"
           },
           {
               "Endpoint": "the-proxy-other-secret.proxy-demo.us-east-1.rds.amazonaws.com",
               "DBProxyName": "the-proxy-other-secret"
           },
           {
               "Endpoint": "the-proxy-rds-secret.proxy-demo.us-east-1.rds.amazonaws.com",
               "DBProxyName": "the-proxy-rds-secret"
           },
           {
               "Endpoint": "the-proxy-t3.proxy-demo.us-east-1.rds.amazonaws.com",
               "DBProxyName": "the-proxy-t3"
           }
       ]
   ]
   ```

1.  在客户端应用程序的连接字符串中指定该端点作为主机参数。例如，指定代理端点作为 `mysql -h` 选项或 `psql -h` 选项的值。

1.  提供您通常使用的相同数据库用户名和密码。

## 使用 IAM 身份验证连接到数据库
<a name="rds-proxy-connecting-iam"></a>

 在对 RDS 代理使用 IAM 身份验证时，客户端与代理之间的身份验证有两种选择：
+ 将数据库用户设置为使用常规用户名和密码进行身份验证。RDS 代理从 Secrets Manager 中检索用户名和密码凭证。从RDS 代理至底层数据库的连接不经由 IAM。
+ 还可以使用端到端 IAM 身份验证，通过代理使用 IAM 连接到数据库，而无需提供数据库凭证。

 要使用 IAM 身份验证连接到 RDS 代理，请使用与对 RDS 数据库实例使用 IAM 身份验证相同的常规连接过程。有关使用 IAM 的一般信息，请参阅[Amazon RDS 中的安全性](UsingWithRDS.md)。如果使用端到端 IAM 身份验证，请向您的数据库用户提供 IAM 身份验证插件。请参阅[使用 IAM 身份验证创建数据库账户](UsingWithRDS.IAMDBAuth.DBAccounts.md)。

 RDS Proxy 在 IAM 用法方面的主要区别包括：
+ 使用标准 IAM 身份验证时，数据库用户在数据库中拥有常规凭证。您可以设置包含这些用户名和密码的 Secrets Manager 密钥，并授权 RDS Proxy 从 Secrets Manager 中检索凭证。IAM 身份验证应用于您的客户端程序与代理之间的连接。然后，代理使用从 Secrets Manager 中检索的用户名和密码凭证对数据库进行身份验证。
+ 使用端到端 IAM 身份验证时，无需为数据库凭证配置 Secrets Manager 密钥。IAM 身份验证适用于客户端与代理及代理与数据库之间的连接。
+ 指定代理端点，而不是实例、集群或读取器端点。有关代理端点的详细信息，请参阅 [使用 IAM 身份验证连接到数据库实例](UsingWithRDS.IAMDBAuth.Connecting.md)。
+ 当使用 IAM 身份验证连接到代理时，确保您使用传输层安全性 (TLS)/安全套接字层 (SSL)。

您可以通过修改 IAM 策略授予特定用户对代理的访问权限。下面是一个示例。

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

**提示**  
为 RDS 代理连接配置 IAM 身份验证时，请遵循以下重要准则以避免连接问题：  
在为同一数据库用户或角色维护常规密码身份验证时，请勿授予 `rds_iam` 角色。
请记住，当客户端使用 IAM 身份验证连接到 RDS 代理时，RDS 代理始终通过 Secrets Manager 使用密码身份验证连接到数据库。
如果您经常遇到连接终止和重新连接的情况，请撤销用户或角色的所有现有 `rds_iam` 授权，仅使用密码身份验证。
确保您的密码策略符合 SCRAM-SHA-256 安全字符要求。
对同一个数据库用户混用 IAM 和密码身份验证方法可能会导致连接不稳定。

## 连接到 Microsoft SQL Server 的注意事项
<a name="rds-proxy-connecting-sqlserver"></a>

要使用 IAM 身份验证连接到代理，请勿使用密码字段。相反，您可以在令牌字段中为每种类型的数据库驱动程序提供相应的令牌属性。例如，对 JDBC 使用 `accessToken` 属性，或对 ODBC 使用 `sql_copt_ss_access_token` 属性。或者对于 .NET SqlClient 驱动程序使用 `AccessToken` 属性。您不能对不支持令牌属性的客户端使用 IAM 身份验证。

在某些情况下，代理无法共享数据库连接，而是将从客户端应用程序到代理的连接固定到专用的数据库连接。有关这些条件的更多信息，请参阅 [避免固定 RDS 代理](rds-proxy-pinning.md)。

## 连接到 PostgreSQL 的注意事项
<a name="rds-proxy-connecting-postgresql"></a>

如果您创建新的 PostgreSQL 数据库用户来连接到 RDS 代理，请确保授予该用户对数据库的 `CONNECT` 权限。否则，用户将无法建立连接。有关更多信息，请参阅 [使用 RDS 代理时向 PostgreSQL 数据库添加新数据库用户](rds-proxy-new-db-user.md#rds-proxy-new-db-user-pg)。

当客户端启动到 PostgreSQL 数据库的连接时，它会发送一条启动消息。此消息包含参数名称/值字符串对。有关详细信息，请参阅 PostgreSQL 文档中的 [PostgreSQL 消息格式](https://www.postgresql.org/docs/current/protocol-message-formats.html)中的 `StartupMessage`。

当您通过 RDS 代理进行连接时，启动消息可以包含以下当前识别的参数：
+  `user` 
+  `database`

 启动消息还可以包含以下其他运行时参数：
+ `[application\$1name](https://www.postgresql.org/docs/current/runtime-config-logging.html#GUC-APPLICATION-NAME) `
+ `[client\$1encoding](https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-CLIENT-ENCODING) `
+ `[DateStyle](https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-DATESTYLE) `
+ `[TimeZone](https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-TIMEZONE) `
+  `[extra\$1float\$1digits](https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-EXTRA-FLOAT-DIGITS) `
+  `[ search\$1path ](https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-SEARCH-PATH)` 

 有关 PostgreSQL 消息收发的更多信息，请参阅 PostgreSQL 文档中的[前端/后端协议](https://www.postgresql.org/docs/current/protocol.html)。

 对于 PostgreSQL，如果您使用 JDBC，我们建议您执行以下操作以避免固定：
+ 将 JDBC 连接参数 `assumeMinServerVersion` 至少设置为 `9.0` 以避免固定。这可阻止 JDBC 驱动程序在运行 `SET extra_float_digits = 3` 时，在连接启动期间执行额外的往返行程。
+ 将 JDBC 连接参数 `ApplicationName` 设置为 `any/your-application-name` 以避免固定。这样做会阻止 JDBC 驱动程序在运行 `SET application_name = "PostgreSQL JDBC Driver"` 时，在连接启动期间执行额外的往返行程。请注意，JDBC 参数为 `ApplicationName`，但 PostgreSQL `StartupMessage` 参数为 `application_name`。

有关更多信息，请参阅 [避免固定 RDS 代理](rds-proxy-pinning.md)。有关使用 JDBC 进行连接的更多信息，请参阅 PostgreSQL 文档中的[连接到数据库](https://jdbc.postgresql.org/documentation/setup/)。