Esta página explica como configurar e usar notificações de eventos para os seus segredos no Secret Manager.
Vista geral
O Secret Manager integra-se com o Pub/Sub para fornecer notificações de eventos sobre alterações aos Secrets e às versões dos Secrets. Pode usar estas notificações para iniciar fluxos de trabalho, como reiniciar uma aplicação quando é adicionada uma nova versão secreta ou notificar os engenheiros de segurança quando um segredo é eliminado. Para mais informações sobre como usar estas notificações para iniciar fluxos de trabalho, consulte a documentação do Pub/Sub.
Como funcionam as notificações de eventos no Secret Manager
Os segredos podem ser configurados com uma lista de até 10 tópicos do Pub/Sub. Sempre que é realizada uma operação que modifica o segredo ou uma das respetivas versões, o Secret Manager publica automaticamente uma mensagem em cada um dos tópicos do Pub/Sub nesse segredo.
As chamadas Get
, List
e Access
não resultam em publicações de mensagens.
As mensagens do Pub/Sub têm um conjunto de pares de chave-valor de atributos que contêm metadados sobre o evento, bem como um campo data que contém uma serialização JSON completa do recurso Secret
ou SecretVersion
que foi criado ou modificado. Este JSON é uma string codificada em UTF-8 que representa o recurso Secret
ou SecretVersion
exatamente no formato especificado pela API pública Secret Manager, codificada em JSON, conforme especificado no mapeamento JSON proto3.
Tipos de eventos
Segue-se uma lista dos tipos de eventos suportados pelo Secret Manager.
Tipo de evento | Descrição |
---|---|
SECRET_CREATE |
Enviado quando um novo secret é criado com êxito. |
SECRET_UPDATE |
Enviado quando um novo segredo é atualizado com êxito. |
SECRET_DELETE |
Enviado quando um segredo é eliminado, devido a um pedido iniciado pelo utilizador ou à expiração do segredo. |
SECRET_VERSION_ADD |
Enviado quando uma nova versão do Secret é adicionada com êxito. |
SECRET_VERSION_ENABLE |
Enviado quando uma versão do segredo é ativada. |
SECRET_VERSION_DISABLE |
Enviado quando uma versão do segredo é desativada. |
SECRET_VERSION_DESTROY |
Enviado quando uma versão do código secreto é destruída. |
SECRET_VERSION_DESTROY_SCHEDULED |
Enviado quando é configurada uma duração do atraso de destruição no segredo e o utilizador tenta destruir uma versão secreta. |
SECRET_ROTATE |
Enviado quando é altura de rodar um segredo. Consulte o artigo Crie programações de rotação para mais informações. |
TOPIC_CONFIGURED |
Esta é uma mensagem de teste sem corpo nem atributos além de Uma mensagem Sempre que os tópicos são atualizados num segredo, é enviada uma mensagem |
Formato de notificação
As notificações enviadas para o tópico do Pub/Sub são compostas por duas partes:
-
Atributos: um conjunto de pares de chave-valor que descrevem o evento.
-
Dados: uma string que contém os metadados do objeto alterado.
Atributos
Os atributos são pares de chaves-valores contidos nas notificações enviadas pelo Secret Manager para o seu tópico do Pub/Sub. Todas as notificações, exceto as TOPIC_CONFIGURED
mensagens de teste
contêm sempre o seguinte conjunto de pares chave:valor, independentemente dos dados da notificação:
Exemplo | Descrição | |
---|---|---|
eventType |
SECRET_CREATE |
O tipo de evento que acabou de ocorrer. Consulte Tipos de eventos para ver uma lista de valores possíveis. |
dataFormat |
JSON_API_V1 |
O formato dos dados do objeto. |
secretId |
projects/p/secrets/my-secret |
O nome do recurso completo do segredo no qual ocorreu o evento. |
timestamp |
2021-01-20T11:17:45.081104-08:00 |
A hora em que o evento ocorreu. |
Além disso, as notificações contêm, por vezes, o seguinte conjunto de pares de chave-valor:
Exemplo | Descrição | |
---|---|---|
versionId |
projects/p/secrets/my-secret/versions/456 |
O nome da versão secreta na qual ocorreu o evento.
Esta opção só está presente nas notificações de eventos de
|
deleteType |
REQUESTED |
Indica se a eliminação foi pedida por um utilizador (REQUESTED ) ou devido à expiração do segredo (EXPIRATION ). Só está presente nas notificações de eventos SECRET_DELETE .
|
Dados
O campo de dados é uma string UTF-8 que contém os metadados do objeto alterado. Os dados são um segredo ou uma versão do segredo.
Para notificações SECRET_DELETE
, os metadados contidos no campo de dados representam os metadados do objeto tal como estavam antes da eliminação. Para todas as outras notificações, os metadados incluídos no campo de dados representam os metadados do objeto após a ocorrência da alteração.
Limitações
As notificações de eventos só estão disponíveis na API Secret Manager v1 e na CLI Google Cloud.
Antes de começar
Pode optar por armazenar todos os recursos no mesmo projeto ou armazenar segredos e tópicos do Pub/Sub em projetos separados.
-
Para configurar o Gestor Secreto, conclua o seguinte:
-
Crie ou use um projeto existente para alojar os recursos do Secret Manager.
-
Se necessário, conclua os passos mencionados na página Ative a API Secret Manager.
-
-
Para configurar o Pub/Sub, conclua o seguinte:
-
Crie ou use um projeto existente para alojar os seus recursos do Pub/Sub.
-
Se necessário, ative a API Pub/Sub.
-
-
Autentique-se no Google Cloud com o seguinte comando:
$ gcloud auth login --update-adc
Crie uma identidade de agente de serviço
Para criar uma identidade de agente de serviço para cada projeto que exija segredos com notificações de eventos, siga estes passos:
-
Para criar uma identidade de serviço com a CLI gcloud, execute o seguinte comando:
$ gcloud beta services identity create \ --service "secretmanager.googleapis.com" \ --project "PROJECT_ID"
Este comando devolve um nome de conta de serviço, com o seguinte formato:
service-PROJECT_NUMBER@gcp-sa-secretmanager.iam.gserviceaccount.com
-
Conceda a esta conta de serviço autorização para publicar nos tópicos do Pub/Sub configurados nos seus segredos.
-
Guarde o nome da conta de serviço como uma variável de ambiente através do seguinte comando:
# This is from the output of the command above $ export SM_SERVICE_ACCOUNT="service-...."
As variáveis de ambiente para o projeto do Secret Manager, o projeto do Pub/Sub e a conta de serviço do Secret Manager têm de ser definidas durante todo o procedimento.
Crie tópicos do Pub/Sub
Siga o início rápido do Pub/Sub para criar tópicos no seu projeto do Pub/Sub na Google Cloud consola. Em alternativa, crie tópicos na CLI do Google Cloud com o seguinte comando:
gcloud
Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:
- PUBSUB_PROJECT_ID: o ID do projeto no qual criar subscrições
- PUBSUB_TOPIC_NAME: o nome do tópico
Execute o seguinte comando:
Linux, macOS ou Cloud Shell
gcloud pubsub topics create "projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME"
Windows (PowerShell)
gcloud pubsub topics create "projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME"
Windows (cmd.exe)
gcloud pubsub topics create "projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME"
Repita este passo várias vezes se quiser criar vários tópicos do Pub/Sub no segredo.
Conceda à conta de serviço do Secret Manager autorização para publicar nos tópicos
Pode conceder autorizações à conta de serviço do Secret Manager através da Google Cloud consola ou da CLI do Google Cloud.
Para conceder a função de publicador do Pub/Sub (roles/pubsub.publisher
) no tópico do Pub/Sub, use o seguinte comando:
gcloud
Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:
- PUBSUB_TOPIC_NAME: o nome do tópico
Execute o seguinte comando:
Linux, macOS ou Cloud Shell
gcloud pubsub topics add-iam-policy-binding PUBSUB_TOPIC_NAME \ --member "serviceAccount:${SM_SERVICE_ACCOUNT}" \ --role "roles/pubsub.publisher"
Windows (PowerShell)
gcloud pubsub topics add-iam-policy-binding PUBSUB_TOPIC_NAME ` --member "serviceAccount:${SM_SERVICE_ACCOUNT}" ` --role "roles/pubsub.publisher"
Windows (cmd.exe)
gcloud pubsub topics add-iam-policy-binding PUBSUB_TOPIC_NAME ^ --member "serviceAccount:${SM_SERVICE_ACCOUNT}" ^ --role "roles/pubsub.publisher"
Crie subscrições do Pub/Sub
Para ver as mensagens publicadas num tópico, também tem de criar uma subscrição para o tópico. Siga o início rápido do Pub/Sub para criar subscrições no seu projeto do Pub/Sub na Google Cloud consola. Em alternativa, crie tópicos na CLI do Google Cloud com o seguinte comando:
gcloud
Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:
- PUBSUB_PROJECT_ID: o ID do projeto no qual criar subscrições
- PUBSUB_SUBSCRIPTION_NAME: o nome da subscrição
- PUBSUB_TOPIC_NAME: o nome do tópico
Execute o seguinte comando:
Linux, macOS ou Cloud Shell
gcloud pubsub subscriptions create projects/PUBSUB_PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_NAME \ --topic projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME
Windows (PowerShell)
gcloud pubsub subscriptions create projects/PUBSUB_PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_NAME ` --topic projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME
Windows (cmd.exe)
gcloud pubsub subscriptions create projects/PUBSUB_PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_NAME ^ --topic projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_NAME
Crie um segredo com tópicos configurados
Crie um segredo com uma lista de até 10 tópicos configurados. Todos os tópicos configurados num segredo recebem notificações de eventos quando o segredo ou uma das respetivas versões é alterado.
gcloud
Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:
- SECRET_ID: o ID do segredo ou o identificador totalmente qualificado do segredo
- PUBSUB_TOPIC_NAME: o nome do tópico
Execute o seguinte comando:
Linux, macOS ou Cloud Shell
gcloud secrets create SECRET_ID --topics PUBSUB_TOPIC_NAME
Windows (PowerShell)
gcloud secrets create SECRET_ID --topics PUBSUB_TOPIC_NAME
Windows (cmd.exe)
gcloud secrets create SECRET_ID --topics PUBSUB_TOPIC_NAME
REST
Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:
- PROJECT_ID: o Google Cloud ID do projeto
- SECRET_ID: o ID do segredo ou o identificador totalmente qualificado do segredo
- TOPIC_NAME: o nome do tópico
Método HTTP e URL:
POST https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets?secretId=SECRET_ID
Corpo JSON do pedido:
{ "replication":{ "automatic":{} }, "topics":{ "name": "TOPIC_NAME" } }
Para enviar o seu pedido, escolha uma destas opções:
curl
Guarde o corpo do pedido num ficheiro com o nome request.json
,
e execute o seguinte comando:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets?secretId=SECRET_ID"
PowerShell
Guarde o corpo do pedido num ficheiro com o nome request.json
,
e execute o seguinte comando:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets?secretId=SECRET_ID" | Select-Object -Expand Content
Deve receber uma resposta JSON semelhante à seguinte:
{ "name": "/projects/my-project/locations/me-central2/secrets/my-drz-secret", "createTime": "2024-03-25T08:24:13.153705Z", "etag": "\"161477e6071da9\"" }
Atualize tópicos secretos
Modifique os tópicos Pub/Sub configurados num segredo atualizando o segredo com os novos nomes de recursos de tópicos Pub/Sub. Com a CLI do Google Cloud, pode adicionar ou remover um ou mais tópicos de um segredo, bem como limpar todos os tópicos do segredo.
Adicione tópicos
Para adicionar um ou mais tópicos a um segredo, use o seguinte comando:
gcloud
Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:
- SECRET_ID: o ID do segredo ou o identificador totalmente qualificado do segredo
- PROJECT_ID: o Google Cloud ID do projeto que contém o segredo
- PUBSUB_PROJECT_ID: o ID do projeto no qual criar subscrições
- PUBSUB_TOPIC_1_NAME e PUBSUB_TOPIC_2_NAME: os nomes dos tópicos que está a adicionar ao segredo
Execute o seguinte comando:
Linux, macOS ou Cloud Shell
gcloud secrets update SECRET_ID \ --project PROJECT_ID \ --add-topics projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2_NAME
Windows (PowerShell)
gcloud secrets update SECRET_ID ` --project PROJECT_ID ` --add-topics projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2_NAME
Windows (cmd.exe)
gcloud secrets update SECRET_ID ^ --project PROJECT_ID ^ --add-topics projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2_NAME
Remova tópicos
Para remover um ou mais tópicos de um segredo, use o seguinte comando:
gcloud
Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:
- SECRET_ID: o ID do segredo ou o identificador totalmente qualificado do segredo
- PROJECT_ID: o projeto Google Cloud que contém o segredo
- PUBSUB_PROJECT_ID: o ID do projeto no qual criar subscrições
- PUBSUB_TOPIC_1_NAME e PUBSUB_TOPIC_2_NAME: os nomes dos tópicos que está a remover do segredo
Execute o seguinte comando:
Linux, macOS ou Cloud Shell
gcloud secrets update SECRET_ID \ --project PROJECT_ID \ --remove-topics projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2_NAME
Windows (PowerShell)
gcloud secrets update SECRET_ID ` --project PROJECT_ID ` --remove-topics projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2_NAME
Windows (cmd.exe)
gcloud secrets update SECRET_ID ^ --project PROJECT_ID ^ --remove-topics projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2_NAME
Limpar tópicos
Para remover todos os tópicos de um segredo, use o seguinte comando:
gcloud
Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:
- SECRET_ID: o ID do segredo ou o identificador totalmente qualificado do segredo
- PROJECT_ID: o projeto Google Cloud que contém o segredo
Execute o seguinte comando:
Linux, macOS ou Cloud Shell
gcloud secrets update SECRET_ID \ --project PROJECT_ID \ --clear-topics
Windows (PowerShell)
gcloud secrets update SECRET_ID ` --project PROJECT_ID ` --clear-topics
Windows (cmd.exe)
gcloud secrets update SECRET_ID ^ --project PROJECT_ID ^ --clear-topics
Consuma notificações de eventos com funções do Cloud Run
As notificações de eventos podem ser usadas para iniciar fluxos de trabalho através da criação de funções do Cloud Run para consumir as mensagens do Pub/Sub. Consulte a documentação das funções do Cloud Run
para mais informações. O seguinte exemplo de código destina-se a uma função do Cloud Run que imprime eventType
,
secretId
e metadados sempre que um evento é publicado no tópico.
C#
Para executar este código, primeiro configure um ambiente de programação em C# e instale o SDK em C# do Secret Manager. No Compute Engine ou no GKE, tem de autenticar-se com o âmbito cloud-platform.
using CloudNative.CloudEvents; using Google.Cloud.Functions.Framework; using Google.Events.Protobuf.Cloud.PubSub.V1; using System; using System.Threading; using System.Threading.Tasks; // Triggered from a message on a Cloud Pub/Sub topic. // The printed value will be visible in Cloud Logging // (https://cloud.google.com/functions/docs/monitoring/logging). namespace PubSubSample { public class Function : ICloudEventFunction<MessagePublishedData> { public Task HandleAsync(CloudEvent cloudEvent, MessagePublishedData data, CancellationToken cancellationToken) { string eventType = data.Message.Attributes["eventType"]; string secretId = data.Message.Attributes["secretId"]; string secretMetadata = data.Message.TextData; Console.WriteLine($"Received {eventType} for {secretId}. New metadata: {secretMetadata}."); return Task.CompletedTask; } } }
Go
Para executar este código, primeiro configure um ambiente de desenvolvimento Go e instale o SDK Go do Secret Manager. No Compute Engine ou no GKE, tem de autenticar-se com o âmbito cloud-platform.
Java
Para saber como instalar e usar a biblioteca de cliente do Secret Manager, consulte as bibliotecas de cliente do Secret Manager.
Para se autenticar no Secret Manager, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.
Node.js
Para executar este código, primeiro configure um ambiente de desenvolvimento do Node.js e instale o SDK do Node.js do Secret Manager. No Compute Engine ou no GKE, tem de autenticar-se com o âmbito cloud-platform.
/** * Triggered from a message on a Cloud Pub/Sub topic. * The printed value will be visible in Cloud Logging * (https://cloud.google.com/functions/docs/monitoring/logging). * * @param {!Object} event Event payload. * @param {!Object} context Metadata for the event. */ exports.smEventsFunction = (event, context) => { const eventType = event.attributes.eventType; const secretID = event.attributes.secretId; const secretMetadata = Buffer.from(event.data, 'base64').toString(); console.log(`Received ${eventType} for ${secretID}. New metadata: ${secretMetadata}.`); };
Python
Para executar este código, primeiro configure um ambiente de desenvolvimento Python e instale o SDK Python do Secret Manager. No Compute Engine ou no GKE, tem de autenticar-se com o âmbito cloud-platform.
Ruby
Para executar este código, primeiro configure um ambiente de desenvolvimento Ruby e instale o SDK Ruby do Secret Manager. No Compute Engine ou no GKE, tem de autenticar-se com o âmbito cloud-platform.
require "functions_framework" require "base64" # Triggered from a message on a Cloud Pub/Sub topic. # The printed value will be visible in Cloud Logging # (https://cloud.google.com/functions/docs/monitoring/logging). FunctionsFramework.cloud_event "sm_events_function" do |event| message = event.data["message"] event_type = message["attributes"]["eventType"] secret_id = message["attributes"]["secretId"] message_data = Base64.decode64 message["data"] FunctionsFramework.logger.info "Received %s for %s. New metadata: %s." % [event_type, secret_id, message_data] end
Para ver uma lista de todos os tipos de eventos, consulte Tipos de eventos.
Tópicos configurados incorretamente
Se forem adicionados tópicos do Pub/Sub a um segredo numa operação de criação ou atualização, mas o Secret Manager não conseguir publicar mensagens no tópico devido a uma configuração incorreta, a operação falha com uma mensagem de erro a indicar o motivo da falha na publicação. Isto pode acontecer, por exemplo, se o tópico não existir ou se a conta de serviço do Secret Manager não tiver autorização para publicar.
Se forem adicionados tópicos do Pub/Sub a um segredo e, posteriormente, o tópico for alterado para que o Secret Manager já não possa publicar mensagens (por exemplo, o tópico é eliminado ou as autorizações da conta de serviço do Secret Manager são removidas), o Secret Manager escreve registos no Secret Manager Secret
com uma mensagem a indicar o motivo da falha na publicação.
O que se segue?
- Saiba como analisar segredos com o Cloud Asset Inventory.