Como usar o Cloud Pub/Sub com o tutorial do Cloud Run

Neste tutorial, mostraremos como gravar, implantar e chamar um serviço do Cloud Run de uma assinatura de push do Cloud Pub/Sub.

É possível usar este tutorial com o Cloud Run ou o Cloud Run no GKE.

Objetivos

  • Gravar, criar e implantar um serviço para o Cloud Run ou o Cloud Run no GKE
  • Chamar o serviço publicando uma mensagem em um tópico do Cloud Pub/Sub.

Custos

Neste tutorial, usamos componentes do Cloud Platform que podem ser cobrados, incluindo estes:

Novos usuários do Cloud Platform podem se qualificar para uma avaliação gratuita.

Antes de começar

  1. Faça login na sua Conta do Google.

    Se você ainda não tiver uma, inscreva-se.

  2. Selecione ou crie um projeto do Google Cloud Platform.

    Acessar a página Gerenciar recursos

  3. Verifique se o faturamento foi ativado no projeto do Google Cloud Platform.

    Saiba como ativar o faturamento

  4. Ative a API Cloud Run.
  5. Instale e inicie o SDK do Cloud.
  6. Instale o componente gcloud Beta.
    gcloud components install beta
  7. Para o Cloud Run no GKE, instale o componente gcloud kubectl:
    gcloud components install kubectl
  8. Atualize os componentes:
    gcloud components update
  9. Se você estiver usando o Cloud Run no GKE, crie um novo cluster usando as instruções em Como configurar o Cloud Run no GKE.

Como configurar padrões da gcloud

Para configurar a gcloud com os padrões do serviço do Cloud Run, realize as etapas a seguir:

  1. Defina seu projeto padrão:

    gcloud config set project [PROJECT-ID]

    Substitua [PROJECT-ID] pelo nome do projeto que você criou para este tutorial.

  2. Se você estiver usando o Cloud Run, configure a gcloud para a região escolhida:

     gcloud config set run/region us-central1
    

    Substitua us-central1 pela região do Cloud Run compatível de sua preferência.

  3. Se você estiver usando o Cloud Run no GKE, configure a gcloud para o cluster:

    gcloud config set run/cluster [CLUSTER-NAME]
    gcloud config set run/cluster_location us-central1-a

    Substitua [CLUSTER-NAME] pelo nome usado por seu cluster e, se necessário, substitua us-central1-a pelo local de cluster compatível com sua escolha.

Locais do Cloud Run

O Cloud Run é regional, o que significa que a infraestrutura que executa seus serviços do Cloud Run está localizada em uma região específica e é gerenciada pelo Google para estar disponível de maneira redundante em todas as zonas da região.

Atender aos seus requisitos de latência, disponibilidade ou durabilidade são os principais fatores para selecionar a região em que seus serviços do Cloud Run são executados. Geralmente, é possível selecionar a região mais próxima de seus usuários, mas considere o local dos outros produtos do GCP usados pelo serviço do Cloud Run. O uso de produtos do GCP em vários locais pode afetar a latência e o custo do serviço.

O Cloud Run está disponível nas regiões a seguir:

  • us-central1 (Iowa)

Se você já criou um serviço do Cloud Run, é possível visualizar a região no painel do Cloud Run no Console do GCP.

Como criar um tópico do Cloud Pub/Sub

O serviço de amostra é acionado por mensagens publicadas em um tópico do Cloud Pub/Sub, então será preciso criar um tópico no Cloud Pub/Sub.

Para criar um novo tópico do Cloud Pub/Sub, use o comando:

gcloud pubsub topics create myRunTopic

É possível usar myRunTopic ou substituir por um nome de tópico exclusivo em seu projeto do GCP.

Como recuperar o exemplo de código

Para recuperar o exemplo de código para uso, siga estas etapas:

  1. Faça o download do código de serviço de amostra:

  2. Descompacte o arquivo. Por exemplo, use estes utilitários de linha de comando padrão do Linux e do macOS:

    Tarball

    tar -xzvf [FILE].tar.gz

    Arquivo ZIP

    unzip [FILE].zip

    [FILE] é o nome do arquivo do download sem a extensão do arquivo.

Como olhar para o código

