顧客管理の暗号鍵

このページでは、独自の暗号鍵を使用して、米国と EU のマルチリージョンにあるデータストアを保護する方法について説明します。

デフォルトでは、Vertex AI Agent Builder は保存されているコンテンツを暗号化します。このデフォルトの暗号化の処理と管理は Vertex AI Agent Builder で自動的に行われるため、ユーザー側での作業は不要です。

ただし、データを保護する鍵に関連する特定のコンプライアンス要件または規制要件がある場合は、顧客管理の暗号鍵（CMEK）を使用してリソースを保護できます。この場合は、Cloud KMS 鍵を使用して、このページの手順に沿って操作します。鍵は、米国のマルチリージョンまたは EU マルチリージョンの特定のロケーションに関連付けられます。

Cloud KMS 鍵は、データストアとアプリ内のデータを暗号化および復号するために使用されます。Cloud KMS の一般的な情報については、Cloud Key Management Service のドキュメントをご覧ください。

Vertex AI Agent Builder での Cloud KMS の制限

Vertex AI Agent Builder の CMEK（Cloud KMS）鍵には、次の制限が適用されます。

  • データストアにすでに適用されている鍵は変更できません。

  • CMEK 組織のポリシーがある場合は、Google Cloud コンソールではなく API を使用して新しいデータストアを作成する必要があります。CMEK 組織のポリシーが有効になっている場合、Google Cloud コンソールを使用して新しいデータストアを作成することはできません。

  • 鍵を登録した後、登録解除したりデータストアから削除したりすることはできません。

  • US または EU のマルチリージョン データストアとアプリ（グローバルでないもの）を使用する必要があります。マルチリージョンとデータ レジデンシーの詳細（グローバル以外のロケーションの使用に関連する上限など）については、Vertex AI Search のロケーションまたは Vertex AI エージェントのロケーションをご覧ください。

  • プロジェクトに複数の鍵を登録する必要がある場合は、Google アカウント チームに連絡して CMEK 構成の割り当て増加をリクエストし、複数の鍵が必要な理由を説明してください。

  • CMEK で外部鍵マネージャー（EKM）またはハードウェア セキュリティ モジュール（HSM）を使用することは、許可リスト付きで一般提供されています。CMEK で EKM または HSM を使用するには、Google アカウント チームにお問い合わせください。

    CMEK を使用する EKM または HSM には、次の制限が適用されます。

    • 暗号化と復号の呼び出しの EKM と HSM の割り当てには、1,000 QPM 以上のヘッドルームが必要です。割り当てを確認する方法については、Cloud KMS の割り当てを確認するをご覧ください。

    • EKM を使用する場合は、30 秒を超える時間枠の 90% 以上で鍵にアクセスできる必要があります。この時間内に鍵にアクセスできないと、インデックス登録と検索の鮮度に悪影響を及ぼす可能性があります。

    • 課金に関する問題、継続した割り当て不足の問題、または 12 時間以上の継続したアクセス不可能の問題がある場合、サービスは EKM 鍵または HSM 鍵に関連付けられた CmekConfig を自動的に停止します。

  • 鍵がプロジェクトに登録される前に作成されたデータストアは、鍵で保護できません。

  • Vertex AI Search の場合は、Enterprise エディションが必要です。Enterprise エディションの詳細については、高度な機能についてをご覧ください。

  • CMEK 鍵で保護されているデータストアに対して検索モデルをチューニングすることはできません。

  • 医療検索データストアは CMEK に準拠しています。ただし、他のサードパーティ コネクタ データストアと BigQuery 定期コネクタは CMEK に準拠していません。医療データストアに関する一般的な情報については、医療検索データストアを作成するをご覧ください。サードパーティ製コネクタについて詳しくは、サードパーティ データソースを接続するをご覧ください。

  • レコメンデーション アプリでは鍵のローテーションはサポートされていません。レコメンデーション アプリに関連付けられているデータストアを保護する鍵バージョンを無効にするか破棄すると、レコメンデーション アプリは機能しなくなります。

  • 鍵のローテーションはアナリティクスに対応していません。データストアの鍵をローテーションすると、そのデータストアを使用するアプリでアナリティクスが表示されなくなります。

  • CMEK 鍵は以下の RAG API には適用されません。 Check grounding、Randking、Grounded generation。

始める前に

