Chaves de criptografia gerenciadas pelo cliente

Esta página descreve como usar sua própria chave de criptografia para proteger os repositórios de dados nas multirregiões dos EUA e da UE.

Por padrão, o Vertex AI Agent Builder criptografa o conteúdo armazenado em repouso. O Vertex AI Agent Builder processa e gerencia essa criptografia padrão para você sem que você precise fazer nada.

No entanto, se você tiver requisitos regulatórios ou de compliance específicos relacionados às chaves que protegem seus dados, use as chaves de criptografia gerenciadas pelo cliente (CMEKs) para proteger seus recursos. Nesse caso, você vai usar chaves do Cloud KMS e seguir o procedimento desta página. A chave está associada a um local específico: a multirregião dos EUA ou da UE.

As chaves do Cloud KMS são usadas para criptografar e descriptografar os dados em seus armazéns de dados e apps. Para informações gerais sobre o Cloud KMS, consulte a documentação do Cloud Key Management Service.

Limitações do Cloud KMS no Vertex AI Agent Builder

As limitações a seguir se aplicam às chaves CMEK (Cloud KMS) no Vertex AI Agent Builder:

  • As chaves que já foram aplicadas a um repositório de dados não podem ser alteradas.

  • Se você tiver políticas da organização da CMEK, será necessário criar novos repositórios de dados usando a API, não o console do Google Cloud. A criação de novos repositórios de dados usando o console do Google Cloud falha se você tiver políticas da organização da CMEK ativadas.

  • Depois que uma chave é registrada, ela não pode ser desregistrada ou removida de um repositório de dados.

  • Use apps e repositórios de dados multirregionais dos EUA ou da UE (não globais). Para mais informações sobre multirregiões e residência de dados, incluindo os limites associados ao uso de locais não globais, consulte Locais do Vertex AI para Pesquisa ou Locais dos agentes da Vertex AI.

  • Se você precisar registrar mais de uma chave para um projeto, entre em contato com a equipe da sua conta do Google para solicitar um aumento de cota para configurações de CMEK, justificando por que você precisa de mais de uma chave.

  • O uso de um gerenciador de chaves externo (EKM) ou um módulo de segurança de hardware (HSM) com CMEK está na versão GA com lista de permissões. Para usar EKM ou HSM com CMEK, entre em contato com a equipe de conta do Google.

    As seguintes limitações se aplicam ao EKM ou HSM com CMEK:

    • Sua cota de EKM e HSM para chamadas de criptografia e descriptografia precisa ter pelo menos 1.000 QPM de espaço. Para saber como verificar suas cotas, consulte Verificar suas cotas do Cloud KMS.

    • Se você estiver usando o EKM, a chave precisa ser acessível por mais de 90% de qualquer janela de tempo superior a 30 segundos. Se a chave não for acessível por esse período, isso poderá afetar negativamente a indexação e a atualização da pesquisa.

    • Se houver problemas de faturamento, problemas persistentes de cota ou problemas persistentes de inacessibilidade por mais de 12 horas, o serviço reduzirá automaticamente a CmekConfig associada à chave EKM ou HSM.

  • Os repositórios de dados criados antes que uma chave seja registrada no projeto não podem ser protegidos por ela.

  • Para a Vertex AI para Pesquisa, a edição Enterprise é obrigatória. Para informações sobre a edição Enterprise, consulte Sobre os recursos avançados.

  • Não é possível ajustar modelos de pesquisa para repositórios de dados protegidos por chaves CMEK.

  • Os repositórios de dados de pesquisa de saúde são compatíveis com o CMEK. No entanto, outras lojas de dados de conectores de terceiros e o conector periódico do BigQuery não são compatíveis com o CMEK. Para informações gerais sobre repositórios de dados de saúde, consulte Criar um repositório de dados de pesquisa de saúde. Para informações gerais sobre conectores de terceiros, consulte Conectar uma fonte de dados de terceiros.

  • A rotação de chaves não é compatível com apps de recomendações. Se você desativar ou destruir uma versão de chave que protege um repositório de dados associado a um app de recomendações, ele vai parar de funcionar.

  • A rotação de chaves não é compatível com o Google Analytics. Se você girar as chaves de um repositório de dados, os apps que usam esse repositório não vão mais mostrar as análises.

  • As chaves CMEK não se aplicam às seguintes APIs de RAG: verificação de embasamento, classificação e geração de embasamento.

Antes de começar

Verifique se você atende aos seguintes pré-requisitos:

  • Uma chave simétrica do Cloud KMS com o período de rotação definido como Nunca (rotação manual). Consulte Criar um keyring e Criar uma chave na documentação do Cloud KMS.

  • O papel do IAM de criptografador/descriptografador de CryptoKey (roles/cloudkms.cryptoKeyEncrypterDecrypter) na chave foi concedido ao agente de serviço do Discovery Engine. Para instruções gerais sobre como adicionar uma função a um agente de serviço, consulte Conceder ou revogar um único papel.

  • O papel de IAM do CryptoKey Encrypter/Decrypter (roles/cloudkms.cryptoKeyEncrypterDecrypter) na chave foi concedido ao agente de serviço do Cloud Storage. Se essa função não for concedida, a importação de dados para repositórios de dados protegidos por CMEK vai falhar porque o Discovery Engine não pode criar o bucket e o diretório temporário protegidos por CMEK que é necessário para a importação.

  • Não crie repositórios de dados ou apps que você quer que sejam gerenciados pela chave até que você conclua as instruções de registro de chave nesta página.

  • Os recursos da edição Enterprise estão ativados para o app. Consulte Ativar ou desativar a edição Enterprise.

