管理 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 角色后，主账号便可以访问项目中的所有实例。

**注意**： 如需了解如何按实例限制用户访问权限，请参阅 根据资源名称前缀授予对一组资源的访问权限。为实例授予有限访问权限时，请使用 resource.name 属性，并使用以下格式作为实例名称：projects/PROJECT/locations/REGION/instances/INSTANCE_NAME。

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

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

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

1. 如果您还没有与 Valkey 实例使用同一 授权网络的 Compute Engine 虚拟机，请创建一个虚拟机并按照 Linux 虚拟机使用快速入门中的说明连接到该虚拟机。

2. 为您的项目启用 Cloud Platform API 范围。如需详细了解如何启用此访问权限范围，请参阅服务帐号并更新访问权限范围。如需详细了解此范围的最佳实践，请参阅 范围最佳实践。

3. 为您的项目启用 Memorystore for Valkey API。

   Memorystore for Valkey API

4. 按照 安装 Valkey 中的说明，在 Compute Engine 虚拟机上安装 valkey-cli。

5. 运行以下命令，检索 IAM 用户的访问令牌：

   gcloud auth print-access-token
   

   访问令牌会在一小时后过期。如需了解详情，请参阅 IAM 访问令牌时限。

6. 连接到实例的发现端点：

   valkey-cli -h NETWORK_ADDRESS -p PORT -a ACCESS_TOKEN -c
   

   替换以下内容：

   • NETWORK_ADDRESS：实例的网络地址。如需查看 网络地址，请参阅查看实例信息。

   • PORT：实例的端口号。如需查看端口号，请参阅 查看实例信息。

   • ACCESS_TOKEN：您在 上一步中检索到的访问令牌。

   如果您指定了用户名，则必须使用 default 用户名或 IAM 主账号电子邮件地址。此外，经过身份验证的连接在令牌过期后仍然有效。如需了解详情，请参阅 IAM 访问令牌时限。

   如果您在实例上启用了传输加密，则必须附加传输层安全协议 (TLS) 标志。例如：

   valkey-cli -h NETWORK_ADDRESS -p PORT -a ACCESS_TOKEN -c --tls --cacert /tmp/server_ca.pem
   

   重要提示：如果您有集群模式已停用的 实例，请勿使用 -c 标志。

7. 可选：如果您有集群模式已启用的实例，请运行 CLUSTER SHARDS 命令以查看节点拓扑。记下其中一个节点的 IP 地址和端口号。

   如果您有集群模式已停用的实例，则可以跳过此步骤。

8. 如需使用 valkey-cli 进行身份验证并连接到节点，请使用以下命令：

   valkey-cli -h NODE_IP_ADDRESS -p NODE_PORT -a ACCESS_TOKEN -c
   

   替换以下内容：

   • NODE_IP_ADDRESS：您在 上一步中记下的节点的 IP 地址
   • NODE_PORT：您在上一步中记下的节点的端口号
   • ACCESS_TOKEN：您在此过程前面检索到的 IAM 访问令牌

9. 如需验证您是否已与节点建立经过身份验证的连接，请运行 Valkey SET 和 GET 命令。

10. 删除用于连接到实例的 Compute Engine 虚拟机 。这有助于避免系统向您的 Cloud Billing 帐号收取费用。

自动检索访问令牌

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

1. （可选） 如果您尚未为应用创建服务帐号，请创建一个（请参阅创建和管理服务账号）。

   gcloud iam service-accounts create SA_NAME \
       --description="DESCRIPTION" \
       --display-name="DISPLAY_NAME"
   

   替换以下内容：

   • SA_NAME 是服务帐号的名称。
   • DESCRIPTION 是服务帐号的可选说明。
   • DISPLAY_NAME 是要在 Google Cloud 控制台中显示的服务帐号名称。

2. 向您的服务帐号授予对项目的 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。

3. 以指定的服务帐号的身份对应用进行身份验证。如需了解详情，请参阅服务账号 。

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

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

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

排查 IAM 身份验证错误消息

出错提示	推荐措施	说明
-WRONGPASS invalid username-password pair or user is disabled	验证提供给 Memorystore for Valkey 服务器的访问令牌，并确保已启用匹配的 ACL 用户。	IAM 主账号缺少所需的权限，您提供的访问令牌无效，或者匹配的 ACL 用户已停用。 验证访问令牌未过期，并且您已按照连接到使用 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.	验证用户名或使用指数退避算法重试。	出现此错误的原因如下： 您提供的用户名无效。您可以使用 default 用户名、省略用户名或使用 IAM 主账号电子邮件地址。 IAM 后端向 Memorystore for Valkey 服务器返回了暂时性错误。 如果用户名有效，我们建议您的应用尝试使用指数退避算法重试此错误，以防止进一步连接失败。