Receba eventos através de mensagens Pub/Sub (Terraform)

Receba eventos através de mensagens Pub/Sub (Terraform)

Padrão

Este início rápido mostra como usar o Terraform para criar um acionador do Eventarc que recebe eventos diretos do Pub/Sub e encaminha os eventos para um serviço do Cloud Run. Para mais informações sobre como usar o Terraform para criar acionadores do Eventarc, consulte o artigo Crie um acionador com o Terraform.

Neste início rápido, vai fazer o seguinte:

1. Prepare-se para implementar o Terraform.

2. Defina uma configuração do Terraform que faça o seguinte:

   1. Ative as APIs.
   2. Crie uma conta de serviço e conceda-lhe as funções de gestão de identidade e de acesso (IAM) necessárias.
   3. Implemente um serviço no Cloud Run como um destino de eventos.
   4. Crie um tópico Pub/Sub como fornecedor de eventos.
   5. Crie um acionador do Eventarc.

3. Aplique a configuração do Terraform.

4. Publique uma mensagem num tópico do Pub/Sub para gerar um evento e vê-lo nos registos do Cloud Run.

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.

Enable the Cloud Resource Manager and IAM APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable cloudresourcemanager.googleapis.com iam.googleapis.com

If you're using a local shell, then create local authentication credentials for your user account:

gcloud auth application-default login

You don't need to do this if you're using Cloud Shell.

If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

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.

Enable the Cloud Resource Manager and IAM APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable cloudresourcemanager.googleapis.com iam.googleapis.com

If you're using a local shell, then create local authentication credentials for your user account:

gcloud auth application-default login

You don't need to do this if you're using Cloud Shell.

If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

1. 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.

   Autorizações necessárias

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

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

   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.

Prepare-se para implementar o Terraform

Prepare-se para implementar recursos do Terraform criando um ficheiro de configuração do Terraform. Um ficheiro de configuração do Terraform permite-lhe definir o estado final preferido para a sua infraestrutura através da sintaxe do Terraform.

1. Se estiver a usar uma shell local, instale e configure o Terraform.

   O Terraform já está integrado no ambiente do Cloud Shell e pode usar o Cloud Shell para implementar os seus recursos do Terraform sem ter de instalar o Terraform.

2. No Cloud Shell ou na shell local, defina o Google Cloud projeto predefinido onde quer aplicar as configurações do Terraform. Só tem de executar este comando uma vez por projeto e pode executá-lo em qualquer diretório:

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Substitua PROJECT_ID pelo ID do seu Google Cloud projeto.

Tenha em atenção que as variáveis de ambiente são substituídas se definir valores explícitos no ficheiro de configuração do Terraform.

Prepare o diretório

Cada ficheiro de configuração do Terraform tem de ter o seu próprio diretório (também denominado módulo raiz). Crie um diretório e um novo ficheiro nesse diretório:

mkdir DIRECTORY && cd DIRECTORY && touch main.tf

O nome do ficheiro tem de ter a extensão .tf. Por exemplo, neste início rápido, o ficheiro é denominado main.tf.

Defina a configuração do Terraform

Copie os seguintes fragmentos do código Terraform para o ficheiro main.tf criado recentemente. Opcionalmente, pode copiar o código do GitHub. (No canto superior direito do fragmento de código, clique em > Ver no GitHub.)

Ativar APIs

Normalmente, os exemplos do Terraform partem do princípio de que as APIs necessárias estão ativadas no seu Google Cloud projeto. Use o seguinte fragmento do código para ativar as APIs necessárias para este início rápido:

# Enable Cloud Run API
resource "google_project_service" "run" {
  service            = "run.googleapis.com"
  disable_on_destroy = false
}

# Enable Eventarc API
resource "google_project_service" "eventarc" {
  service            = "eventarc.googleapis.com"
  disable_on_destroy = false
}

# Enable Pub/Sub API
resource "google_project_service" "pubsub" {
  service            = "pubsub.googleapis.com"
  disable_on_destroy = false
}

