Chiavi di crittografia gestite dal cliente (CMEK)

Per impostazione predefinita, Gemini Enterprise Agent Platform cripta i contenuti inattivi dei clienti. Agent Platform 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, inclusa la piattaforma Agent. L'utilizzo delle chiavi Cloud KMS ti consente di controllare il livello di protezione, la località, la pianificazione della rotazione, le autorizzazioni di utilizzo e di accesso e i limiti crittografici. Con Cloud KMS puoi inoltre monitorare l'utilizzo delle chiavi, visualizzare gli audit log e controllare i cicli di vita delle chiavi. Invece di Google, sei tu ad avere la proprietà e la gestione delle chiavi di crittografia della chiave (KEK) simmetriche che proteggono i tuoi dati. Puoi controllare e gestire queste chiavi in Cloud KMS.

Dopo aver configurato le risorse con le CMEK, l'esperienza di accesso alle risorse di Agent Platform è simile all'utilizzo della crittografia predefinita di Google. Per saperne di più sulle opzioni di crittografia, consulta Chiavi di crittografia gestite dal cliente (CMEK).

Questa guida descrive alcuni vantaggi dell'utilizzo di CMEK per le risorse di Gemini Enterprise Agent Platform e illustra come configurare un job di addestramento per utilizzare CMEK.

Per saperne di più su come utilizzare CMEK per Colab Enterprise, consulta la pagina CMEK di Colab Enterprise. Per saperne di più su come utilizzare CMEK per le istanze Gemini Enterprise Agent Platform Workbench, consulta la pagina CMEK delle istanze Agent Platform Workbench.

CMEK per le risorse di Gemini Enterprise Agent Platform

Le sezioni seguenti descrivono le informazioni di base su CMEK per le risorse di Gemini Enterprise Agent Platform che devi comprendere prima di configurare CMEK per i tuoi job.

Vantaggi di CMEK

In generale, CMEK è più utile se hai bisogno del pieno controllo sulle chiavi utilizzate per criptare i tuoi dati. Con CMEK, puoi gestire le chiavi in Cloud KMS. Ad esempio, puoi ruotare o disabilitare una chiave oppure puoi configurare una pianificazione della rotazione utilizzando l'API Cloud KMS. Per saperne di più sulle CMEK in generale, incluso quando e perché attivarle, consulta la documentazione di Cloud KMS.

Quando esegui un job di AutoML personalizzato o AutoML, il tuo codice viene eseguito su una o più istanze di macchine virtuali (VM) gestite da Gemini Enterprise Agent Platform. Quando abiliti CMEK per le risorse di Gemini Enterprise Agent Platform, la chiave che designi, anziché una chiave gestita da Google, viene utilizzata per criptare i dati sui dischi di avvio di queste VM. La chiave CMEK cripta i seguenti tipi di dati:

  • La copia del codice sulle VM.
  • Tutti i dati caricati dal tuo codice.
  • Qualsiasi dato temporaneo salvato sul disco locale dal tuo codice.
  • Modelli addestrati con AutoML.
  • File multimediali (dati) caricati nei set di dati multimediali.

In generale, la chiave CMEK non cripta i metadati associati alla tua operazione, come il nome e la regione del job o il nome visualizzato di un set di dati. I metadati associati alle operazioni vengono sempre criptati utilizzando il meccanismo di crittografia predefinito di Google.

Per i set di dati, quando un utente importa dati nel set di dati, gli elementi di dati e le annotazioni vengono criptati con CMEK. Il nome visualizzato del set di dati non è criptato con CMEK.

Per i modelli, i modelli archiviati nel sistema di archiviazione (ad esempio, il disco) sono crittografati con CMEK. Tutti i risultati della valutazione del modello sono criptati con CMEK.

Per gli endpoint, tutti i file del modello utilizzati per il deployment del modello nell'endpoint sono criptati con CMEK. Ciò non include i dati in memoria.