O código deste tutorial consiste nisto:

  • Um servidor que lida com solicitações HTTP recebidas

    Node.js

    Para que a facilidade no teste do serviço do Node.js seja mantida, a configuração do servidor é separada da inicialização dele.

    O servidor da Web do Node.js está configurado em app.js

    const express = require('express')
    const bodyParser = require('body-parser');
    const app = express()
    
    app.use(bodyParser.json())
    
    O servidor da Web é iniciado em index.js:
    const app = require('./app.js');
    const PORT = process.env.PORT || 8080;
    
    app.listen(PORT, () => console.log(`nodejs-pubsub-tutorial listening on port ${PORT}`))

    Go

    // Sample run-pubsub is a Cloud Run service which handles Pub/Sub messages.
    package main
    
    import (
    	"encoding/json"
    	"fmt"
    	"log"
    	"net/http"
    	"os"
    )
    
    func main() {
    	http.HandleFunc("/", HelloPubSub)
    	// Determine port for HTTP service.
    	port := os.Getenv("PORT")
    	if port == "" {
    		port = "8080"
    		log.Printf("Defaulting to port %s", port)
    	}
    	// Start HTTP server.
    	log.Printf("Listening on port %s", port)
    	log.Fatal(http.ListenAndServe(fmt.Sprintf(":%s", port), nil))
    }
    

  • Uma função do Hello World que manipula a mensagem do Cloud Pub/Sub e registra uma saudação.

    Node.js

    app.post('/', (req, res) => {
    
      if (!req.body) {
        const msg = 'no Pub/Sub message received'
        console.error(`error: ${msg}`)
        res.status(400).send(`Bad Request: ${msg}`)
        return
      }
      if (!req.body.message) {
        const msg = 'invalid Pub/Sub message format'
        console.error(`error: ${msg}`)
        res.status(400).send(`Bad Request: ${msg}`)
        return
      }
    
      const pubSubMessage = req.body.message
      const name = pubSubMessage.data
        ? Buffer.from(pubSubMessage.data, 'base64').toString().trim()
        : 'World'
    
      console.log(`Hello ${name}!`)
      res.status(204).send()
    })
    

    Go

    // PubSubMessage is the payload of a Pub/Sub event. Please refer to the docs for
    // additional information regarding Pub/Sub events.
    type PubSubMessage struct {
    	Message struct {
    		Data []byte `json:"data,omitempty"`
    		ID   string `json:"id"`
    	} `json:"message"`
    	Subscription string `json:"subscription"`
    }
    
    // HelloPubSub consumes a Pub/Sub message.
    func HelloPubSub(w http.ResponseWriter, r *http.Request) {
    	// Parse the Pub/Sub message.
    	var m PubSubMessage
    
    	if err := json.NewDecoder(r.Body).Decode(&m); err != nil {
    		log.Printf("json.NewDecoder: %v", err)
    		http.Error(w, "Bad Request", http.StatusBadRequest)
    		return
    	}
    
    	name := string(m.Message.Data)
    	if name == "" {
    		name = "World"
    	}
    	log.Printf("Hello %s!", name)
    }
    

    É necessário codificar o serviço para retornar um código de resposta HTTP preciso. Códigos de êxito, como HTTP 200 ou 204, confirmam o processamento completo da mensagem do Cloud Pub/Sub. Códigos de erro, como HTTP 400 ou 500, indicam que a mensagem será repetida, conforme descrito em Como receber mensagens usando o guia de push.

  • Um Dockerfile que define o ambiente operacional do serviço. O conteúdo do Dockerfile varia por linguagem.

    Node.js

    # Use the official Node.js 10 image.
    # https://hub.docker.com/_/node
    FROM node:10
    
    # Create and change to the app directory.
    WORKDIR /usr/src/app
    
    # Copy application dependency manifests to the container image.
    # A wildcard is used to ensure both package.json AND package-lock.json are copied.
    # Copying this separately prevents re-running npm install on every code change.
    COPY package*.json ./
    
    # Install production dependencies.
    RUN npm install --only=production
    
    # Copy local code to the container image.
    COPY . .
    
    # Service must listen to $PORT environment variable.
    # This default value facilitates local development.
    ENV PORT 8080
    
    # Run the web service on container startup.
    CMD [ "npm", "start" ]
    

    Go

    # Use the offical Golang image to create a build artifact.
    # This is based on Debian and sets the GOPATH to /go.
    # https://hub.docker.com/_/golang
    FROM golang as builder
    
    # Copy local code to the container image.
    WORKDIR /app
    COPY . .
    
    # Build the outyet command inside the container.
    # (You may fetch or manage dependencies here,
    # either manually or with a tool like "godep".)
    RUN CGO_ENABLED=0 GOOS=linux go build -v -o hellopubsub
    
    # Use a Docker multi-stage build to create a lean production image.
    # https://docs.docker.com/develop/develop-images/multistage-build/#use-multi-stage-builds
    FROM alpine
    
    # Copy the binary to the production image from the builder stage.
    COPY --from=builder /app/hellopubsub .
    
    # Service must listen to $PORT environment variable.
    # This default value facilitates local development.
    ENV PORT 8080
    
    # Run the web service on container startup.
    CMD ["/hellopubsub"]
    