Crie uma conta de serviço e configure o respetivo acesso

Cada acionador do Eventarc está associado a uma conta de serviço do IAM. Para concluir este início rápido, tem de conceder à conta de serviço gerida pelo utilizador as seguintes funções de IAM:

• Função de invocador do Cloud Run (roles/run.invoker)
• Função Publicador do Pub/Sub (roles/pubsub.publisher)

Use o seguinte fragmento do código para criar uma conta de serviço dedicada e conceder-lhe funções específicas do IAM para gerir eventos:

# Used to retrieve project information later
data "google_project" "project" {}

# Create a dedicated service account
resource "google_service_account" "eventarc" {
  account_id   = "eventarc-trigger-sa"
  display_name = "Eventarc trigger service account"
}

# Grant permission to invoke Cloud Run services
resource "google_project_iam_member" "runinvoker" {
  project = data.google_project.project.id
  role    = "roles/run.invoker"
  member  = "serviceAccount:${google_service_account.eventarc.email}"
}

# Grant permission to publish messages to a Pub/Sub topic
resource "google_project_iam_member" "pubsubpublisher" {
  project = data.google_project.project.id
  member  = "serviceAccount:${google_service_account.eventarc.email}"
  role    = "roles/pubsub.publisher"
}

Se ativou o agente do serviço Pub/Sub a 8 de abril de 2021 ou antes, conceda a função Criador de tokens de conta de serviço (roles/iam.serviceAccountTokenCreator) ao agente do serviço.

resource "google_project_iam_member" "tokencreator" {
  project  = data.google_project.project.id
  role     = "roles/iam.serviceAccountTokenCreator"
  member   = "serviceAccount:service-${data.google_project.project.number}@gcp-sa-pubsub.iam.gserviceaccount.com"
}

Implemente um recetor de eventos no Cloud Run

Crie um serviço do Cloud Run como destino de eventos para o acionador do Eventarc através do recurso do Terraform:google_cloud_run_v2_service

