Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

管理 IAM 身份验证

本页面提供了有关 Memorystore for Valkey 的 IAM 身份验证功能的常见任务的说明。如需详细了解此功能，请参阅 IAM 身份验证简介。

使用 IAM 身份验证创建实例

如需创建使用 IAM 身份验证的 Memorystore for Valkey 实例，请运行 create 命令：

gcloud memorystore instances create INSTANCE_ID --region=REGION_ID --network=NETWORK --node-type=NODE_TYPE --shard-count=SHARD_COUNT --authorization-mode=iam-auth

替换以下内容：

INSTANCE_ID 是您要创建的 Memorystore for Valkey 实例的 ID。实例 ID 的长度必须介于 1 到 63 个字符之间，并且只能使用小写字母、数字或连字符。它必须以小写字母开头，并以小写字母或数字结尾。
REGION_ID 是您希望实例所在的区域。
NETWORK 是用于创建实例的网络。它必须使用以下格式：projects/NETWORK_PROJECT_ID/global/networks/NETWORK_ID。此处使用的网络 ID 必须与服务连接政策使用的网络 ID 匹配。否则，create 操作会失败。如需了解详情，请参阅网络。
NODE_TYPE 是实例的节点类型。

注意：我们建议您仅将 shared-core-nano节点类型用于开发或测试目的，因为此节点类型没有 SLA。如果您在生产环境中运行 Memorystore for Valkey，我们建议您使用其他节点类型。
SHARD_COUNT 决定了实例中的分片数量。分片数量决定了用于存储实例数据的总内存容量。如需详细了解实例规范，请参阅实例和节点规范。

授予 IAM 身份验证的权限

如需授予 IAM 访问权限，请使用授予 IAM 角色说明向主账号授予 roles/memorystore.dbConnectionUser角色。

默认情况下，向主账号授予 roles/memorystore.dbConnectionUser 角色后，主账号便可以访问项目中的所有实例。

为实例创建受限 IAM 管理员角色

您可能需要创建一个可以修改实例连接 IAM 权限的角色，而无需授予完整的 IAM 管理员访问权限。为此，您可以为 roles/memorystore.dbConnectionUser 角色创建受限 IAM 管理员。如需了解更多详情，请参阅创建受限 IAM 管理员。

连接到使用 IAM 身份验证的实例

如果您还没有与 Valkey 实例使用同一授权网络的 Compute Engine 虚拟机，请创建一个虚拟机并按照 Linux 虚拟机使用快速入门中的说明连接到该虚拟机。
为您的项目启用 Cloud Platform API 范围。如需详细了解如何启用此访问权限范围，请参阅服务帐号并更新访问权限范围。如需详细了解此范围的最佳实践，请参阅范围最佳实践。
为您的项目启用 Memorystore for Valkey API。
Memorystore for Valkey API
按照安装 Valkey 中的说明，在 Compute Engine 虚拟机上安装 valkey-cli。
运行以下命令，检索 IAM 用户的访问令牌：
```
gcloud auth print-access-token
```
访问令牌会在 1 小时后过期。如需了解详情，请参阅 IAM 访问令牌时限。
连接到实例的发现端点：
```
valkey-cli -h NETWORK_ADDRESS -p PORT -a ACCESS_TOKEN -c
```
替换以下内容：
- NETWORK_ADDRESS：实例的网络地址。如需查看网络地址，请参阅查看实例信息。
- PORT：实例的端口号。如需查看端口号，请参阅查看实例信息。
- ACCESS_TOKEN：您在上一步中检索到的访问令牌。
经过身份验证的连接有效期为 12 小时。如需了解详情，请参阅 IAM 访问令牌时限。

如果您在实例上启用了传输加密，则必须附加传输层安全协议 (TLS) 标志。例如：
```
valkey-cli -h NETWORK_ADDRESS -p PORT -a ACCESS_TOKEN -c --tls --cacert /tmp/server_ca.pem
```
运行 CLUSTER SHARDS 命令，查看节点拓扑。记下其中一个节点的 IP 地址和端口号。
如需使用 valkey-cli 进行身份验证并连接到节点，请使用以下命令：
```
valkey-cli -h NODE_IP_ADDRESS -p NODE_PORT -a ACCESS_TOKEN -c
```
替换以下内容：
- NODE_IP_ADDRESS：您在上一步中记下的节点的 IP 地址
- NODE_PORT：您在上一步中记下的节点的端口号
- ACCESS_TOKEN：您在此过程前面检索到的 IAM 访问令牌
如需验证您是否已与节点建立经过身份验证的连接，请运行 Valkey SET 和 GET 命令。
删除用于连接到实例的 Compute Engine 虚拟机。这有助于避免系统向您的 Cloud Billing 帐号收取费用。

自动检索访问令牌

我们强烈建议您在应用中自动检索访问令牌。由于访问令牌的生命周期较短，因此很难对令牌进行硬编码。

（可选） 如果您尚未为应用创建服务帐号，请创建一个（请参阅创建和管理服务账号）。
```
gcloud iam service-accounts create SA_NAME \
    --description="DESCRIPTION" \
    --display-name="DISPLAY_NAME"
```
替换以下内容：
- SA_NAME 是服务帐号的名称。
- DESCRIPTION 是服务帐号的可选说明。
- DISPLAY_NAME 是要在 Google Cloud 控制台中显示的服务帐号名称。
向您的服务帐号授予对项目的 memorystore.dbConnectionUser 角色。
```
gcloud projects add-iam-policy-binding PROJECT_ID \
--member="serviceAccount:SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
--role=roles/"ROLE_NAME"
```
替换以下内容：
- PROJECT_ID：项目 ID。
- SA_NAME：服务帐号的名称。
- ROLE_NAME：角色名称。对于此示例：memorystore.dbConnectionUser。
以指定服务帐号的身份对应用进行身份验证。如需了解详情，请参阅服务账号。

如需查看展示如何使用热门客户端库对应用进行身份验证的代码示例，请参阅客户端库代码示例。

连接到使用 IAM 身份验证的实例的代码示例

如需查看与 Valkey 兼容的代码示例，了解如何设置客户端库以连接到使用 IAM 身份验证的实例，请参阅IAM 身份验证和传输加密的代码示例。

排查 IAM 身份验证错误消息

出错提示	推荐措施	说明
`-WRONGPASS invalid username-password pair or user is disabled`	验证提供给 Memorystore for Valkey 服务器的用户名和访问令牌	提供的用户名或访问令牌无效。仅支持用户名“default”。如果您的应用已在使用“default”用户名，请验证访问令牌是否已过期，并按照连接到使用 IAM 身份验证的实例中的说明检索访问令牌。如果 IAM 权限是最近更改的，则可能需要几分钟才能完成同步。
`-NOAUTH Authentication required`	检查应用是否配置为向 Memorystore for Valkey 服务器提供 IAM 访问令牌	应用未向 Memorystore for Valkey 服务器提供访问令牌。按照连接到使用 IAM 身份验证的实例中的说明，验证应用是否配置为提供访问令牌
`-ERR (ERR_IAM_EXHAUSTED) Memorystore IAM authentication backend quota exceeded.`	使用指数退避算法重试	IAM 后端过载，并向 Memorystore for Valkey 服务器返回了超出配额错误。应用应尝试使用指数退避算法重试此错误，以防止进一步的连接失败。
`-ERR (ERR_IAM_OTHER) Memorystore IAM authentication backend error.`	使用指数退避算法重试	IAM 后端向 Memorystore for Valkey 服务器返回了暂时性错误。应用应尝试使用指数退避算法重试此错误，以防止进一步的连接失败。