Par défaut, Vertex AI Agent Builder chiffre le contenu client au repos. Vertex AI Agent Builder gère le chiffrement sans intervention de votre part. Cette option est appelée chiffrement par défaut de Google.
Si vous souhaitez contrôler vos clés de chiffrement, vous pouvez utiliser des clés de chiffrement gérées par le client (CMEK) dans Cloud KMS avec des services bénéficiant d'une intégration des CMEK, y compris Vertex AI Agent Builder. L'utilisation de clés Cloud KMS vous permet de contrôler leur niveau de protection, leur emplacement, leur calendrier de rotation, leurs autorisations d'utilisation et d'accès, ainsi que leurs limites cryptographiques. Cloud KMS vous permet également d'afficher les journaux d'audit et de contrôler les cycles de vie des clés. Au lieu de laisser Google posséder et gérer les clés de chiffrement de clés (KEK) symétriques qui protègent vos données, c'est vous qui vous chargez de cette tâche dans Cloud KMS.
Une fois que vous avez configuré vos ressources avec des CMEK, l'accès à vos ressources Vertex AI Agent Builder est semblable à celui du chiffrement par défaut de Google. Pour en savoir plus sur les options de chiffrement, consultez Clés de chiffrement gérées par le client (CMEK).
Limites de Cloud KMS dans Vertex AI Agent Builder
Les limites suivantes s'appliquent aux clés CMEK (Cloud KMS) dans Vertex AI Agent Builder:
Les clés déjà appliquées à un entrepôt de données ne peuvent pas être modifiées.
Une fois qu'une clé a été enregistrée, vous ne pouvez plus la désenregistrer ni la supprimer d'un entrepôt de données.
Vous devez utiliser des applications et des magasins de données multirégionaux aux États-Unis ou dans l'UE (et non des applications et des magasins de données globaux). Pour en savoir plus sur les multirégions et la résidence des données, y compris les limites associées à l'utilisation d'emplacements non globaux, consultez les pages Emplacements Vertex AI Search ou Emplacements des agents Vertex AI.
Si vous devez enregistrer plusieurs clés pour un projet, contactez l'équipe responsable de votre compte Google pour demander une augmentation de quota pour les configurations CMEK, en expliquant pourquoi vous avez besoin de plusieurs clés.
L'utilisation d'un gestionnaire de clés externe (EKM) ou d'un module de sécurité matérielle (HSM) avec CMEK est disponible en version GA avec une liste d'autorisation. Pour utiliser un EKM ou un HSM avec les CMEK, contactez l'équipe chargée de votre compte Google.
Les restrictions suivantes s'appliquent aux EKM ou aux HSM avec CMEK:
Votre quota EKM et HSM pour le chiffrement et le déchiffrement des appels doit être d'au moins 1 000 QPM. Pour savoir comment vérifier vos quotas, consultez Vérifier vos quotas Cloud KMS.
Si vous utilisez un EKM, la clé doit être accessible pendant plus de 90% de toute période de plus de 30 secondes. Si la clé n'est pas accessible pendant cette période, cela peut avoir un impact négatif sur l'indexation et la fraîcheur des résultats de recherche.
En cas de problèmes de facturation, de dépassement de quota persistant ou d'indisponibilité persistante pendant plus de 12 heures, le service désactive automatiquement la configuration Cmek associée à la clé EKM ou HSM.
Les magasins de données créés avant qu'une clé ne soit enregistrée dans le projet ne peuvent pas être protégés par la clé.
Pour Vertex AI Search, l'édition Enterprise est requise. Pour en savoir plus sur l'édition Enterprise, consultez la section À propos des fonctionnalités avancées.
Vous ne pouvez pas ajuster les modèles de recherche pour les data stores protégés par des clés CMEK.
Les data stores de recherche de données de santé et les connecteurs tiers sont compatibles avec les CMEK. Toutefois, les connecteurs propriétaires, comme le connecteur périodique BigQuery, ne sont pas compatibles avec les CMEK. Pour en savoir plus sur les datastores de recherche dans le secteur de la santé, consultez Créer un datastore de recherche dans le secteur de la santé. Pour savoir comment rendre les connecteurs tiers compatibles avec CMEK, consultez la section À propos des clés à région unique pour les connecteurs tiers dans la documentation Google Agentspace.
La rotation des clés n'est pas compatible avec les applications de recommandations. Si vous désactivez ou détruisez une version de clé qui protège un espace de stockage de données associé à une application de recommandations, l'application de recommandations ne fonctionne plus.
La rotation des clés n'est pas compatible avec les connecteurs tiers. Si vous désactivez ou détruissez une version de clé qui protège un entrepôt de données associé à un connecteur tiers, le connecteur cesse de fonctionner.
La rotation des clés n'est pas compatible avec les données analytiques. Si vous faites pivoter des clés pour un datastore, les applications qui l'utilisent n'affichent plus d'analyse.
Les clés CMEK ne s'appliquent pas aux API RAG suivantes : check grounding (vérifier la mise à la terre), ranking (classement) et grounded generation (génération avec mise à la terre).
Avant de commencer
Assurez-vous de remplir les conditions préalables suivantes:
Une clé Cloud KMS symétrique dont la période de rotation est définie sur Never (Rotation manuelle) (Jamais). Consultez Créer un trousseau de clés et Créer une clé dans la documentation Cloud KMS.
Le rôle IAM de chiffreur/déchiffreur de clés cryptographiques (
roles/cloudkms.cryptoKeyEncrypterDecrypter) sur la clé a été accordé à l'agent de service Discovery Engine. Pour obtenir des instructions générales sur l'ajout d'un rôle à un agent de service, consultez la section Attribuer ou révoquer un rôle unique.Le rôle IAM de chiffreur/déchiffreur de clés cryptographiques (
roles/cloudkms.cryptoKeyEncrypterDecrypter) sur la clé a été accordé à l'agent de service Cloud Storage. Si ce rôle n'est pas accordé, l'importation de données pour les datastores protégés par CMEK échouera, car Discovery Engine ne pourra pas créer le bucket et le répertoire temporaires protégés par CMEK requis pour l'importation.Ne créez pas de data stores ni d'applications que vous souhaitez gérer avec votre clé tant que vous n'avez pas suivi les instructions d'enregistrement de la clé sur cette page.
Les fonctionnalités de l'édition Enterprise sont activées pour l'application. Consultez Activer ou désactiver l'édition Enterprise.
Enregistrer votre clé Cloud KMS
Pour enregistrer votre propre clé gérée pour Vertex AI Agent Builder, procédez comme suit:
Appelez la méthode
UpdateCmekConfigavec la clé Cloud KMS que vous souhaitez enregistrer.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"Remplacez les éléments suivants :
KMS_PROJECT_ID: ID de votre projet contenant la clé. Le numéro de projet ne fonctionne pas.KMS_LOCATION: multirégion de votre clé KMS:usoueurope.KEY_RING: nom du trousseau de clés qui contient la clé.KEY_NAME: nom de la clé.PROJECT_ID: ID de votre projet contenant le magasin de données.LOCATION: emplacement multirégional de votre magasin de données:usoueu.CMEK_CONFIG_ID: ID de la ressource CmekConfig.SET_DEFAULT: défini surtruepour utiliser la clé comme clé par défaut pour les datastores créés ultérieurement dans l'emplacement multirégional.
Voici un exemple d'appel et de réponse curl:
$ 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" } }Facultatif: enregistrez la valeur
namerenvoyée par la méthode et suivez les instructions de la section Obtenir des informations sur une opération de longue durée pour savoir quand l'opération est terminée.L'enregistrement d'une clé prend généralement quelques minutes.
Si vous figurez sur la liste d'autorisation pour utiliser des connecteurs tiers et que vous souhaitez protéger vos données tierces avec votre propre clé gérée, suivez la procédure d'enregistrement des clés à région unique dans la documentation Google Agentspace.
Une fois l'opération terminée, les nouveaux magasins de données de cette multirégion sont protégés par la clé. Pour en savoir plus sur la création de datastores, consultez la page Créer un datastore de recherche.
Afficher les clés Cloud KMS
Pour afficher une clé enregistrée pour Vertex AI Agent Builder, procédez comme suit:
Si vous disposez du nom de la ressource CmekConfig, appelez la méthode
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"Remplacez les éléments suivants :
LOCATION: emplacement multirégional de votre magasin de données:usoueu.PROJECT_ID: ID de votre projet contenant les donnéesCMEK_CONFIG_ID: ID de la ressource CmekConfig.
Voici un exemple d'appel et de réponse curl:
$ 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 }Si vous ne connaissez pas le nom de la ressource CmekConfig, appelez la méthode
ListCmekConfigs:curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cmekConfigs"Remplacez les éléments suivants :
LOCATION: emplacement multirégional de votre magasin de données:usoueu.PROJECT_ID: ID de votre projet contenant les données
Voici un exemple d'appel et de réponse curl:
$ 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" } ] }
Désenregistrer votre clé Cloud KMS
Pour désenregistrer votre clé de Vertex AI Agent Builder, procédez comme suit:
Appelez la méthode
DeleteCmekConfigavec le nom de la ressource CmekConfig que vous souhaitez désenregistrer.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"Remplacez les éléments suivants :
LOCATION: emplacement multirégional de votre magasin de données:usoueu.PROJECT_ID: ID de votre projet contenant le magasin de données.CMEK_CONFIG_ID: ID de la ressource CmekConfig.
Voici un exemple d'appel et de réponse curl:
$ 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" } }Facultatif: enregistrez la valeur
namerenvoyée par la méthode et suivez les instructions de la section Obtenir des informations sur une opération de longue durée pour savoir quand l'opération est terminée.La suppression d'une clé prend généralement quelques minutes.
Vérifier qu'un datastore est protégé par une clé
Les datastores créés avant l'enregistrement de votre clé ne sont pas protégés par celle-ci. Si vous souhaitez vérifier qu'un data store particulier est protégé par votre clé, procédez comme suit:
Exécutez la commande curl suivante sur le magasin de données:
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"Remplacez les éléments suivants :
LOCATION: emplacement multirégional de votre magasin de données:usoueu.PROJECT_ID: ID de votre projet contenant le magasin de données.DATA_STORE_ID: ID du magasin de données.
Voici un exemple d'appel curl:
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"
Examinez la sortie de la commande: si le champ
cmekConfigfigure dans la sortie et que le champkmsKeyaffiche la clé que vous avez enregistrée, le datastore est protégé par la clé.Voici un exemple de réponse:
{ "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" } }
Rotation des clés
Lorsque vous effectuez une rotation de clés, vous créez une nouvelle version de la clé et définissez cette nouvelle version comme version principale. Laissez la version d'origine de la clé activée pendant un certain temps avant de la désactiver. Cela permet à toutes les opérations de longue durée qui pourraient utiliser l'ancienne clé de se terminer.
La procédure suivante décrit comment faire pivoter les clés d'un datastore Vertex AI Agent Builder. Pour en savoir plus sur la rotation des clés, consultez la section Rotation des clés du guide Cloud KMS.
Important:Ne faites pas pivoter les clés sur les magasins de données associés aux applications de recommandations ni aux applications nécessitant des données analytiques. Consultez la section Limites de Cloud KMS dans Vertex AI Agent Builder.
Réenregistrez votre clé. Pour ce faire, répétez l'étape 1 de la section Enregistrer votre clé Cloud KMS.
Pour effectuer les opérations suivantes, consultez les instructions de la section Gérer les clés du guide Cloud KMS:
Créez une version de clé, activez-la et définissez-la comme version principale.
Laissez l'ancienne version de clé activée.
Après environ une semaine, désactivez l'ancienne version de clé et assurez-vous que tout fonctionne comme avant.
À une date ultérieure, lorsque vous êtes certain qu'aucun problème n'a été causé par la désactivation de l'ancienne version de clé, vous pouvez la détruire.
Si une clé est désactivée ou révoquée
Si une clé est désactivée ou si les autorisations associées sont révoquées, le datastore cesse d'ingérer et de diffuser des données sous 15 minutes. Toutefois, la réactivation d'une clé ou la restauration des autorisations prend beaucoup de temps. Le data store peut mettre jusqu'à 24 heures à reprendre la diffusion des données.
Par conséquent, ne désactivez une clé que si nécessaire. La désactivation et l'activation d'une clé sur un data store est une opération fastidieuse. Par exemple, si vous désactivez et activez une clé à plusieurs reprises, le magasin de données mettra beaucoup de temps à atteindre un état protégé. Désactiver une clé et la réactiver immédiatement par la suite peut entraîner des jours d'indisponibilité, car la clé est d'abord désactivée du magasin de données, puis réactivée.