顧客管理の暗号鍵

デフォルトでは、Agent Search は保存状態のお客様コンテンツを 暗号化します。Agent Search では、ユーザーが追加で操作を行わなくても、暗号化が行われます。このオプションは、Google のデフォルトの暗号化と呼ばれます。

暗号鍵を管理する場合は、Cloud KMS の顧客管理の暗号鍵 （CMEK）を、Cloud KMS の Agent Search などの CMEK 統合サービスで使用できます。Cloud KMS 鍵を使用すると、保護 レベル、ロケーション、ローテーション スケジュール、使用とアクセスの権限、暗号境界を制御できます。 Cloud KMS を使用すると、鍵の使用状況を追跡すること、監査ログを表示すること、鍵のライフサイクルを管理することが可能です。 データを保護する対称鍵暗号鍵（KEK）は Google が所有して管理するのではなく、ユーザーが Cloud KMS でこれらの鍵を制御および 管理します。

CMEK を使用してリソースを設定した後は、 Agent Search リソースへのアクセスは、Google のデフォルトの暗号化を使用する場合と同様です。 暗号化 オプションの詳細については、顧客管理の暗号鍵（CMEK）をご覧ください。

CMEK 鍵が登録されると、Agent Search は Cloud KMS を定期的に呼び出して、データの論理的に分離されたインスタンスを維持します。これは、CMEK 構成がデフォルトとして設定されておらず、それを使用するアプリやデータ コネクタがない場合でも発生します。使用量は、インスタンスの設定と実行によるものであり、データ量やアクセスするユーザー数によるものではありません。 Cloud Key Management Service の料金をご覧ください。

Agent Search における Cloud KMS の制限事項

Agent Search の CMEK（Cloud KMS）鍵には、以下の制限が適用されます。

  • アプリまたはデータ コネクタにすでに適用されている鍵は変更できませんが、鍵バージョンはローテーションできます。
  • 米国または EU のマルチリージョン アプリとデータストア（グローバルでないもの）を使用する必要があります。 マルチリージョンとデータ所在地の詳細（グローバル以外のロケーションの使用に伴う制限事項など）については、 ロケーションをご覧ください。

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

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

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

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

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

  • 鍵がプロジェクトに登録される前に作成されたアプリやデータ コネクタは、鍵で保護できません。
  • 鍵で保護されているアプリやデータ コネクタの検索モデルをチューニング することはできません。
  • 複数のデータ コネクタがあるアプリでは、1 つのデータ コネクタで CMEK 構成を使用している場合、他のすべてのデータ コネクタでも同じ CMEK 構成を使用する必要があります。

サードパーティ コネクタの単一リージョン鍵について

サードパーティ コネクタを使用していて、独自の鍵を使用して接続データを保護する場合は、マルチリージョン鍵に加えて、単一リージョン鍵を 3 つ追加で作成する必要があります。鍵を作成するコマンドについては、 Cloud KMS 鍵 を登録するの手順をご覧ください。

単一鍵は、次のリージョンに作成する必要があります。

マルチリージョン 単一リージョン
eu europe-west1 europe-west4 europe-north1
us us-east1 us-central1 us-west1

始める前に

次の前提条件を満たしていることを確認してください。

  • マルチリージョン対称 Cloud KMS 鍵を作成します。Cloud KMS ドキュメントのキーリングを作成するとキーを作成するをご覧ください。

    • ローテーション期間を [なし（手動ローテーション）] に設定します。

    • [ロケーション] で [マルチリージョン] を選択し、プルダウンから [europe] または [us] を選択します。

  • 鍵に対する CryptoKey の暗号化 / 複合 IAM ロール（roles/cloudkms.cryptoKeyEncrypterDecrypter）が Discovery Engine サービス エージェントに付与されています。 サービス エージェント アカウントのメールアドレスは、service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com という形式になります。サービス エージェントにロールを追加する一般的な手順については、単一のロールの付与または取り消しをご覧ください。

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

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

Cloud KMS 鍵を登録する

CMEK を使用してデータを暗号化するには、マルチリージョン鍵を登録する必要があります。必要に応じて、データに単一リージョン鍵が必要な場合（サードパーティ コネクタを使用する場合など）は、単一リージョン鍵を登録する必要があります。

始める前に

以下のことを確認してください。

  • リージョンが鍵で保護されていない。鍵が REST コマンドですでにリージョンに登録されている場合、次の手順は失敗します。 ロケーションの Agent Search にアクティブな鍵があるかどうかを確認するには、Cloud KMS 鍵を表示するをご覧ください。

手順

REST

