Se usó la API de Cloud Translation para traducir esta página.

Claves de encriptación administradas por el cliente

En esta página, se describe cómo usar tu propia clave de encriptación para proteger tus almacenes de datos en las regiones múltiples de EE.UU. y la UE.

De forma predeterminada, Vertex AI Agent Builder encripta el contenido almacenado en reposo. Vertex AI Agent Builder controla y administra esta encriptación predeterminada por ti sin que debas realizar ninguna acción adicional.

Sin embargo, si tienes requisitos normativos o de cumplimiento específicos relacionados con las claves que protegen los datos, puedes usar claves de encriptación administradas por el cliente (CMEK) para proteger tus recursos. En este caso, usarás las claves de Cloud KMS y seguirás el procedimiento que se indica en esta página. La clave está asociada con una ubicación específica: la multirregión de EE.UU. o la multirregión de la UE.

Las claves de Cloud KMS se usan para encriptar y desencriptar los datos en tus apps y almacenes de datos. Para obtener información general sobre Cloud KMS, consulta la documentación de Cloud Key Management Service.

Limitaciones de Cloud KMS en Vertex AI Agent Builder

Las siguientes limitaciones se aplican a las claves de CMEK (Cloud KMS) en Vertex AI Agent Builder:

No se pueden cambiar las claves que ya se aplicaron a un almacén de datos.
Si tienes políticas de la organización de CMEK, debes crear almacenes de datos nuevos con la API, no con la consola de Google Cloud. La creación de almacenes de datos nuevos con la consola de Google Cloud falla si tienes habilitadas las políticas de la organización de CMEK.
Una vez que se registra una clave, no se puede anular su registro ni quitarla de un almacén de datos.
Debes usar apps y almacenes de datos multirregionales de EE.UU. o la UE (no globales). Para obtener más información sobre las multirregiones y la residencia de datos, incluidos los límites asociados con el uso de ubicaciones no globales, consulta Ubicaciones de Vertex AI Search o Ubicaciones de los agentes de Vertex AI.
Si necesitas registrar más de una clave para un proyecto, comunícate con tu equipo de cuentas de Google para solicitar un aumento de la cuota de las configuraciones de CMEK y proporciona una justificación de por qué necesitas más de una clave.
El uso de un administrador de claves externo (EKM) o un módulo de seguridad de hardware (HSM) con CMEK está disponible en GA con la lista de entidades permitidas. Para usar EKM o HSM con CMEK, comunícate con tu equipo de cuentas de Google.

Se aplican las siguientes limitaciones a la EKM o al HSM con CMEK:
- Tu cuota de EKM y HSM para encriptar y desencriptar llamadas debe tener al menos 1,000 QPM de margen. Para consultar cómo verificar tus cuotas, consulta Cómo verificar tus cuotas de Cloud KMS.
- Si usas un EKM, se debe poder acceder a la clave durante más del 90% de cualquier período de tiempo superior a 30 segundos. Si no se puede acceder a la clave durante este período, puede afectar negativamente la indexación y la actualización de la búsqueda.
- Si hay problemas de facturación, problemas persistentes de falta de cuota o problemas persistentes de inaccesibilidad durante más de 12 horas, el servicio rechaza automáticamente la CmekConfig asociada con la clave de EKM o HSM.
Los almacenes de datos creados antes de que se registre una clave en el proyecto no se pueden proteger con la clave.
Para Vertex AI Search, se requiere la edición Enterprise. Para obtener información sobre la edición Enterprise, consulta Acerca de las funciones avanzadas.
No puedes ajustar los modelos de búsqueda para los almacenes de datos que están protegidos por claves CMEK.
Los almacenes de datos de búsqueda de atención médica cumplen con CMEK. Sin embargo, otros almacenes de datos de conectores de terceros y el conector periódico de BigQuery no cumplen con CMEK. Para obtener información general sobre los almacenes de datos de atención médica, consulta Cómo crear un almacén de datos de búsqueda de atención médica. Para obtener información general sobre los conectores de terceros, consulta Conecta una fuente de datos de terceros.
La rotación de claves no es compatible con las apps de recomendaciones. Si inhabilitas o destruyes una versión de clave que protege un almacén de datos asociado con una app de recomendaciones, esta dejará de funcionar.
La rotación de claves no es compatible con las analíticas. Si rotas las claves de un almacén de datos, las apps que lo usan ya no muestran estadísticas.
Las claves de CMEK no se aplican a las siguientes APIs de RAG: verificación de conexión a tierra, clasificación y generación con conexión a tierra.

Antes de comenzar

Asegúrate de cumplir con los siguientes requisitos previos:

Una clave simétrica de Cloud KMS con el período de rotación establecido en Nunca (rotación manual) Consulta Crea un llavero de claves y Crea una clave en la documentación de Cloud KMS.
Se otorgó el rol de IAM de encriptador/desencriptador de CryptoKey (roles/cloudkms.cryptoKeyEncrypterDecrypter) en la clave al agente de servicio de Discovery Engine. Para obtener instrucciones generales sobre cómo agregar un rol a un agente de servicio, consulta Otorga o revoca un solo rol.
Se otorgó el rol de IAM de encriptador/desencriptador de CryptoKey (roles/cloudkms.cryptoKeyEncrypterDecrypter) en la clave al agente de servicio de Cloud Storage. Si no se otorga este rol, fallará la importación de datos para los almacenes de datos protegidos por CMEK, ya que Discovery Engine no puede crear el bucket y el directorio temporales protegidos por CMEK que se requiere para la importación.
No crees ningún almacén de datos ni apps que quieras que administre tu clave hasta que completes las instrucciones de registro de claves que se indican en esta página.
Las funciones de la edición Enterprise están activadas para la app. Consulta Cómo activar o desactivar la edición Enterprise.