Registrar sua chave do Cloud KMS

Para registrar sua própria chave gerenciada para o Vertex AI Agent Builder, siga estas etapas:

  1. Chame o método UpdateCmekConfig com a chave do Cloud KMS que você quer 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: o ID do projeto que contém a chave. O número do projeto não funciona.
    • KMS_LOCATION: a multirregião da chave do KMS: us ou europe.
    • KEY_RING: o nome do keyring que contém a chave.
    • KEY_NAME: o nome da chave.
    • PROJECT_ID: o ID do projeto que contém o repositório de dados.
    • LOCATION: a multirregião do repositório de dados: us ou eu.
    • CMEK_CONFIG_ID: o ID do recurso CmekConfig.
    • SET_DEFAULT: defina como true para usar a chave como padrão para armazenamentos de dados subsequentes criados na multirregião.

    Um exemplo de chamada e resposta do curl é assim: 

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

  2. Opcional: registre o valor name retornado pelo método e siga as instruções em Conferir detalhes sobre uma operação de longa duração para saber quando a operação for concluída.

    Normalmente, leva alguns minutos para registrar uma chave.

Depois que a operação for concluída, os novos repositórios de dados nessa multirregião serão protegidos pela chave. Para informações gerais sobre a criação de repositórios de dados, consulte Criar um repositório de dados de pesquisa.

Conferir chaves do Cloud KMS

Para conferir uma chave registrada do Vertex AI Agent Builder, siga um destes procedimentos:

  • Se você tiver o nome do recurso CmekConfig, chame o 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: a multirregião do repositório de dados: us ou eu.
    • PROJECT_ID: o ID do projeto que contém os dados
    • CMEK_CONFIG_ID: o ID do recurso CmekConfig.

    Um exemplo de chamada e resposta do curl é assim: 

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

  • Se você não tiver o nome do recurso CmekConfig, chame o 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: a multirregião do repositório de dados: us ou eu.
    • PROJECT_ID: o ID do projeto que contém os dados

    Um exemplo de chamada e resposta do curl é assim: 

    $ 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: verificar se um repositório de dados está protegido por uma chave

Os repositórios de dados criados antes do registro da chave não são protegidos por ela. Se você quiser confirmar que um repositório de dados específico está protegido pela sua chave, siga estas etapas:

  1. Execute o comando curl a seguir no repositório de dados:

    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: a multirregião do repositório de dados: us ou eu.
    • PROJECT_ID: o ID do projeto que contém o repositório de dados.
    • DATA_STORE_ID: o ID do repositório de dados.

    Um exemplo de chamada curl é assim: 

    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"

  2. Analise a saída do comando: se o campo cmekConfig estiver na saída e o campo kmsKey mostrar a chave que você registrou, o repositório de dados estará protegido pela chave.

    Um exemplo de resposta é este:

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

Alternar chaves

Ao fazer a rotação de chaves, você cria uma nova versão da chave e a define como a principal. Deixe a versão original da chave ativada por um tempo antes de desativá-la. Isso permite que operações de longa duração que estejam usando a chave mais antiga sejam concluídas.

O procedimento a seguir descreve as etapas para girar chaves de um repositório de dados do Vertex AI Agent Builder. Para informações gerais sobre a rotação de chaves, consulte Rotação de chaves no guia do Cloud KMS.

Importante:não faça a rotação de chaves em repositórios de dados associados a apps de recomendações ou a apps que precisam de análises. Consulte Limitações do Cloud KMS no Vertex AI Agent Builder.

  1. Registre a chave novamente. Para isso, repita a etapa 1 de Registrar sua chave do Cloud KMS.

  2. Consulte as instruções na seção Gerenciar chaves do guia do Cloud KMS para fazer o seguinte:

    1. Crie uma nova versão da chave, ative-a e torne-a principal.

    2. Deixe a versão de chave mais antiga ativada.

    3. Depois de uma semana, desative a versão de chave mais antiga e verifique se tudo está funcionando como antes.

    4. Em uma data posterior, quando tiver certeza de que nenhum problema foi causado pela desativação da versão de chave mais antiga, você poderá destruí-la.

Se uma chave for desativada ou revogada

Se uma chave for desativada ou as permissões dela forem revogadas, o repositório de dados vai parar de processar e exibir dados em 15 minutos. No entanto, reativar uma chave ou restaurar permissões leva muito tempo. Pode levar até 24 horas para que o repositório de dados volte a servir dados.

Portanto, não desative uma chave, a menos que seja necessário. Desativar e ativar uma chave em um repositório de dados é uma operação demorada. Por exemplo, alternar repetidamente uma chave entre desativada e ativada significa que levará muito tempo para que o repositório de dados atinja um estado protegido. Desativar uma chave e ativá-la novamente imediatamente depois pode resultar em dias de inatividade porque a chave é desativada primeiro no repositório de dados e, em seguida, ativada novamente.