Configurar notificações em um secret

Esta página explica como configurar e usar notificações de eventos para seus segredos no Secret Manager.

Visão geral

O Secret Manager se integra ao Pub/Sub para fornecer notificações de eventos sobre mudanças em secrets e versões de secrets. É possível usar essas notificações para iniciar fluxos de trabalho, como reiniciar um aplicativo quando uma nova versão do secret é adicionada ou notificar engenheiros de segurança quando um secret é excluído. Para mais informações sobre como usar essas notificações para iniciar fluxos de trabalho, consulte a documentação do Pub/Sub.

Como as notificações de eventos funcionam no Gerenciador de secrets

Os secrets podem ser configurados com uma lista de até 10 tópicos do Pub/Sub. Sempre que uma operação for realizada que modifique o secret ou uma das versões dele, o Secret Manager vai publicar automaticamente uma mensagem em cada um dos tópicos do Pub/Sub nesse secret. 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 atributo que contêm metadados sobre o evento, além de um campo data com uma serialização JSON completa do recurso Secret ou SecretVersion que foi criado ou modificado. Esse JSON é uma string codificada em UTF-8 que representa o recurso Secret ou SecretVersion exatamente no formato especificado pela API pública do Secret Manager, codificado em JSON, conforme especificado no Mapeamento JSON de proto3.

Tipos de evento

Confira a seguir uma lista dos tipos de evento compatíveis com o Secret Manager.

Tipo de evento Descrição
SECRET_CREATE É enviado quando um novo secret é criado.
SECRET_UPDATE É enviado quando uma nova chave secreta é atualizada.
SECRET_DELETE É enviado quando uma chave secreta é excluída, seja por uma solicitação iniciada pelo usuário ou pela expiração da chave secreta.
SECRET_VERSION_ADD É enviado quando uma nova versão do secret é adicionada.
SECRET_VERSION_ENABLE É enviado quando uma versão do secret é ativada.
SECRET_VERSION_DISABLE É enviado quando uma versão do secret é desativada.
SECRET_VERSION_DESTROY É enviado quando uma versão do secret é destruída.
SECRET_VERSION_DESTROY_SCHEDULED É enviado quando uma duração de atraso de destruição é configurada no secret e o usuário tenta destruir uma versão do secret.
SECRET_ROTATE É enviado quando é hora de fazer a rotação de um secret. Consulte Criar programações de rotação para mais informações.
TOPIC_CONFIGURED

Esta é uma mensagem de teste sem corpo ou atributos diferentes de eventType: TOPIC_CONFIGURED. É enviado quando um secret é criado ou atualizado com uma lista de tópicos do Pub/Sub, mas não indica que a operação foi bem-sucedida.

Uma mensagem SECRET_CREATE ou SECRET_UPDATE é enviada imediatamente depois se a operação for bem-sucedida.

Sempre que os tópicos são atualizados em um secret, uma mensagem TOPIC_CONFIGURED é enviada para todos os tópicos no secret, incluindo aqueles que já estavam presentes.

Formato da notificação

As notificações enviadas ao tópico do Pub/Sub são compostas de duas partes:

  • Atributos: um conjunto de pares de chave-valor com a descrição do evento.

  • Payload: uma string de caracteres que contém os metadados do objeto alterado.

Atributos

Os atributos são pares de chave-valor contidos em notificações enviadas pelo Secret Manager para seu tópico do Pub/Sub. Todas as notificações, exceto as mensagens de teste TOPIC_CONFIGURED, sempre contêm o seguinte conjunto de pares de chave-valor, independentemente dos dados da notificação:

Nome do atributo Exemplo Descrição
eventType SECRET_CREATE Tipo de evento que acabou de ocorrer. Consulte Tipos de evento para conferir uma lista de valores possíveis.
dataFormat JSON_API_V1 O formato dos dados do objeto.
secretId projects/p/secrets/my-secret O nome completo do recurso do secret em que o evento ocorreu.
timestamp 2021-01-20T11:17:45.081104-08:00 Hora em que o evento ocorreu

Além disso, as notificações às vezes contêm o seguinte conjunto de pares de chave-valor:

Nome do atributo Exemplo Descrição
versionId projects/p/secrets/my-secret/versions/456

É o nome da versão do secret em que o evento ocorreu.