Para saber detalhes sobre como autenticar a origem das solicitações do Cloud Pub/Sub, leia a seção abaixo sobre como integrar com o Cloud Pub/Sub.

Como enviar o código

O código de remessa consiste em três etapas: compilar uma imagem de contêiner com o Cloud Build, fazer o upload da imagem do contêiner no Container Registry e implantar a imagem do contêiner no Cloud Run ou no Cloud Run no GKE.

Para enviar seu código, siga estas etapas:

  1. Compile seu contêiner e publique no Container Registry.

    gcloud builds submit --tag gcr.io/[PROJECT-ID]/pubsub

    [PROJECT-ID] é o ID de projeto do GCP e pubsub é o nome que você quer dar ao seu serviço.

    Após a conclusão, você verá uma mensagem de "SUCESSO" contendo o código, a hora da criação e o nome da imagem. A imagem é armazenada no Container Registry e poderá ser reutilizada, se você quiser.

  2. Execute o comando a seguir para implantar seu aplicativo:

    gcloud beta run deploy pubsub-tutorial --image gcr.io/[PROJECT-ID]/pubsub

    Substitua [PROJECT-ID] pelo ID do projeto do GCP. pubsub é o nome do contêiner e pubsub-tutorial é o nome do serviço. Observe que a imagem do contêiner é implantada no serviço e na região (Cloud Run) ou no cluster (Cloud Run no GKE) que você configurou anteriormente em Como configurar a gcloud

    Se estiver implantando no Cloud Run, responda n ("não") à solicitação "allow unauthenticated". Mantendo o serviço particular, é possível contar com a integração automática do Cloud Pub/Sub no Cloud Run para autenticar as solicitações. Consulte Como integrar com o Cloud Pub/Sub para mais detalhes sobre como isso é configurado. Consulte Como gerenciar o acesso para mais detalhes sobre a autenticação baseada em IAM.

    Aguarde até que a implantação esteja concluída. Isso pode levar cerca de 30 segundos. Em caso de sucesso, a linha de comando exibe o URL de serviço. Esse URL é usado para configurar uma assinatura do Cloud Pub/Sub.

  3. Se você quer implantar uma atualização de código no serviço, repita as etapas anteriores. Cada implantação em um serviço cria uma nova revisão e inicia automaticamente o tráfego de serviço quando estiver pronto.

Como integrar com o Cloud Pub/Sub

Agora que implantamos nosso serviço do Cloud Run, configuraremos o Cloud Pub/Sub para enviar mensagens para ele.

