Encaminhar eventos de alertas do Firebase para o GKE

Visualização — Eventarc for GKE destinations

Esse recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos de serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Um gatilho do Eventarc declara seu interesse em um determinado evento ou conjunto de eventos. É possível configurar o encaminhamento de eventos especificando filtros para o gatilho, incluindo a origem do evento e o serviço de destino do Google Kubernetes Engine (GKE) em execução em um cluster do GKE. Os destinos só podem incluir serviços em execução em clusters (públicos ou privados) do GKE com endpoints públicos. Para segmentar serviços em clusters do GKE com endpoints particulares, encaminhe eventos para endpoints HTTP internos.

O Eventarc entrega eventos ao receptor de eventos no formato CloudEvents por uma solicitação HTTP.

Nestas instruções, mostramos como configurar o roteamento de eventos para o serviço do GKE que é acionado por um evento Firebase Alerts direto. Para saber mais, consulte a lista de eventos diretos compatíveis.

Observação: se os eventos de registro direto e de auditoria forem compatíveis com um provedor do Google, recomendamos criar um gatilho que filtre o evento direto. Os eventos diretos oferecem várias vantagens sobre os eventos de registro de auditoria. Para mais informações, consulte Encaminhamentos de eventos.

Antes de começar

Ative a Identidade da carga de trabalho no cluster do GKE em que o serviço de destino está sendo executado. A Identidade da carga de trabalho é necessária para configurar corretamente o Encaminhador de eventos. Ela é a maneira indicada de acessar os serviços do Google Cloud usando aplicativos executados no GKE devido às propriedades de segurança e capacidade de gerenciamento.

Identidade da carga de trabalho

Os aplicativos em execução no GKE podem precisar de acesso às APIs do Google Cloud. A Identidade da carga de trabalho permite que uma conta de serviço do Kubernetes no cluster do GKE atue como uma conta de serviço do IAM. Os pods que usam a conta de serviço configurada do Kubernetes serão autenticados automaticamente como a conta de serviço do IAM ao acessar as APIs do Google Cloud. Com o uso da Identidade da carga de trabalho, é possível atribuir autorizações e identidades detalhadas e distintas para cada aplicativo no cluster. Permissões específicas precisam ser concedidas à conta de serviço do gatilho do Eventarc. Neste documento, consulte as etapas para Criar uma conta de serviço.

Para mais informações sobre como ativar e configurar a Identidade da carga de trabalho nos clusters do GKE, consulte Usar a Identidade da carga de trabalho.

Encaminhador de eventos

O encaminhador de eventos do Eventarc extrai novos eventos do Eventarc e os encaminha para o destino do GKE. Esse componente atua como mediador entre a camada de transporte do Pub/Sub e o serviço de destino. Ele funciona em serviços atuais e também oferece suporte a serviços de sinalização (incluindo os não expostos fora do cluster totalmente gerenciado), além de simplificar a configuração e a manutenção. No nível da rede, para receber eventos em um serviço do GKE, não é necessário abrir o serviço para o tráfego externo, já que todos os eventos são entregues de uma origem que está no mesmo cluster do GKE.

O ciclo de vida do encaminhador de eventos é gerenciado pelo Eventarc. Se você excluir acidentalmente o encaminhador de eventos, o Eventarc vai restaurar esse componente.

Para cada gatilho que direciona para um destino do GKE, o encaminhador de eventos (um pod gke-forwarder configurado especificamente) realiza as seguintes ações:

1. Ele usa a API Pub/Sub para abrir uma conexão StreamingPull com o transportador de gatilho (um tópico e uma assinatura do Pub/Sub) e recebe eventos conforme eles ficam disponíveis.

2. Ele transforma eventos para o formato do CloudEvents correto, os codifica e os entrega como uma solicitação HTTP POST para o serviço de destino do GKE.

O agente de serviço do Eventarc precisa de permissão para executar e atualizar regularmente a instância gke-forwarder. Essa permissão precisa ser concedida uma vez por projeto. Para mais detalhes, neste documento, consulte Ativar destinos do GKE.

Preparar para criar um gatilho

