Receber eventos do Pub/Sub em um endpoint HTTP interno em uma rede VPC

Neste tutorial, mostramos como criar um endpoint HTTP interno em uma rede de nuvem privada virtual (VPC) que recebe eventos de mensagens do Pub/Sub usando o Eventarc. Para saber mais sobre esse destino de evento, consulte Rotear eventos para um endpoint HTTP interno em uma rede VPC.

É possível executar os comandos a seguir usando a CLI do Google Cloud no terminal ou no Cloud Shell.

Objetivos

Com este tutorial, você vai:

  1. Crie uma rede VPC para fornecer rede a recursos e serviços baseados na nuvem. Uma rede VPC é isolada logicamente de outras redes no Google Cloud.
  2. Crie uma sub-rede. Cada rede VPC consiste em um ou mais intervalos de endereços IP chamados sub-redes. As sub-redes são recursos regionais e têm intervalos de endereços IP associados a elas.
  3. Crie regras de firewall de VPC para permitir ou negar tráfego de/para instâncias de VM (máquina virtual) na rede VPC.
  4. Crie um anexo de rede que permita que uma rede VPC produtora inicie conexões com uma rede VPC consumidora.
  5. Crie uma instância de VM do Compute Engine na rede VPC.
  6. Implante um servidor da Web como um serviço receptor de eventos na instância de VM.
  7. Crie um gatilho do Eventarc que direcione eventos do Pub/Sub para o receptor de eventos na instância de VM.
  8. Estabeleça uma conexão SSH com a instância da VM.
  9. Publique uma mensagem em um tópico do Pub/Sub para gerar um evento e visualize o corpo do evento na ferramenta SSH no navegador.

Custos

Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços. Novos usuários do Google Cloud podem estar qualificados para uma avaliação gratuita.

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

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.

    • 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 Compute Engine, Eventarc, and Pub/Sub APIs: 

    gcloud services enable compute.googleapis.com eventarc.googleapis.com pubsub.googleapis.com
  7. Install the Google Cloud CLI.

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

    gcloud init

  9. Create or select a Google Cloud 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.

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

  11. Enable the Compute Engine, Eventarc, and Pub/Sub APIs: 

    gcloud services enable compute.googleapis.com eventarc.googleapis.com pubsub.googleapis.com
  12. Atualize os componentes da CLI do Google Cloud: 
    gcloud components update
  13. Faça login usando sua conta: 
    gcloud auth login
  14. Defina as variáveis de configuração usadas neste guia de início rápido: 
    REGION=us-central1
ZONE=us-central1-a

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

    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.

  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:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator
     Substitua:
    • PROJECT_ID: o ID do projeto do Google Cloud
    • PROJECT_NUMBER: o 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)'

Criar uma rede VPC de modo personalizado

Uma rede VPC é uma versão virtual de uma rede física, implementada dentro da rede de produção do Google Ela fornece conectividade para suas instâncias de VM do Compute Engine.

Quando uma rede VPC de modo personalizado é criada, nenhuma sub-rede é criada automaticamente. Esse tipo de rede oferece controle total das sub-redes e dos intervalos de IP.

gcloud compute networks create NETWORK_NAME \
    --subnet-mode=custom \
    --bgp-routing-mode=regional \
    --mtu=1460

Substitua NETWORK_NAME por um nome para a rede VPC.

Observações:

  • Cada rede nova que você cria precisa ter um nome exclusivo dentro do mesmo projeto.
  • O modo de roteamento do protocolo de gateway de borda (BGP) controla o comportamento dos Cloud Routers na rede e pode ser global ou regional. O padrão é regional.
  • A unidade máxima de transmissão (MTU), que é o maior tamanho de pacote da rede. A MTU pode ser definida como qualquer valor de 1300 a 8896. O padrão é 1460. Antes de definir a MTU como um valor maior que 1460, consulte Unidade máxima de transmissão.

Para mais informações, consulte Criar e gerenciar redes VPC.

Criar uma sub-rede somente IPv4

Uma rede precisa ter pelo menos uma sub-rede para que você possa usá-la.

Ao criar uma sub-rede, você define um nome, uma região e pelo menos um intervalo de endereço de IPv4 principal de acordo com as regras da sub-rede. Não é possível criar instâncias em uma região que não tenha uma sub-rede definida.

gcloud compute networks subnets create SUBNET_NAME \
    --region=$REGION \
    --network=NETWORK_NAME \
    --range=10.10.10.0/24

Substitua SUBNET_NAME por um nome para a nova sub-rede.

Para mais informações, consulte Sub-redes.

Criar regras de firewall da VPC