Isso está presente apenas nas notificações de eventos SECRET_VERSION_ADD, SECRET_VERSION_ENABLE, SECRET_VERSION_DISABLE e SECRET_VERSION_DESTROY.

deleteType REQUESTED Se a exclusão foi solicitada por um usuário (REQUESTED) ou devido à expiração do secret (EXPIRATION). Presente apenas em 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 secret ou uma versão do secret.

Para notificações SECRET_DELETE, os metadados contidos no campo de dados representam os metadados do objeto como eram antes da exclusão. Para todas as outras notificações, os metadados incluídos no campo de dados representam os metadados do objeto após a mudança ocorrer.

Limitações

As notificações de eventos estão disponíveis apenas na API Secret Manager v1 e na Google Cloud CLI.

Antes de começar

É possível armazenar todos os recursos no mesmo projeto ou armazenar segredos e tópicos do Pub/Sub em projetos separados.

  1. Para configurar o Secret Manager, faça o seguinte:

    • Crie ou use um projeto atual para armazenar os recursos do Secret Manager.

    • Se necessário, conclua as etapas mencionadas na página Ativar a API Secret Manager.

  2. Para configurar o Pub/Sub, faça o seguinte:

    • Crie ou use um projeto atual para armazenar seus recursos do Pub/Sub.

    • Se necessário, ative a API Pub/Sub.

  3. Autentique-se no Google Cloud usando o seguinte comando:

        $ gcloud auth login --update-adc

Criar uma identidade de agente de serviço

Para criar uma identidade de agente de serviço para cada projeto que exige segredos com notificações de eventos, siga estas etapas:

  1. Para criar uma identidade de serviço com a Google Cloud CLI, execute o seguinte comando:

          $ gcloud beta services identity create \
          --service "secretmanager.googleapis.com" \
          --project "PROJECT_ID"

    Esse comando retorna um nome de conta de serviço com o seguinte formato:

        service-PROJECT_ID@gcp-sa-secretmanager.iam.gserviceaccount.com

  2. Conceda permissão a essa conta de serviço para publicar nos tópicos do Pub/Sub configurados nos seus segredos.

  3. Salve o nome da conta de serviço como uma variável de ambiente usando o 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 precisam ser definidas durante todo o procedimento que você está seguindo.

Criar tópicos Pub/Sub

Siga o guia de início rápido do Pub/Sub para criar tópicos no seu projeto do Pub/Sub no console do Google Cloud. Como alternativa, crie tópicos na Google Cloud CLI usando o seguinte comando:

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

  • PROJECT_ID: o ID do projeto do Google Cloud que contém o segredo
  • PUBSUB_PROJECT_ID: o ID do projeto em que as assinaturas serão criadas
  • 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 essa ação várias vezes se quiser criar vários tópicos do Pub/Sub no secret.

Conceda permissão à conta de serviço do Secret Manager para publicar nos tópicos

É possível conceder permissões à conta de serviço do Secret Manager pelo console do Google Cloud ou pela Google Cloud CLI.

Para conceder o papel Publicador do Pub/Sub (roles/pubsub.publisher) no tópico do Pub/Sub, use o seguinte comando:

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

  • PUBSUB_TOPIC_NAME: o nome do tópico

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud pubsub topics create add-iam-policy-binding PUBSUB_TOPIC_NAME \
    --member "serviceAccount:${SM_SERVICE_ACCOUNT}" \
    --role "roles/pubsub.publisher"

Windows (PowerShell)

gcloud pubsub topics create add-iam-policy-binding PUBSUB_TOPIC_NAME `
    --member "serviceAccount:${SM_SERVICE_ACCOUNT}" `
    --role "roles/pubsub.publisher"

Windows (cmd.exe)

gcloud pubsub topics create add-iam-policy-binding PUBSUB_TOPIC_NAME ^
    --member "serviceAccount:${SM_SERVICE_ACCOUNT}" ^
    --role "roles/pubsub.publisher"

Criar assinaturas do Pub/Sub

Para visualizar as mensagens publicadas em um tópico, você também precisa criar uma assinatura dele. Siga o guia de início rápido do Pub/Sub para criar assinaturas no seu projeto do Pub/Sub no console do Google Cloud. Como alternativa, crie tópicos na Google Cloud CLI usando o seguinte comando:

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

  • PUBSUB_PROJECT_ID: o ID do projeto em que as assinaturas serão criadas
  • PUBSUB_SUBSCRIPTION_NAME: o nome da assinatura
  • 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

