Fundamentos do EventBridge

Um alarme do CloudWatch consegue reiniciar a única instância que as dimensões dele apontam. Ele não consegue fazer isto: quando qualquer instância marcada com Environment=prod entrar no estado stopped, abrir um OpsItem do Systems Manager, iniciar um runbook que captura a saída do console e avisar o time dono. Aqui não existe número para comparar com um limite. Nada sobe nem desce. Uma coisa simplesmente aconteceu, uma vez, com um recurso, e várias outras precisam acontecer por causa disso.

Essa é a lacuna que o EventBridge preenche. Ele é o roteador entre as coisas que acontecem na sua conta e as coisas que deveriam rodar em resposta.

Eventos são fatos; métricas são números

Vale acertar essa fronteira antes de qualquer outra coisa, porque metade das questões de diagnóstico deste domínio depende dela.

Uma métrica é uma série temporal de números. CPUUtilization numa instância é 4% às 09:00 e 71% às 09:01. Alarmes existem para observar essa série e decidir quando os números ficaram ruins por tempo suficiente para importar.

Um evento é um documento JSON descrevendo algo que ocorreu, entregue uma vez, perto do momento em que ocorreu. Uma instância mudou de estado. Um snapshot de EBS terminou. Alguém chamou AuthorizeSecurityGroupIngress. Uma notificação do AWS Health abriu para uma região. Nenhum desses é um número, então nenhum alarme consegue observá-los.

Teste rápido: se uma pessoa descreveria a situação com um verbo no passado, é evento. Se descreveria com um número e uma comparação, é métrica.

Os dois se conectam, e a prova gosta dessa conexão. Um alarme do CloudWatch mudando de estado é, ele mesmo, um evento no bus default (aws.cloudwatch, detail-type CloudWatch Alarm State Change). Então a resposta para "meu alarme precisa acionar um reparo de cinco etapas" é quase sempre: mantenha o alarme e deixe o EventBridge corresponder ao evento de mudança de estado dele e iniciar o fluxo.

O envelope do evento

Todo evento tem a mesma estrutura externa, com a carga específica do serviço aninhada dentro de detail. Este é um evento real de mudança de estado do EC2:

{
  "version": "0",
  "id": "6a7e8feb-b491-4cf7-a9f1-bf3703467718",
  "detail-type": "EC2 Instance State-change Notification",
  "source": "aws.ec2",
  "account": "111122223333",
  "time": "2017-12-22T18:43:48Z",
  "region": "us-west-1",
  "resources": [
    "arn:aws:ec2:us-west-1:123456789012:instance/i-1234567890abcdef0"
  ],
  "detail": {
    "instance-id": "i-1234567890abcdef0",
    "state": "terminated"
  }
}

Os dois campos contra os quais você vai escrever pattern o tempo todo são source (qual serviço ou aplicação emitiu isto, aws.* para serviços AWS) e detail-type (que tipo de evento é este dentro daquele source). Tudo que é específico do evento fica embaixo de detail, e o formato é definido pelo serviço que emite.

Dois detalhes sobre resources pegam bastante gente. Eventos de chamada de API originados do CloudTrail muitas vezes vêm com resources vazio, então um pattern que filtra por esse campo nunca corresponde. E serviços globais como IAM e Route 53 existem apenas em US East (N. Virginia), então os eventos de chamada de API deles estão disponíveis só naquela região. Uma regra em eu-west-1 esperando por uma mudança de policy do IAM vai esperar para sempre.

Event buses: default, customizado, de parceiro

Um event bus é um roteador que recebe eventos e os oferece às regras anexadas a ele. Existem três tipos, e a distinção não é cosmética.

O event bus default existe em toda conta e região, e é para onde os serviços AWS entregam os eventos deles. Isso não é configurável. Quando uma instância EC2 muda de estado, o evento vai para o bus default daquela conta, ponto final.

Um event bus customizado é um que você cria. Suas próprias aplicações publicam nele com PutEvents, e você pode encaminhar eventos de um bus para outro (inclusive entre contas e regiões) tornando um bus o target de uma regra. Buses customizados existem para que eventos de aplicação não precisem dividir espaço de regras com o tráfego dos serviços AWS, e para que você anexe uma resource-based policy que permita a outras contas específicas publicarem ali.

Um partner event bus recebe eventos de um provedor SaaS por meio de um partner event source que você associa a ele.

