Receba eventos Pub/Sub através de um serviço do Cloud Run autenticado

Padrão

---

Este tutorial mostra como implementar uma aplicação em contentor através de um serviço do Cloud Run autenticado que recebe eventos através do Pub/Sub. O Pub/Sub é um serviço de mensagens em tempo real totalmente gerido que lhe permite enviar e receber mensagens entre aplicações independentes.

Nota: todos os serviços do Cloud Run são implementados de forma privada por predefinição, o que significa que não é possível aceder aos mesmos sem fornecer credenciais de autenticação no pedido. Para projetos com políticas organizacionais de partilha restrita por domínio, use um serviço de destino do Cloud Run autenticado em vez de um que permita o acesso público (não autenticado).

Objetivos

Neste tutorial, vai:

1. Implemente um serviço de receção de eventos no Cloud Run que exija invocações autenticadas.

2. Crie um acionador do Eventarc que ligue um tópico do Pub/Sub ao serviço do Cloud Run.

3. Publique uma mensagem no tópico Pub/Sub para gerar um evento.

4. Veja o evento nos registos do Cloud Run.

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

• Artifact Registry
• Cloud Build
• Cloud Run
• Eventarc
• Pub/Sub

Para gerar uma estimativa de custos com base na sua utilização projetada, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação gratuita.

Antes de começar

As restrições de segurança definidas pela sua organização podem impedir a conclusão dos seguintes passos. Para informações de resolução de problemas, consulte o artigo Desenvolva aplicações num ambiente Google Cloud restrito.

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.

Install the Google Cloud CLI.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

Verify that billing is enabled for your Google Cloud project.

Install the Google Cloud CLI.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

Verify that billing is enabled for your Google Cloud project.

1. Atualize os componentes da CLI do Google Cloud:

   gcloud components update

2. Inicie sessão com a sua conta:

   gcloud auth login

3. Ative as APIs:

   gcloud services enable artifactregistry.googleapis.com \
       cloudbuild.googleapis.com \
       eventarc.googleapis.com \
       pubsub.googleapis.com \
       run.googleapis.com

4. Defina as variáveis de configuração usadas neste tutorial:

   export REGION=us-central1
   gcloud config set run/region ${REGION}
   gcloud config set run/platform managed
   gcloud config set eventarc/location ${REGION}
   export SERVICE_NAME=trigger-pubsub

5. Se for o criador do projeto, é-lhe atribuída a função básica de proprietário (roles/owner). Por predefinição, esta função do Identity and Access Management (IAM) inclui as autorizações necessárias para acesso total à maioria dos Google Cloud recursos e pode ignorar este passo.

   Se não for o criador do projeto, as autorizações necessárias têm de ser concedidas no projeto ao principal adequado. Por exemplo, um principal pode ser uma Conta Google (para utilizadores finais) ou uma conta de serviço (para aplicações e cargas de trabalho de computação). Para mais informações, consulte a página Funções e autorizações do destino de eventos.

   Tenha em atenção que, por predefinição, as autorizações do Cloud Build incluem autorizações para carregar e transferir artefactos do Artifact Registry.

   Autorizações necessárias

   Para receber as autorizações de que precisa para concluir este tutorial, peça ao seu administrador que lhe conceda as seguintes funções da IAM no seu projeto:

   • Editor do Cloud Build (roles/cloudbuild.builds.editor)
   • Administrador do Cloud Run (roles/run.admin)
   • Eventarc Admin (roles/eventarc.admin)
   • Aceder à vista de registos (roles/logging.viewAccessor)
   • Project IAM Admin (roles/resourcemanager.projectIamAdmin)
   • Publicador do Pub/Sub (roles/pubsub.publisher)
   • Administrador da conta de serviço (roles/iam.serviceAccountAdmin)
   • Utilizador da conta de serviço (roles/iam.serviceAccountUser)
   • Administrador de utilização de serviços (roles/serviceusage.serviceUsageAdmin)
   • Administrador de armazenamento (roles/storage.admin)

   Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

   Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