Para cada gatilho que segmenta um serviço do GKE, o Eventarc cria um componente de encaminhamento de eventos. O Eventarc exige permissões para instalar o componente e gerenciar recursos no cluster do GKE. Antes de criar um gatilho do Eventarc para destinos do GKE, conclua as seguintes tarefas.

Console

1. No Console do Google Cloud, na página do seletor de projetos, selecione ou crie 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.

   Acessar o seletor de projetos

2. Ative as APIs Eventarc, Eventarc Publishing, Google Kubernetes Engine e Resource Manager.

   Ative as APIs

3. Se aplicável, ative a API relacionada aos eventos diretos. Por exemplo, para eventos Firebase Alerts, ative a API Firebase Alerts.

4. Se você ainda não tiver uma, crie uma conta de serviço gerenciada pelo usuário e conceda a ela os papéis e as permissões necessários para que o Eventarc gerencie os eventos do serviço de destino.

   1. No Console do Google Cloud, acesse a página Criar conta de serviço.

      Acesse "Criar conta de serviço"

   2. Selecione o projeto.

   3. No campo Nome da conta de serviço, insira um nome. O Console do Google Cloud preenche o campo ID da conta de serviço com base nesse nome.

      No campo Descrição da conta de serviço, insira uma descrição. Por exemplo, Service account for event trigger.

   4. Clique em Criar e continuar.

   5. Para fornecer o acesso apropriado, na lista Selecionar um papel, escolha os papéis necessários do Identity and Access Management (IAM) para conceder à sua conta de serviço. Para mais informações, consulte Papéis e permissões para destinos do GKE.

      Para papéis adicionais, clique em Adicionar outro papel e adicione os papéis adicionais.

   6. Clique em Continuar.

   7. Para concluir a criação da conta de serviço, clique em Concluído.

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Ative as APIs Eventarc, Eventarc Publishing, Google Kubernetes Engine e Resource Manager.

   gcloud services enable eventarc.googleapis.com \
       eventarcpublishing.googleapis.com \
       container.googleapis.com \
       cloudresourcemanager.googleapis.com

3. Se aplicável, ative a API relacionada aos eventos diretos. Por exemplo, para eventos Firebase Alerts, ative firestore.googleapis.com.

4. Se você ainda não tiver uma, crie uma conta de serviço gerenciada pelo usuário e conceda a ela os papéis e as permissões necessários para que o Eventarc possa gerenciar eventos para o destino pretendido do GKE.

   1. Crie a conta de serviço:

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
      

      Substitua SERVICE_ACCOUNT_NAME pelo nome da conta de serviço. Ele precisa ter entre 6 e 30 caracteres e pode conter letras minúsculas, caracteres alfanuméricos e traços. Depois de criar uma conta de serviço, não é possível alterar o nome dela.

   2. Conceda os papéis ou as permissões necessários do Identity and Access Management (IAM). Para mais informações, consulte Papéis e permissões para destinos do GKE.

Ativar destinos do GKE

Para permitir que o Eventarc gerencie recursos no cluster do GKE, ative os destinos do GKE e vincule o agente de serviço do Eventarc aos papéis necessários.

1. Ative os destinos do GKE para o Eventarc:

   gcloud eventarc gke-destinations init
   

2. No prompt para vincular os papéis necessários, digite y.

   Os papéis a seguir estão vinculados:

   • roles/compute.viewer
   • roles/container.developer
   • roles/iam.serviceAccountAdmin

Criar um gatilho

É possível criar um gatilho do Eventarc usando a CLI do Google Cloud ou o console do Google Cloud.

Observação: a filtragem é feita por uma correspondência exata e não permite caracteres curinga ou expressões regulares. No entanto, é possível usar a sinalização --event-filters-path-pattern no comando da gcloud CLI a seguir ou definir um padrão de caminho usando o console. Para mais informações, consulte Entender os padrões de caminho.

Console

1. No Console do Google Cloud, acesse a página Gatilhos do Eventarc.

   Acessar gatilhos

2. Clique em Criar gatilho.
3. Digite um Nome de gatilho.

   Esse é o ID do gatilho e precisa começar com uma letra. Ele pode conter até 63 letras minúsculas, números ou hífens.