Criar um secret com tópicos configurados

Crie um secret com uma lista de até 10 tópicos configurados. Todos os tópicos configurados em um secret recebem notificações de eventos quando o secret ou uma das versões dele muda.

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

  • SECRET_ID: o ID do secret ou do identificador totalmente qualificado
  • PUBSUB_TOPIC_NAME: o nome do tópico
  • LOCATION: o local do Google Cloud do segredo

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud secrets create SECRET_ID --topics PUBSUB_TOPIC_NAME --location=LOCATION

Windows (PowerShell)

gcloud secrets create SECRET_ID --topics PUBSUB_TOPIC_NAME --location=LOCATION

Windows (cmd.exe)

gcloud secrets create SECRET_ID --topics PUBSUB_TOPIC_NAME --location=LOCATION

Atualizar tópicos secretos

Modifique os tópicos do Pub/Sub configurados em um secret atualizando-o com os novos nomes de recursos dos tópicos do Pub/Sub. Com a CLI do Google Cloud, é possível adicionar ou remover um ou mais tópicos de um secret, além de limpar todos os tópicos dele.

Adicionar tópicos

Para adicionar um ou mais tópicos a um secret, use o seguinte comando:

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

  • SECRET_ID: o ID do secret ou do identificador totalmente qualificado
  • LOCATION: o local do Google Cloud do segredo
  • PROJECT_ID: o ID do projeto do Google Cloud que contém o segredo
  • PUBSUB_PROJECT_ID: o ID do projeto em que as assinaturas serão criadas
  • PUBSUB_TOPIC_1_NAME e PUBSUB_TOPIC_2_NAME: os nomes dos tópicos que você está adicionando ao secret.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud secrets update SECRET_ID --location=LOCATION \
  --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 --location=LOCATION `
  --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 --location=LOCATION ^
  --project PROJECT_ID ^
  --add-topics projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2_NAME

Remover tópicos

Para remover um ou mais tópicos de um secret, use o seguinte comando:

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

  • SECRET_ID: o ID do secret ou do identificador totalmente qualificado
  • LOCATION: o local do Google Cloud do segredo
  • PROJECT_ID: o projeto do Google Cloud que contém o segredo
  • PUBSUB_PROJECT_ID: o ID do projeto em que as assinaturas serão criadas
  • PUBSUB_TOPIC_1_NAME e PUBSUB_TOPIC_2_NAME: os nomes dos tópicos que você está removendo do secret.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud secrets update SECRET_ID --location=LOCATION \
  --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 --location=LOCATION `
  --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 --location=LOCATION ^
  --project PROJECT_ID ^
  --remove-topics "projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_1_NAME,projects/PUBSUB_PROJECT_ID/topics/PUBSUB_TOPIC_2__NAME

Limpar temas

Para remover todos os tópicos de um secret, use o seguinte comando:

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

  • SECRET_ID: o ID do secret ou do identificador totalmente qualificado
  • PROJECT_ID: o projeto do Google Cloud que contém o segredo
  • LOCATION: o local do Google Cloud do segredo

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud secrets update SECRET_ID --location=LOCATION \
  --project PROJECT_ID \
  --clear-topics

Windows (PowerShell)

gcloud secrets update SECRET_ID --location=LOCATION `
  --project PROJECT_ID `
  --clear-topics

Windows (cmd.exe)

gcloud secrets update SECRET_ID --location=LOCATION ^
  --project PROJECT_ID ^
  --clear-topics

Consumir notificações de eventos com funções do Cloud Run

As notificações de eventos podem ser usadas para iniciar fluxos de trabalho, criando 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 exemplo de código a seguir é para uma função do Cloud Run que imprime eventType, secretId e metadados sempre que um evento é publicado no tópico.

C#

Para executar esse código, primeiro configure um ambiente de desenvolvimento em C# e instale o SDK do C# do Secret Manager. No Compute Engine ou no GKE, você precisa fazer a autenticação com o escopo do 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 esse código, primeiro configure um ambiente de desenvolvimento do Go e instale o SDK do Go do Secret Manager. No Compute Engine ou no GKE, você precisa fazer a autenticação com o escopo do cloud-platform. 

import (
	"context"
	"fmt"
)

