Publicar e receber eventos criando um barramento e uma inscrição

Neste guia de início rápido, mostramos como publicar e receber mensagens de evento criando um bus avançado do Eventarc e uma inscrição no seu projeto do Google Cloud.

Uma linha permite centralizar o fluxo de mensagens no sistema e atua como um roteador. Ele recebe eventos de uma origem de mensagem ou publicados por um provedor e os avalia de acordo com uma inscrição.

Um registro identifica uma assinatura de um barramento específico e define os critérios de correspondência para as mensagens, fazendo com que elas sejam roteadas de acordo com um ou mais destinos.

Neste guia de início rápido, você fará as seguintes tarefas:

  1. Crie uma sub-rede e ative o Acesso privado do Google.

  2. Criar um anexo de rede.

  3. Implantar um serviço de receptor de eventos no Cloud Run

  4. Crie um barramento do Eventarc Advanced.

  5. Crie uma inscrição no Eventarc Advanced.

  6. Publique uma mensagem de evento no barramento.

  7. Confira os dados do evento nos registros do Cloud Run.

Conclua este guia de início rápido usando a Google Cloud CLI.

Antes de começar

As restrições de segurança definidas pela sua organização podem impedir que você conclua as etapas a seguir. Para informações sobre solução de problemas, consulte Desenvolver aplicativos em um ambiente restrito do Google Cloud.

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. Install the Google Cloud CLI.

  3. To initialize the gcloud CLI, run the following command: 

    gcloud init

  4. Create or select a Google Cloud project.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  5. Make sure that billing is enabled for your Google Cloud project.

  6. Enable the Artifact Registry, Cloud Build, Cloud Run, Compute Engine, and Eventarc APIs: 

    gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com compute.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com
  7. Install the Google Cloud CLI.

  8. To initialize the gcloud CLI, run the following command: 

    gcloud init

  9. Create or select a Google Cloud project.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  10. Make sure that billing is enabled for your Google Cloud project.

  11. Enable the Artifact Registry, Cloud Build, Cloud Run, Compute Engine, and Eventarc APIs: 

    gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com compute.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com

  12. Atualize os componentes gcloud: 
    gcloud components update

  13. Faça login usando sua conta: 
    gcloud auth login

  14. Defina a variável de configuração usada neste guia de início rápido: 
    REGION=REGION

    Substitua REGION por um local compatível com o ônibus.

  15. Se você for o criador do projeto, receberá o papel de proprietário básico (roles/owner). Por padrão, esse papel do gerenciamento de identidade e acesso (IAM) inclui as permissões necessárias para acesso total à maioria dos recursos do Google Cloud, e você pode pular esta etapa.

    Se você não é o criador do projeto, as permissões necessárias precisam ser concedidas ao principal apropriado. Por exemplo, um principal pode ser uma Conta do Google (para usuários finais) ou uma conta de serviço (para aplicativos e cargas de trabalho de computação).

    Observe que, por padrão, as permissões do Cloud Build incluem permissões para upload e download de artefatos do Artifact Registry.

    Permissões necessárias

    Para conseguir as permissões necessárias a fim de concluir o guia de início rápido, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

    Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

    Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

  16. Conceda os seguintes papéis no projeto à conta de serviço padrão do Compute Engine. Estes papéis são necessários ao criar e implantar a imagem do contêiner: 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/artifactregistry.writer
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/logging.logWriter
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/storage.objectUser

    Substitua PROJECT_NUMBER pelo número do projeto do Google Cloud. Encontre o número do projeto na página Boas-vindas do console do Google Cloud ou executando o seguinte comando:

    gcloud projects describe PROJECT_ID --format='value(projectNumber)'

  17. Por padrão, somente proprietários do projeto, editores do projeto, administradores do Cloud Run e invocadores do Cloud Run podem chamar os serviços do Cloud Run. Para configurar a autenticação, conceda o papel de invocador do Cloud Run (run.invoker) no seu projeto do Google Cloud a uma conta de serviço:
    1. Crie uma conta de serviço. Para fins de teste, você vai anexar essa conta de serviço a um pipeline do Eventarc Advanced para representar a identidade do pipeline. 
      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
       Substitua SERVICE_ACCOUNT_NAME por um nome para sua conta de serviço.
    2. Conceda o papel do IAM roles/run.invoker à conta de serviço: 
      gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
    --role=roles/run.invoker

    É possível configurar quem pode acessar o serviço do Cloud Run das seguintes maneiras:

    • Conceda permissão para selecionar contas de serviço ou grupos para permitir o acesso ao serviço. Todas as solicitações precisam ter um cabeçalho de autorização HTTP com um token do OpenID Connect assinado pelo Google para uma das contas de serviço autorizadas. É assim que o acesso é configurado neste guia de início rápido.
    • Conceda permissão para allUsers permitir acesso não autenticado.

    Para mais informações, consulte Controle de acesso do Cloud Run.

