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 --auth-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 VM がまだない場合は、作成してから、 Linux VM の使用に関するクイックスタートに沿って接続します。

2. プロジェクトで、Cloud Platform API スコープを有効にします。このアクセス スコープを有効にする方法について詳しくは、 サービス アカウントを接続してアクセス スコープを更新するをご覧ください。このスコープのベスト プラクティスについて詳しくは、 スコープのベスト プラクティスをご覧ください。

3. プロジェクトで、Memorystore for Valkey API を有効にします。

   Memorystore for Valkey API

4. Valkey をインストールするの手順に沿って、 `valkey-cli` を Compute Engine VM にインストールします。valkey-cli

5. 次のコマンドを実行して、IAM ユーザーのアクセス トークンを取得します。

   gcloud auth print-access-token
   

   注: アクセス トークンの有効期限は 1 時間です。詳細については、IAM アクセス トークンの有効期間をご覧ください。

6. インスタンスの検出エンドポイントに接続します。

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

   以下を置き換えます。

   • NETWORK_ADDRESS は、インスタンスのネットワーク アドレスです。ネットワーク アドレスを表示するには、インスタンス情報を表示するをご覧ください。

   • PORT は、インスタンスのポート番号です。ポート番号を表示するには、 インスタンス情報を表示するをご覧ください。

   • ACCESS_TOKEN は、前の手順で取得した IAM アクセス トークンです。

   注: 認証済み接続は 12 時間有効です。詳細については、 IAM アクセス トークンの有効期間をご覧ください。

7. CLUSTER SHARDS コマンドを実行して、ノード トポロジを表示します。ノードの IP アドレスとポート番号のいずれかをメモします。

8. 次のコマンドを実行して、選択したノードに接続します。

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

   以下を置き換えます。

   • NODE_IP_ADDRESS は、前のステップで確認したノードの IP アドレスです。
   • NODE_PORT は、前のステップで確認したノードのポート番号です。

9. Valkey の SET コマンドと GET コマンドを実行して、インスタンスのノードに対する認証済み接続が確立されたことを確認します。

10. Valkey インスタンスへの接続をテストしたら、Valkey インスタンスへの接続に使用した Compute Engine VM を削除することを検討してください。そうすることで、Cloud 請求先アカウントへの課金を回避できます。

11. 次のコマンドを実行して valkey-cli を使用し、認証を行いインスタンスに接続します。変数は適切な値に置き換えます。

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

    以下を置き換えます。

    • NETWORK_ADDRESS は、インスタンスのネットワーク アドレスです。ネットワーク アドレスを表示するには、インスタンス情報を表示するをご覧ください。

    • PORT は、インスタンスのポート番号です。ポート番号を表示するには、 インスタンス情報を表示するをご覧ください。

    • ACCESS_TOKEN は、前の手順で取得した IAM アクセス トークンです。

    注: 認証済み接続は 12 時間有効です。詳細については、 IAM アクセス トークンの有効期間をご覧ください。

12. Valkey の SET コマンドと GET コマンドを実行して、インスタンスに対する認証済み接続が確立されたことを確認します。

13. Valkey インスタンスへの接続をテストしたら、Valkey インスタンスへの接続に使用した Compute Engine VM を削除することを検討してください。そうすることで、Cloud 請求先アカウントへの課金を回避できます。

アクセス トークンの取得を自動化する

アプリケーションでアクセス トークンの取得を自動化することを強くおすすめします。アクセス トークンの有効期限は短いため、トークンをハードコードすることは困難です。

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 認証を使用するインスタンスに接続するコードサンプル

IAM 認証を使用するインスタンスに接続するようにクライアント ライブラリを設定する方法を示す Valkey 互換のコードサンプルについては、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 サーバーに一時的なエラーを返しました。接続障害がさらに発生しないように、アプリケーションは指数バックオフを使用してこのエラーを再試行する必要があります。