Usar o Eventarc para receber eventos do Cloud Storage


Neste tutorial, mostramos como implantar um aplicativo em contêiner usando um serviço autenticado do Cloud Run que recebe eventos por meio do Eventarc.

Ao especificar filtros para um gatilho do Eventarc, você pode configurar o roteamento de eventos, incluindo a origem e o destino do evento. Nesse caso, uma atualização em um bucket do Cloud Storage aciona o evento e uma solicitação é enviada ao serviço do Cloud Run em forma de solicitação HTTP.

Objetivos

Com este tutorial, você vai:

  1. Criar um bucket do Cloud Storage para ser a origem do evento.

  2. Implante um serviço de receptor de eventos no Cloud Run que exige invocações autenticadas.

  3. Criar um gatilho do Eventarc que encaminha eventos do bucket do Cloud Storage para o serviço do Cloud Run.

  4. Gerar um evento fazendo upload de um arquivo no bucket do Cloud Storage e visualizar o evento nos registros do Cloud Run.

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.

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

  1. Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, 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. Para inicializar a CLI gcloud, execute o seguinte comando:

    gcloud init
  4. Crie ou selecione um projeto do Google Cloud.

    • Crie um projeto do Google Cloud:

      gcloud projects create PROJECT_ID

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

    • Selecione o projeto do Google Cloud que você criou:

      gcloud config set project PROJECT_ID

      Substitua PROJECT_ID pelo nome do projeto do Google Cloud.

  5. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

  6. Instale a CLI do Google Cloud.
  7. Para inicializar a CLI gcloud, execute o seguinte comando:

    gcloud init
  8. Crie ou selecione um projeto do Google Cloud.

    • Crie um projeto do Google Cloud:

      gcloud projects create PROJECT_ID

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

    • Selecione o projeto do Google Cloud que você criou:

      gcloud config set project PROJECT_ID

      Substitua PROJECT_ID pelo nome do projeto do Google Cloud.

  9. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

  10. Se você não estiver usando o Cloud Shell, atualize os componentes da Google Cloud CLI e faça login usando sua conta:
    gcloud components update
    gcloud auth login
  11. Ative as APIs:
    gcloud services enable artifactregistry.googleapis.com \
        cloudbuild.googleapis.com \
        eventarc.googleapis.com \
        run.googleapis.com \
        storage.googleapis.com
  12. Defina as variáveis de configuração usadas neste tutorial:
    export REGION=us-central1
    gcloud config set run/region ${REGION}
    gcloud config set run/platform managed
    gcloud config set eventarc/location ${REGION}
  13. 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.

    Observe que, por padrão, as permissões do Cloud Build incluem permissões para upload e download de artefatos do Artifact Registry.

    Permissões necessárias

    Para conseguir as permissões necessárias para concluir o tutorial, peça ao administrador para conceder a você os seguintes papéis do IAM no seu projeto:

    Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

    Também é possível conseguir as permissões necessárias com papéis personalizados ou outros papéis predefinidos.

  14. A conta de serviço padrão do Compute Engine é criada automaticamente depois de ativar ou usar um serviço do Google Cloud que usa o Compute Engine.

    Para fins de teste, é possível anexar essa conta de serviço a um gatilho do Eventarc para representar a identidade do gatilho. Observe o formato de e-mail a ser usado ao criar um acionador:

    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)'

    A conta de serviço do Compute Engine recebe o papel básico de Editor (roles/editor) de modo automático no projeto. No entanto, se as concessões automáticas de papéis tiverem sido desativadas, consulte as instruções aplicáveis em Papéis e permissões para criar uma nova conta de serviço e conceder os papéis necessários.

  15. Por padrão, os serviços do Cloud Run só podem ser chamados por proprietários do projeto, editores do projeto e administradores e invocadores do Cloud Run. É possível controlar o acesso por serviço. No entanto, para fins de teste, conceda o papel de chamador do Cloud Run (run.invoker) no projeto do Google Cloud à conta de serviço do Compute Engine. Isso concede o papel em todos os serviços e jobs do Cloud Run em um projeto.
    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
        --role=roles/run.invoker

    Se você criar um gatilho para um serviço autenticado do Cloud Run sem conceder o papel de chamador do Cloud Run, o gatilho será criado com sucesso e estará ativo. No entanto, o acionador não funcionará conforme o esperado e uma mensagem semelhante à seguinte aparecerá nos registros:

    The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
  16. Conceda o papel de receptor de eventos do Eventarc (roles/eventarc.eventReceiver) no projeto à conta de serviço padrão do Compute Engine para que o gatilho do Eventarc possa receber eventos de provedores de eventos.
    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
        --role=roles/eventarc.eventReceiver
  17. Se você ativou o agente de serviço do Cloud Pub/Sub até 8 de abril de 2021, para oferecer suporte a solicitações push autenticadas do Pub/Sub, conceda o papel Criador de token da conta de serviço. (roles/iam.serviceAccountTokenCreator) à conta de serviço gerenciada pelo Google. 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

Criar um repositório padrão do Artifact Registry

Crie um repositório padrão do Artifact Registry para armazenar a imagem do contêiner:

gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=$REGION

Substitua REPOSITORY por um nome exclusivo para o repositório.

crie um bucket do Cloud Storage

Crie um bucket do Cloud Storage para usar como origem do evento:

gsutil mb -l us-central1 gs://PROJECT_ID-bucket/

Depois que a origem do evento é criada, implante o serviço de receptor de eventos no Cloud Run.