Registra tu clave de Cloud KMS

Para registrar tu propia clave administrada para Vertex AI Agent Builder, sigue estos pasos:

Llama al método UpdateCmekConfig con la clave de Cloud KMS que deseas registrar.

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: Es el ID de tu proyecto que contiene la clave. El número de proyecto no funcionará.
KMS_LOCATION: Es la multirregión de tu clave de KMS: us o europe.
KEY_RING: Es el nombre del llavero de claves que contiene la clave.
KEY_NAME: El nombre de la clave.
PROJECT_ID: Es el ID de tu proyecto que contiene el almacén de datos.
LOCATION: Es la multirregión de tu almacén de datos: us o eu.
CMEK_CONFIG_ID: Es el ID del recurso CmekConfig.
SET_DEFAULT: Establece en true para usar la clave como la clave predeterminada para los almacenes de datos posteriores que se creen en la región múltiple.

Un ejemplo de llamada y respuesta de curl se ve de la siguiente manera:

$ 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"
 }
}

Opcional: Registra el valor name que muestra el método y sigue las instrucciones que se indican en Obtén detalles sobre una operación de larga duración para ver cuándo se completa la operación.

Por lo general, el registro de una clave tarda unos minutos.

Una vez que se completa la operación, la clave protege los almacenes de datos nuevos de esa multirregión. Para obtener información general sobre la creación de almacenes de datos, consulta Cómo crear un almacén de datos de búsqueda.

Cómo ver las claves de Cloud KMS

Para ver una clave registrada de Vertex AI Agent Builder, haz lo siguiente:

Si tienes el nombre del recurso CmekConfig, llama al método 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: Es la multirregión de tu almacén de datos: us o eu.
PROJECT_ID: Es el ID de tu proyecto que contiene los datos.
CMEK_CONFIG_ID: Es el ID del recurso CmekConfig.

Un ejemplo de llamada y respuesta de curl se ve de la siguiente manera:

$ 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
}

Si no tienes el nombre del recurso CmekConfig, llama al método 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: Es la multirregión de tu almacén de datos: us o eu.
PROJECT_ID: Es el ID de tu proyecto que contiene los datos.

Un ejemplo de llamada y respuesta de curl se ve de la siguiente manera:

$ 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"
    }
  ]
}

Opcional: Verifica que un almacén de datos esté protegido por una clave

Los almacenes de datos que se crearon antes de que se registrara tu clave no están protegidos por esta. Si deseas confirmar que una clave en particular protege un almacén de datos, sigue estos pasos:

Ejecuta el siguiente comando curl en el almacén de datos:

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: Es la multirregión de tu almacén de datos: us o eu.
PROJECT_ID: Es el ID de tu proyecto que contiene el almacén de datos.
DATA_STORE_ID: Es el ID del almacén de datos.

Un ejemplo de llamada a curl se ve de la siguiente manera:

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"

Revisa el resultado del comando: Si el campo cmekConfig está en el resultado y el campo kmsKey muestra la clave que registraste, el almacén de datos está protegido por la clave.

Un ejemplo de respuesta se ve de la siguiente manera:

{
 "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"
 }
}

Rotar claves

Cuando rota las claves, creas una versión nueva de la clave y la configuras como la versión principal. Deja la versión original de la clave habilitada durante un tiempo antes de inhabilitarla. Esto les da tiempo para completarse a las operaciones de larga duración que podrían estar usando la clave anterior.

En el siguiente procedimiento, se describen los pasos para rotar las claves de un almacén de datos de Vertex AI Agent Builder. Para obtener información general sobre la rotación de claves, consulta Rotación de claves en la guía de Cloud KMS.

Importante: No rotes las claves en los almacenes de datos asociados con apps de recomendaciones ni con ninguna app que necesite estadísticas. Consulta Limitaciones de Cloud KMS en Vertex AI Agent Builder.

Vuelve a registrar tu llave. Para ello, repite el paso 1 de Registra tu clave de Cloud KMS.

Nota: Volver a registrarse es mucho más rápido que registrarse. No necesitarás supervisar el registro nuevamente como una operación de larga duración.
Consulta las instrucciones de la sección Administrar claves de la guía de Cloud KMS para hacer lo siguiente:
1. Crea una versión de clave nueva, habilítala y conviértela en la versión principal.
2. Deja habilitada la versión de clave anterior.
3. Después de aproximadamente una semana, inhabilita la versión de clave anterior y asegúrate de que todo funcione como antes.
4. Más adelante, cuando estés seguro de que inhabilitar la versión anterior de la clave no causó ningún problema, puedes destruirla.

Si se inhabilita o revoca una clave

Si se inhabilita una clave o se revocan los permisos de la clave, el almacén de datos deja de transferir y publicar datos en un plazo de 15 minutos. Sin embargo, volver a habilitar una clave o restablecer permisos lleva mucho tiempo. El almacén de datos puede tardar hasta 24 horas en reanudar la publicación de datos.

Por lo tanto, no inhabilites una clave, a menos que sea necesario. Inhabilitar y habilitar una clave en un almacén de datos es una operación que consume mucho tiempo. Por ejemplo, cambiar una clave de inhabilitada a habilitada de forma repetida significa que el almacén de datos tardará mucho tiempo en alcanzar un estado protegido. Inhabilitar una clave y volver a habilitarla inmediatamente después podría generar días de tiempo de inactividad, ya que la clave primero se inhabilita del almacén de datos y, luego, se vuelve a habilitar.