Com as regras de firewall da VPC, é possível permitir ou negar o tráfego entre recursos em uma rede VPC com base no número da porta, na tag ou no protocolo.

As regras de firewall são identificadas no nível da rede e se aplicam apenas à rede em que são criadas. No entanto, o nome escolhido para cada regra precisa ser único no projeto.

  1. Crie uma regra de firewall para sua rede VPC que permita o tráfego de entrada de qualquer endereço IPv4 (0.0.0.0/0) para qualquer instância na rede usando a porta 22. Essa regra não é necessária para a entrega de eventos. No entanto, para os fins deste tutorial, crie a regra para que você possa se conectar à VM usando SSH e confirme a entrega do evento:

    gcloud compute firewall-rules create RULE_NAME_ONE \
    --network=projects/PROJECT_ID/global/networks/NETWORK_NAME \
    --direction=INGRESS \
    --priority=65534 \
    --action=ALLOW \
    --source-ranges=0.0.0.0/0 \
    --rules=tcp:22

  2. Crie uma regra de firewall para sua rede VPC que permita o tráfego de entrada de um intervalo de endereços IP específico para qualquer instância na rede usando a porta 80 (já que você implantará um servidor da Web na VM que detecta na porta 80):

    gcloud compute firewall-rules create RULE_NAME_TWO \
    --network=projects/PROJECT_ID/global/networks/NETWORK_NAME \
    --direction=INGRESS \
    --priority=1000 \
    --action=ALLOW \
    --source-ranges=10.10.10.0/24 \
    --rules=tcp:80

    Substitua RULE_NAME_ONE e RULE_NAME_TWO pelos nomes exclusivos das regras de firewall.

    O uso de --source-ranges é opcional e indica uma lista de blocos de endereços IP que têm permissão para fazer conexões de entrada que correspondam à regra de firewall para as instâncias na rede. Nesse caso, o intervalo corresponde ao intervalo usado na sub-rede criada anteriormente.

    Recomendamos que você use a flag para aplicar sua regra de firewall especificamente ao tráfego do Eventarc. Se --source-ranges e --source-tags não forem especificados, --source-ranges assumirá 0.0.0.0/0 como padrão, o que significa que a regra se aplica a todas as conexões IPv4 de entrada de dentro ou fora da VPC.

Para mais informações, consulte Usar regras de firewall da VPC.

Criar um anexo de rede

Um anexo de rede é um recurso que permite que uma rede VPC produtora inicie conexões com uma rede VPC consumidora por uma interface do Private Service Connect.

Para publicar eventos, o Eventarc usa o anexo de rede para estabelecer uma conexão com o endpoint HTTP interno hospedado em uma rede VPC.

É possível criar um anexo de rede que aceite automaticamente conexões de qualquer interface do Private Service Connect que se refira ao anexo de rede. Crie o anexo de rede na mesma rede e região que contém o serviço de destino HTTP.

gcloud compute network-attachments create ATTACHMENT_NAME \
    --region=$REGION \
    --subnets=SUBNET_NAME \
    --connection-preference=ACCEPT_AUTOMATIC

Substitua ATTACHMENT_NAME por um nome para o anexo de rede.

Para mais informações, consulte Sobre anexos de rede.

Criar uma instância de VM em uma sub-rede específica

Uma instância de VM do Compute Engine é uma máquina virtual hospedada na infraestrutura do Google. Os termos instância do Compute Engine, instância de VM e VM são sinônimos. As instâncias de VM incluem clusters do Google Kubernetes Engine (GKE), instâncias de ambiente flexível do App Engine e outros produtos do Google Cloud criados em VMs do Compute Engine.

Crie uma instância de VM do Compute Engine na rede VPC em que é possível implantar um serviço de receptor de eventos.

gcloud compute instances create INSTANCE_NAME \
      --zone=$ZONE \
      --machine-type=e2-medium \
      --subnet=SUBNET_NAME

Substitua INSTANCE_NAME por um nome para a VM.

Para mais informações, consulte Criar e iniciar uma instância de VM.

Implantar um receptor de eventos na VM

Implante um servidor da Web na VM que detecte na porta 80, além de receber e registrar eventos.

  1. Estabeleça uma conexão SSH com a instância de VM usando o botão SSH no console do Google Cloud para se conectar à VM.

    Depois que uma conexão com o servidor SSH for estabelecida, use o terminal SSH no navegador para executar comandos na instância de VM.

  2. No terminal SSH no navegador, crie um arquivo de texto com o nome de arquivo server.py que contenha o seguinte código Python:

    #!/usr/bin/env python3