A confusão para matar agora: criar um bus customizado não move os eventos de serviços AWS para ele. Se um cenário diz "isole nossos eventos de aplicação do ruído dos serviços AWS", o bus customizado está certo. Se um cenário diz "receber eventos do S3 no nosso bus customizado", a resposta honesta é que eles chegam no bus default e você encaminha.

Cotas que vale guardar: 100 event buses por conta por região, 300 regras por event bus na maioria das regiões e 5 targets por regra (esta última não é ajustável).

Regras: o pattern é o filtro

Uma regra tem um filtro e uma lista de targets. O filtro é ou um event pattern (corresponder eventos por conteúdo) ou uma schedule expression (disparar num cron ou numa rate expression). É um ou outro.

O pattern tem o mesmo formato do evento que ele corresponde, e é essa decisão de design que deixa os patterns legíveis. Este pattern seleciona encerramentos de instância EC2:

{
  "source": ["aws.ec2"],
  "detail-type": ["EC2 Instance State-change Notification"],
  "detail": {
    "state": ["terminated"]
  }
}

São três requisitos separados, e todos precisam valer.

Como a correspondência de pattern funciona de verdade

Quatro regras governam todo pattern que você vai escrever ou depurar. Aprenda as quatro aqui e a maioria dos problemas de "minha regra não dispara" vira um diagnóstico de 30 segundos.

A correspondência é um teste de subconjunto. Todo campo que você nomeia precisa bater. Todo campo que você omite é ignorado. Então {"source": ["aws.ecs"]} corresponde a todos os eventos de ECS no bus. É esse o mecanismo por trás de regras que acabam disparando centenas de vezes por dia: o pattern estava pouco específico, não errado.

Um array significa OR. "state": ["stopped", "terminated"] corresponde a qualquer um dos dois valores. Para exigir duas condições, nomeie dois campos, o que é um AND implícito. Existe uma armadilha relacionada: se você escrever a mesma chave duas vezes num pattern, o EventBridge usa só a última referência e ignora a primeira em silêncio.

A correspondência é exata, caractere a caractere. A maioria dos serviços AWS trata : e / num ARN como intercambiáveis. O EventBridge não trata. Se o evento traz instance/i-0abc e seu pattern diz instance:i-0abc, nada corresponde, e nada te avisa por quê.

Operadores de comparação funcionam apenas em nós folha. $or e anything-but são as duas exceções.

Esses operadores são a segunda metade da fluência em patterns:

Duas restrições sobre os dois últimos. O wildcard é suportado em regras de event bus, mas não em filtros de pipe, e cada event bus permite apenas 30 regras contendo wildcards, uma cota que você não consegue aumentar. E um $or que expande para mais de 1.000 combinações de regra é rejeitado com InvalidEventPatternException; a contagem de combinações é o produto da quantidade de argumentos de cada array $or do pattern.

Um event pattern é limitado a 2.048 caracteres por padrão.

O hábito de depuração mais útil aqui é o EventBridge Sandbox no console (ou a API TestEventPattern). Cole um evento real, cole seu pattern, receba um sim ou um não. Não custa nada e resolve discussões que de outro jeito consomem uma tarde.

Targets e os dois modelos de permissão

Até 5 targets por regra. A lista é longa, e os que importam para remediação são Lambda, SNS, SQS, Step Functions, Systems Manager Automation, Systems Manager Run Command, OpsItem do Systems Manager, response plans do Incident Manager, tarefas ECS, API destinations e outros event buses. Alguns targets nem recebem o evento: RebootInstances, StopInstances e TerminateInstances do EC2 tratam o evento apenas como gatilho para aquela chamada de API.

As permissões funcionam de duas maneiras, e saber qual se aplica a qual target é matéria de prova.

Uma IAM execution role. Você define RoleArn no target, a trust policy da role permite que events.amazonaws.com a assuma, e a permission policy concede a ação de que o target precisa. É assim que a maioria dos targets funciona, e é a única opção para targets como Systems Manager Automation e ECS.

Uma resource-based policy no target. Para Lambda, SNS e SQS, se nenhuma execution role estiver configurada, o EventBridge recorre a uma policy no próprio recurso alvo concedendo a events.amazonaws.com permissão de invocar ou publicar.

