Receber eventos usando mensagens do Pub/Sub (CLI gcloud)

Receber eventos usando mensagens do Pub/Sub (CLI gcloud)

Padrão

Visualização

Este produto está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço Gerais" dos Termos Específicos do Serviço. Os produtos 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.

Neste guia de início rápido, mostramos como configurar um serviço do Google Kubernetes Engine (GKE) como destino para receber eventos de tópicos do Pub/Sub usando o Eventarc.

Observação: o suporte para GKE como destino do Eventarc inclui os endpoints públicos de serviços públicos e particulares em execução em um cluster do GKE.

.

Neste guia de início rápido, você vai:

1. Conclua as tarefas preparatórias, como ativar APIs e configurar uma conta de serviço.
2. Criar um cluster do GKE.
3. Inicializar destinos do GKE no Eventarc.
4. Implantar um serviço do GKE que recebe eventos.
5. Criar um gatilho do Eventarc que conecte um tópico do Pub/Sub ao serviço do GKE.
6. Gerar e visualizar um evento do Pub/Sub.

Antes de começar

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.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the 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. Install the Google Cloud CLI.

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

   gcloud init

8. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the 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.

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

10. Atualize os componentes da CLI do Google Cloud:

    gcloud components update

11. Ative as APIs Eventarc, Resource Manager e Google Kubernetes Engine:

    gcloud services enable eventarc.googleapis.com \
       cloudresourcemanager.googleapis.com \
       container.googleapis.com

12. Defina as variáveis de configuração usadas neste guia de início rápido:

    PROJECT_ID=$(gcloud config get-value project)
    CLUSTER_NAME=events-cluster
    SERVICE_NAME=hello-gke
    LOCATION=us-central1

13. 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). Para mais informações, consulte a página Papéis e permissões do destino do evento.

    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:

    • Administrador do Eventarc (roles/eventarc.admin)
    • Administrador do Kubernetes Engine (roles/container.admin)
    • Acessador de exibição de registros (roles/logging.viewAccessor)
    • Administrador de projetos do IAM (roles/resourcemanager.projectIamAdmin)
    • Publicador do Pub/Sub (roles/pubsub.publisher)
    • Administrador da conta de serviço (roles/iam.serviceAccountAdmin)
    • Usuário da conta de serviço (roles/iam.serviceAccountUser)
    • Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin)

    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.

14. Anote as propriedades da conta de serviço padrão do Compute Engine, porque você vai anexá-la a um gatilho do Eventarc para representar a identidade do acionador para fins de teste. Essa conta de serviço é criada automaticamente depois de ativar ou usar um serviço do Google Cloud que usa o Compute Engine e com o seguinte formato de e-mail:

    [e-mail]

    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)'

    Para ambientes de produção, é altamente recomendável criar uma nova conta de serviço, conceder a ela um ou mais papéis do IAM que contenham as permissões mínimas necessárias, bem como seguir o princípio de privilégio mínimo.

    Observação:

    O iam.automaticIamGrantsForDefaultServiceAccounts restrição de política da organização impede que o papel de editor seja concedido automaticamente a contas de serviço padrão. Se você criou a organização após 3 de maio de 2024, essa restrição será aplicada por padrão.

    É altamente recomendável aplicar essa restrição para desativar a concessão automática de papéis. Se você desativar a concessão automática de papéis, precisará decidir quais papéis conceder às contas de serviço padrão e, em seguida, conceder esses papéis por conta própria.

    Se a conta de serviço padrão já tiver o papel de Editor, recomendamos que você o substitua por papéis menos permissivos. Para modificar com segurança os papéis da conta de serviço, use o Simulador de política para ver o impacto da alteração e, em seguida, conceda e revogue os papéis apropriados.

15. Conceda o papel de Assinante do Pub/Sub (roles/pubsub.subscriber) no projeto à conta de serviço padrão do Compute Engine para que o gatilho do Eventarc possa extrair eventos do Pub/Sub.

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=serviceAccount:[e-mail] \
        --role=roles/pubsub.subscriber

16. Se você ativou o agente de serviço do Cloud Pub/Sub até 8 de abril de 2021, para oferecer compatibilidade com solicitações push autenticadas do Pub/Sub, conceda o papel de Criador de token da conta de serviço (roles/iam.serviceAccountTokenCreator) ao agente de serviço. Caso contrário, esse papel é concedido por padrão:

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=serviceAccount:[e-mail] \
        --role=roles/iam.serviceAccountTokenCreator

Criar um cluster do GKE

Um cluster do GKE consiste em pelo menos uma máquina de plano de controle de clusters e várias máquinas de worker chamadas de nós. Os nós são instâncias de máquina virtual (VM) do Compute Engine que executam os processos do Kubernetes necessários para integrá-los ao cluster. Você implanta os aplicativos nos clusters para que eles sejam executados nos nós.

Crie um cluster do Autopilot chamado events-cluster:

gcloud container clusters create-auto $CLUSTER_NAME \
    --region $LOCATION

A criação do cluster pode levar vários minutos para ser concluída. Depois que o cluster é criado, a saída fica mais ou menos assim:

