Receber eventos diretos do Cloud Storage (CLI gcloud)

Receber eventos diretos do Cloud Storage (CLI gcloud)

Neste guia de início rápido, mostramos como receber eventos diretos do Cloud Storage (sem usar os Registros de auditoria do Cloud) em um serviço do Cloud Run não autenticado usando o Eventarc.

Observação: todos os serviços do Cloud Run são implantados de modo privado por padrão, o que significa que eles não podem ser acessados sem fornecer credenciais de autenticação na solicitação. Para projetos com políticas da organização de compartilhamento restrito de domínio, use um serviço de destino autenticado do Cloud Run em vez de um que permita acesso público (não autenticado).

É possível configurar o acionamento de notificações em resposta a vários eventos dentro de um bucket do Cloud Storage: criação, exclusão e arquivamento de objetos e atualizações de metadados. Para mais informações, consulte Criar um gatilho para rotear eventos do Cloud Storage para o Cloud Run.

Neste guia de início rápido, você fará as seguintes tarefas:

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

2. Implantar um serviço de receptor de eventos no Cloud Run

3. Criar um gatilho do Eventarc.

4. Gerar um evento fazendo upload de um arquivo no bucket do Cloud Storage e visualizá-lo 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 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.

   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

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

   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

   • 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. Ative as APIs Cloud Build, Cloud Run, Cloud Storage, Eventarc e Pub/Sub.

    gcloud services enable \
    cloudbuild.googleapis.com \
    eventarc.googleapis.com \
    pubsub.googleapis.com \
    run.googleapis.com \
    storage.googleapis.com

11. Atualize os componentes gcloud:

    gcloud components update

12. Faça login usando sua conta:

    gcloud auth login

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

    gcloud config set run/region us-central1
    gcloud config set run/platform managed
    gcloud config set eventarc/location us-central1

14. 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 para concluir o tutorial, peça ao administrador para conceder a você os seguintes papéis do IAM no seu projeto:

    • Editor do Cloud Build (roles/cloudbuild.builds.editor)
    • 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)
    • 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)
    • Administrador de armazenamento (roles/storage.admin)

    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.

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

    [e-mail]
    

    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 automaticamente o papel básico de Editor (roles/editor) no seu 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.

    Cuidado: recomendamos o uso da conta de serviço padrão do Compute Engine apenas para fins de teste. Para ambientes de produção, recomendamos criar uma nova conta de serviço e conceder a ela um ou mais papéis do IAM que contenham as permissões mínimas necessárias e seguir o princípio de privilégio mínimo.
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:[e-mail] \
        --role=roles/eventarc.eventReceiver

17. Antes de criar um gatilho para eventos diretos do Cloud Storage, conceda o papel de Editor do Pub/Sub (roles/pubsub.publisher) ao agente de serviço do Cloud Storage, um conta de serviço gerenciada:

    SERVICE_ACCOUNT="$(gsutil kms serviceaccount -p PROJECT_ID)"
    
    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member="serviceAccount:${SERVICE_ACCOUNT}" \
        --role='roles/pubsub.publisher'
    

18. 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:[e-mail] \
        --role=roles/iam.serviceAccountTokenCreator

19. Faça o download e instale a ferramenta de gerenciamento de código-fonte Git.

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/

Observação: o bucket do Cloud Storage precisa residir no mesmo projeto e região ou multirregião do Google Cloud que o gatilho do Eventarc.

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

Implantar o serviço de receptor de eventos no Cloud Run

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

1. Clone o repositório e altere para o diretório que contém o código de amostra do Cloud Run:

   Go

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

   Java

   git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
   cd java-docs-samples/eventarc/audit-storage
   

   .NET

   git clone https://github.com/GoogleCloudPlatform/dotnet-docs-samples.git
   cd dotnet-docs-samples/eventarc/audit-storage
   

   Node.js

   git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git
   cd nodejs-docs-samples/eventarc/audit-storage
   

   Python

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
   cd python-docs-samples/eventarc/audit-storage
   

2. Crie o contêiner e faça upload dele para o Cloud Build:

    gcloud builds submit --tag gcr.io/PROJECT_ID/helloworld-events
   

3. Implante a imagem do contêiner no Cloud Run:

    gcloud run deploy helloworld-events \
        --image gcr.io/PROJECT_ID/helloworld-events \
        --allow-unauthenticated
   

   Quando a implantação for bem-sucedida, a linha de comando exibirá o URL de serviço.

   Agora que você implantou o serviço de receptor de eventos chamado helloworld-events no Cloud Run, configure o gatilho.

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.

1. Crie um gatilho que filtre edventos do Cloud Storage e que use a conta de serviço parão do Compute Engine.

    gcloud eventarc triggers create storage-events-trigger \
        --destination-run-service=helloworld-events \
        --destination-run-region=us-central1 \
        --event-filters="type=google.cloud.storage.object.v1.finalized" \
        --event-filters="bucket=PROJECT_ID-bucket" \
        --service-account=[e-mail]
   

   Isso gera um gatilho chamado storage-events-trigger.

   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. Para confirmar se storage-events-trigger foi criado, execute:

    gcloud eventarc triggers list --location=us-central1
   

   A saída será assim:

    NAME                    TYPE                                      DESTINATION_RUN_SERVICE  DESTINATION_RUN_PATH  ACTIVE
    storage-events-trigger  google.cloud.storage.object.v1.finalized  helloworld-events                              Yes
   

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

Gerar e visualizar um evento

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, filtre as entradas e retorne a saída no formato JSON:

   gcloud logging read 'textPayload: "Detected change in Cloud Storage bucket"'
   

3. Procure uma entrada de registro semelhante a esta:

   "textPayload": "2021/08/09 19:04:25 Detected change in Cloud Storage bucket: objects/random.txt"
   

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

Parabéns! 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

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados nesta página, exclua o projeto do Google Cloud com esses recursos.

O Cloud Run não gera custos quando o serviço não está em uso, mas ainda é possível receber cobranças pelo armazenamento da imagem do contêiner no Container Registry, pelo armazenamento de arquivos no bucket do Cloud Storage e por recursos do Eventarc.

Você pode:

1. Excluir a imagem.

2. Excluir o bucket de armazenamento.

3. Excluir o gatilho do Eventarc.

Se preferir, exclua o projeto do Google Cloud para evitar cobranças. A exclusão do projeto do Google Cloud interrompe o faturamento de todos os recursos usados no projeto.

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.

Exclua um projeto do Google Cloud:

gcloud projects delete PROJECT_ID

A seguir

• Criar contêineres
• Executar um job do Cloud Run em um fluxo de trabalho usando um gatilho do Eventarc.
• Desenvolver serviços do Cloud Run