4. Em Tipo de gatilho, selecione Fontes do Google.
5. Na lista Provedor de eventos, selecione Firebase Alerts.

   O nome do provedor de eventos usado na documentação do Google Cloud associada pode não ter o prefixo Cloud ou Google Cloud. Por exemplo, no console, o Memorystore para Redis é chamado de Google Cloud Memorystore para Redis.

6. Na lista Tipo de evento, nos eventos Diretos, selecione um tipo de evento.
7. Para especificar a codificação do payload do evento, na lista Tipo de conteúdo de dados do evento, selecione application/json ou application/protobuf.

   Um payload de evento formatado em JSON é maior que um formatado em Protobuf. Isso pode afetar a confiabilidade dependendo do destino do evento e dos limites do tamanho do evento. Saiba mais em Problemas conhecidos.

8. Na lista Região, selecione global (global).

   Saiba mais em Locais do Eventarc.

9. No campo Atributo 1, o ID do recurso alerttype atua como um filtro de evento. Selecione um operador para esse filtro:
   • Igual
   • Padrão de caminho

     Para mais informações, consulte Entender os padrões de caminho.

10. No campo Valor do atributo 1, digite uma das seguintes opções:
    • appDistribution.inAppFeedback: o evento é enviado quando um testador envia feedback no app para um determinado app.
    • appDistribution.newTesterIosDevice: o evento é enviado quando um novo dispositivo testador do iOS está registrado para um determinado app.
    • billing.planAutomatedUpdate: o evento é enviado quando o plano de faturamento de um projeto do Firebase é atualizado automaticamente. Por exemplo, quando é feito o downgrade de um plano devido a problemas de pagamento
    • billing.planUpdate: o evento é enviado quando o plano de faturamento de um projeto do Firebase é modificado por um usuário. por exemplo, quando uma conta de faturamento é anexada ou desanexada de um projeto
    • crashlytics.missingSymbolFile: o evento é enviado quando o Firebase Crashlytics determina que não tem os símbolos de depuração adequados para simbolizar um relatório de erros recebido.
    • crashlytics.newAnrIssue: o evento é enviado quando um app tem um novo erro de "O app não está respondendo" (ANR, na sigla em inglês), e não a nenhum evento subsequente e idêntico.
    • crashlytics.newFatalIssue: o evento é enviado quando um app tem uma nova falha fatal (não para qualquer evento subsequente e idêntico).
    • crashlytics.newNonfatalIssue: o evento é enviado quando um app tem um novo erro não fatal (não para eventos idênticos e subsequentes).
    • crashlytics.regression: o evento é enviado quando ocorre uma falha no app devido a um problema marcado como fechado em uma versão anterior do app
    • crashlytics.stabilityDigest: o evento é enviado quando há uma notificação dos principais problemas em alta no Crashlytics.
    • crashlytics.velocity: o evento é enviado quando um único problema é responsável por causar uma falha em um número significativo de sessões do app.
    • performance.threshold: o evento é enviado quando o desempenho de uma métrica ultrapassa o limite definido.
11. Se preferir, filtre eventos para um ID específico do app do Firebase. Clique em Adicionar filtro e especifique o appid.
12. Selecione a conta de serviço que vai invocar seu serviço ou fluxo de trabalho.

    ou crie uma nova conta de serviço.

    Ele especifica o e-mail da conta de serviço do Identity and Access Management (IAM) associado ao gatilho e aos quais você já concedeu papéis específicos exigidos pelo Eventarc.

13. Na lista Destino do evento, selecione Kubernetes Engine.
14. Selecione um serviço.
    

    Esse é o nome do serviço que recebe os eventos do gatilho. O serviço precisa estar no mesmo projeto que o gatilho e receberá eventos como solicitações POST HTTP enviadas para o caminho de URL raiz (/) sempre que o evento for gerado.

15. Se preferir, especifique o Caminho do URL do serviço para enviar a solicitação recebida.

    Esse é o caminho relativo no serviço de destino para o qual os eventos do gatilho precisam ser enviados. Por exemplo: /, /route, route, route/subroute.

