本页面介绍了如何设置和使用 AlloyDB Auth Proxy 以建立与 AlloyDB 实例的授权加密连接。如需从概念上大致了解 Auth Proxy,请参阅 AlloyDB Auth Proxy 简介。
如需使用 AlloyDB Auth Proxy,您需要执行几个一次性设置步骤,然后启动 Auth Proxy 客户端,接下来使用该客户端连接到数据库:
- 设置步骤:
- 将 Auth Proxy 客户端下载到您的客户端主机。
- 选择要用于授权的 Identity and Access Management (IAM) 主账号,确保它具有所需的权限,并确保其凭据在客户端主机上可用。
- 针对您要连接的 AlloyDB 实例收集连接 URI。
- 在客户端主机上启动 Auth Proxy 客户端。
- 打开与 Auth Proxy 客户端的本地连接,以将应用连接到数据库。
准备工作
-
客户端主机必须满足以下要求:
它必须可通过网络访问您要连接到的实例所在的虚拟私有云 (VPC) 网络。此虚拟私有云 (VPC) 网络中的客户端主机(例如 Compute Engine 实例)本身便可进行这种访问。如果 AlloyDB 实例的 VPC 网络使用Cloud VPN 隧道或是用于专用互连或合作伙伴互连的 VLAN 连接来连接到外部网络,则外部网络(本地网络或其他 VPC 网络)中的客户端主机可进行这种访问。
如果客户端主机具有出站防火墙政策,则必须允许与 AlloyDB 实例 IP 地址上的端口
5433
建立传出连接,并允许与所有 IP 地址的端口443
(标准 HTTPS 端口)建立传出连接。如果您使用 Compute Engine 实例作为客户端主机,则该实例必须具有
https://www.googleapis.com/auth/cloud-platform
访问权限范围,以便可以使用 AlloyDB Admin API。如有必要,请更改其访问权限范围以包含此范围。
下载 Auth Proxy 客户端
您下载 Auth Proxy 客户端的机器取决于您是想从其 VPC 网络内部还是从其外部连接到 AlloyDB 实例。
如果您想使用专用服务访问通道连接到集群,则可以将 Auth Proxy 客户端下载到在 VPC 网络中运行且对集群具有专用服务访问通道的 Compute Engine 虚拟机 (VM) 实例。
如果您打算从 VPC 外部连接到集群,则安装客户端的机器取决于您使用的外部连接策略。例如,您可以将 Auth Proxy 客户端安装到位于应用本地的 macOS 或 Windows 机器上,然后使用在 AlloyDB VPC 网络中运行的 SOCKS 服务器作为连接中介。如需了解详情,请参阅从集群的 VPC 外部连接到该集群。
Linux
64 位 (AMD)
下载 Auth Proxy 客户端:
wget https://storage.googleapis.com/alloydb-auth-proxy/v1.13.0/alloydb-auth-proxy.linux.amd64 -O alloydb-auth-proxy
使 Auth Proxy 客户端可执行:
chmod +x alloydb-auth-proxy
32 位 (AMD)
下载 Auth Proxy 客户端:
wget https://storage.googleapis.com/alloydb-auth-proxy/v1.13.0/alloydb-auth-proxy.linux.386 -O alloydb-auth-proxy
使 Auth Proxy 客户端可执行:
chmod +x alloydb-auth-proxy
64 位 (ARM)
下载 Auth Proxy 客户端:
wget https://storage.googleapis.com/alloydb-auth-proxy/v1.13.0/alloydb-auth-proxy.linux.arm64 -O alloydb-auth-proxy
使 Auth Proxy 客户端可执行:
chmod +x alloydb-auth-proxy
32 位 (ARM)
下载 Auth Proxy 客户端:
wget https://storage.googleapis.com/alloydb-auth-proxy/v1.13.0/alloydb-auth-proxy.linux.arm -O alloydb-auth-proxy
使 Auth Proxy 客户端可执行:
chmod +x alloydb-auth-proxy
macOS
M1
下载 Auth Proxy 客户端:
curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.13.0/alloydb-auth-proxy.darwin.arm64
使 Auth Proxy 客户端可执行:
chmod +x alloydb-auth-proxy
64 位
下载 Auth Proxy 客户端:
curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.13.0/alloydb-auth-proxy.darwin.amd64
使 Auth Proxy 客户端可执行:
chmod +x alloydb-auth-proxy
32 位
下载 Auth Proxy 客户端:
curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.13.0/alloydb-auth-proxy.darwin.386
使 Auth Proxy 客户端可执行:
chmod +x alloydb-auth-proxy
Windows
64 位
右键点击 https://storage.googleapis.com/alloydb-auth-proxy/v1.13.0/alloydb-auth-proxy-x64.exe,然后选择链接另存为以下载 Auth Proxy 客户端。将文件重命名为 alloydb-auth-proxy.exe
。
32 位
右键点击 https://storage.googleapis.com/alloydb-auth-proxy/v1.13.0/alloydb-auth-proxy-x86.exe,然后选择链接另存为以下载 Auth Proxy 客户端。将文件重命名为 alloydb-auth-proxy.exe
。
Docker 映像
为方便起见,Container Registry 中提供了多个包含 Auth Proxy 客户端的容器映像。
您可以通过 Docker 使用以下命令将最新映像拉取到本地机器:
docker pull gcr.io/alloydb-connectors/alloydb-auth-proxy:latest
其他操作系统
对于此处未列出的其他操作系统,您可以通过源代码编译 Auth Proxy 客户端。
选择 IAM 主账号并为授权做好准备
AlloyDB Auth Proxy 支持使用以下类型的 IAM 主账号向客户端与 AlloyDB 实例之间的连接授权:
用户管理的服务账号。您可以为应用创建 IAM 服务账号,然后使用该账号向连接授权。
Google 强烈建议您在生产环境中使用服务账号进行授权。
您的用户账号。您可以使用自己的 IAM 用户账号向连接授权。
在开发环境中,使用自己的用户账号非常方便,您在该环境中会使用 gcloud CLI 管理 AlloyDB 资源,使用
psql
等工具开发数据库,并在同一主机上开发所有应用代码。Compute Engine 默认服务账号。如果客户端主机是 Compute Engine 实例,您可以使用 Compute Engine 默认服务账号向连接授权。
选择要使用的 IAM 主账号后,您需要确保它具有所需的 IAM 权限,并确保其凭据在客户端主机上可用。
必需的 IAM 权限
您用于向连接授权的 IAM 主账号必须具有 roles/alloydb.client
(Cloud AlloyDB Client) 和 roles/serviceusage.serviceUsageConsumer
(Service Usage Consumer) 预定义角色提供的权限。
如需将 Cloud AlloyDB Client 角色分配给 IAM 主账号,请执行以下操作:
必须在 Google Cloud 项目中启用 Cloud Resource Manager API。
您必须在 Google Cloud 项目中拥有
roles/owner
(Owner) 基本 IAM 角色,或者拥有授予以下权限的角色:resourcemanager.projects.get
resourcemanager.projects.getIamPolicy
resourcemanager.projects.setIamPolicy
如需获得这些权限,同时遵循最小权限原则,请让管理员向您授予
roles/resourcemanager.projectIamAdmin
(Project IAM Admin) 角色。
在客户端主机上提供 IAM 凭据
您如何在客户端主机上提供 IAM 凭据取决于您用于向连接授权的 IAM 主账号的类型:
用户管理的服务账号
如需为用户管理的服务账号提供 IAM 凭据,请创建 JSON 格式的服务账号密钥,并将其下载到您的客户端主机。启动 Auth Proxy 客户端时,请使用
--credentials-file
标志指定密钥文件的位置。您的用户账号
如需为您的用户账号提供 IAM 凭据,请在客户端主机上安装 Google Cloud CLI,然后运行
gcloud init
命令,使用您的用户账号对其进行初始化。启动 Auth Proxy 客户端时,如果您未提供用户管理的服务账号凭据,它会自动发现并使用您的用户账号凭据。Compute Engine 默认服务账号
如果您使用 Compute Engine 实例作为客户端主机,则 Compute Engine 默认服务账号的凭据已处于主机上。启动 Auth Proxy 客户端时,如果用户管理的服务账号和用户账号凭据不可用,它会自动发现并使用这些凭据。
收集 AlloyDB 实例的连接 URI
启动 Auth Proxy 客户端时,您可以使用以下连接 URI 格式确定要连接到的 AlloyDB 实例:
projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID
如需查看所有实例的连接 URI 列表,请使用 gcloud CLI alloydb instances list
命令。
收集您要连接到的每个实例的实例连接 URI。
启动 Auth Proxy 客户端
启动 Auth Proxy 客户端时,您需要向其提供有关要连接到的 AlloyDB 实例的信息,并根据需要提供向这些连接授权时要使用的凭据信息。
启动后,Auth Proxy 客户端会执行以下操作:
- 使用您配置的 IAM 主账号的凭据和 IAM 权限授权连接到 AlloyDB 实例。它会按照特定的步骤序列查找凭据。
- 如果实例启用了公共 IP,则自动授权与来源网络建立公共 IP 连接。
- 配置与每个实例的 Auth Proxy 服务器的专用 TLS 1.3 连接。
- 开始监听本地客户端连接请求。
默认情况下,Auth Proxy 客户端会在 IP 地址 127.0.0.1 上监听 TCP 连接,从端口 5432 开始,每增加一个 AlloyDB 实例(第一个实例除外),端口号便会递增 1。您可以在启动 Auth Proxy 客户端时指定不同的监听器地址和不同的端口。
命令行
./alloydb-auth-proxy INSTANCE_URI... \
[ --credentials-file PATH_TO_KEY_FILE \ ]
[ --token OAUTH_ACCESS_TOKEN \ ]
[ --port INITIAL_PORT_NUMBER \ ]
[ --address LOCAL_LISTENER_ADDRESS \ ]
[ --auto-iam-authn ] \
[ --psc] \
[ --public-ip]
替换以下内容:
INSTANCE_URI
:要连接到的 AlloyDB 实例的实例连接 URI,使用以下格式指定:projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID
您可以通过向 URI 添加
port
查询参数来替换 Auth Proxy 客户端为实例使用的默认本地监听器端口:"projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID?port=PORT"
可选:
PATH_TO_KEY_FILE
:要用于连接授权的用户管理的服务账号的 JSON 密钥文件路径。可选:
OAUTH_ACCESS_TOKEN
:要用于连接授权的 OAuth2 令牌值。可选:
INITIAL_PORT_NUMBER
:在监听本地 TCP 连接时要使用的起始端口号(而不是默认端口5432
)。可选:
LOCAL_LISTENER_ADDRESS
:在监听本地 TCP 连接时要使用的监听器地址(而不是默认的127.0.0.1
)。
可选的 --auto-iam-authn
标志可允许向实例进行自动身份验证。这仅适用于与运行 Auth Proxy 客户端的 IAM 账号关联的数据库用户。如需了解详情,请参阅使用 Auth Proxy 自动进行身份验证。
可选的 --psc
标志可让 Auth Proxy 连接到启用了 Private Service Connect 的实例。如需详细了解如何使用 Private Service Connect 设置 DNS,请参阅配置 DNS 托管式区域和 DNS 记录。
可选的 --public-ip
标志可让 Auth Proxy 使用实例的公共 IP 地址连接到启用了公共 IP 的实例。如需详细了解公共 IP,请参阅使用公共 IP 进行连接。
Docker 容器
使用 docker run
命令启动 Auth Proxy 客户端。
如果您使用的是 Compute Engine 实例提供的凭据,则可以使用类似于以下内容的命令:
docker run \
--publish 127.0.0.1:PORT:PORT \
gcr.io/alloydb-connectors/alloydb-auth-proxy:latest \
--address 0.0.0.0 \
--port PORT \
INSTANCE_URI
替换以下内容:
PORT
:要用于与 Auth Proxy 客户端建立本地连接的端口。默认值为5432
。INSTANCE_URI
:要连接到的 AlloyDB 实例的实例连接 URI,使用以下格式指定:projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID
您可以通过向 URI 添加
port
查询参数来替换 Auth Proxy 客户端为实例使用的默认本地监听器端口:"projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID?port=PORT"
请务必在 --publish
标志中指定 127.0.0.1
前缀,以免 Auth Proxy 客户端在本地主机外部公开。
如需可从 Docker 容器外部访问监听器,必须在 --address
标志中指定 0.0.0.0
值。
如需提供您已存储在本地 JSON 文件中的凭据,请在运行 docker run
命令时添加 --volume
和 --credentials-file
标志:
docker run \
--volume PATH_TO_KEY_FILE:/key.json \
--publish 127.0.0.1:PORT:PORT \
gcr.io/alloydb-connectors/alloydb-auth-proxy:latest \
--address 0.0.0.0 \
--port PORT \
--credentials-file=/key.json \
INSTANCE_URI
将 PATH_TO_KEY_FILE
替换为要用于连接授权的用户管理的服务账号的 JSON 密钥文件路径。
启动示例
以下示例展示了启动 Auth Proxy 客户端的各种方式。它们使用以下示例实例连接 URI:
projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary
projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool
基本启动
./alloydb-auth-proxy \
"projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary"
在此示例中,Auth Proxy 客户端会按照其正常的授权步骤序列向连接授权,然后开始在 127.0.0.1:5432
上监听与 myprimary
实例的本地连接。
使用用户管理的服务账号的启动
./alloydb-auth-proxy \
"projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \\
--credentials-file "myappaccount/key.json"
在此示例中,Auth Proxy 客户端使用用户管理的服务账号的 JSON 密钥(存储在 myappaccount/key.json
)向连接授权,然后开始在 127.0.0.1:5432
上监听与 myprimary
实例的本地连接。
连接到多个实例的启动
./alloydb-auth-proxy \
"projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
"projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool"
在此示例中,Auth Proxy 客户端会按照其正常的授权步骤序列向连接授权,然后开始在 127.0.0.1:5432
上监听与 myprimary
实例的本地连接,并在 127.0.0.1:5433
上监听与 myreadpool
实例的本地连接。
在自定义端口上监听的启动
如果您需要为其他 PostgreSQL 连接预留端口 5432
,将自定义端口用于 Auth Proxy 客户端可能会非常有用。
./alloydb-auth-proxy \
"projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary?port=5000" \
"projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool?port=5001"
在此示例中,Auth Proxy 客户端会按照其正常的授权步骤序列向连接授权,然后开始在 127.0.0.1:5000
上监听与 myprimary
实例的本地连接,并在 127.0.0.1:5001
上监听与 myreadpool
实例的本地连接。
由于这些自定义端口是顺序的,因此可以使用以下启动命令实现相同的效果:
./alloydb-auth-proxy \
"projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
"projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool" \
--port 5000
在自定义 IP 地址上监听的启动
./alloydb-auth-proxy \
"projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
--address "0.0.0.0"
在此示例中,Auth Proxy 客户端会按照其正常的授权步骤序列向连接授权,然后开始在 0.0.0.0:5432
上监听与 myprimary
实例的本地连接。
使用 AlloyDB Auth Proxy 将应用连接到数据库
以下示例展示了如何使用 AlloyDB Auth Proxy 将应用连接到数据库。
psql
示例提供了一个连接命令行工具的示例。
对于某些编程语言,使用 AlloyDB Auth Proxy 连接到 AlloyDB 实例与使用 Cloud SQL Auth 代理连接到 Cloud SQL for PostgreSQL 相同,因此此处的语言示例与用于 Cloud SQL for PostgreSQL 的内容相同。
这些示例基于 Auth Proxy 客户端的默认启动,以便它在 127.0.0.1:5432
上监听本地 TCP 连接。
psql
psql -h 127.0.0.1 -p 5432 -U DB_USER
将 DB_USER
替换为您要以其身份连接的数据库用户,例如 postgres
。
这会提示您输入 DB_USER
用户的密码。
Python
Java
Node.js
Go
如需了解 Web 应用环境下的此代码段,请查看 GitHub 上的自述文件。
C#
如需了解 Web 应用环境下的此代码段,请查看 GitHub 上的自述文件。
Ruby
如需了解 Web 应用环境下的此代码段,请查看 GitHub 上的自述文件。
PHP
如需了解 Web 应用环境下的此代码段,请查看 GitHub 上的自述文件。