管理 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 節點類型沒有服務水準協議，因此建議您僅用於開發或測試。如果您在正式環境中執行 Memorystore for Valkey，建議使用其他節點類型。

• SHARD_COUNT 會決定執行個體中的 shard 數量。分片數量會決定儲存執行個體資料的總記憶體容量。如要進一步瞭解執行個體規格，請參閱「執行個體和節點規格」。

授予 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. Compute Engine VM 必須與 Valkey 執行個體使用相同的授權網路，如果不存在這樣的 VM，請按照快速入門導覽課程：使用 Linux VM 來建立及連線至 VM。

2. 為專案啟用 Cloud Platform API 範圍。如要進一步瞭解如何啟用這項存取權範圍，請參閱「附加服務帳戶並更新存取權範圍」。如要進一步瞭解這個範圍的最佳做法，請參閱「範圍最佳做法」。

3. 為專案啟用 Memorystore for Valkey API。

   Memorystore for Valkey API

4. 按照「安裝 Valkey」一文的操作說明，在 Compute Engine VM 上安裝 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 VM。這樣可以避免 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 伺服器。 如果使用者名稱有效，建議應用程式嘗試以指數輪詢重試此錯誤，避免連線進一步失敗。