16. Clique em Criar.

Depois que um gatilho é criado, os filtros da origem de eventos não podem ser modificados. Crie um novo gatilho e exclua o antigo. Para mais informações, consulte Gerenciar acionadores.

gcloud

Para criar um gatilho, execute um comando gcloud eventarc triggers create com as flags obrigatórias e opcionais.

gcloud eventarc triggers create TRIGGER \
    --location=global \
    --destination-gke-cluster=DESTINATION_GKE_CLUSTER \
    --destination-gke-location=DESTINATION_GKE_LOCATION \
    --destination-gke-namespace=DESTINATION_GKE_NAMESPACE \
    --destination-gke-service=DESTINATION_GKE_SERVICE \
    --destination-gke-path=DESTINATION_GKE_PATH \
    --event-filters="type=google.firebase.firebasealerts.alerts.v1.published" \
    --event-filters="alerttype=ALERT_TYPE" \
    --event-data-content-type="EVENT_DATA_CONTENT_TYPE" \
    --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"

Substitua:

• TRIGGER: o ID do gatilho ou um identificador totalmente qualificado.
• DESTINATION_GKE_CLUSTER: o nome do cluster do GKE em que o serviço do GKE de destino que recebe eventos está em execução.
• DESTINATION_GKE_LOCATION: (opcional) a região do Compute Engine do cluster do GKE em que o serviço do GKE de destino está sendo executado. Se não for especificado, supõe-se que o cluster seja regional e esteja na mesma região que o gatilho.
• DESTINATION_GKE_NAMESPACE: (opcional) o namespace em que o serviço do GKE de destino está em execução. Se não for especificado, o namespace default será usado.
• DESTINATION_GKE_SERVICE: o nome do serviço do GKE que recebe os eventos do gatilho. O serviço pode estar em qualquer um dos locais compatíveis com o GKE e não precisa estar no mesmo local que o gatilho. No entanto, o serviço precisa estar no mesmo projeto que o gatilho e receberá eventos como solicitações POST HTTP enviadas para o caminho de URL raiz (/) sempre que o evento for gerado.
• DESTINATION_GKE_PATH: (opcional) o caminho relativo especificado no serviço de destino do GKE para o qual os eventos do gatilho precisam ser enviados. Por exemplo: /, /route, route, route/subroute.

• ALERT_TYPE: o tipo de alerta do Firebase e pode ser um dos valores a seguir:
  • appDistribution.inAppFeedback: o evento é enviado quando um testador envia feedback no app para um determinado app.
  • appDistribution.newTesterIosDevice: o evento é enviado quando um novo dispositivo testador do iOS está registrado para um determinado app.
  • billing.planAutomatedUpdate: o evento é enviado quando o plano de faturamento de um projeto do Firebase é atualizado automaticamente. Por exemplo, quando é feito o downgrade de um plano devido a problemas de pagamento
  • billing.planUpdate: o evento é enviado quando o plano de faturamento de um projeto do Firebase é modificado por um usuário. por exemplo, quando uma conta de faturamento é anexada ou desanexada de um projeto
  • crashlytics.missingSymbolFile: o evento é enviado quando o Firebase Crashlytics determina que não tem os símbolos de depuração adequados para simbolizar um relatório de erros recebido.
  • crashlytics.newAnrIssue: o evento é enviado quando um app tem um novo erro de "O app não está respondendo" (ANR, na sigla em inglês), e não a nenhum evento subsequente e idêntico.
  • crashlytics.newFatalIssue: o evento é enviado quando um app tem uma nova falha fatal (não para qualquer evento subsequente e idêntico).
  • crashlytics.newNonfatalIssue: o evento é enviado quando um app tem um novo erro não fatal (não para eventos idênticos e subsequentes).
  • crashlytics.regression: o evento é enviado quando ocorre uma falha no app devido a um problema marcado como fechado em uma versão anterior do app
  • crashlytics.stabilityDigest: o evento é enviado quando há uma notificação dos principais problemas em alta no Crashlytics.
  • crashlytics.velocity: o evento é enviado quando um único problema é responsável por causar uma falha em um número significativo de sessões do app.
  • performance.threshold: o evento é enviado quando o desempenho de uma métrica ultrapassa o limite definido.
  O operador de ALERT_TYPE precisa ser um destes:
  • Igual por exemplo, --event-filters="alerttype=appDistribution.inAppFeedback"
  • Padrão de caminho. Por exemplo, --event-filters-path-pattern="alerttype=appDistribution.*" ou --event-filters-path-pattern="alerttype=crashlytics.new*".

    Para mais informações, consulte Entender os padrões de caminho.