Criar uma sub-rede e ativar o Acesso privado do Google

A menos que você crie uma política organizacional que proíba isso, os novos projetos do Google Cloud começam com uma rede Virtual Private Cloud (VPC) padrão (uma rede VPC de modo automático) que tenha uma sub-rede em cada região. As sub-redes têm intervalos de endereços IP associados a elas.

Como você está encaminhando mensagens para um destino do Cloud Run usando um endereço DNS, é necessário ativar o Acesso privado do Google na sub-rede usada no anexo de rede. Caso contrário, não será possível resolver o endereço DNS. Para mais informações sobre redes privadas e o Cloud Run, consulte Receber solicitações de redes VPC.

Crie uma sub-rede na rede padrão do projeto e use a flag --enable-private-ip-google-access para ativar o Acesso privado do Google:

gcloud compute networks subnets create SUBNET_NAME \
    --network=default \
    --range=10.8.0.0/24 \
    --region=$REGION \
    --enable-private-ip-google-access

Substitua SUBNET_NAME pelo nome da sub-rede, por exemplo, my-subnet.

Os intervalos de IP da sub-rede precisam ser exclusivos e não podem se sobrepor em uma rede VPC ou em uma rede VPC com peering. Para mais informações sobre tipos e intervalos de sub-rede válidos, consulte Sub-redes.

Criar um anexo de rede

Um anexo de rede é um recurso que permite que uma rede VPC do produtor inicie conexões com uma rede VPC do consumidor. Para publicar eventos, o Eventarc Advanced usa o anexo de rede para estabelecer uma conexão com o endpoint hospedado em uma rede VPC.

Crie um anexo de rede na mesma rede e região que contém o endpoint de destino do evento e que aceita automaticamente conexões de qualquer interface do Private Service Connect que se refira ao anexo de rede:

gcloud compute network-attachments create ATTACHMENT_NAME \
   --region=$REGION \
   --connection-preference=ACCEPT_AUTOMATIC \
   --subnets=SUBNET_NAME

Substitua ATTACHMENT_NAME pelo nome do anexo de rede, por exemplo, my-network-attachment.

Criar um repositório padrão do Artifact Registry

Crie um repositório padrão do Artifact Registry para armazenar a imagem do contêiner.

gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=$REGION

Substitua REPOSITORY por um nome exclusivo para o repositório do Artifact Registry, por exemplo, my-repo.

Implantar um serviço de receptor de eventos no Cloud Run

Implante um serviço do Cloud Run que registre o conteúdo de um evento. Esse serviço só é acessível em redes VPC do mesmo projeto, e o URL do serviço não é acessível diretamente porque ele só permite invocações autenticadas.

  1. Clone o repositório do GitHub:

    git clone https://github.com/GoogleCloudPlatform/eventarc-samples.git

  2. Mude para o diretório que contém o código de amostra do Cloud Run:

    cd eventarc-samples/eventarc-advanced-quickstart/

  3. Crie uma imagem de contêiner do Docker e envie a imagem para o repositório:

    gcloud builds submit \
    --tag $REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/log-events:v1

  4. Implante a imagem do contêiner no Cloud Run:

    gcloud run deploy SERVICE_NAME \
    --image $REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/log-events:v1 \
    --platform managed \
    --ingress internal \
    --no-allow-unauthenticated \
    --region=$REGION

    Substitua SERVICE_NAME pelo nome do serviço, por exemplo, my-service.

Quando o URL do serviço do Cloud Run for exibido, a implantação estará concluída. Anote esse URL para usá-lo em uma etapa posterior.

Criar um barramento do Eventarc Advanced

Crie um barramento do Eventarc Advanced no seu projeto usando o comando gcloud beta eventarc message-buses create:

gcloud beta eventarc message-buses create BUS_NAME \
    --location=$REGION

Substitua BUS_NAME pelo ID ou identificador totalmente qualificado do bus, por exemplo, my-bus.

Para mais informações, consulte Criar um bus para encaminhar mensagens.

Criar uma inscrição do Eventarc Advanced

Uma inscrição determina quais mensagens são roteadas para um destino. Ele também especifica o pipeline pelo qual as mensagens precisam ser roteadas. O pipeline é usado para configurar um destino para as mensagens de evento.

Para mais informações, consulte Criar uma inscrição para receber eventos.