# Deploy a Cloud Run service
resource "google_cloud_run_v2_service" "default" {
  name     = "hello-events"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

  template {
    containers {
      # This container will log received events
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
    service_account = google_service_account.eventarc.email
  }

  depends_on = [google_project_service.run]
}

Crie um tópico Pub/Sub como fornecedor de eventos

Crie um tópico do Pub/Sub com o recurso do Terraform: google_pubsub_topic

# Create a Pub/Sub topic
resource "google_pubsub_topic" "default" {
  name = "pubsub_topic"
}

Crie um acionador do Eventarc

Crie um acionador do Eventarc para ouvir mensagens do Pub/Sub com o recurso do Terraform google_eventarc_trigger:

# Create an Eventarc trigger, routing Pub/Sub events to Cloud Run
resource "google_eventarc_trigger" "default" {
  name     = "trigger-pubsub-cloudrun-tf"
  location = google_cloud_run_v2_service.default.location

  # Capture messages published to a Pub/Sub topic
  matching_criteria {
    attribute = "type"
    value     = "google.cloud.pubsub.topic.v1.messagePublished"
  }

  # Send events to Cloud Run
  destination {
    cloud_run_service {
      service = google_cloud_run_v2_service.default.name
      region  = google_cloud_run_v2_service.default.location
    }
  }

  transport {
    pubsub {
      topic = google_pubsub_topic.default.id
    }
  }

  service_account = google_service_account.eventarc.email
  depends_on = [
    google_project_service.eventarc,
    google_project_iam_member.pubsubpublisher
  ]
}

Nota: embora o acionador seja criado imediatamente, pode demorar até dois minutos para que os acionadores estejam totalmente funcionais.

Aplique o Terraform

Use a CLI do Terraform para aprovisionar a infraestrutura com base no ficheiro de configuração.

Para saber como aplicar ou remover uma configuração do Terraform, consulte os comandos básicos do Terraform.

1. Inicialize o Terraform. Só tem de fazer isto uma vez por diretório.

   terraform init

   Opcionalmente, para usar a versão mais recente do fornecedor Google, inclua a opção -upgrade:

   terraform init -upgrade

2. Reveja a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expetativas:

   terraform plan

   Faça as correções necessárias à configuração.

3. Aplique a configuração do Terraform executando o seguinte comando e introduzindo yes no comando:

   terraform apply

   Normalmente, aplica toda a configuração de uma só vez. No entanto, também pode segmentar um recurso específico. Por exemplo:

   terraform apply -target="google_eventarc_trigger.default"

   Depois de ativar as APIs, a ação pode demorar alguns minutos a propagar-se e antes de poder implementar mais recursos. Se tiver um problema, experimente aplicar novamente a configuração do Terraform.

   Aguarde até que o Terraform apresente a mensagem "Apply complete!" (Aplicação concluída!).

Valide a criação de recursos

1. Confirme que o serviço do Cloud Run foi criado:

   gcloud run services list --region us-central1
   

   O resultado deve ser semelhante ao seguinte:

   SERVICE: hello-events
   REGION: us-central1
   URL: https://hello-events-13335919645.us-central1.run.app
   LAST DEPLOYED BY: ...
   LAST DEPLOYED AT: 2024-12-16T15:00:52.606160Z
   

2. Confirme que o acionador do Eventarc foi criado:

   gcloud eventarc triggers list --location us-central1
   

   O resultado deve ser semelhante ao seguinte:

   NAME: trigger-pubsub-cloudrun-tf
   TYPE: google.cloud.pubsub.topic.v1.messagePublished
   DESTINATION: Cloud Run service: hello-events
   ACTIVE: Yes
   LOCATION: us-central1
   

Gere e veja um evento de tópico Pub/Sub

Pode gerar um evento publicando uma mensagem no tópico do Pub/Sub. O acionador do Eventarc encaminha a mensagem para o serviço de receção de eventos implementado no Cloud Run, e o serviço regista a mensagem de evento.

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

   gcloud config set eventarc/location us-central1
   export RUN_TOPIC=$(gcloud eventarc triggers describe trigger-pubsub-cloudrun-tf \
       --format='value(transport.pubsub.topic)')
   

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

   gcloud pubsub topics publish $RUN_TOPIC --message "Hello World!"
   

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

3. Para ver as entradas de registo relacionadas com eventos criadas pelo seu serviço, execute o seguinte comando:

   gcloud logging read 'jsonPayload.message: "Received event of type google.cloud.pubsub.topic.v1.messagePublished"'
   

4. Procure uma entrada de registo semelhante a:

   jsonPayload:
   ...
   message: 'Received event of type google.cloud.pubsub.topic.v1.messagePublished.
       Event data: Hello World!'
   

   Nota: se não vir uma entrada de registo, aguarde alguns minutos e tente novamente o comando gcloud logging read. O acionador pode demorar até dois minutos após a criação para começar a filtrar eventos.

Usou o Terraform com êxito para implementar um serviço de receção de eventos no Cloud Run e criar um acionador do Eventarc. Depois de gerar um evento a partir do Pub/Sub, pode vê-lo nos registos do Cloud Run.

Limpar

Quando terminar as tarefas descritas neste início rápido, pode evitar a faturação contínua eliminando os recursos que criou.

Remova os recursos aplicados anteriormente com a sua configuração do Terraform executando o seguinte comando e introduzindo yes no comando:

terraform destroy

Em alternativa, pode eliminar o seu Google Cloud projeto para evitar incorrer em custos. A eliminação do seu Google Cloud projeto 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

Se planeia explorar vários tutoriais e inícios rápidos, a reutilização de projetos pode ajudar a evitar exceder os limites de quota de projetos.

O que se segue?

• Desenvolva serviços para o Cloud Run
• Documentação do Google Cloud Terraform