Per la previsioni in batch, tutti i file temporanei (come file del modello, log, dischi VM) utilizzati per eseguire il job di previsioni in batch sono criptati con CMEK. I risultati della previsione batch vengono memorizzati nella destinazione fornita dall'utente. Di conseguenza, Agent Platform rispetta il valore predefinito della configurazione di crittografia della destinazione. In caso contrario, i risultati verranno criptati anche con CMEK.

Per l'etichettatura dei dati, tutti i file di input (immagine, testo, tabellare), la discussione temporanea (ad esempio domande, feedback) e l'output (risultato dell'etichettatura) sono criptati con CMEK. I nomi visualizzati delle specifiche di annotazione non sono criptati con CMEK.

Per gli agenti, CMEK cripta tutti i file di origine utilizzati per lo sviluppo degli agenti. Inoltre, anche le immagini container e le istanze di cui è stato eseguito il deployment per l'agente sono crittografate con CMEK.

Chiavi esterne

Puoi utilizzare Cloud External Key Manager (Cloud EKM) per creare chiavi esterne, che gestisci, per criptare i dati in Google Cloud.

Quando utilizzi una chiave Cloud EKM, Google non ha alcun controllo sulla disponibilità della chiave gestita esternamente. Se richiedi l'accesso a una risorsa criptata con una chiave gestita esternamente e la chiave non è disponibile, Gemini Enterprise Agent Platform rifiuterà la richiesta. Potrebbe verificarsi un ritardo di massimo 10 minuti prima di poter accedere alla risorsa una volta che la chiave diventa disponibile.

Per ulteriori considerazioni sull'utilizzo di chiavi esterne, consulta Cloud External Key Manager.

Utilizzare CMEK con altri prodotti Google Cloud

La configurazione di CMEK per le risorse di Gemini Enterprise Agent Platform non configura automaticamente CMEK per altri prodotti Google Cloud che utilizzi insieme a Gemini Enterprise Agent Platform. Per utilizzare CMEK per criptare i dati in altri prodottiGoogle Cloud , è necessaria una configurazione aggiuntiva. Ad esempio:

Risorse attuali supportate da CMEK

Le risorse Gemini Enterprise Agent Platform attuali coperte da CMEK sono le seguenti. Il supporto di CMEK per le funzionalità in anteprima è anch'esso in stato di anteprima.

Risorsa Materiale criptato Link alla documentazione
Set di dati
  • Tutti i dati importati dall'utente (ad esempio, contenuti di testo) per DataItems e Annotations.
  • Contenuti creati dall'utente, ad esempio AnnotationSpecs, ColumnSpecs.
Modello
  • File del modello caricati.
  • Risultati della valutazione del modello addestrato.
Endpoint
  • Tutti i file del modello utilizzati per il deployment del modello nell'endpoint. Ciò non include i dati in memoria, ma il modello verrà annullato automaticamente se la chiave è disattivata.
CustomJob
  • La copia del codice sulle VM utilizzate per eseguire l'operazione.
  • Tutti i dati caricati dal tuo codice.
  • Qualsiasi dato temporaneo salvato sul disco locale dal tuo codice.
HyperparameterTuningJob
  • La copia del codice sulle VM utilizzate per eseguire l'operazione.
  • Tutti i dati caricati dal tuo codice.
  • Qualsiasi dato temporaneo salvato sul disco locale dal tuo codice.
TrainingPipeline
  • La copia del codice sulle VM utilizzate per eseguire l'operazione.
  • Tutti i dati caricati dal tuo codice.
  • Qualsiasi dato temporaneo salvato sul disco locale dal tuo codice.
  • Modelli addestrati con AutoML.
BatchPredictionJob (escluso batchPrediction di immagini AutoML)
  • Eventuali file temporanei (ad esempio file del modello, log, dischi VM) utilizzati nel job per procedere con il job di previsioni in batch.
  • Se i risultati scritti di BatchPrediction vengono archiviati nella destinazione fornita dall'utente, verrà rispettata la configurazione di crittografia del valore predefinito. In caso contrario, verrà criptato anche con CMEK.
ModelDeploymentMonitoringJob
  • Tutti i file temporanei (ad esempio, file del set di dati di addestramento, log, dischi VM) utilizzati nel job per elaborare il job di monitoraggio del deployment del modello.
  • Tutti i dati utilizzati per il monitoraggio del rilevamento delle anomalie.
  • Se la chiave è disattivata, il job di monitoraggio del deployment del modello verrà messo in pausa.
PipelineJob
  • Il job della pipeline e tutte le relative risorse secondarie.
MetadataStore
  • Tutti i contenuti del datastore dei metadati.
TensorBoard
  • Tutti i dati dei log di TensorBoard caricati, inclusi scalari, istogrammi, definizioni di grafici, immagini e testo.
Feature Store
  • L'archivio di caratteristiche e tutti i contenuti al suo interno.
Indice
  • Tutti i file di dati utilizzati per gli indici di Vector Search archiviati in Cloud Storage, Pub/Sub e memoria interna. Index e IndexEndpoint devono essere creati con la stessa chiave.
IndexEndpoint
  • Tutti i file di dati utilizzati per gli indici di Vector Search archiviati in Cloud Storage, Pub/Sub e memoria interna. Index e IndexEndpoint devono essere creati con la stessa chiave.
Runtime di Colab Enterprise
  • Il disco di avvio e i dischi di dati della VM del runtime
Notebook Colab Enterprise
  • Il file del notebook e i relativi commenti
Agent Runtime
  • La copia dei file di origine dell'agente, inclusi codice, script e file di dipendenza
  • Le immagini container create dai file sorgente dell'agente
  • Le istanze in esecuzione di cui è stato eseguito il deployment dalle immagini container dell'agente
Sandbox di Agent Platform
  • Stati dei checkpoint della memoria e spazio di archiviazione su disco delle istanze sandbox in esecuzione
  • Overlay di container personalizzati e configurazioni dell'ambiente
  • Snapshot e modelli sandbox salvati
ServingProfile
  • Dati archiviati a riposo dalle API senza risorse (basate su richieste), ad esempio i dati di ripresa della sessione dell'API Gemini Live e le interazioni archiviate dell'API Interactions.

Supporto di CMEK per le pipeline di ottimizzazione dell'AI generativa

Il supporto di CMEK è fornito nella pipeline di ottimizzazione dei seguenti modelli:

  • BERT
  • T5
  • image-generation (GPU)

Limitazioni

Il supporto CMEK non è fornito nei seguenti casi:

  • Previsioni in batch del modello di immagine AutoML (BatchPredictionJob)
  • Ottimizzazione TPU
  • Agent Platform Memory Bank o Agent Platform Sessions configurati per utilizzare l'endpoint globale. Cloud KMS richiede che le chiavi di crittografia risiedano all'interno di un limite geografico fisso di residenza dei dati. Poiché la regione globale non ha un confine geografico fisico, non può criptare le risorse regionali o multiregionali localizzate.
  • L'utilizzo di CMEK per le API senza risorse è limitato all'API Gemini Live e all'API Interactions nelle multiregioni us e eu. La regione globale non è supportata.

Configura CMEK per le risorse

Le sezioni seguenti descrivono come creare un keyring e una chiave in Cloud Key Management Service, come concedere le autorizzazioni di crittografia e decrittografia di Agent Platform per la chiave e come creare risorse che utilizzano CMEK.

Prima di iniziare

Questa guida presuppone che tu utilizzi due progetti Google Cloud separati per configurare CMEK per i dati di Agent Platform:

  • Un progetto per la gestione della chiave di crittografia (denominato "progetto Cloud KMS").
  • Un progetto per accedere ai dati o all'output di Agent Platform in Cloud Storage e interagire con altri prodotti Google Cloud necessari per il tuo caso d'uso (denominato "progetto AI Platform").

Questa configurazione consigliata supporta una separazione dei compiti.

In alternativa, puoi utilizzare un unico Google Cloud progetto per l'intera guida. Per farlo, utilizza lo stesso progetto per tutte le seguenti attività che fanno riferimento al progetto Cloud KMS e per le attività che fanno riferimento al progetto AI Platform.

Configurare il progetto Cloud KMS

  1. Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei carichi di lavoro.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Cloud KMS API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Cloud KMS API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    8.

Configura il progetto AI Platform

  1. Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei carichi di lavoro.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    8.

Configura Google Cloud CLI

gcloud CLI è obbligatoria per alcuni passaggi di questa guida e facoltativa per altri.

Installa Google Cloud CLI. Dopo l'installazione, inizializza Google Cloud CLI eseguendo il comando seguente: 

gcloud init

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Crea chiavi automatizzate e una chiave

Segui la guida di Cloud KMS per creare chiavi simmetriche per creare un keyring e una chiave. Quando crei il tuo keyring, specifica una regione che supporta le operazioni di Agent Platform come posizione del keyring. L'addestramento di Agent Platform supporta CMEK solo quando la risorsa e la chiave utilizzano la stessa regione. Non devi specificare una località dual-regionale, multiregionale o globale per il portachiavi.

Assicurati di creare il keyring e la chiave nel tuo progetto Cloud KMS.

Concedere le autorizzazioni per Agent Platform

Per utilizzare CMEK per le tue risorse, devi concedere ad Agent Platform l'autorizzazione per criptare e decriptare i dati utilizzando la tua chiave. Agent Platform utilizza un service agent gestito da Google per eseguire operazioni utilizzando le tue risorse. Questo account di servizio è identificato da un indirizzo email con il seguente formato:

service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com

Per trovare l'account di servizio appropriato per il tuo progetto AI Platform, vai alla pagina IAM della console Google Cloud e trova il membro che corrisponde a questo formato di indirizzo email, con il numero di progetto per il tuo progetto AI Platform che sostituisce la variabile AI_PLATFORM_PROJECT_NUMBER. Il account di servizio ha anche il nome Agent Platform Service Agent.

Vai alla pagina IAM

Prendi nota dell'indirizzo email di questo account di servizio e utilizzalo nei passaggi successivi per concedergli l'autorizzazione a criptare e decriptare i dati utilizzando la tua chiave. Puoi concedere l'autorizzazione utilizzando la console Google Cloud o Google Cloud CLI:

Console Google Cloud

  1. Nella console Google Cloud , fai clic su Sicurezza e seleziona Gestione chiavi. Verrà visualizzata la pagina Chiavi di crittografia e seleziona il tuo progetto Cloud KMS.

    Vai alla pagina Chiavi crittografiche

  2. Fai clic sul nome del keyring che hai creato in una sezione precedente di questa guida per andare alla pagina Dettagli del keyring.

  3. Seleziona la casella di controllo relativa alla chiave che hai creato in una sezione precedente di questa guida. Se un riquadro informazioni con il nome della chiave non è già aperto, fai clic su Mostra riquadro informazioni.

  4. Nel riquadro informazioni, fai clic su Aggiungi membro per aprire la finestra di dialogo Aggiungi membri a "KEY_NAME". In questa finestra di dialogo, procedi nel seguente modo:

    1. Nella casella Nuovi membri, inserisci l'indirizzo email del account di servizio che hai annotato nella sezione precedente: service-AI_PLATFORM_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com

    2. Nell'elenco a discesa Seleziona un ruolo, fai clic su Cloud KMS e poi seleziona il ruolo Cloud KMS CryptoKey Encrypter/Decrypter.

    3. Fai clic su Salva.

gcloud

Esegui questo comando:

gcloud kms keys add-iam-policy-binding KEY_NAME \
  --keyring=KEY_RING_NAME \
  --location=REGION \
  --project=KMS_PROJECT_ID \
  --member=serviceAccount:service-AI_PLATFORM_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com \
  --role=roles/cloudkms.cryptoKeyEncrypterDecrypter

In questo comando, sostituisci i seguenti segnaposto:

  • KEY_NAME: il nome della chiave che hai creato in una sezione precedente di questa guida.
  • KEY_RING_NAME: le chiavi automatizzate che hai creato in una sezione precedente di questa guida.
  • REGION: la regione in cui hai creato le chiavi automatizzate.
  • KMS_PROJECT_ID: l'ID del tuo progetto Cloud KMS.
  • AI_PLATFORM_PROJECT_NUMBER: il numero del progetto AI Platform, che hai annotato nella sezione precedente come parte di un indirizzo email del account di servizio.

Crea risorse con la chiave KMS

Quando crei una nuova risorsa supportata da CMEK, puoi specificare la tua chiave come uno dei parametri di creazione.

Console

Quando crei una nuova risorsa supportata da CMEK nella sezione Piattaforma agente della consoleGoogle Cloud , puoi selezionare la chiave nella sezione delle opzioni generali o avanzate:

Seleziona la chiave di crittografia per la sezione delle risorse

REST e riga di comando

Quando crei una risorsa supportata, aggiungi un oggetto encryptionSpec alla richiesta e imposta il campo encryptionSpec.kmsKeyName in modo che punti alla risorsa chiave.

Ad esempio, quando crei una risorsa dataset, devi specificare la chiave nel corpo della richiesta:

 {
   "displayName": DATASET_NAME,
   "metadataSchemaUri": METADATA_URI,
   "encryptionSpec": {
     "kmsKeyName": "projects/PROJECT_ID/locations/LOCATION_ID/keyRings/KEY_RING_NAME/cryptoKeys/KEY_NAME"
   }
 }

Java

Quando crei una risorsa supportata, imposta EncryptionSpec in modo che punti alla risorsa chiave. Per saperne di più, consulta la documentazione della libreria client di Agent Platform per Java.

Node.js

Quando crei una risorsa supportata, imposta il parametro encryptionSpec in modo che punti alla risorsa delle chiavi. Per saperne di più, consulta la documentazione della libreria client della piattaforma agent per Node.js.

Python

Quando crei una risorsa supportata, imposta il parametro encryption_spec in modo che punti alla risorsa delle chiavi. Per saperne di più, consulta la documentazione relativa al client Python per Cloud AI Platform.

Utilizzare CMEK con API senza risorse

Alcune API Gemini Enterprise Agent Platform sono senza risorse (basate su richieste): gestiscono le richieste di inferenza senza creare una risorsa di primo livello di lunga durata. Per supportare funzionalità come la continuità della sessione e le conversazioni stateful, queste API possono archiviare i dati degli utenti inattivi per un periodo di tempo limitato. Ad esempio, l'API Gemini Live archivia i dati di ripresa della sessione per un massimo di 24 ore e l'API Interactions archivia i dati delle interazioni stateful per un massimo di 7 giorni. Poiché non esiste una risorsa permanente a cui collegare una chiave quando vengono creati i dati, utilizzi un profilo di pubblicazione per applicare la CMEK a questi dati inattivi.

Un profilo di pubblicazione è una risorsa di Gemini Enterprise Agent Platform che collega una chiave Cloud KMS a un progetto, una località e un ambito API. Se esiste un profilo di pubblicazione per il progetto, la posizione e l'ambito di una richiesta, Agent Platform cripta automaticamente i dati persistenti dell'ambito con la tua chiave. Il formato della richiesta di inferenza non cambia.

Vantaggi della pubblicazione dei profili

  • Soddisfa i requisiti di conformità: soddisfa i criteri di controllo che richiedono il controllo del cliente sulla chiave di crittografia e sul ciclo di vita dei dati.
  • Controllo completo dei tuoi dati: disattiva o revoca l'accesso alle chiavi in qualsiasi momento per interrompere l'accesso ai tuoi dati criptati.
  • Trasparente, senza modifiche al codice: il formato della richiesta di inferenza esistente rimane invariato. La crittografia viene applicata automaticamente se esiste un profilo di pubblicazione.
  • Controllo granulare: applica una chiave distinta per ogni ambito API per limitare l'impatto se una chiave viene compromessa e segui il principio del privilegio minimo.

Come funziona la crittografia trasparente

  1. Invii una richiesta a un'API senza risorse supportata all'endpoint Agent Platform regionale.
  2. Agent Platform risolve il profilo di pubblicazione per il tuo progetto, la tua posizione e il tuo ambito.
  3. I dati persistenti per questo ambito vengono criptati automaticamente con la tua chiave, senza modifiche alla richiesta.
  4. Se non esiste un profilo di pubblicazione per il progetto, la località e l'ambito, Agent Platform utilizza la crittografia gestita da Google per impostazione predefinita.

Limitazioni del profilo di pubblicazione

  • API supportate: API Gemini Live (ambito GEMINI_LIVE) e API Interactions (ambito INTERACTIONS_API).
  • Regioni supportate: le multiregioni us e eu. La regione globale non è supportata a causa delle limitazioni di Cloud KMS e CMEK di archiviazione nella regione globale.
  • La chiave di crittografia e l'ambito sono immutabili dopo la creazione. È possibile aggiornare solo il nome visualizzato e la descrizione. Per modificare la chiave o l'ambito, elimina il profilo di pubblicazione e creane uno nuovo con un servingProfileId diverso (vedi Disattivare CMEK e ripristinare la crittografia predefinita).

Prima di iniziare

  1. Abilita l'API Cloud KMS e l'API Agent Platform nel tuo progetto.
  2. Crea o identifica una chiave Cloud KMS in una multiregione supportata (us o eu); non utilizzare la regione globale. Vedi Creare chiavi automatizzate e chiave.
  3. Concedi al service agent Gemini Enterprise Agent Platform il ruolo roles/cloudkms.cryptoKeyEncrypterDecrypter sulla chiave. Vedi Concedere le autorizzazioni di Agent Platform.
  4. Assicurati di disporre delle autorizzazioni IAM per gestire i profili di pubblicazione (aiplatform.servingProfiles.create, get, list, update e delete).

Gli esempi nelle sezioni seguenti utilizzano questi valori:

  • LOCATION: la multiregione, us o eu.
  • PROJECT: il tuo ID progetto o numero.
  • API_VERSION: v1 o v1beta1.
  • SERVING_PROFILE_ID: da 1 a 63 caratteri: lettere minuscole, cifre e trattini; deve iniziare con una lettera e terminare con una lettera o una cifra. Questo valore diventa l'ultimo componente del nome della risorsa.
  • scope: l'API senza risorse a cui si applica il profilo di pubblicazione. I valori supportati sono GEMINI_LIVE e INTERACTIONS_API.
  • La chiave Cloud KMS è impostata in cmekConfig.encryptionSpec.kmsKeyName e deve corrispondere a projects/*/locations/*/keyRings/*/cryptoKeys/*.

Le richieste REST vengono inviate all'endpoint regionale https://aiplatform.LOCATION.rep.googleapis.com e autenticate con un token di tipo bearer OAuth 2.0:

-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"

Crea un profilo di pubblicazione

La creazione di un profilo di pubblicazione consente la protezione CMEK per i dati permanenti dell'ambito. I campi displayName, scope (GEMINI_LIVE o INTERACTIONS_API) e cmekConfig.encryptionSpec.kmsKeyName sono obbligatori.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.LOCATION.rep.googleapis.com/API_VERSION/projects/PROJECT/locations/LOCATION/servingProfiles?servingProfileId=SERVING_PROFILE_ID" \
  -d '{
    "displayName": "My CMEK serving profile",
    "description": "CMEK for Gemini Live",
    "scope": "GEMINI_LIVE",
    "cmekConfig": {
      "encryptionSpec": {
        "kmsKeyName": "projects/PROJECT/locations/LOCATION/keyRings/RING/cryptoKeys/KEY"
      }
    }
  }'

Create restituisce un'operazione a lunga esecuzione. Esegui il polling a GET https://aiplatform.LOCATION.rep.googleapis.com/API_VERSION/OPERATION_NAME fino a quando la risposta non contiene "done": true. Attendi il completamento dell'operazione prima di recuperare, aggiornare o eliminare il profilo di pubblicazione.

Conferma il profilo di pubblicazione

Al termine dell'operazione di creazione, utilizza get o list per confermare il profilo di pubblicazione:

# Get one serving profile.
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://aiplatform.LOCATION.rep.googleapis.com/API_VERSION/projects/PROJECT/locations/LOCATION/servingProfiles/SERVING_PROFILE_ID"

# List serving profiles in a location.
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://aiplatform.LOCATION.rep.googleapis.com/API_VERSION/projects/PROJECT/locations/LOCATION/servingProfiles?pageSize=50"

Aggiorna i metadati del profilo di pubblicazione

Puoi aggiornare solo i campi displayName e description; la chiave e l'ambito sono immutabili. Il parametro updateMask è facoltativo. Se lo ometti, vengono aggiornati tutti i campi modificabili compilati. Questa chiamata restituisce il profilo di pubblicazione aggiornato.

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.LOCATION.rep.googleapis.com/API_VERSION/projects/PROJECT/locations/LOCATION/servingProfiles/SERVING_PROFILE_ID?updateMask=displayName,description" \
  -d '{"displayName": "Renamed profile", "description": "Updated description"}'

Disattivare CMEK e ripristinare la crittografia predefinita

Elimina il profilo di pubblicazione. I nuovi dati per l'ambito vengono quindi criptati con la crittografia gestita da Google. I dati già criptati con la tua chiave rimangono protetti finché non raggiungono il TTL o non vengono cancellati, in base alle norme di conservazione dell'API.

curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://aiplatform.LOCATION.rep.googleapis.com/API_VERSION/projects/PROJECT/locations/LOCATION/servingProfiles/SERVING_PROFILE_ID"

Dopo aver eliminato un profilo di pubblicazione, il relativo servingProfileId viene riservato per 30 giorni, in modo che tu possa ripristinare la chiave e l'ambito originali. Durante questo periodo, per creare un profilo di pubblicazione con una chiave o un ambito diverso, utilizza un servingProfileId diverso.

Ripristinare un profilo di pubblicazione eliminato

Puoi ripristinare un profilo di pubblicazione entro 30 giorni dalla sua eliminazione. Verifica che la chiave Cloud KMS originale sia ancora abilitata e che il service agent della piattaforma di agenti Gemini Enterprise abbia ancora accesso. Poi crea un profilo di pubblicazione con gli stessi servingProfileId, scope e chiave. Agent Platform riprende a proteggere i dati persistenti dell'ambito con la tua chiave, inclusi i dati criptati prima dell'eliminazione del profilo.

Revoca della chiave

Se disabiliti la chiave Cloud KMS o rimuovi l'accesso del service agent Gemini Enterprise Agent Platform, si verifica quanto segue:

  • Agent Platform non può più criptare o decriptare i dati persistenti dell'ambito.
  • Le richieste che devono accedere a dati protetti non vanno a buon fine e restituiscono un errore FAILED_PRECONDITION che indica che la chiave non è disponibile.

Riattiva la chiave o ripristina la concessione IAM per ripristinare l'accesso.

Prezzi dei profili di pubblicazione

Non sono previsti costi aggiuntivi per la pubblicazione dei profili. Paghi le tariffe standard per le operazioni con le chiavi Cloud KMS per la crittografia e la decrittografia.

Risoluzione dei problemi

  • La creazione del profilo di pubblicazione non riesce o è bloccata: verifica che il service agent Gemini Enterprise Agent Platform disponga del ruolo roles/cloudkms.cryptoKeyEncrypterDecrypter sulla chiave e che la chiave sia abilitata e in una multiregione supportata (us o eu, non globale).
  • L'inferenza non utilizza CMEK: verifica che esista un profilo di pubblicazione per il progetto, la località e l'ambito corrispondenti (GEMINI_LIVE o INTERACTIONS_API).
  • Errori FAILED_PRECONDITION: questi errori in genere indicano che la chiave è stata disattivata o che l'accesso è stato revocato. Riattiva la chiave o ripristina la concessione IAM.

Passaggi successivi