Para integrar o serviço com o Cloud Pub/Sub, siga estas etapas:

  1. Permita que seu projeto para crie tokens de autenticação do Cloud Pub/Sub:

    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] pelo ID do projeto do GCP;
    • [PROJECT NUMBER] pelo número do projeto do GCP.
  2. Crie ou selecione uma conta de serviço para representar a identidade da assinatura do Cloud Pub/Sub.

    gcloud iam service-accounts create cloud-run-pubsub-invoker \
         --display-name "Cloud Run Pub/Sub Invoker"

    É possível usar o cloud-run-pubsub-invoker ou substituir por um nome exclusivo em seu projeto do Google Cloud Platform.

  3. Para o Cloud Run, conceda permissão a essa conta de serviço para chamar seu serviço de pubsub-tutorial:

    gcloud beta run services add-iam-policy-binding pubsub-tutorial \
         --member=serviceAccount:cloud-run-pubsub-invoker@[PROJECT-ID].iam.gserviceaccount.com \
         --role=roles/run.invoker

    Pode levar vários minutos para que as alterações do IAM sejam propagadas. Enquanto isso, você pode ver erros HTTP 403 nos registros de serviço.

  4. Crie uma assinatura do Cloud Pub/Sub com a conta de serviço:

    gcloud beta pubsub subscriptions create myRunSubscription --topic myRunTopic \
       --push-endpoint=[SERVICE-URL]/ \
       --push-auth-service-account=cloud-run-pubsub-invoker@[PROJECT-ID].iam.gserviceaccount.com

    Substitua:

    • myRunTopic pelo tópico que você criou anteriormente;
    • [SERVICE-URL] pelo URL HTTPS fornecido na implantação do serviço;
    • [PROJECT-ID] pelo ID do projeto do GCP.

    A sinalização --push-account-service-account ativa a funcionalidade de push do Cloud Pub/Sub para autenticação e autorização.

  5. Se você implantou no Cloud Run e está usando o domínio run.app padrão, seu domínio de serviço é registrado automaticamente para uso com assinaturas do Cloud Pub/Sub no mesmo projeto. Caso contrário, se você estiver usando um domínio personalizado, será necessário registrar a propriedade do domínio. Para configurar uma inscrição para realizar o push para um serviço do Cloud Run com segurança com um domínio personalizado, sua assinatura precisa ser criada desta forma:

    gcloud beta pubsub subscriptions create myRunSubscription --topic myRunTopic \
       --push-endpoint=https://[CUSTOM-DOMAIN] \
       --push-auth-service-account=cloud-run-pubsub-invoker@[PROJECT-ID].iam.gserviceaccount.com \
       --push-auth-token-audience=[SERVICE-URL]/

    Substitua:

    • myRunTopic pelo tópico que você criou anteriormente;
    • [CUSTOM-DOMAIN] pelo seu domínio personalizado mapeado anteriormente;
    • [PROJECT-ID] pelo ID do projeto do GCP;
    • [SERVICE-URL] pelo URL HTTPS fornecido na implantação do serviço.
  6. Se você implantar no Cloud Run, todas as solicitações do Cloud Pub/Sub serão autenticadas antes de chegar ao seu serviço. Se você tiver casos de uso avançados ou implantar no Cloud Run no GKE, verifique o token da Web do JSON que é enviado como parte da solicitação do Cloud Pub/Sub como parte de seu serviço. Para mais informações, consulte Autenticação e autorização.

Seu serviço agora está totalmente integrado ao Cloud Pub/Sub.

Como testar

Para testar a solução de ponta a ponta, siga estas etapas:

  1. Envie uma mensagem do Cloud Pub/Sub para o tópico:

    gcloud pubsub topics publish myRunTopic --message "Runner"

    Também é possível publicar mensagens programaticamente em vez de usar a linha de comando, conforme mostrado neste tutorial. Para mais informações, consulte Como publicar mensagens.

  2. Navegue até os registros de serviço:

    1. Navegue até o Console do Google Cloud Platform
    2. Clique no serviço do pubsub-tutorial.
    3. Selecione a guia Registros.

      Os registros podem demorar alguns instantes para aparecer. Se você não os vir imediatamente, verifique novamente após alguns instantes.

  3. Procure pela mensagem "Hello Runner!".

Como fazer a limpeza

Como excluir o projeto

O jeito mais fácil de evitar cobranças é excluindo o projeto que você criou para o tutorial.

Para excluir o projeto:

  1. No Console do GCP, acesse a página Projetos.

    Acessar a página Projetos

  2. Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir delete.
  3. Na caixa de diálogo, digite o código do projeto e clique em Encerrar para excluí-lo.

Como excluir o serviço do Cloud Run

Observe que a exclusão dos serviços do Cloud Run não remove nenhum recurso armazenado no Cloud Storage. Se quiser eliminá-los, exclua-os separadamente.

Para excluir o serviço que você implementou neste tutorial, use este código:

gcloud beta run services delete [SERVICE-NAME]

[SERVICE-NAME] é o nome do seu serviço escolhido.

Também é possível excluir os serviços do Cloud Run ou do Cloud Run no GKE no Console do Google Cloud Platform.

A seguir

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…