Agent Search 用に独自の鍵を登録する手順は次のとおりです。

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

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"kmsKey":"projects/KMS_PROJECT_ID/locations/KMS_LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME"}' \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cmekConfigs/CMEK_CONFIG_ID?set_default=SET_DEFAULT"

    次のように置き換えます。

    • KMS_PROJECT_ID: 鍵を含むプロジェクトの ID。プロジェクト番号は使用できません。
    • KMS_LOCATION: 鍵のマルチリージョン（us または europe）。
    • KEY_RING: 鍵を含むキーリングの名前。
    • KEY_NAME: 鍵の名前
    • PROJECT_ID: アプリまたはデータ コネクタを含むプロジェクトの ID。
    • LOCATION: アプリまたはデータ コネクタのマルチリージョン（us または eu）。
    • CMEK_CONFIG_ID: CmekConfig リソースの一意の ID を設定します（例: default_cmek_config）。

    • SET_DEFAULT: マルチリージョンで作成される後続のアプリとデータ コネクタのデフォルト鍵としてこの鍵を使用するには、true に設定します。

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

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

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

  3. アプリを作成します。手順については、アプリを作成するとアプリとデータストアについてをご覧ください。

コンソール

手順

Agent Search 用に独自の鍵を登録する手順は次のとおりです。

  1. コンソールで、[AI アプリケーション] ページに移動します。 Google Cloud

    AI Applications

  2. [**設定**] をクリックし、[**CMEK**] タブを選択します。

  3. [us] または [eu] のロケーションの [鍵を追加] をクリックします。

    ロケーションの [鍵を追加] をクリックします。
    [鍵を追加] をクリックします。

    1. [Cloud KMS 鍵の選択] プルダウンをクリックして、鍵を選択します。

      • 鍵が別のプロジェクトにある場合は、[プロジェクトを切り替え] をクリックしてプロジェクト名をクリックし、作成した鍵の名前を入力して鍵を選択します。

      • 鍵のリソース名がわかっている場合は、[手動で入力] をクリックし、鍵のリソース名を貼り付けて [保存] をクリックします。

    2. [OK > 保存] をクリックします。

  4. アプリを作成します。手順については、アプリとデータ ストアについてをご覧ください。

これにより鍵が登録され、default_cmek_config という CmekResource が作成されます。

取り込まれたデータが検索結果に表示されるまでには数時間かかることがあります。

Cloud KMS 鍵を表示する

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

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

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cmekConfigs/CMEK_CONFIG_ID"

    次のように置き換えます。

    • LOCATION: アプリまたはデータ コネクタのマルチリージョン（us または eu）。
    • PROJECT_ID: データを含むプロジェクトの ID。
    • CMEK_CONFIG_ID: CmekConfig リソースの ID。コンソールを使用して鍵を登録した場合、ID は default_cmek_config です。

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

    $ curl -X GET
-H "Authorization: Bearer $(gcloud auth print-access-token)"
"https://us-discoveryengine.googleapis.com/v1/projects/my-ai-app-project-123/locations/us/cmekConfigs/default_cmek_config"

    
{
  "name":
  "projects/my-ai-app-project-123/locations/us/cmekConfigs/default_cmek_config",
  "kmsKey": "projects/key-project-456/locations/us/keyRings/my-key-ring/cryptoKeys/my-key"
  "state": "ACTIVE"
  "isDefault": true
}

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

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-discoveryengine.googleapis.com/v1/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/v1/projects/my-ai-app-project-123/locations/us/cmekConfigs"

    
{
  "cmek_configs": [
    {
      "name":
      "projects/my-ai-app-project-123/locations/us/cmekConfigs/default_cmek_config",
      "kmsKey": "projects/key-project-456/locations/us/keyRings/my-key-ring/cryptoKeys/my-key"
      "state": "ACTIVE"
      "isDefault": true
    }
  ]
}

Cloud KMS 鍵の登録を解除する

Agent Search から鍵の登録を解除する手順は次のとおりです。

  1. 登録を解除する CmekConfig リソース名を指定して DeleteCmekConfig メソッドを呼び出します。

    curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cmekConfigs/CMEK_CONFIG_ID"

    次のように置き換えます。

    • LOCATION: アプリまたはデータ コネクタのマルチリージョン（us または eu）。
    • PROJECT_ID: アプリまたはデータ コネクタを含むプロジェクトの ID。
    • CMEK_CONFIG_ID: CmekConfig リソースの ID。コンソールを使用して鍵を登録した場合、ID は default_cmek_config です。

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

    $ curl -X DELETE
-H "Authorization: Bearer $(gcloud auth print-access-token)"
"https://us-discoveryengine.googleapis.com/v1/projects/my-ai-app-project-123/locations/us/cmekConfigs/default_cmek_config"
 
{
 "name": "projects/my-ai-app-project-123/locations/us/operations/delete-cmek-config-56789",
 "metadata": {
  "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.DeleteCmekConfigMetadata"
 }
}

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

    CmekConfig の削除は長時間実行オペレーションであり、完了までに数日かかることがあります。これは、CmekConfig が削除される前に、基盤となる暗号化されたリソースが完全にプロビジョニング解除されるためです。

アプリまたはデータ コネクタが鍵で保護されていることを確認する