Ao usar a CLI gcloud, primeiro crie um pipeline e, em seguida, uma inscrição.

  1. Crie um pipeline usando o comando gcloud beta eventarc pipelines create:

    gcloud beta eventarc pipelines create PIPELINE_NAME \
    --destinations=http_endpoint_uri='CLOUD_RUN_SERVICE_URL',network_attachment=ATTACHMENT_NAME,google_oidc_authentication_service_account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --location=$REGION

    Substitua:

    • PIPELINE_NAME: o ID do pipeline ou um nome totalmente qualificado.
    • CLOUD_RUN_SERVICE_URL: o URL totalmente qualificado do seu serviço do Cloud Run, por exemplo, https://SERVICE_NAME-abcdef-uc.a.run.app. Esse é o destino das suas mensagens de evento.

    A chave google_oidc_authentication_service_account especifica um e-mail da conta de serviço usado para gerar um token do OIDC.

  2. Crie uma inscrição usando o comando gcloud beta eventarc enrollments create:

    gcloud beta eventarc enrollments create ENROLLMENT_NAME \
    --cel-match=MATCH_EXPRESSION \
    --destination-pipeline=PIPELINE_NAME \
    --message-bus=BUS_NAME \
    --message-bus-project=PROJECT_ID \
    --location=$REGION

    Substitua:

    • ENROLLMENT_NAME: o ID da inscrição ou um nome totalmente qualificado.
    • MATCH_EXPRESSION: a expressão correspondente para essa inscrição usando CEL, por exemplo, "message.type == 'hello-world-type'".

Publicar uma mensagem de evento no barramento

Para publicar uma mensagem diretamente no bus, use o comando gcloud beta eventarc message-buses publish ou envie uma solicitação para a API REST Eventarc Publishing. Para mais informações, consulte Publicar eventos diretamente.

A mensagem precisa estar em um formato CloudEvents, que é uma especificação para descrever dados de eventos de uma maneira comum. O elemento data é o payload do seu evento. Qualquer JSON bem formado pode ser colocado nesse campo. Para mais informações sobre atributos de contexto do CloudEvents, consulte Formato de evento.

Confira a seguir exemplos de publicação direta de um evento em um barramento do Eventarc Advanced:

Exemplo 1

É possível publicar um evento em um barramento usando a CLI gcloud e uma --event-data e outras flags de atributo de evento:

gcloud beta eventarc message-buses publish BUS_NAME \
    --event-data='{"key": "hello-world-data"}' \
    --event-id=hello-world-id-1234 \
    --event-source=hello-world-source \
    --event-type=hello-world-type \
    --event-attributes="datacontenttype=application/json" \
    --location=$REGION

Exemplo 2

É possível publicar um evento em um barramento como uma mensagem JSON usando a CLI gcloud e uma flag --json-message:

gcloud beta eventarc message-buses publish BUS_NAME \
    --location=$REGION \
    --json-message='{"id": "hello-world-id-1234", "type":
 "hello-world-type", "source":
 "hello-world-source", "specversion": "1.0", "data":
 {"key": "hello-world-data"}}'

Depois de publicar um evento, você vai receber uma mensagem "Evento publicado com sucesso".

Conferir os dados do evento nos registros do Cloud Run

Depois de publicar um evento no barramento do Eventarc Advanced, é possível verificar os registros do serviço do Cloud Run para conferir se o evento foi recebido conforme o esperado.

  1. Filtre as entradas de registro e retorne a saída usando o comando gcloud logging read:

    gcloud logging read 'textPayload: "hello-world-data"'

  2. Procure uma entrada de registro semelhante a esta:

    insertId: 670808e70002b5c6477709ae
labels:
instanceId: 007989f2a10a4a33c21024f2c8e06a9de65d9b4fdc2ee27697a50379b3fab2f975b9233dc357d50b06270829b9b479d5a1ee54a10fa2cb2d98c5f77a0895e2be0f9e6e4b20
logName: projects/PROJECT_ID/logs/run.googleapis.com%2Fstderr
receiveTimestamp: '2024-10-10T17:03:35.424659450Z'
resource:
labels:
...
type: cloud_run_revision
textPayload: "[2024-10-21 15:33:19,581] INFO in server: Body: b'{\"value\":\"hello-world-data\"\
  }'"
timestamp: '2024-10-10T17:03:35.177606Z'

Você criou um barramento e uma inscrição do Eventarc Advanced, publicou uma mensagem de evento no barramento e verificou o resultado esperado nos registros do serviço de receptor de eventos.

Limpar

Ao concluir as tarefas descritas neste guia de início rápido, é possível evitar o faturamento contínuo excluindo os recursos criados:

  1. Excluir uma sub-rede VPC.

  2. Exclua um anexo de rede VPC.

  3. Excluir um repositório do Artifact Registry.

  4. Exclua um serviço do Cloud Run.

  5. Exclua os recursos do Eventarc Advanced:

    1. Excluir uma inscrição.

    2. Excluir um pipeline.

    3. Excluir um barramento.

Se preferir, exclua o projeto do Google Cloud para evitar cobranças. A exclusão do projeto do Google Cloud interrompe o faturamento de todos os recursos usados no projeto.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

A seguir