Implantar um receptor de eventos no Cloud Run

Implante um serviço do Cloud Run que recebe e registra eventos.

  1. Clone o repositório do GitHub:

    Node.js

    git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git

    Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.

    Python

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

    Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.

    Go

    git clone https://github.com/GoogleCloudPlatform/golang-samples.git

    Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.

    Java

    git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

    Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.

    C#

    git clone https://github.com/GoogleCloudPlatform/dotnet-docs-samples.git

    Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.

  2. Mude para o diretório que contém o código de amostra do Cloud Run:

    Node.js

    cd nodejs-docs-samples/eventarc/audit-storage/

    Python

    cd python-docs-samples/eventarc/audit-storage/

    Go

    cd golang-samples/eventarc/audit_storage/

    Java

    cd java-docs-samples/eventarc/audit-storage/

    C#

    cd dotnet-docs-samples/eventarc/audit-storage/
  3. Crie o contêiner para o serviço do Cloud Run:

    export PROJECT_ID=$(gcloud config get-value project)
    export SERVICE_NAME=helloworld-events
    gcloud builds submit --tag $REGION-docker.pkg.dev/${PROJECT_ID}/REPOSITORY/${SERVICE_NAME}:v1
  4. Implante a imagem do contêiner no Cloud Run:

    gcloud run deploy ${SERVICE_NAME} \
        --image $REGION-docker.pkg.dev/${PROJECT_ID}/REPOSITORY/${SERVICE_NAME}:v1
  5. No comando Permitir invocações não autenticadas para helloworld-events (y/N)?, responda n em "Não".

Quando o URL do serviço do Cloud Run for exibido, a implantação estará concluída.

Criar um gatilho do Eventarc

O gatilho do Eventarc envia eventos do bucket do Cloud Storage para o serviço helloworld-events do Cloud Run. O serviço exige autenticação, e o evento deve ser acionado por um autor da chamada que tenha uma conta de serviço com os papéis e permissões do IAM necessários para usar o recurso.

  1. Crie um gatilho que filtre eventos do Cloud Storage:

    gcloud eventarc triggers create ${SERVICE_NAME} \
        --destination-run-service=${SERVICE_NAME} \
        --destination-run-region=${REGION} \
        --location=${REGION} \
        --event-filters="type=google.cloud.storage.object.v1.finalized" \
        --event-filters="bucket=PROJECT_ID-bucket" \
        --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Isso gera um gatilho chamado helloworld-events.

    Ao criar um gatilho do Eventarc pela primeira vez em um projeto do Google Cloud, pode haver um atraso no provisionamento do agente de serviço do Eventarc. Esse problema geralmente pode ser resolvido ao tentar criar o acionador novamente. Para mais informações, consulte Erros de permissão negada.

  2. Confirme se o gatilho foi criado com êxito. Embora o gatilho seja criado imediatamente, pode levar até dois minutos para que ele seja totalmente funcional.

    gcloud eventarc triggers list --location=${REGION}

    A saída será semelhante a esta:

    NAME: helloworld-events
    TYPE: google.cloud.storage.object.v1.finalized
    DESTINATION: Cloud Run service: helloworld-events
    ACTIVE: Yes
    

Gerar e visualizar um evento

Faça upload de um arquivo de texto para o bucket do Cloud Storage para gerar um evento roteado para o serviço do Cloud Run. O serviço do Cloud Run registra o evento nos registros do serviço.

  1. Para gerar um evento:

    Faça upload de um arquivo de texto para o Cloud Storage:

     echo "Hello World" > random.txt
     gsutil cp random.txt gs://PROJECT_ID-bucket/random.txt
    

    O upload gera um evento e o serviço do Cloud Run registra a mensagem do evento.

  2. Para visualizar a entrada de registro:

    1. Filtre as entradas de registro e retorne a saída no formato JSON:

      gcloud logging read "resource.labels.service_name=helloworld-events AND textPayload:random.txt" --format=json
      
    2. Procure uma entrada de registro semelhante a esta:

      "textPayload": "Detected change in Cloud Storage bucket: objects/random.txt"
      

Os registros podem demorar alguns instantes para aparecer. Se eles não aparecerem imediatamente, verifique novamente após um minuto.

Você implantou com sucesso um serviço de receptor de eventos no Cloud Run, criou um gatilho do Eventarc, gerou um evento a partir do Cloud Storage e o visualizou nos registros do Cloud Run.

Limpar

Se você criou um novo projeto para este tutorial, exclua o projeto. Se você usou um projeto já existente e quer mantê-lo sem as alterações incluídas com este tutorial, exclua os recursos criados para o tutorial.

Exclua o projeto

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

Para excluir o projeto:

  1. No Console do Google Cloud, acesse a página Gerenciar recursos.

    Acessar "Gerenciar recursos"

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

delete-tutorial-resources

  1. Exclua o serviço do Cloud Run que você implantou neste tutorial:

    gcloud run services delete SERVICE_NAME

    SERVICE_NAME é o nome escolhido do serviço.

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

  2. Remova as configurações padrão do gcloud CLI que você adicionou durante a configuração do tutorial.

    Exemplo:

    gcloud config unset run/region

    ou

    gcloud config unset project

  3. Exclua outros recursos do Google Cloud criados neste tutorial:

    • Exclua o gatilho do Eventarc:
      gcloud eventarc triggers delete TRIGGER_NAME
      
      Substitua TRIGGER_NAME pelo nome do gatilho.

A seguir