Creating cluster events-cluster...done.
Created [https://container.googleapis.com/v1/projects/MY_PROJECT/zones/us-central1/clusters/events-cluster].
[...]
STATUS: RUNNING

Isso cria um cluster do GKE chamado events-cluster em um projeto com um ID de projeto do Google Cloud de MY_PROJECT.

Ativar destinos do GKE

Para cada gatilho que segmenta um serviço do GKE, o Eventarc cria um componente de encaminhamento de eventos que extrai eventos do Pub/Sub e o encaminha ao destino. Para criar o componente e gerenciar recursos no cluster do GKE, conceda permissões ao agente de serviço do Eventarc:

1. Ative os destinos do GKE para o Eventarc:

   gcloud eventarc gke-destinations init

2. No prompt para vincular os papéis necessários, digite y.

   Os papéis a seguir estão vinculados à conta de serviço:

   • compute.viewer
   • container.developer
   • iam.serviceAccountAdmin

Criar um destino de serviço do GKE

Implante um serviço do GKE que receberá e registrará eventos usando uma imagem pré-criada, us-docker.pkg.dev/cloudrun/container/hello:

1. O Kubernetes usa um arquivo YAML chamado kubeconfig para armazenar informações de autenticação de cluster para kubectl. Atualize o arquivo kubeconfig com credenciais e informações de endpoint para apontar kubectl no cluster do GKE:

   gcloud container clusters get-credentials $CLUSTER_NAME \
       --region $LOCATION
   

2. Crie uma implantação do Kubernetes:

   kubectl create deployment $SERVICE_NAME \
       --image=us-docker.pkg.dev/cloudrun/container/hello
   

3. Exponha-a como um serviço do Kubernetes:

   kubectl expose deployment $SERVICE_NAME \
       --type ClusterIP \
       --port 80 \
       --target-port 8080
   

Criar um gatilho do Eventarc

Quando uma mensagem é publicada no tópico do Pub/Sub, o gatilho do Eventarc envia mensagens para o serviço hello-gke do GKE.

1. Crie um gatilho do GKE para detectar mensagens do Pub/Sub:

   Novo tópico pub/sub

   gcloud eventarc triggers create gke-trigger-pubsub \
       --location="$LOCATION" \
       --destination-gke-cluster=$CLUSTER_NAME \
       --destination-gke-location=$LOCATION \
       --destination-gke-namespace=default \
       --destination-gke-service=$SERVICE_NAME \
       --destination-gke-path=/ \
       --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
       --service-account="[e-mail]"
   

   Isso cria um novo tópico do Pub/Sub e um gatilho para ele chamado gke-trigger-pubsub.

   Tópico do Pub/Sub atual

   gcloud eventarc triggers create gke-trigger-pubsub \
       --location="$LOCATION" \
       --destination-gke-cluster=$CLUSTER_NAME \
       --destination-gke-location=$LOCATION \
       --destination-gke-namespace=default \
       --destination-gke-service=$SERVICE_NAME \
       --destination-gke-path=/ \
       --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
       --service-account="[e-mail]" \
       --transport-topic=projects/PROJECT_ID/topics/TOPIC_ID
   

   Substitua:

   • PROJECT_ID: seu ID do projeto no Google Cloud.
   • TOPIC_ID: o ID do tópico do Pub/Sub. Isso cria um gatilho chamado gke-trigger-pubsub para o tópico atual do Pub/Sub.

2. Confirme se o gatilho foi criado com sucesso. Pode levar até dois minutos para que o gatilho esteja totalmente funcional.

    gcloud eventarc triggers list
   

   A saída será semelhante a esta:

   NAME: gke-trigger-pubsub
   TYPE: google.cloud.pubsub.topic.v1.messagePublished
   DESTINATION: GKE: hello-gke
   ACTIVE: Yes
   LOCATION: us-central1
   

Gerar e visualizar um evento

É possível gerar um evento para acionar o serviço do GKE publicando uma mensagem no tópico do Pub/Sub. Em seguida, visualize a mensagem nos registros do pod.

1. Encontre e defina o tópico do Pub/Sub como uma variável de ambiente:

   TOPIC=$(gcloud eventarc triggers describe gke-trigger-pubsub \
       --location=us-central1 \
       --format='value(transport.pubsub.topic)')

2. Envie uma mensagem para o tópico do Pub/Sub a fim de gerar um evento:

   gcloud pubsub topics publish $TOPIC --message="Hello World"

   O serviço do GKE registra a mensagem do evento.

3. Para visualizar a mensagem de evento:

   1. Encontre o ID do pod:

      kubectl get pods

      A saída será semelhante a esta:

      NAME                                         READY   STATUS             RESTARTS   AGE
      hello-gke-645964f578-2mjjt                   1/1     Running            0          35s

      Copie o NAME do pod para usar na próxima etapa.

   2. Verifique os registros do pod:

      kubectl logs NAME

      Substitua NAME pelo nome do pod que você copiou.

   3. Procure uma entrada de registro semelhante a esta:

      2022/02/24 22:23:49 Hello from Cloud Run! The container started successfully and is listening for HTTP requests on $PORT
      {"severity":"INFO","eventType":"google.cloud.pubsub.topic.v1.messagePublished","message":"Received event of type google.cloud.pubsub.topic.v1.messagePublished. Event data: Hello World"[...]}
      

Limpar

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados.

Você pode:

1. Excluir o gatilho do Eventarc.

   Isso também exclui o tópico associado do Pub/Sub.

2. Excluir o cluster do GKE.

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.

Cuidado: excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto existente para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos no projeto.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um código do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Se você planeja ver vários tutoriais e guias de início rápido, a reutilização de projetos pode evitar que você exceda os limites da cota do projeto.

A seguir

Receber eventos usando os Registros de auditoria do Cloud (Google Cloud CLI)