Chiavi di crittografia gestite dal cliente

In questa pagina viene descritto come utilizzare la tua chiave di crittografia per proteggere i tuoi dati in più regioni negli Stati Uniti e nell'UE.

Per impostazione predefinita, Vertex AI Agent Builder cripta i contenuti archiviati a riposo. Vertex AI Agent Builder gestisce questa crittografia predefinita per conto tuo senza che tu debba fare altro.

Tuttavia, se hai requisiti normativi o di conformità specifici relativi le chiavi che proteggono i tuoi dati, puoi utilizzare le chiavi di crittografia gestite dal cliente (CMEK) per proteggere le tue risorse. In questo caso, utilizzerai Cloud KMS e seguire la procedura descritta in questa pagina. La chiave è associata a una località specifica: la regione multipla degli Stati Uniti o la regione multipla dell'UE.

Le chiavi Cloud KMS vengono utilizzate per criptare e decriptare i dati nei tuoi dati negozi e app. Per informazioni generali su Cloud KMS, consulta la documentazione di Cloud Key Management Service.

Limitazioni di Cloud KMS in Vertex AI Agent Builder

Le seguenti limitazioni si applicano alle chiavi CMEK (Cloud KMS) in Vertex AI Agent Builder:

  • Le chiavi già applicate a un datastore non possono essere modificate.

  • Se hai criteri dell'organizzazione CMEK, devi creare nuovi datastore utilizzando l'API, non la console Google Cloud. La creazione di nuovi data store utilizzando la console Google Cloud non va a buon fine se hai attivato i criteri dell'organizzazione CMEK.

  • Dopo aver registrato una chiave, non è possibile annullarne la registrazione o rimuoverla da un un datastore.

  • Devi utilizzare app e data store multiregione degli Stati Uniti o dell'UE (non globali). Per saperne di più su più regioni e sulla residenza dei dati, inclusi i limiti associate all'utilizzo di località non globali, consulta Località di Vertex AI Search o Località di Vertex AI Agents.

  • Se devi registrare più di una chiave per un progetto, contatta il team degli account Google per richiedere un aumento della quota per le configurazioni CMEK, fornendo una motivazione per cui hai bisogno di più di una chiave.

  • Utilizzo di un gestore di chiavi esterno (EKM) o di un modulo di sicurezza hardware (HSM) con CMEK è in GA con lista consentita. Per utilizzare EKM o HSM con CMEK, contatta il team degli account Google.

    Le seguenti limitazioni si applicano a EKM o HSM con CMEK:

    • La tua quota EKM e HSM per le chiamate di crittografia e decriptazione deve essere pari ad almeno 1000 QPM di margine. Per scoprire come controllare le quote, consulta Verifica le tue quote Cloud KMS.

    • Se utilizzi EKM, la chiave deve essere raggiungibile per oltre il 90% del tempo in qualsiasi momento di durata superiore a 30 secondi. Se la chiave non è raggiungibile per questo periodo di tempo, può influire negativamente sull'indicizzazione e sull'aggiornamento della ricerca.

    • In caso di problemi di fatturazione, problemi persistenti di fuori quota o di non raggiungibile per più di 12 ore, il servizio disattiva la configurazione CmekConfig associata alla chiave EKM o HSM.

  • Non è possibile eseguire datastore creati prima della registrazione di una chiave nel progetto protette dalla chiave.

  • Per Vertex AI Search è richiesta la versione Enterprise. Per informazioni sulla versione Enterprise, consulta Informazioni sulle funzionalità avanzate.

  • Non puoi ottimizzare i modelli di ricerca per datastore che sono protette da chiavi CMEK.

  • I datastore di ricerca di Healthcare sono compatibili con CMEK. Tuttavia, altri data store dei connettori di terze parti e il connettore periodico BigQuery non sono conformi a CMEK. Per informazioni generali sui datastore dei dati sanitari, consulta Crea un datastore di dati di ricerca in ambito sanitario. Per informazioni generali sui connettori di terze parti, vedi Collegare un'origine dati di terze parti.

  • La rotazione della chiave non è supportata per le app di consigli. Se disattivi o distruggi una versione della chiave che protegge un data store associato a un'app di consigli, l'app di consigli smette di funzionare.

  • La rotazione delle chiavi non è compatibile con analytics. Se ruoti le chiavi di un datastore, le app che lo utilizzano non mostrano più gli analytics.

  • Le chiavi CMEK non si applicano alle seguenti API RAG: check grounding, ranking e grounded generation.

Prima di iniziare

Assicurati di soddisfare i seguenti prerequisiti:

  • Una chiave Cloud KMS simmetrica con il periodo di rotazione impostato su Mai (rotazione manuale). Consulta Creare un keyring e Creare una chiave nella documentazione di Cloud KMS.

  • Ruolo IAM Autore crittografia/decrittografia CryptoKey (roles/cloudkms.cryptoKeyEncrypterDecrypter) sulla chiave è stata concesso all'agente di servizio di Discovery Engine. Per istruzioni generali su come aggiungere un ruolo a un agente di servizio, consulta l'articolo su come concedere o revocare una singola ruolo.

  • Ruolo IAM Autore crittografia/decrittografia CryptoKey L'utente (roles/cloudkms.cryptoKeyEncrypterDecrypter) sulla chiave è stato concesso a l'agente di servizio Cloud Storage. Se questo ruolo non viene concesso, i carichi di lavoro per i datastore protetti da CMEK non riuscirà perché Discovery Engine impossibile creare il bucket temporaneo e la directory protetti da CMEK richiesta per l'importazione.

  • Non creare app o datastore che vuoi gestire con la chiave fino a quando Dopo aver completato la registrazione della chiave istruzioni in questa pagina.

  • Le funzionalità della versione Enterprise sono attivate per l'app. Vedi Turn Enterprise attivare o disattivare la versione.