次の前提条件を満たしていることを確認します。

  • 対称 Cloud KMS 鍵のローテーション期間が [なし（手動ローテーション）] に設定されている。Cloud KMS のドキュメントで、キーリングを作成すると鍵を作成するをご覧ください。

  • 鍵に対する CryptoKey Encrypter/Decrypter IAM ロール（roles/cloudkms.cryptoKeyEncrypterDecrypter）が Discovery Engine サービス エージェントに付与されいる。 サービス エージェントにロールを追加する一般的な手順については、単一ロールの付与または取り消しをご覧ください。

  • 鍵に対する CryptoKey Encrypter/Decrypter IAM ロール（roles/cloudkms.cryptoKeyEncrypterDecrypter）が Cloud Storage サービス エージェントに付与されている。このロールが付与されていない場合、Discovery Engine はインポートに必要な CMEK で保護された一時バケットとディレクトリを作成できないため、CMEK で保護されたデータストアのデータのインポートは失敗します。

  • このページの鍵の登録手順を完了するまで、鍵で管理するデータストアやアプリを作成しないでください。

  • アプリで Enterprise エディションの機能が有効になっている。Enterprise エディションを有効または無効にするをご覧ください。

Cloud KMS 鍵を登録する

Vertex AI Agent Builder に独自のマネージド キーを登録する手順は次のとおりです。

  1. 登録する Cloud KMS 鍵を指定して UpdateCmekConfig メソッドを呼び出します。

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"kms_key":"projects/KMS_PROJECT_ID/locations/KMS_LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME"}' \
"https://LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/cmekConfigs/CMEK_CONFIG_ID?set_default=SET_DEFAULT"
    • KMS_PROJECT_ID: 鍵を含むプロジェクトの ID。プロジェクト番号は使用できません。
    • KMS_LOCATION: KMS 鍵のマルチリージョン（us または europe）。
    • KEY_RING: 鍵を含むキーリングの名前
    • KEY_NAME: 鍵の名前。
    • PROJECT_ID: データストアを含むプロジェクトの ID。
    • LOCATION: データストアのマルチリージョン（us または eu）。
    • CMEK_CONFIG_ID: CmekConfig リソースの ID。
    • SET_DEFAULT: マルチリージョンで作成される後続のデータストアのデフォルト鍵としてこの鍵を使用するには、true に設定します。

    curl の呼び出しとレスポンスの例を次に示します。

    $ curl -X PATCH
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json
-d '{"kms_key":"projects/key-project-456/locations/us/keyRings/my-key-ring/cryptoKeys/my-key"}'
"https://us-discoveryengine.googleapis.com/v1alpha/projects/my-ai-app-project-123/locations/us/cmekConfigs/cmek-config-1?set_default=true"
 
{
 "name": "projects/my-ai-app-project-123/locations/us/operations/update-cmek-config-56789",
 "metadata": {
  "@type": "type.googleapis.com/google.cloud.discoveryengine.v1alpha.UpdateCmekConfigMetadata"
 }
}

  2. 省略可: メソッドから返された name 値を記録し、長時間実行オペレーションの詳細を取得するの手順に沿って、オペレーションが完了したかどうかを確認します。

    通常、鍵の登録には数分かかります。

オペレーションが完了すると、そのマルチリージョン内の新しいデータストアが鍵で保護されます。データストアの作成に関する一般的な情報については、検索データストアを作成するをご覧ください。

Cloud KMS 鍵を表示する

Vertex AI Agent Builder に登録されている鍵を表示するには、次のいずれかを行います。

  • CmekConfig リソース名がある場合は、GetCmekConfig メソッドを呼び出します。

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/cmekConfigs/CMEK_CONFIG_ID"
    • LOCATION: データストアのマルチリージョン（us または eu）。
    • PROJECT_ID: データを含むプロジェクトの ID
    • CMEK_CONFIG_ID: CmekConfig リソースの ID。

    curl の呼び出しとレスポンスの例を次に示します。

    $ curl -X GET
-H "Authorization: Bearer $(gcloud auth print-access-token)"
"https://us-discoveryengine.googleapis.com/v1alpha/projects/my-ai-app-project-123/locations/us/cmekConfigs/cmek-config-1"
 
{
  "name": "projects/my-ai-app-project-123/locations/us/cmekConfigs/cmek-config-1",
  "kms_key": "projects/key-project-456/locations/us/keyRings/my-key-ring/cryptoKeys/my-key"
  "state": "ACTIVE"
  "is_default": true
}

  • CmekConfig リソース名がない場合は、ListCmekConfigs メソッドを呼び出します。

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/cmekConfigs"
    • LOCATION: データストアのマルチリージョン（us または eu）。
    • PROJECT_ID: データを含むプロジェクトの ID

    curl の呼び出しとレスポンスの例を次に示します。

    $ curl -X GET
-H "Authorization: Bearer $(gcloud auth print-access-token)"
"https://us-discoveryengine.googleapis.com/v1alpha/projects/my-ai-app-project-123/locations/us/cmekConfigs"
 
