Per impostazione predefinita, Vertex AI Agent Builder cripta i contenuti inattivi dei clienti. Vertex AI Agent Builder gestisce la crittografia per conto tuo senza che tu debba fare altro. Questa opzione è denominata Crittografia predefinita di Google.
Se vuoi controllare le tue chiavi di crittografia, puoi utilizzare le chiavi di crittografia gestite dal cliente (CMEK) in Cloud KMS con i servizi integrati con CMEK, tra cui Vertex AI Agent Builder. L'utilizzo delle chiavi Cloud KMS ti consente di controllare il loro livello di protezione, la posizione, la pianificazione della rotazione, le autorizzazioni di utilizzo e di accesso e i confini di crittografia. L'utilizzo di Cloud KMS ti consente inoltre di visualizzare gli audit log e controllare i cicli di vita delle chiavi. Invece che essere di proprietà e gestite da Google, le chiavi di crittografia della chiave (KEK) simmetriche che proteggono i tuoi dati sono sotto il tuo controllo e vengono gestite in Cloud KMS.
Dopo aver configurato le risorse con i CMEK, l'esperienza di accesso alle risorse di Vertex AI Agent Builder è simile all'utilizzo della crittografia predefinita di Google. Per saperne di più sulle opzioni di crittografia, consulta Chiavi di crittografia gestite dal cliente (CMEK).
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.
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 persistenti di irraggiungibilità 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 su come rendere i connettori di terze parti conformi a CMEK, consulta Informazioni sulle chiavi a regione singola per i connettori di terze parti nella documentazione di Agentspace di Google.
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 chiavi automatizzate 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.
Se sei nella lista consentita per l'utilizzo di connettori di terze parti e vuoi proteggere i tuoi dati di terze parti con la tua chiave gestita, segui la procedura per registrare le chiavi per una singola regione nella documentazione di Agentspace di Google.
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 alcuni 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 dei dati.
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.