Receba eventos Pub/Sub num ponto final HTTP interno numa rede VPC

Padrão

---

Pré-visualização

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Este tutorial mostra como criar um ponto final HTTP interno numa rede da nuvem virtual privada (VPC) que recebe eventos de mensagens do Pub/Sub através do Eventarc. Para saber mais sobre este destino de eventos, consulte o artigo Encaminhe eventos para um ponto final HTTP interno numa rede VPC.

Pode executar os seguintes comandos através da CLI Google Cloud no seu terminal ou na Cloud Shell.

Objetivos

Neste tutorial, vai:

1. Crie uma rede VPC para fornecer redes aos seus recursos e serviços baseados na nuvem. Uma rede VPC está logicamente isolada de outras redes no Google Cloud.
2. Crie uma sub-rede. Cada rede de VPC consiste num ou mais intervalos de endereços IP denominados sub-redes. As sub-redes são recursos regionais e têm intervalos de endereços IP associados.
3. Crie regras de firewall da VPC para poder permitir ou negar tráfego de ou para instâncias de VMs (máquinas virtuais) na sua rede VPC.
4. Crie uma associação da rede que permita a uma rede VPC do produtor iniciar ligações a uma rede VPC do consumidor.
5. Crie uma instância de VM do Compute Engine na rede VPC.
6. Implemente um servidor Web como um serviço de receção de eventos na sua instância de VM.
7. Crie um acionador do Eventarc que encaminhe eventos do Pub/Sub para o recetor de eventos na sua instância de VM.
8. Estabeleça uma ligação SSH à instância de VM.
9. Publique uma mensagem num tópico do Pub/Sub para gerar um evento e veja o corpo do evento na ferramenta SSH no navegador.

Custos

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

• Cloud Next Generation Firewall
• Compute Engine
• Eventarc
• Pub/Sub
• VPC

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.

Quando terminar as tarefas descritas neste documento, pode evitar a faturação contínua eliminando os recursos que criou. Para mais informações, consulte o artigo Limpe.

Antes de começar

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 Compute Engine, Eventarc, and Pub/Sub 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 compute.googleapis.com eventarc.googleapis.com pubsub.googleapis.com

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 Compute Engine, Eventarc, and Pub/Sub 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 compute.googleapis.com eventarc.googleapis.com pubsub.googleapis.com

1. Atualize os componentes da CLI do Google Cloud:

   gcloud components update

2. Inicie sessão com a sua conta:

   gcloud auth login

3. Defina as variáveis de configuração usadas neste início rápido:

   REGION=us-central1
   ZONE=us-central1-a

4. 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 de rede de Calcular (roles/compute.networkAdmin)
   • Administrador de segurança do Compute (roles/compute.securityAdmin)
   • 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.

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

   Substitua o seguinte:
   • PROJECT_ID: o ID do seu Google Cloud projeto
   • PROJECT_NUMBER: o número do seu Google Cloud 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)'

Crie uma rede VPC no modo personalizado

Uma rede VPC é uma versão virtual de uma rede física que é implementada na rede de produção da Google. Fornece conetividade para as suas instâncias de VM do Compute Engine.

Quando é criada uma rede VPC no modo personalizado, não são criadas automaticamente sub-redes. Este tipo de rede oferece-lhe controlo completo sobre as respetivas sub-redes e intervalos de IPs.

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.

Tenha em conta o seguinte:

• Cada nova rede que criar tem de ter um nome exclusivo no mesmo projeto.
• O modo de encaminhamento do Border Gateway Protocol (BGP) controla o comportamento dos routers na nuvem na rede e pode ser global ou regional. O valor predefinido é regional.
• A unidade de transmissão máxima (MTU) é o maior tamanho de pacote da rede. A MTU pode ser definida para qualquer valor entre 1300 e 8896. A predefinição é 1460. Antes de definir a MTU para um valor superior a 1460, reveja o artigo Unidade de transmissão máxima.

Para mais informações, consulte o artigo Crie e faça a gestão de redes VPC.

Crie uma sub-rede apenas IPv4

Uma rede tem de ter, pelo menos, uma sub-rede antes de a poder usar.

Quando cria uma sub-rede, define um nome, uma região e, pelo menos, um intervalo de endereços IPv4 principal de acordo com as regras da sub-rede. Tenha em atenção que não pode criar instâncias numa 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 o artigo Sub-redes.

Crie regras de firewall da VPC

As regras de firewall de VPC permitem-lhe autorizar ou recusar tráfego entre recursos numa rede de VPC com base no número da porta, na etiqueta ou no protocolo.

As regras de firewall de VPC são definidas ao nível da rede e aplicam-se apenas à rede onde são criadas. No entanto, o nome que escolher para uma regra tem de ser exclusivo do projeto.

