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, a 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 a as chaves que protegem seus dados, é possível usar chaves de criptografia gerenciadas pelo cliente (CMEK) para proteger seus recursos. Nesse caso, você vai usar o Cloud KMS e siga o procedimento nesta 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 de organização do CMEK, será necessário criar novos repositórios de dados usando a API, não o console do Google Cloud. Criar novos repositórios de dados usando o O console do Google Cloud falhará se as políticas da organização de CMEK estiverem ativadas.

• Depois que uma chave é registrada, não é possível cancelar o registro ou removê-la de um repositório de dados.

• Use repositórios e apps de dados multirregionais dos EUA ou da UE (não globais). Para mais informações sobre multirregiões e residência de dados, incluindo limites associadas ao uso de locais não globais, consulte Locais da 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 seu equipe de conta para solicitar aumento de cota para configurações de CMEK fornecendo uma justificativa para o motivo da necessidade de mais de uma chave.

• O uso do gerenciador de chaves externo (EKM) ou do 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 deve ter pelo menos 1.000 QPM de margem. Para saber como verificar suas cotas, consulte esta página cotas do Cloud KMS.

  • Se você estiver usando o EKM, a chave vai precisar estar acessível por mais de 90% do tempo de mais de 30 segundos. Se não for possível acessar a chave pode afetar negativamente a indexação e a atualização das pesquisas.

  • Se houver problemas de faturamento, problemas persistentes de falta de cota ou problemas de inacessibilidade por mais de 12 horas, o serviço automaticamente desativa o CmekConfig associado à 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 é necessá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 que são protegidos por chaves CMEK.

• Os repositórios de dados de pesquisa de saúde são compatíveis com 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 mais informações sobre conectores de terceiros, consulte Conectar um provedor de dados fonte.

• 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 chaves para um repositório de dados, os apps que usam esse repositório de dados não exibem mais análise de dados em nuvem.

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

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 Crie uma chave no Cloud KMS na documentação do Google Cloud.

• 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 um papel a um agente de serviço, consulte Conceder ou revogar um único de rede.

• Papel do IAM para criptografador/descriptografador de CryptoKey (roles/cloudkms.cryptoKeyEncrypterDecrypter) na chave foi concedido a o agente de serviço do Cloud Storage. Se esse papel não for concedido, a importação de dados para repositórios de dados protegidos por CMEKs vai falhar porque o Discovery Engine está criar o bucket e o diretório temporários protegidos pela CMEK necessários 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 Turn Enterprise ou desativar a edição.

Registrar sua chave do Cloud KMS

Para registrar sua própria chave gerenciada no 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 sua chave 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 os dados loja on-line.
   • LOCATION: a multirregião do armazenamento 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.

   Veja um exemplo de chamada e resposta 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/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.

   Geralmente, o registro de uma chave leva alguns minutos.

Após a conclusão da operação, novos repositórios de dados nessa multirregião são protegidas pela chave. Para informações gerais sobre a criação de repositórios de dados, consulte Criar um repositório de dados de pesquisa.

Observação :a criação do primeiro repositório de dados após a chave ser concluída por várias horas registrados. No entanto, os repositórios de dados subsequentes serão criados em segundos.

Conferir chaves do Cloud KMS

Para visualizar uma chave registrada para o 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 seu 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 é este:

  $ 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 seu 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 é este:

  $ 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 pela chave. 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 seu 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.

   Veja um exemplo de chamada 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/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 no a saída e o campo kmsKey mostrar a chave registrada, então a repositório de dados é protegido pela chave.

   Um exemplo de resposta é semelhante a 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

Visualização

Este produto ou recurso está sujeito aos "Termos das ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos do serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Ao fazer a rotação de chaves, você cria uma nova versão delas e cria a nova versão como principal. Deixe a versão original da chave ativada por um tempo antes de desativá-la. Assim, qualquer campanha de longa duração operações que podem estar usando o tempo de chave mais antigo para serem concluídas.

O procedimento a seguir descreve as etapas para alternar chaves para um Repositório de dados do Agent Builder da Vertex AI. 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 de 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.

   Observação: o novo registro é muito mais rápido do que o registro. Não será necessário monitorar o registro novamente como uma operação de longa duração.

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

   1. Criar uma nova versão de chave, ativá-la e torná-la primária.

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

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

   4. Em algum momento posterior, quando tiver certeza de que nenhum problema foi causado por desativar a versão de chave mais antiga, você poderá destruir a versão mais antiga.

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, a reativação de uma chave ou a restauração de permissões demora muito. Ela pode levar até 24 horas para que o repositório de dados possa retomar a veiculação de dados.

Portanto, não desative uma chave, a menos que seja necessário. Como desativar e ativar uma chave no 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 armazenamento de dados atinja um estado protegido. Desativar uma chave e reativá-la imediatamente depois pode resultar em dias de inatividade porque a chave é desativada primeiro do repositório de dados e, reativado.