Receber eventos usando mensagens do Pub/Sub (Terraform)

Neste guia de início rápido, mostramos como usar o Terraform para criar um gatilho do Eventarc que recebe eventos diretos do Pub/Sub e os encaminha para um serviço do Cloud Run. Para mais informações sobre como usar o Terraform para criar gatilhos do Eventarc, consulte Criar um gatilho usando o Terraform.

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

  1. Prepare-se para implantar o Terraform.

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

    1. Ativar APIs.
    2. Crie uma conta de serviço.
    3. Crie um tópico do Pub/Sub como um provedor de eventos.
    4. Implante um serviço no Cloud Run como destino de evento.
    5. Criar um gatilho do Eventarc.

  3. Aplique a configuração do Terraform.

Isso permite gerar um evento publicando uma mensagem no tópico do Pub/Sub. O gatilho do Eventarc encaminha a mensagem para o serviço de receptor de eventos implantado no Cloud Run, e o serviço registra a mensagem do evento, fornecendo um exemplo simples de uma arquitetura orientada a eventos.

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 de Google Cloud .

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

  2. Instale a CLI do Google Cloud.

  3. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

  4. Para inicializar a CLI gcloud, execute o seguinte comando: 

    gcloud init

  5. Crie ou selecione um Google Cloud projeto.

    Funções necessárias para selecionar ou criar um projeto

    • Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
    • Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

    • Crie um projeto do Google Cloud :

      gcloud projects create PROJECT_ID

      Substitua PROJECT_ID por um nome para o projeto Google Cloud que você está criando.

    • Selecione o projeto Google Cloud que você criou:

      gcloud config set project PROJECT_ID

      Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

  6. Verifique se o faturamento está ativado para o projeto do Google Cloud .

  7. Ative as APIs Cloud Resource Manager e Identity and Access Management (IAM):

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis. 

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

  8. Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário: 

    gcloud auth application-default login

    Não é necessário fazer isso se você estiver usando o Cloud Shell.

    Se um erro de autenticação for retornado e você estiver usando um provedor de identidade (IdP) externo, confirme se você fez login na CLI gcloud com sua identidade federada.

  9. Instale a CLI do Google Cloud.

  10. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

  11. Para inicializar a CLI gcloud, execute o seguinte comando: 

    gcloud init

  12. Crie ou selecione um Google Cloud projeto.

    Funções necessárias para selecionar ou criar um projeto

    • Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
    • Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

    • Crie um projeto do Google Cloud :

      gcloud projects create PROJECT_ID

      Substitua PROJECT_ID por um nome para o projeto Google Cloud que você está criando.

    • Selecione o projeto Google Cloud que você criou:

      gcloud config set project PROJECT_ID

      Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

  13. Verifique se o faturamento está ativado para o projeto do Google Cloud .

  14. Ative as APIs Cloud Resource Manager e Identity and Access Management (IAM):

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis. 

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

  15. Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário: 

    gcloud auth application-default login

    Não é necessário fazer isso se você estiver usando o Cloud Shell.

    Se um erro de autenticação for retornado e você estiver usando um provedor de identidade (IdP) externo, confirme se você fez login na CLI gcloud com sua identidade federada.

  16. Se você estiver usando um projeto atual para este guia, verifique se tem as permissões necessárias para concluir o processo. Se você criou um projeto, já tem as permissões necessárias.

    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 usando papéis personalizados ou outros papéis predefinidos.

Preparar a implantação do Terraform

Antes de implantar qualquer recurso do Terraform, crie um arquivo de configuração do Terraform. Um arquivo de configuração do Terraform permite definir o estado final preferido da infraestrutura usando a sintaxe do Terraform.

  1. Se você estiver usando um shell local, instale o Terraform.

    O Terraform já está integrado ao ambiente do Cloud Shell, e você pode usar o Cloud Shell para implantar seus recursos do Terraform sem precisar instalar o Terraform.

  2. No Cloud Shell ou no shell local, defina o projeto Google Cloud padrão em que você quer aplicar a configuração do Terraform. Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório:

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Substitua PROJECT_ID pelo ID do seu projeto do Google Cloud .

    Observe que as variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.

  3. Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz. Crie um diretório e um novo arquivo nele:

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

    Substitua DIRECTORY pelo nome do diretório do Terraform.

    O nome do arquivo precisa ter a extensão .tf. Por exemplo, neste guia de início rápido, o arquivo de configuração é main.tf.

Definir sua configuração do Terraform

Copie os seguintes snippets de código do Terraform no arquivo main.tf. Ou, para copiar todo o exemplo de código do GitHub, no canto superior direito de um snippet de código, clique em > Ver no GitHub.