Registra la tua chiave Cloud KMS

Per registrare la tua chiave gestita per Vertex AI Agent Builder, segui questi passaggi:

  1. Chiama il metodo UpdateCmekConfig con la chiave Cloud KMS che vuoi registrare.

    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: l'ID del progetto che contiene la chiave. Il numero del progetto non funziona.
    • KMS_LOCATION: la regione multipla della chiave KMS: us o europe.
    • KEY_RING: il nome del keyring che contiene la chiave.
    • KEY_NAME: il nome della chiave.
    • PROJECT_ID: l'ID del progetto che contiene il data store.
    • LOCATION: la località multiregionale del tuo datastore: us o eu.
    • CMEK_CONFIG_ID: l'ID della risorsa CmekConfig.
    • SET_DEFAULT: imposta su true per utilizzare la chiave come predefinita per datastore successivi creati in più regioni.

    Un esempio di chiamata e risposta curl ha il seguente aspetto: 

    $ 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. (Facoltativo) Registra il valore name restituito dal metodo e segui le istruzioni riportate in Ottenere dettagli su un'operazione di lunga durata per vedere quando l'operazione è completata.

    In genere sono necessari alcuni minuti per registrare una chiave.

Al termine dell'operazione, i nuovi datastore in quell'area multiregionale vengono protette dalla chiave. Per informazioni generali sulla creazione di datastore, consulta Crea un datastore di ricerca.

Visualizza chiavi Cloud KMS

Per visualizzare una chiave registrata per Vertex AI Agent Builder, esegui una delle seguenti operazioni:

  • Se disponi del nome risorsa CmekConfig, chiama il metodo 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: la regione multipla del tuo data store: us o eu.
    • PROJECT_ID: l'ID del progetto che contiene i dati
    • CMEK_CONFIG_ID: l'ID della risorsa CmekConfig.

    Un esempio di chiamata e risposta curl è il seguente: 

    $ 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
}

  • Se non hai il nome della risorsa CmekConfig, chiama il metodo 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: la regione multipla del tuo data store: us o eu.
    • PROJECT_ID: l'ID del progetto che contiene i dati

    Un esempio di chiamata e risposta curl è il seguente: 

    $ 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"
    }
  ]
}

(Facoltativo) Verifica che un datastore sia protetto da una chiave

I datastore creati prima della registrazione della chiave non sono protetti per chiave. Per verificare che un determinato data store sia protetto dalla tua chiave, segui questi passaggi:

  1. Esegui il comando curl seguente sul datastore:

    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: la località multiregionale del tuo datastore: us o eu.
    • PROJECT_ID: l'ID del progetto che contiene il data store.
    • DATA_STORE_ID: l'ID del datastore.

    Un esempio di chiamata curl è il seguente: 

    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. Rivedi l'output del comando: se il campo cmekConfig è nel e il campo kmsKey mostra la chiave registrata, poi il datastore è protetto dalla chiave.

    Un esempio di risposta è il seguente:

    {
 "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"
 }
}

Ruota le chiavi

Quando ruoti le chiavi, ne crei una nuova versione e la imposti come principale. Lascia attiva la versione originale della chiave per un po' di tempo prima di disattivarla. In questo modo, qualsiasi pod a lunga durata operazioni che potrebbero utilizzare il tempo della chiave precedente.

La procedura riportata di seguito illustra i passaggi per ruotare le chiavi di un datastore Vertex AI Agent Builder. Per informazioni generali sulla rotazione delle chiavi, consulta Rotazione delle chiavi nella guida di Cloud KMS.

Importante: non ruotare le chiavi sui datastore associati ai suggerimenti o con qualsiasi app che richieda dati e analisi. Vedi Limiti di Cloud KMS in Vertex AI Agent Builder.

  1. Registra di nuovo la chiave. Per farlo, ripeti il passaggio 1 della sezione Registra la chiave Cloud KMS.

  2. Leggi le istruzioni riportate nella sezione Gestisci chiavi del Guida di Cloud KMS per:

    1. Crea una nuova versione della chiave, attivala e impostala come principale.

    2. Lascia abilitata la versione precedente della chiave.

    3. Dopo circa una settimana, disabilita la versione precedente della chiave e assicurati che tutto funziona come prima.

    4. In un secondo momento, quando sei sicuro che non siano stati causati problemi Disabilitando la versione precedente della chiave, puoi eliminare quella precedente.

Se una chiave viene disattivata o revocata

Se una chiave è disattivata o se le relative autorizzazioni sono revocata, il datastore smette di importare i dati e di fornire dati entro 15 minuti. Tuttavia, la riattivazione di una chiave o il ripristino delle autorizzazioni richiede molto tempo. Possono essere necessarie fino a 24 ore prima che lo spazio dati possa riprendere il servizio.

Pertanto, non disattivare una chiave a meno che non sia necessario. Disattivare e attivare una chiave un'operazione datastore in termini di tempo. Ad esempio, se imposti ripetutamente una chiave su disattivata e attivata, il datastore impiegherà molto tempo per raggiungere uno stato protetto. Quando disattivi una chiave la sua riattivazione subito dopo potrebbe comportare giorni di inattività perché la chiave viene prima disabilitata dal datastore e, successivamente, riattivate.