from http.server import BaseHTTPRequestHandler, HTTPServer
import logging

class S(BaseHTTPRequestHandler):
    def _set_response(self):
        self.send_response(200)
        self.send_header('Content-type', 'text/html')
        self.end_headers()

    def do_GET(self):
        logging.info("GET request,\nPath: %s\nHeaders:\n%s\n", str(self.path), str(self.headers))
        self._set_response()
        self.wfile.write("GET request for {}".format(self.path).encode('utf-8'))

    def do_POST(self):
        content_length = int(self.headers['Content-Length'])
        post_data = self.rfile.read(content_length)
        logging.info("POST request,\nPath: %s\nHeaders:\n%s\n\nBody:\n%s\n",
                str(self.path), str(self.headers), post_data.decode('utf-8'))

        self._set_response()
        self.wfile.write("POST request for {}".format(self.path).encode('utf-8'))

def run(server_class=HTTPServer, handler_class=S, port=80):
    logging.basicConfig(level=logging.INFO)
    server_address = ('', port)
    http_server = server_class(server_address, handler_class)
    logging.info('Starting HTTP Server at port %d...\n', port)
    try:
        http_server.serve_forever()
    except KeyboardInterrupt:
        pass
    http_server.server_close()
    logging.info('Stopping HTTP Server...\n')

if __name__ == '__main__':
    from sys import argv

    if len(argv) == 2:
        run(port=int(argv[1]))
    else:
        run()

  3. Inicie o servidor e mantenha-o em execução nas etapas restantes deste tutorial:

    sudo python3 server.py

Criar um gatilho do Eventarc

Crie um gatilho do Eventarc que crie um novo tópico do Pub/Sub e encaminhe eventos para o receptor de eventos implantado na VM quando uma mensagem for publicada no tópico do Pub/Sub.

Por se tratar de um teste, o acionador usa a Conta de serviço padrão do Compute Engine (PROJECT_NUMBER-compute@developer.gserviceaccount.com) para a identidade. Esta conta de serviço foi criada automaticamente depois que você ativou a API Compute Engine.

Observe que, 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.

gcloud eventarc triggers create TRIGGER_NAME \
    --location=$REGION \
    --destination-http-endpoint-uri=http://INSTANCE_NAME.$ZONE.c.PROJECT_ID.internal \
    --network-attachment="projects/PROJECT_ID/regions/$REGION/networkAttachments/ATTACHMENT_NAME" \
    --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

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 mais informações sobre como configurar seu gatilho, consulte Rotear eventos para um endpoint HTTP interno em uma rede VPC.

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

É possível gerar um evento publicando uma mensagem em um tópico do Pub/Sub.

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

    export MY_TOPIC=$(gcloud eventarc triggers describe TRIGGER_NAME \
    --location=$REGION \
    --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 $MY_TOPIC --message "Hello World"

    O gatilho do Eventarc encaminha o evento para o endpoint HTTP interno na sua rede VPC. No terminal SSH no navegador, o corpo do evento é a saída. Ela será semelhante a esta:

    Body:
{
    "message": {
        "data": "SGVsbG8gV29ybGQ=",
        "messageId": "8795720366614192",
        "publishTime": "2023-08-26T13:09:48Z"
    }
}

10.10.10.3 - - [26/Aug/2023 13:09:49] "POST / HTTP/1.1" 200 -

    Se você decodificar o valor data de SGVsbG8gV29ybGQ= do formato Base64, "Hello World" será retornado.

Você implantou com sucesso um serviço de receptor de eventos em um endpoint HTTP interno em uma rede VPC, criou um gatilho do Eventarc, gerou um evento do Pub/Sub e confirmou que o evento foi roteado conforme esperado pelo gatilho para o endpoint de destino.

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.

Excluir o projeto

    Delete a Google Cloud project:

    gcloud projects delete PROJECT_ID

Excluir recursos individuais

  1. Exclua o gatilho do Eventarc: 
    gcloud eventarc triggers delete TRIGGER_NAME --location=$REGION
  2. Exclua a instância: 
    gcloud compute instances delete INSTANCE_NAME
  3. Exclua o anexo de rede: 
    gcloud compute network-attachments delete ATTACHMENT_NAME --region=$REGION
  4. Exclua as regras de firewall: 
    gcloud compute firewall-rules delete RULE_NAME_ONE
gcloud compute firewall-rules delete RULE_NAME_TWO
  5. Exclua a sub-rede: 
    gcloud compute networks subnets delete SUBNET_NAME --region=$REGION
  6. Exclua a rede VPC: 
    gcloud compute networks delete NETWORK_NAME

A seguir