鍵の登録後に作成されたアプリとデータ コネクタは、鍵で保護されます。特定のアプリまたはデータ コネクタが鍵で保護されていることを確認する手順は次のとおりです。

コンソールを使用して Google Cloud 確認する

コンソールを使用して、デフォルトの CMEK 構成が設定されているかどうかを確認できます。 Google Cloud

  1. コンソールで、[AI アプリケーション] ページに移動します。 Google Cloud
  2. [**設定**] をクリックし、[**CMEK**] タブを選択します。
  3. ロケーションの構成ステータスが [有効] と表示され、登録した鍵が表示されていることを確認します。

CLI / API を使用して確認する

  1. データストアを確認するには:

    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/v1/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/v1/projects/my-ai-app-project-123/locations/us/collections/default_collection/dataStores/my-data-store-1"

  2. アプリを確認するには:

    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/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/ENGINE_ID"

    次のように置き換えます。

    • LOCATION: プロジェクトのマルチリージョン（us または eu）。
    • PROJECT_ID: アプリを含むプロジェクトの ID。
    • ENGINE_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/v1/projects/my-ai-app-project-123/locations/us/collections/default_collection/engines/my-app"

  3. コマンドの出力を確認します。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/default_cmek_config",
   "kmsKey": "projects/my-ai-app-project-123/locations/us/keyRings/my-key-ring/cryptoKeys/my-key"
 }
}

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

    {
  "name": "projects/969795412903/locations/us/collections/default_collection/engines/my-app",
  "displayName": "my-app",
  "dataStoreIds": [
    "my-data-store-1"
  ],
  "solutionType": "SOLUTION_TYPE_SEARCH",
  "searchEngineConfig": {
    "searchTier": "SEARCH_TIER_STANDARD"
  },
  "industryVertical": "GENERIC",
  "appType": "APP_TYPE_INTRANET",
  "cmekConfig": {
   "name": "projects/969795412903/locations/us/collections/default_collection/dataStores/my-data-store-1/cmekConfigs/default_cmek_config",
   "kmsKey": "projects/my-ai-app-project-123/locations/us/keyRings/my-key-ring/cryptoKeys/my-key"
 }
}

Cloud KMS 鍵で保護されている他のデータ

鍵は、アプリやデータ コネクタ内のデータだけでなく、Agent Search が保持するアプリ所有の他の種類のコア情報（ フォローアップ 検索中に生成されたセッションデータなど）も保護できます。アプリとデータ コネクタが CMEK で保護されている場合、この種のコア情報は CMEK で保護されます。

セッションが保護されていることを確認する特定のコマンドを実行することはできませんが、アプリが保護されているかどうかを確認できます。アプリに対してアプリまたはデータコネクタが 鍵で保護されていることを確認するコマンドを実行して、cmekConfig リソースに鍵が表示された場合は、セッション データが保護されていることを確認できます。

Cloud KMS 鍵をローテーションする

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

次の手順では、Agent Search アプリまたはデータコネクタの鍵をローテーションする手順の概要を示します。鍵のローテーションに関する一般的な情報については、Cloud KMS ガイドの鍵のローテーションをご覧ください。

重要: レコメンデーションやアナリティクスを必要とするアプリに関連付けられたアプリやデータ コネクタで鍵をローテーションしないでください。また、サードパーティ コネクタに使用される単一リージョン鍵をローテーションしないでください。Agent Search における Cloud KMS の制限事項をご覧ください。

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

  2. Cloud KMS ガイドの鍵の管理セクションの手順に沿って、次の操作を行います。

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

      新しい鍵がプライマリになると、アプリまたはデータ コネクタ内のドキュメントは新しい鍵を使用して再暗号化されます。アプリまたはデータ コネクタに追加される後続のドキュメントは新しい鍵で暗号化されます。

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

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

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

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

鍵が無効になった場合、または鍵の権限が 取り消された場合、アプリまたはデータ コネクタは 15 分以内にデータの取り込みとデータの提供を停止します。30 日以内に鍵を再度有効にすると、CMEK 構成の有効期限が切れて関連データが完全に削除される前にオペレーションを再開できます。 ただし、鍵の再有効化や権限の復元には時間がかかります。アプリまたはデータ コネクタがデータの提供を再開するまでに最大 24 時間かかることがあります。

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

トラブルシューティング: KMS 鍵プロジェクトが見つからないエラー

症状: KMS 鍵を使用してアプリまたはデータ コネクタを作成しようとすると、次のようなエラーが表示されます。

KMS key projects/[...] not found for location: [...] and project number: [...]

問題: このエラー メッセージは誤解を招く可能性があります。これは、必ずしもキーが存在しないことを意味するわけではありません。指定されたロケーションで Agent Search で使用するために KMS 鍵が登録されていないことを示す場合があります。

解決策: この問題を解決するには、 Cloud KMS 鍵を登録するの手順に沿って鍵を登録します。登録が完了すると、その鍵で保護されたアプリまたはデータ コネクタを作成できます。