6. Tome nota da conta de serviço predefinida do Compute Engine, uma vez que a vai anexar a um acionador do Eventarc para representar a identidade do acionador para fins de teste. Esta conta de serviço é criada automaticamente depois de ativar ou usar um Google Cloud serviço que usa o Compute Engine e com o seguinte formato de email:

   [e-mail]

   Substitua PROJECT_NUMBER pelo seu Google Cloud número do projeto. Pode encontrar o número do projeto na página Boas-vindas da Google Cloud consola ou executando o seguinte comando:

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

   Para ambientes de produção, recomendamos vivamente que crie uma nova conta de serviço e lhe conceda uma ou mais funções do IAM que contenham as autorizações mínimas necessárias e siga o princípio do privilégio mínimo.

   Nota:

   A iam.automaticIamGrantsForDefaultServiceAccounts restrição da política da organização impede que a função de editor seja concedida automaticamente às contas de serviço predefinidas. Se tiver criado a sua organização após 3 de maio de 2024, esta restrição é aplicada por predefinição.

   Recomendamos vivamente que aplique esta restrição para desativar a concessão automática de funções. Se desativar a concessão automática de funções, tem de decidir que funções conceder às contas de serviço predefinidas e, em seguida, conceder estas funções manualmente.

   Se a conta de serviço predefinida já tiver a função de editor, recomendamos que substitua a função de editor por funções menos permissivas.Para modificar as funções da conta de serviço em segurança, use o Simulador de políticas para ver o impacto da alteração e, em seguida, conceda e revogue as funções adequadas.

7. Por predefinição, os serviços do Cloud Run só podem ser chamados por proprietários do projeto, editores do projeto e administradores e invocadores do Cloud Run. Pode controlar o acesso por serviço. No entanto, para fins de teste, conceda a função de invocador do Cloud Run (run.invoker) no Google Cloud projeto à conta de serviço do Compute Engine. Isto concede a função a todos os serviços e trabalhos do Cloud Run num projeto.

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

   Tenha em atenção que, se criar um acionador para um serviço do Cloud Run autenticado sem conceder a função de invocador do Cloud Run, o acionador é criado com êxito e está ativo. No entanto, o acionador não funciona conforme esperado e é apresentada uma mensagem semelhante à seguinte nos registos:

   The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
8. Se ativou o agente do serviço Cloud Pub/Sub a 8 de abril de 2021 ou antes, para suportar pedidos de envio autenticados do Pub/Sub, conceda a função de criador de tokens de conta de serviço (roles/iam.serviceAccountTokenCreator) ao agente do serviço. Caso contrário, esta função é concedida por predefinição:

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

Crie um repositório padrão do Artifact Registry

Crie um repositório padrão do Artifact Registry para armazenar a imagem de contentor:

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

Substitua REPOSITORY por um nome exclusivo para o repositório.

Implemente um recetor de eventos no Cloud Run

Implemente um serviço do Cloud Run que registe o conteúdo de um evento.

1. Clone o repositório do GitHub:

   Node.js

   git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git

   Em alternativa, pode transferir o exemplo como um ficheiro ZIP e extraí-lo.

   Python

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

   Em alternativa, pode transferir o exemplo como um ficheiro ZIP e extraí-lo.

   Go

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

   Em alternativa, pode transferir o exemplo como um ficheiro ZIP e extraí-lo.

   Java

   git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

   Em alternativa, pode transferir o exemplo como um ficheiro ZIP e extraí-lo.

   Ruby

   git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples.git

   Em alternativa, pode transferir o exemplo como um ficheiro ZIP e extraí-lo.

   C#

   git clone https://github.com/GoogleCloudPlatform/dotnet-docs-samples.git

   Em alternativa, pode transferir o exemplo como um ficheiro ZIP e extraí-lo.

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

   Node.js

   cd nodejs-docs-samples/eventarc/pubsub/

   Python

   cd python-docs-samples/eventarc/pubsub/

   Go

   cd golang-samples/eventarc/pubsub/

   Java

   cd java-docs-samples/eventarc/pubsub/

   Ruby

   cd ruby-docs-samples/eventarc/pubsub/

   C#

   cd dotnet-docs-samples/eventarc/pubsub/

3. Crie o contentor e carregue-o para o Cloud Build:

   gcloud builds submit --tag $REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/trigger-pubsub:v1

4. Implemente a imagem do contentor no Cloud Run:

   gcloud run deploy ${SERVICE_NAME} \
       --image $REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/trigger-pubsub:v1

5. No comando Allow unauthenticated invocations to trigger-pubsub (y/N)?, responda n para "Não".

Nota: com base no nível de acesso à rede necessário para o serviço do Cloud Run, também pode definir a flag de entrada.