1. Crie uma regra de firewall para a 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 através da porta 22. Esta regra não é necessária para o envio de eventos. No entanto, para os fins deste tutorial, crie a regra para que possa estabelecer ligação à VM através de SSH e confirmar 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 a 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 através da porta 80 (uma vez que vai implementar um servidor Web na sua VM que escuta 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 por nomes exclusivos para as regras da firewall.

   Tenha em atenção que a utilização de --source-ranges é opcional e indica uma lista de blocos de endereços IP que podem estabelecer ligações de entrada que correspondam à regra de firewall às instâncias na rede. Neste caso, o intervalo corresponde ao intervalo usado na sub-rede que criou anteriormente.

   Recomendamos que use a flag para aplicar a regra de firewall especificamente ao tráfego do Eventarc. Se não for especificado --source-ranges nem --source-tags, o valor predefinido de --source-ranges é 0.0.0.0/0, o que significa que a regra aplica-se a todas as ligações IPv4 recebidas de dentro ou fora da rede.

Para mais informações, consulte o artigo Use regras da firewall da VPC.

Crie uma associação de rede

Uma associação de rede é um recurso que permite a uma rede da VPC do produtor iniciar ligações a uma rede da VPC do consumidor através de uma interface do Private Service Connect.

Para publicar eventos, o Eventarc usa a associação de rede para estabelecer uma ligação ao ponto final HTTP interno alojado numa rede VPC.

Nota: o Eventarc reserva o intervalo de endereços IP CIDR 240.0.0.0/20. A sub-rede usada para a associação de rede não deve sobrepor-se a este intervalo.

Pode criar uma associação de rede que aceite automaticamente ligações de qualquer interface do Private Service Connect que faça referência à associação de rede. Crie a associação 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 o artigo Acerca das associações de rede.

Crie uma instância de VM numa sub-rede especificada

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

Crie uma instância de VM do Compute Engine na rede VPC na qual pode implementar um serviço de recetor 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 o artigo Crie e inicie uma instância de VM.

Implemente um recetor de eventos na VM

Implemente um servidor Web na sua VM que detete na porta 80 e receba e registe eventos.

1. Estabeleça uma ligação SSH à sua instância de VM através do botão SSH na Google Cloud consola para estabelecer ligação à sua VM.

   Depois de estabelecer uma ligação ao servidor SSH, use o terminal SSH no navegador para executar comandos na instância da VM.

2. No terminal SSH no navegador, crie um ficheiro de texto com o nome de ficheiro 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 para os passos restantes neste tutorial:

   sudo python3 server.py
   

Crie um acionador do Eventarc

Crie um acionador do Eventarc que crie um novo tópico do Pub/Sub e encaminhe eventos para o recetor de eventos implementado na VM quando uma mensagem é publicada no tópico do Pub/Sub.

Depois de ativar a API Compute Engine, a conta de serviço predefinida é a conta de serviço predefinida do Compute Engine ([e-mail]). Para fins de teste, o acionador usa esta conta de serviço predefinida para a sua identidade.

Aviso: 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. Não deve usar a conta de serviço predefinida, uma vez que lhe é concedida automaticamente a função básica de Editor com privilégios elevados.

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=[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 mais informações sobre a configuração do acionador, consulte o artigo Encaminhe eventos para um ponto final HTTP interno numa rede de VPC.

Nota: a criação do acionador pode demorar vários minutos e, em seguida, o acionador pode demorar até dois minutos a ficar totalmente funcional.

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

Pode gerar um evento publicando uma mensagem num tópico do Pub/Sub.

1. Encontre e defina o tópico 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 no tópico Pub/Sub para gerar um evento:

   gcloud pubsub topics publish $MY_TOPIC --message "Hello World"

   O acionador do Eventarc encaminha o evento para o ponto final HTTP interno na sua rede VPC. No terminal SSH no navegador, o corpo do evento é emitido. Deve ser semelhante ao seguinte:

   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 -
   

   Tenha em atenção que, se descodificar o valor data de SGVsbG8gV29ybGQ= a partir do respetivo formato Base64, é devolvido "Hello World".

Implementou com êxito um serviço de receção de eventos num ponto final HTTP interno numa rede VPC, criou um acionador do Eventarc, gerou um evento a partir do Pub/Sub e confirmou que o evento foi encaminhado conforme esperado pelo acionador para o ponto final de destino.

Limpar

Para evitar incorrer em custos na sua conta do Google Cloud pelos recursos usados neste tutorial, elimine o projeto que contém os recursos ou mantenha o projeto e elimine os recursos individuais.

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

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

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Elimine recursos individuais

1. Elimine o acionador do Eventarc:
   gcloud eventarc triggers delete TRIGGER_NAME --location=$REGION

2. Elimine a instância:

   gcloud compute instances delete INSTANCE_NAME

3. Elimine a associação de rede:
   gcloud compute network-attachments delete ATTACHMENT_NAME --region=$REGION

4. Elimine as regras de firewall:
   gcloud compute firewall-rules delete RULE_NAME_ONE
   gcloud compute firewall-rules delete RULE_NAME_TWO

5. Elimine a sub-rede:
   gcloud compute networks subnets delete SUBNET_NAME --region=$REGION

6. Elimine a rede de VPC:
   gcloud compute networks delete NETWORK_NAME

O que se segue?

• Receba eventos do Pub/Sub num ponto final HTTP privado num cluster do GKE privado
• Faça a gestão dos acionadores do Eventarc
• Veja todos os fornecedores de eventos e destinos