// PubSubMessage is the payload of a Pub/Sub event.
type PubSubMessage struct {
	Attributes PubSubAttributes `json:"attributes"`
	Data       []byte           `json:"data"`
}

// PubSubAttributes are attributes from the Pub/Sub event.
type PubSubAttributes struct {
	SecretId  string `json:"secretId"`
	EventType string `json:"eventType"`
}

// ConsumeEventNotification demonstrates how to consume and process the Pub/Sub
// notification from Secret Manager.
func ConsumeEventNotification(ctx context.Context, m PubSubMessage) (string, error) {
	// The printed value will be visible in Cloud Logging:
	//
	//     https://cloud.google.com/functions/docs/monitoring/logging
	//
	eventType := m.Attributes.EventType
	secretID := m.Attributes.SecretId
	data := m.Data

	return fmt.Sprintf("Received %s for %s. New metadata: %q.",
		eventType, secretID, data), nil
}

Java

Para saber como instalar e usar a biblioteca de cliente do Secret Manager, consulte Bibliotecas de cliente do Secret Manager.

Para autenticar no Secret Manager, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 


import java.util.Base64;
import java.util.Map;
import java.util.logging.Logger;
import lombok.Data;

// Demonstrates how to consume and process a Pub/Sub notification from Secret Manager. Triggered
// by a message on a Cloud Pub/Sub topic.
// Ideally the class should implement a background function that accepts a Pub/Sub message.
// public class ConsumeEventNotification implements BackgroundFunction<PubSubMessage> { }
public class ConsumeEventNotification {

  // You can configure the logs to print the message in Cloud Logging.
  private static final Logger logger = Logger.getLogger(ConsumeEventNotification.class.getName());

  // Accepts a message from a Pub/Sub topic and writes it to logger.
  public static String accept(PubSubMessage message) {
    String eventType = message.attributes.get("eventType");
    String secretId = message.attributes.get("secretId");
    String data = new String(Base64.getDecoder().decode(message.data));
    String log = String.format("Received %s for %s. New metadata: %s", eventType, secretId, data);
    logger.info(log);
    return log;
  }

  // Event payload. Mock of the actual Pub/Sub message.
  @Data
  public static class PubSubMessage {

    byte[] data;
    Map<String, String> attributes;
    String messageId;
    String publishTime;
    String orderingKey;
  }
}

Node.js

Para executar esse 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, você precisa fazer a autenticação com o escopo do 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 esse código, primeiro configure um ambiente de desenvolvimento do Python e instale o SDK do Python do Secret Manager. No Compute Engine ou no GKE, você precisa fazer a autenticação com o escopo do cloud-platform. 

import base64


def consume_event_notification(event: dict, unused_context: None) -> str:
    """
    consume_event_notification demonstrates how to consume and process a
    Pub/Sub notification from Secret Manager.
    Args:
          event (dict): Event payload.
          unused_context (google.cloud.functions.Context): Metadata for the event.
    """
    event_type = event["attributes"]["eventType"]
    secret_id = event["attributes"]["secretId"]
    secret_metadata = base64.b64decode(event["data"]).decode("utf-8")
    event_notification = (
        f"Received {event_type} for {secret_id}. New metadata: {secret_metadata}"
    )
    print(event_notification)
    return event_notification

Ruby

Para executar esse código, primeiro configure um ambiente de desenvolvimento em Ruby e instale o SDK do Ruby do Secret Manager. No Compute Engine ou no GKE, você precisa fazer a autenticação com o escopo do 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 conferir uma lista de todos os tipos de evento, consulte Tipos de evento.

Tópicos configurados incorretamente

Se os tópicos do Pub/Sub forem adicionados a um secret em uma operação Create ou Update, mas o Secret Manager não puder publicar mensagens no tópico devido a uma configuração incorreta, a operação vai falhar com uma mensagem de erro indicando o motivo da falha na publicação. Isso pode acontecer, por exemplo, se o tópico não existir ou se a conta de serviço do Secret Manager não tiver permissão para publicar.

Se os tópicos do Pub/Sub forem adicionados a um secret e depois forem alterados para que o Secret Manager não possa mais publicar mensagens (por exemplo, se o tópico for excluído ou as permissões da conta de serviço do Secret Manager forem removidas), o Secret Manager vai gravar registros no Secret do Secret Manager com uma mensagem indicando por que a publicação falhou.

A seguir