Receber eventos usando mensagens do Pub/Sub (Terraform)

Receber eventos usando mensagens do Pub/Sub (Terraform)

Padrão

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:

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 e conceda a ela os papéis necessários do Identity and Access Management (IAM).
   3. Implante um serviço no Cloud Run como destino de evento.
   4. Crie um tópico do Pub/Sub como provedor de eventos.
   5. Criar um gatilho do Eventarc.

3. Aplique a configuração do Terraform.

4. Publicar uma mensagem em um tópico do Pub/Sub para gerar um evento e visualizá-la nos registros do Cloud Run

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

   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. Enable the Cloud Resource Manager and IAM APIs:

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

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

8. Install the Google Cloud CLI.

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

   gcloud init

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

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

12. Enable the Cloud Resource Manager and IAM APIs:

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

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

14. Se você for o criador do projeto, receberá o papel de proprietário básico (roles/owner). Por padrão, esse papel do Identity and Access Management (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 Cloud Run (roles/run.admin)
    • Administrador do Eventarc (roles/eventarc.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.

Preparar para implantar o Terraform

Prepare-se para implantar os recursos do Terraform criando um arquivo de configuração do Terraform. Um arquivo de configuração do Terraform permite definir o estado final de sua preferência para a infraestrutura usando a sintaxe do Terraform.

1. Se você estiver usando um shell local, instale e configure 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 padrão do Google Cloud em que você quer aplicar as configurações 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 projeto Google Cloud .

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

Preparar o diretório

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

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

Definir a configuração do Terraform

Copie os seguintes snippets de código do Terraform para o arquivo main.tf recém-criado. Se preferir, copie o código do GitHub. No canto superior direito do snippet de código, clique em > View on GitHub (em inglês).

Ativar APIs

As amostras do Terraform geralmente presumem que as APIs necessárias estejam ativadas no seu projeto doGoogle Cloud . Use o snippet de código abaixo para ativar as APIs necessárias para este guia de 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
}

Criar uma conta de serviço e configurar o acesso

Cada gatilho do Eventarc é associado a uma conta de serviço do IAM. Para concluir este guia de início rápido, conceda à conta de serviço gerenciada pelo usuário os seguintes papéis do IAM:

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

Use o snippet de código abaixo para criar uma conta de serviço dedicada e conceder papéis específicos do IAM para gerenciar 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 você ativou o agente de serviço do Pub/Sub até 8 de abril de 2021, conceda o papel de 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"
}

Implantar um receptor de eventos no Cloud Run

Crie um serviço do Cloud Run como destino do evento para o gatilho do Eventarc usando o recurso google_cloud_run_v2_service do Terraform:

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

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

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

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

Criar um gatilho do Eventarc

Crie um gatilho do Eventarc para detectar mensagens do Pub/Sub usando o recurso google_eventarc_trigger do Terraform:

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

Observação: o gatilho é criado imediatamente, mas pode levar até dois minutos para que ele funcione.

Aplicar o Terraform

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

Para saber como aplicar ou remover uma configuração do Terraform, 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

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

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 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 e para que você possa implantar outros recursos. Se você encontrar um problema, tente aplicar a configuração do Terraform novamente.

   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, que 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. Publique uma mensagem para o tópico do Pub/Sub a fim de gerar um evento:

   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. Para visualizar as entradas de registro relacionadas a eventos criadas pelo 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 registro semelhante a esta:

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

   Observação: se não aparecer uma entrada de registro, aguarde alguns minutos e tente novamente o comando gcloud logging read. Pode levar até dois minutos após a criação para o gatilho começar a filtrar os eventos.

Você usou o Terraform para implantar um serviço de receptor de eventos no Cloud Run e criar um acionador do Eventarc. Depois de gerar um evento do Pub/Sub, você pode acessá-lo 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 seu projeto do Google Cloud para evitar cobranças. A exclusão do projeto do Google Cloud interrompe o faturamento de todos os recursos usados nele.

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

• Desenvolver serviços para o Cloud Run
• Terraform no Google Cloud da T-Systems Sovereign Cloud