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 Agent Builder di Vertex AI:
Le chiavi già applicate a un data store non possono essere modificate.
Se hai criteri dell'organizzazione CMEK, devi creare nuovi data store 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 data store.
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à 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.
L'utilizzo di un gestore chiavi esterno (EKM) o di un modulo di sicurezza hardware (HSM) con CMEK è in versione 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 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 la sezione 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 sull'edizione Enterprise, consulta Informazioni sulle funzionalità avanzate.
Non puoi ottimizzare i modelli di ricerca per i datastore protetti dalle chiavi CMEK.
Gli archivi dei dati sanitari e i connettori di terze parti sono conformi a CMEK. Tuttavia, i connettori proprietari, come il connettore periodico BigQuery, non sono conformi a CMEK. Per informazioni generali sui datastore per la salute, consulta Creare un datastore di ricerca per la salute. 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 è supportata per i connettori di terze parti. Se disattivi o distruggi una versione della chiave che protegge un archivio dati associato a un connettore di terze parti, il connettore 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:
Chiama il metodo
UpdateCmekConfigcon 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/v1/projects/PROJECT_ID/locations/LOCATION/cmekConfigs/CMEK_CONFIG_ID?set_default=SET_DEFAULT"Sostituisci quanto segue:
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:usoeurope.KEY_RING: il nome del mazzo di chiavi 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 data store:usoeu.CMEK_CONFIG_ID: l'ID della risorsa CmekConfig.SET_DEFAULT: impostato sutrueper 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/v1/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.v1.UpdateCmekConfigMetadata" } }(Facoltativo) Registra il valore
namerestituito 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/v1/projects/PROJECT_ID/locations/LOCATION/cmekConfigs/CMEK_CONFIG_ID"Sostituisci quanto segue:
LOCATION: la regione multipla del tuo data store:usoeu.PROJECT_ID: l'ID del progetto che contiene i datiCMEK_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/v1/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/v1/projects/PROJECT_ID/locations/LOCATION/cmekConfigs"Sostituisci quanto segue:
LOCATION: la regione multipla del tuo data store:usoeu.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/v1/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" } ] }
Annullare la registrazione della chiave Cloud KMS
Per annullare la registrazione della chiave da Vertex AI Agent Builder, segui questi passaggi:
Chiama il metodo
DeleteCmekConfigcon il nome della risorsa CmekConfig che vuoi annullare la registrazione.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"Sostituisci quanto segue:
LOCATION: la regione multipla del tuo data store:usoeu.PROJECT_ID: l'ID del progetto che contiene il data store.CMEK_CONFIG_ID: l'ID della risorsa CmekConfig.
Un esempio di chiamata e risposta curl è il seguente:
$ 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/cmek-config-1" { "name": "projects/my-ai-app-project-123/locations/us/operations/delete-cmek-config-56789", "metadata": { "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.DeleteCmekConfigMetadata" } }(Facoltativo) Registra il valore
namerestituito 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 pochi minuti per eliminare una chiave.
Verificare che un data store sia protetto da una chiave
I datastore creati prima della registrazione della chiave non sono protetti dalla chiave. Se vuoi verificare che un determinato data store sia protetto dalla tua chiave, segui questi passaggi:
Esegui il seguente comando curl nell'archivio dati:
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"Sostituisci quanto segue:
LOCATION: la regione multipla del tuo data store:usoeu.PROJECT_ID: l'ID del progetto che contiene il data store.DATA_STORE_ID: l'ID del data store.
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/v1/projects/my-ai-app-project-123/locations/us/collections/default_collection/dataStores/my-data-store-1"
Esamina l'output del comando: se il campo
cmekConfigè presente nell'output e il campokmsKeymostra la chiave che hai registrato, l'archivio dati è 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.
Registra di nuovo la chiave. Per farlo, ripeti il passaggio 1 della sezione Registra la chiave Cloud KMS.
Consulta le istruzioni nella sezione Gestire le chiavi della guida Cloud KMS per eseguire le seguenti operazioni:
Crea una nuova versione della chiave, attivala e impostala come principale.
Lascia attiva la versione precedente della chiave.
Dopo circa una settimana, disattiva la versione precedente della chiave e assicurati che tutto funzioni come prima.
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 data store 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. Potrebbero essere necessarie fino a 24 ore prima che lo spazio dati possa riprendere il servizio.
Pertanto, non disattivare una chiave se non è necessario. La disattivazione e l'attivazione di una chiave in un data store è 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.