Chiavi di crittografia gestite dal cliente

Questa pagina descrive come utilizzare la tua chiave di crittografia per proteggere i tuoi depositi di dati nelle regioni multiple degli Stati Uniti e dell'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 di conformità o normativi specifici relativi alle chiavi che proteggono i tuoi dati, puoi utilizzare le chiavi di crittografia gestite dal cliente (CMEK) per proteggere le tue risorse. In questo caso, dovrai utilizzare le chiavi 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 datastore e nelle tue 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.

  • Una volta registrata, una chiave non può essere annullata o rimossa da un datastore.

  • Devi utilizzare app e data store multiregione degli Stati Uniti o dell'UE (non globali). Per ulteriori informazioni sulle regioni multiple e sulla residenza dei dati, inclusi i limiti associati all'utilizzo di località non globali, consulta Località di Vertex AI Search o Località degli agenti Vertex AI.

  • 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.

  • L'utilizzo di un gestore chiavi esterno (EKM) o di un modulo di sicurezza hardware (HSM) con CMEK è disponibile in versione GA con la 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 quota EKM e HSM per le chiamate di crittografia e decrittografia deve avere almeno 1000 QPM di headroom. Per scoprire come controllare le quote, consulta Verifica le tue quote Cloud KMS.

    • Se utilizzi EKM, la chiave deve essere raggiungibile per più del 90% di qualsiasi finestra temporale 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 superamento della quota o problemi di irraggiungibilità persistenti per più di 12 ore, il servizio disattiva automaticamente CmekConfig associato alla chiave EKM o HSM.

  • Gli archivi dati creati prima della registrazione di una chiave al progetto non possono essere protetti dalla chiave.

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

  • Non puoi ottimizzare i modelli di ricerca per i datastore protetti dalle chiavi CMEK.

  • I datastore di ricerca sanitaria sono conformi a 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 sanitari, consulta Creare un datastore di ricerca per la salute. Per informazioni generali sui connettori di terze parti, consulta 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 datastore 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 generatione con grounding.

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.

  • Il ruolo IAM Autore crittografia/decrittografia CryptoKey (roles/cloudkms.cryptoKeyEncrypterDecrypter) sulla chiave è stato concesso all'agente di servizio Discovery Engine. Per istruzioni generali su come aggiungere un ruolo a un agente di servizio, vedi Concedere o revocare un singolo ruolo.

  • Il ruolo IAM Autore crittografia/decrittografia CryptoKey (roles/cloudkms.cryptoKeyEncrypterDecrypter) sulla chiave è stato concesso all'agente di servizio Cloud Storage. Se questo ruolo non viene concesso, l'importazione dei dati per i datastore protetti da CMEK non andrà a buon fine perché Discovery Engine non è in grado di creare il bucket e la directory temporanei protetti da CMEK necessari per l'importazione.

  • Non creare datastore o app che vuoi gestire con la tua chiave finché non hai completato le istruzioni per la registrazione della chiave riportate in questa pagina.

  • Le funzionalità della versione Enterprise sono attive per l'app. Consulta Attivare o disattivare la versione Enterprise.

Registra la 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 regione multipla del tuo datastore: us o eu.
    • CMEK_CONFIG_ID: l'ID della risorsa CmekConfig.
    • SET_DEFAULT: impostato su true per utilizzare la chiave come chiave predefinita per i datastore successivi creati nella regione multipla.

    Un esempio di chiamata e risposta curl è il seguente: 

    $ 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 data store nella regione multipla sono protetti dalla chiave. Per informazioni generali sulla creazione di datastore, consulta Creare un datastore di ricerca.

Visualizzare le chiavi Cloud KMS

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

  • Se hai il nome della 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 datastore: 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 datastore: 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 dalla chiave. Se vuoi verificare che un determinato datastore sia protetto dalla tua chiave, segui questi passaggi:

  1. Esegui il seguente comando curl nell'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 regione multipla 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. Esamina l'output del comando: se il campo cmekConfig è presente nell'output e il campo kmsKey mostra la chiave che hai registrato, l'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, le operazioni a lunga esecuzione che potrebbero utilizzare la chiave precedente avranno il tempo di essere completate.

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 la sezione Rotazione delle chiavi nella guida di Cloud KMS.

Importante:non ruotare le chiavi negli store di dati associati alle app di consigli o ad altre app che richiedono dati e analisi. Consulta Limitazioni 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. Consulta le istruzioni nella sezione Gestire le chiavi della guida Cloud KMS per eseguire le seguenti operazioni:

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

    2. Lascia attiva la versione precedente della chiave.

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

    4. In un secondo momento, quando avrai la certezza che la disattivazione della versione precedente della chiave non ha causato problemi, potrai distruggerla.

Se una chiave viene disattivata o revocata

Se una chiave viene disattivata o le autorizzazioni per la chiave vengono revocate, il datastore interrompe l'importazione e la pubblicazione dei 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 datastore possa riprendere il servizio.

Pertanto, non disattivare una chiave se non è necessario. La disattivazione e l'attivazione di una chiave in un datastore è un'operazione che richiede tempo. Ad esempio, se attivi e disattivi ripetutamente una chiave, il datastore impiegherà molto tempo per raggiungere uno stato protetto. La disattivazione di una chiave e la sua riattivazione immediata potrebbero comportare giorni di inattività perché la chiave viene prima disattivata dal datastore e poi riattivata.