{
  "cmek_configs": [
    {
      "name": "projects/my-ai-app-project-123/locations/us/cmekConfigs/cmek-config-1",
      "kms_key": "projects/key-project-456/locations/us/keyRings/my-key-ring/cryptoKeys/my-key"
      "state": "ACTIVE"
      "is_default": true
    }
    {
      "name": "projects/my-ai-app-project-123/locations/us/cmekConfigs/cmek-config-2",
      "kms_key": "projects/key-project-456/locations/us/keyRings/my-key-ring/cryptoKeys/my-key-2"
      "state": "ACTIVE"
    }
  ]
}

省略可: データストアが鍵で保護されていることを確認する

鍵が登録される前に作成されたデータストアは、鍵で保護されません。特定のデータストアが鍵で保護されていることを確認する手順は次のとおりです。

  1. データストアで次の curl コマンドを実行します。

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "x-goog-user-project: PROJECT_ID" \
"https://LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/dataStores/DATA_STORE_ID"
    • LOCATION: データストアのマルチリージョン（us または eu）。
    • PROJECT_ID: データストアを含むプロジェクトの ID。
    • DATA_STORE_ID: データストアの ID。

    curl 呼び出しの例を次に示します。 

    curl -X GET
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
-H "x-goog-user-project: my-ai-app-project-123"
"https://us-discoveryengine.googleapis.com/v1alpha/projects/my-ai-app-project-123/locations/us/collections/default_collection/dataStores/my-data-store-1"

  2. コマンドの出力を確認します。cmekConfig フィールドが出力に含まれ、kmsKey フィールドに登録した鍵が表示されている場合、データストアは鍵で保護されています。

    レスポンスの例は次のようになります。

    {
 "name": "projects/969795412903/locations/us/collections/default_collection/dataStores/my-data-store-1",
 "displayName": "my-data-store-1",
 "industryVertical": "GENERIC",
 "createTime": "2023-09-05T21:20:21.520552Z",
 "solutionTypes": [
   "SOLUTION_TYPE_SEARCH"
 ],
 "defaultSchemaId": "default_schema",
 "cmekConfig": {
   "name": "projects/969795412903/locations/us/collections/default_collection/dataStores/my-data-store-1/cmekConfigs/cmek-config-1",
   "kmsKey": "projects/my-ai-app-project-123/locations/us/keyRings/my-key-ring/cryptoKeys/my-key"
 }
}

鍵のローテーション

鍵をローテーションすると、新しいバージョンの鍵が作成され、新しいバージョンがメインのバージョンとして設定されます。元のバージョンの鍵は、無効にする前にしばらく有効なままにしておきます。これにより、古い鍵を使用している可能性のある長時間実行オペレーションを完了させます。

次の手順では、Vertex AI Agent Builder データストアの鍵をローテーションする手順について説明します。鍵のローテーションの一般的な情報については、Cloud KMS ガイドの鍵のローテーションをご覧ください。

重要: レコメンデーション アプリやアナリティクスを必要とするアプリに関連付けられたデータストアで鍵をローテーションしないでください。Vertex AI Agent Builder での Cloud KMS の制限事項をご覧ください。

  1. 鍵を再登録します。これを行うには、Cloud KMS 鍵を登録するのステップ 1 を繰り返します。

  2. 次の操作を行うには、Cloud KMS ガイドの鍵を管理するセクションの手順をご覧ください。

    1. 新しい鍵バージョンを作成し、有効にして、メインにします。

    2. 古い鍵バージョンは有効のままにします。

    3. 1 週間ほど経過したら、古い鍵バージョンを無効にして、すべてが以前と同じように動作していることを確認します。

    4. 後日、古い鍵バージョンを無効にしても問題が発生していないことを確認できたら、古い鍵バージョンを破棄できます。

鍵が無効化または取り消された場合

鍵が無効になった場合、または鍵の権限が取り消された場合、データストアは 15 分以内にデータの取り込みとデータの提供を停止します。 ただし、鍵を再度有効にしたり、権限を復元したりするには時間がかかります。データストアがデータの提供を再開するまでには、最長で 24 時間ほどかかることがあります。

したがって、必要でない限り鍵を無効にしないでください。データストアで鍵を無効化または有効化するのは時間のかかるオペレーションです。たとえば、鍵を無効と有効の間で繰り返し切り替えると、データストアが保護された状態になるまでに時間がかかることになります。鍵を無効にしてすぐに再度有効にすると、鍵が最初にデータストアから無効にされ、その後再度有効になるため、数日間のダウンタイムが発生する可能性があります。