Quando vir o URL do serviço do Cloud Run, a implementação está concluída.

Crie um acionador do Eventarc

Quando uma mensagem é publicada no tópico Pub/Sub, o evento aciona o serviço Cloud Run.

Nota: por predefinição, as subscrições do Pub/Sub criadas para o Eventarc persistem independentemente da atividade e não expiram. Para alterar a duração da inatividade, consulte as propriedades da subscrição.

1. Crie um acionador para ouvir mensagens do Pub/Sub:

   Novo tópico do Pub/Sub

     gcloud eventarc triggers create ${SERVICE_NAME} \
         --destination-run-service=${SERVICE_NAME} \
         --destination-run-region=${REGION} \
         --location=${REGION} \
         --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
         --service-account=[e-mail]
   

   Esta ação cria um novo tópico Pub/Sub e um acionador para o mesmo denominado trigger-pubsub.

   Tópico do Pub/Sub existente

     gcloud eventarc triggers create ${SERVICE_NAME} \
         --destination-run-service=${SERVICE_NAME} \
         --destination-run-region=${REGION} \
         --location=${REGION} \
         --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
         --transport-topic=projects/PROJECT_ID/topics/TOPIC_ID \
         --service-account=[e-mail]
   

   Substitua o seguinte:

   • PROJECT_ID: o ID do seu Google Cloud projeto
   • TOPIC_ID: o ID do tópico do Pub/Sub existente

   Esta ação cria um acionador denominado trigger-pubsub para o tópico Pub/Sub existente.

   Tenha em atenção que, quando cria um acionador do Eventarc pela primeira vez num projeto, pode haver um atraso no aprovisionamento do agente do serviço Eventarc. Google Cloud Normalmente, pode resolver este problema tentando criar o acionador novamente. Para mais informações, consulte o artigo Erros de acesso negado.

2. Confirme que o acionador foi criado com êxito. Tenha em atenção que, embora o acionador seja criado imediatamente, pode demorar até dois minutos para que um acionador fique totalmente funcional.

   gcloud eventarc triggers list --location=${REGION}

   O estado do acionador devolvido deve ser ACTIVE: Yes.

Gere e veja um evento

Publicar uma mensagem num tópico Pub/Sub para gerar um evento e acionar o serviço do Cloud Run. O serviço do Cloud Run regista as mensagens nos registos do serviço.

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

   export TOPIC_ID=$(gcloud eventarc triggers describe ${SERVICE_NAME} \
       --format='value(transport.pubsub.topic)')

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

   gcloud pubsub topics publish $TOPIC_ID --message "Hello there"

   O evento é enviado para o serviço do Cloud Run, que regista a mensagem do evento.

3. Veja as entradas de registo relacionadas com eventos criadas pelo seu serviço:

   gcloud logging read 'textPayload: "Hello there!"'

   A entrada do registo deve ser semelhante à seguinte:

   textPayload: 'Hello, Hello there!'

Os registos podem demorar alguns momentos a aparecer. Se não os vir imediatamente, verifique novamente após um minuto.

Limpar

Para evitar incorrer em custos, como: armazenar a imagem do contentor no Artifact Registry, armazenar ficheiros no seu contentor do Cloud Storage e acionar o Eventarc, pode eliminar os recursos que criou para este tutorial:

1. Elimine o serviço do Cloud Run.

2. Elimine a imagem de contentor.

3. Elimine o acionador do Eventarc.

Em alternativa, pode eliminar o seu Google Cloud projeto. A eliminação do seu projeto Google Cloud interrompe a faturação de todos os recursos usados nesse projeto.

Atenção: a eliminação de um projeto tem os seguintes efeitos:

• Tudo no projeto é eliminado. Se usou um projeto existente para as tarefas neste documento, quando o elimina, também elimina qualquer outro trabalho que tenha feito no projeto.
• Os IDs dos projetos personalizados são perdidos. Quando criou este projeto, pode ter criado um ID do projeto personalizado que quer usar no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, elimine os recursos selecionados no projeto em vez de eliminar o projeto inteiro.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

O que se segue?

• Receba um evento do Pub/Sub através de um serviço do Cloud Run não autenticado
• Crie contentores
• Crie um acionador para encaminhar eventos do Pub/Sub para o Cloud Run
• Desenvolva serviços do Cloud Run