• EVENT_DATA_CONTENT_TYPE: (opcional) a codificação do payload do evento. Os valores podem ser application/json ou application/protobuf. A codificação padrão é application/json.

  Um payload de evento formatado em JSON é maior do que um formatado em Protobuf. Isso pode afetar a confiabilidade dependendo do destino do evento e dos limites dele no tamanho. Saiba mais em Problemas conhecidos.

• SERVICE_ACCOUNT_NAME: o nome da conta de serviço gerenciada pelo usuário.
• PROJECT_ID: é seu ID do projeto no Google Cloud.

Observações:

• A sinalização --location precisa ser global. Saiba mais em Locais do Eventarc.

• Essas sinalizações são necessárias:
  • --event-filters="type=google.firebase.firebasealerts.alerts.v1.published"
  • --event-filters="alerttype=ALERT_TYPE" ou --event-filters-path-pattern="alerttype=ALERT_TYPE"
• Opcionalmente, é possível filtrar eventos de um ID de app específico do Firebase usando a flag --event-filters="appid=APP_ID" e especificando uma correspondência exata.
• Após a criação de um gatilho, o tipo do filtro de evento não pode ser alterado. Para um tipo de evento diferente, é necessário criar um novo gatilho e excluir o antigo.
• A flag --service-account é usada para especificar o e-mail da conta de serviço do Identity and Access Management (IAM) associado ao gatilho.

Exemplo:

gcloud eventarc triggers create helloworld-trigger \
    --location=us-central1 \
    --destination-gke-cluster=gke-events-cluster \
    --destination-gke-location=us-central1-a \
    --destination-gke-namespace=default \
    --destination-gke-service=helloworld-events \
    --destination-gke-path=/ \
    --event-filters="type=google.firebase.firebasealerts.alerts.v1.published" \
    --event-filters="alerttype=crashlytics.velocity" \
    --service-account="${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"

Esse comando cria um gatilho chamado helloworld-trigger para o evento identificado como google.firebase.firebasealerts.alerts.v1.published e para um tipo de alerta crashlytics.velocity.

Terraform

É possível criar um gatilho para um destino do GKE usando o Terraform. Para mais detalhes, acesse Criar um gatilho usando o Terraform.

Observação: o gatilho é criado imediatamente, mas pode levar até dois minutos para que ele seja propagado e filtre eventos.

Listar um gatilho

É possível confirmar a criação de um gatilho listando os gatilhos do Eventarc usando a CLI do Google Cloud ou o console do Google Cloud.

Console

1. No Console do Google Cloud, acesse a página Gatilhos do Eventarc.

   Acessar gatilhos

   Confira nesta página os gatilhos em todos os locais e os detalhes como nomes, regiões, provedores de eventos, destinos e muito mais.

2. Para filtrar os gatilhos, siga estas etapas:

   1. Clique em Filtrar ou no campo Filtrar gatilhos.
   2. Na lista Propriedades, selecione uma opção para filtrar os gatilhos.

   É possível selecionar uma única propriedade ou usar o operador lógico OR para adicionar mais propriedades.

3. Para classificar gatilhos, ao lado de qualquer cabeçalho de coluna com suporte, clique em Ordenar.

gcloud

Execute o comando a seguir para listar os gatilhos:

gcloud eventarc triggers list --location=-

Esse comando lista os gatilhos em todos os locais e inclui detalhes como nomes, tipos, destinos e status.

A seguir

• Saiba mais sobre o Eventarc.
• Saiba como gerenciar gatilhos.