管理 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 是執行個體的節點類型。

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

授予 IAM 驗證權限

如要授予 IAM 存取權，請按照授予 IAM 角色操作說明，將 roles/memorystore.dbConnectionUser 角色授予主體。

根據預設，將 roles/memorystore.dbConnectionUser 角色授予主體後，主體就能存取專案中的所有執行個體。

為執行個體建立權限受限的 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：在上一個步驟中擷取的存取權杖。

    通過驗證的連線有效期限為 12 小時。詳情請參閱「IAM 存取權杖時間範圍」。

    如果您在執行個體上啟用傳輸中資料加密功能，就必須附加傳輸層安全標準 (TLS) 旗標。例如：

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

  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 伺服器的使用者名稱和存取權杖 您提供的使用者名稱或存取權杖無效。系統只支援「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 伺服器傳回暫時性錯誤。應用程式應嘗試以指數輪詢方式重試，避免連線再次失敗。