A consequência prática é um cenário favorito. Crie a regra pelo console e ela funciona, porque o console anexa a resource-based policy por você. Crie a mesma regra com PutTargets e o target nunca é invocado, porque nada anexou aquela policy. A métrica TriggeredRules mostra que a regra disparou; Invocations não mostra nada chegando. Mais duas variações do mesmo formato: uma fila SQS ou um tópico SNS criptografados precisam de kms:Decrypt e kms:GenerateDataKey concedidos a events.amazonaws.com na key policy, e o EventBridge não consegue usar uma fila SQS criptografada com uma AWS owned key de jeito nenhum.

Transformação de entrada: remodelar o evento

Alguns targets querem o evento como está. Outros precisam de uma estrutura específica, ou de uma linha legível por gente. O input transformer resolve isso em duas partes.

O input path define variáveis a partir do evento com JSON path:

{
  "timestamp": "$.time",
  "instance": "$.detail.instance-id",
  "state": "$.detail.state"
}

O input template é o que o target de fato recebe:

{
  "instance": <instance>,
  "state": <state>,
  "note": "a instância \"<instance>\" está em <state>"
}

Você tem até 100 variáveis, mais as reservadas que não precisa definir: aws.events.rule-arn, aws.events.rule-name, aws.events.event.ingestion-time e aws.events.event.json para a carga original inteira.

O modo de falha esperado: o EventBridge não valida input paths quando você salva a regra. Um path que não corresponde a nada produz nenhuma variável, e aquele campo simplesmente desaparece da saída. Sem erro, sem aviso, apenas um target recebendo menos do que você pretendia.

Regras agendadas e o EventBridge Scheduler

Uma regra pode disparar por agendamento em vez de por pattern, usando rate(...) ou cron(...). Dois fatos sobre regras agendadas que viram questão: a expressão é avaliada em UTC, e a resolução mais fina é de um minuto, com a invocação caindo em algum ponto dentro daquele minuto em vez de no segundo exato.

O EventBridge Scheduler é o serviço separado e dedicado a agendamento, e é a resposta certa sempre que um cenário enfatiza escala ou flexibilidade por agendamento. Ele lida com milhões de schedules, aceita invocações únicas além das recorrentes, entende fusos horários, oferece flexible time windows para espalhar carga e alcança mais de 270 serviços pelo universal target parameter. Regras agendadas são limitadas pela cota de regras por bus e pelo limite de 5 targets por regra; o Scheduler não é.

Pista de palavra-chave: "milhares de agendamentos por cliente", "uma única vez" ou "no fuso horário local do cliente" aponta para o Scheduler. "Reagir quando este serviço AWS fizer algo" aponta para uma regra.

Dicas para a prova

• Procure um verbo no passado no enunciado. "Quando uma instância for encerrada", "quando um snapshot terminar", "quando alguém mudar uma policy" são todos EventBridge. "Quando a CPU passar de 80% por 10 minutos" é alarme.
• Uma regra que dispara muito mais do que o esperado tem um pattern pouco específico. Uma regra que nunca dispara costuma ser uma de três coisas: um pattern com a pontuação errada no ARN, um evento de serviço global esperado fora de us-east-1, ou um filtro sobre o campo resources que eventos vindos do CloudTrail deixam vazio.
• TriggeredRules maior que zero com Invocations em zero significa que o roteamento funcionou e as permissões não. Essa é a questão de resource-based policy em forma de métrica.
• Alarmes compostos não executam ações de EC2 nem de Auto Scaling. Quando um cenário precisa que uma condição composta dirija um reparo de várias etapas, o alarme composto notifica e uma regra do EventBridge corresponde ao evento de mudança de estado do alarme.
• Event buses customizados nunca recebem eventos de serviços AWS diretamente. Se uma alternativa afirmar o contrário, elimine.
• Guarde os três números fixos: 5 targets por regra (não ajustável), 300 regras por event bus, 100 event buses por conta por região.

O modelo mental para levar: o bus não escolhe um destino. Toda regra anexada a um bus vê todo evento que chega, decide sozinha se corresponde e entrega aos próprios targets. Adicione uma regra e você adiciona um consumidor sem encostar em nada que já está rodando, e é isso que "baixo acoplamento" significa na prática aqui. Em seguida você vai ver o Pipes, que cobre o caso em que um bus é a ferramenta errada: um fluxo específico que precisa dos registros filtrados, enriquecidos com uma consulta e entregues a exatamente um destino.