Ativar APIs

Para ativar as APIs necessárias para aplicar a configuração do Terraform, use o recurso do Terraform google_project_service:

# 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
}

Criar uma conta de serviço

Cada gatilho do Eventarc está associado a uma conta de serviço do IAM. Para criar uma conta de serviço dedicada para fins de teste, use o recurso do Terraform google_service_account:

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

Se você ativou o agente de serviço do Pub/Sub até 8 de abril de 2021, conceda o papel Criador de token da conta de serviço (roles/iam.serviceAccountTokenCreator) ao agente de 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"
}

Criar um tópico do Pub/Sub como um provedor de eventos

Para criar um tópico do Pub/Sub, use o recurso do Terraform google_pubsub_topic. Para conceder à sua conta de serviço o papel de Publicador do Pub/Sub (roles/pubsub.publisher) no nível do tópico, use o recurso do Terraform google_pubsub_topic_iam_member:

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

# Grant permission to publish messages to a Pub/Sub topic
resource "google_pubsub_topic_iam_member" "pubsubpublisher" {
  project    = google_pubsub_topic.default.project
  topic      = google_pubsub_topic.default.name
  member     = "serviceAccount:${google_service_account.eventarc.email}"
  role       = "roles/pubsub.publisher"
  depends_on = [google_pubsub_topic.default]
}

Implantar um receptor de eventos no Cloud Run

Para criar um serviço do Cloud Run como destino de evento, use o recurso do Terraform google_cloud_run_v2_service. Para conceder à sua conta de serviço o papel de Invocador do Cloud Run (roles/run.invoker) no nível do serviço, use o recurso do Terraform google_cloud_run_v2_service_iam_member:

# 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 sample container listens to HTTP requests and logs received events
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
    service_account = google_service_account.eventarc.email
  }

  depends_on = [google_project_service.run]
}

# Grant permission to invoke Cloud Run services
resource "google_cloud_run_v2_service_iam_member" "runinvoker" {
  project    = google_cloud_run_v2_service.default.project
  location   = google_cloud_run_v2_service.default.location
  name       = google_cloud_run_v2_service.default.name
  role       = "roles/run.invoker"
  member     = "serviceAccount:${google_service_account.eventarc.email}"
  depends_on = [google_cloud_run_v2_service.default]
}

Criar um gatilho do Eventarc

Para criar um gatilho do Eventarc que detecte mensagens do Pub/Sub, use 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_pubsub_topic_iam_member.pubsubpublisher
  ]
}

Aplique a configuração do Terraform:

Use a CLI do Terraform para provisionar a infraestrutura com base no arquivo de configuração. Para mais informações, consulte Comandos básicos do Terraform.

  1. Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório.

    terraform init

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

    terraform init -upgrade

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

    terraform plan

    Corrija a configuração conforme necessário.

  3. Para aplicar a configuração do Terraform, execute o comando a seguir e digite yes no prompt:

    terraform apply

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

    terraform apply -target="google_eventarc_trigger.default"

    Depois de ativar as APIs, pode levar alguns minutos para que a ação seja propagada antes de você implantar outros recursos. Se você encontrar um problema, tente aplicar a configuração do Terraform de novo.

    Aguarde até que o Terraform exiba a mensagem "Apply complete!".

Verificar a criação de recursos

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

    gcloud run services list --region us-central1

    A saída será semelhante a esta:

    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 se o gatilho do Eventarc foi criado:

    gcloud eventarc triggers list --location us-central1

    A saída será semelhante a esta:

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

Gerar e visualizar um evento de tópico do Pub/Sub.

É possível gerar um evento publicando uma mensagem no tópico do Pub/Sub. O gatilho do Eventarc encaminha a mensagem para o serviço de receptor de eventos implantado no Cloud Run, e o serviço registra a mensagem do evento.

  1. Encontre e defina o tópico do 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. Para gerar um evento, publique uma mensagem no tópico do Pub/Sub:

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

    O evento é encaminhado ao serviço do Cloud Run, que registra a mensagem do evento.

  3. Filtre as entradas de registro criadas pelo seu serviço:

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

  4. Procure uma entrada de registro semelhante a esta:

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

Você usou o Terraform para implantar um serviço de receptor de eventos no Cloud Run e criar um gatilho do Eventarc. Depois de gerar um evento do Pub/Sub, você pode conferir nos registros do Cloud Run.

Limpar

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

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

terraform destroy

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

Excluir um projeto do Google Cloud :

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