Pular para o conteúdo

Recursos

Notificações de alertas

O orbit-api pode publicar os alertas do Deck num canal do Slack, num canal do Microsoft Teams ou num espaço do Google Chat por meio de um webhook de entrada. Um admin configura cada destino em Alertas → Notificações: escolhe a plataforma, cola a URL do webhook, define quais alertas ele recebe, envia um teste e salva. Não há Alertmanager para operar, e nada precisa ser instalado na ferramenta de chat além do próprio webhook.

O que é enviado, e quando

A cada alerting.interval (30 segundos por padrão), o orbit-api lê os alertas de cada cluster com os reconhecimentos e silêncios definidos no Deck aplicados por cima, exatamente como a página de Alertas os mostra. Para cada canal ativo cujas regras aceitam um alerta:

MensagemEnviada quando
DisparadoO alerta se manteve pelo tempo de espera do canal (0, 2, 5 ou 10 minutos; 2 por padrão) e este canal ainda não foi avisado.
RepetiçãoEle continua disparado, continua aberto, e a repetição do canal (1 hora, 4 horas ou 24 horas; 4 horas por padrão, ou nunca) passou desde a última mensagem.
ResolvidoEle sumiu e este canal tinha sido avisado de que estava disparado, quando o canal envia mensagens de resolução (ligado por padrão).
  • Alertas reconhecidos ou silenciados não acionam ninguém. Não há primeira mensagem nem repetição enquanto um alerta está reconhecido ou silenciado. Quando um silêncio termina e o alerta continua, a mensagem de disparo sai na leitura seguinte. Um alerta que some depois de um canal ter sido avisado ainda envia a sua mensagem de resolução.
  • Agrupado. Tudo o que uma leitura tem para um canal sai como uma mensagem por tipo, então um incidente que dispara vinte alertas publica uma vez, não vinte. As mensagens saem no máximo uma por segundo.
  • Sem repetições depois de um restart. O que cada canal já recebeu fica guardado em ORBIT_DATA_DIR, então reiniciar o orbit-api não aciona de novo nem esquece uma mensagem de resolução que ainda deve.
  • Uma entrega que falha é refeita. A leitura seguinte envia de novo, depois de uma espera que dobra a partir do intervalo, até 5 minutos para aquele canal. Nada é marcado como enviado antes de o webhook aceitar.
  • Só clusters reais. Com ORBIT_DEMO_DATA=true, nada é enviado sozinho; a mensagem de teste continua saindo, para que a configuração possa ser experimentada.

Criando o webhook

O canal em que a mensagem chega é aquele para o qual o webhook foi criado: a escolha do canal acontece na ferramenta de chat, na hora de criar o webhook. Um webhook por canal; para levar os mesmos alertas a vários canais, crie um canal do Orbit para cada um.

Slack. No workspace do Slack, adicione o app Incoming Webhooks (ou crie um app do Slack com webhooks de entrada ligados), escolha o canal e copie a URL. Ela começa com https://hooks.slack.com/services/.

Microsoft Teams. Os conectores do Office 365 foram aposentados; o Teams recebe webhooks pelos Workflows. No canal, abra Workflows e escolha o modelo Post to a channel when a webhook request is received, selecione a equipe e o canal, e copie a URL gerada. Ela fica em logic.azure.com ou em environment.api.powerplatform.com.

Google Chat. No espaço, abra Apps e integrações → Webhooks, adicione um webhook com um nome e um avatar opcional, e copie a URL. Ela começa com https://chat.googleapis.com/v1/spaces/.

Escolhendo quais alertas um canal recebe

ConfiguraçãoPadrãoSignificado
Severidadescritical, warningQuais entre critical, warning e info ele recebe.
Clusterstodos os clustersSó estes clusters, quando houver algum na lista.
Namespacestodos os namespacesSó estes namespaces, quando houver algum na lista.
Espera2 minutosQuanto tempo um alerta precisa se manter antes da primeira mensagem.
Repetição4 horasA cada quanto tempo um alerta ainda disparado e aberto é publicado de novo; nunca é uma opção.
Mensagens de resoluçãoligadoSe um alerta que sumiu é publicado.
Avisos de segurançadesligadoPublica também um aviso quando a senha de qualquer conta é trocada ou um administrador a redefine, um segundo fator é ligado ou desligado, um e-mail muda, um token de API é criado, ou alguém digita a senha de uma conta com um código já usado.

Um aviso de segurança cita as contas, quem agiu e o endereço do cliente, no idioma do canal, e nunca uma senha, um código, um token ou um endereço de e-mail. Cada envio entra nas entregas do canal com o tipo security. Aponte para ele um canal que os seus administradores leem: o SRE Orbit não envia e-mail, então é assim que o titular de uma conta fica sabendo que as credenciais dela mudaram.

Deixando a mensagem do seu jeito

  • Emoji por severidade: um para critical, um para warning, um para info e um para resolvido (🔴 🟠 🔵 ✅ por padrão).
  • Título: um modelo com estas variáveis: {emoji}, {severity}, {name}, {summary}, {cluster}, {namespace}, {workload}, {since}, {link}. O padrão é {emoji} [{severity}] {name} · {cluster}. Uma linha de rodapé opcional aceita as mesmas variáveis.
  • Menção (só no Slack): @here ou @channel nas mensagens críticas.
  • Idioma: as palavras fixas da mensagem (resolvido, o texto do link, quantos a mais) em português ou em inglês.
  • Link: uma ação que abre o alerta no Deck, montada a partir de publicUrl (ou ORBIT_PUBLIC_URL). Vazio, o chart deriva o endereço do host do ingress; sem ingress, as mensagens saem sem link.

Enquanto o canal é editado, o Deck mostra uma prévia da mensagem na aparência da plataforma escolhida.

Segurança

  • URLs de webhook são segredos. Quem tem uma consegue publicar no canal. O orbit-api as guarda seladas com ORBIT_SEAL_KEY (AES-256-GCM), a mesma chave das conexões de banco, e nunca as devolve: o Deck mostra só o host e os últimos caracteres. Sem ORBIT_SEAL_KEY, um canal não pode ser salvo.
  • Só os hosts das próprias plataformas. Uma URL precisa ser HTTPS em hooks.slack.com, chat.googleapis.com, ou num host do Teams: Workflows em logic.azure.com ou environment.api.powerplatform.com, ou um conector legado em webhook.office.com (a Microsoft aposentou esses conectores; eles ainda são aceitos). O alerting.allowedHosts (ORBIT_ALERTING_ALLOWED_HOSTS) acrescenta hosts, para um proxy de saída ou uma nuvem soberana. Redirecionamentos não são seguidos.
  • Quem pode alterar. Listar, salvar, excluir, testar e pré-visualizar canais exige settings.manage. Pelo web, essas rotas exigem sessão e prova de mesma origem, sem token de operador, porque mudam o estado do próprio Orbit e nunca o cluster.
  • Auditado. Salvar, excluir e testar um canal são eventos de auditoria, alerting.channel.update, alerting.channel.delete e alerting.channel.test, sem a URL.
  • Saída de rede. Com networkPolicy.enabled e alerting.notifications.enabled (ligado por padrão), o orbit-api pode abrir TCP 443 para endereços públicos, nunca para faixas privadas nem para o endereço de metadados da nuvem. Desligado num cluster que aplica NetworkPolicy, os canais continuam sendo salvos, mas toda entrega falha na rede.

Configuração

ValorVariávelPadrão
alerting.notifications.enabled(só saída de rede)true
alerting.intervalORBIT_ALERTING_INTERVAL30s, no mínimo 10s
alerting.allowedHostsORBIT_ALERTING_ALLOWED_HOSTSnenhum
publicUrlORBIT_PUBLIC_URLderivado do ingress

Solução de problemas

  • Histórico de entregas. Cada canal guarda as suas últimas 50 entregas (horário, tipo, quantos alertas, o status HTTP do webhook e um erro curto, nunca a URL), e o card do canal mostra a última.
  • A métrica. orbit_api_alert_notifications_total{kind,result} conta as mensagens por tipo (firing, renotify, resolved, test) e por resultado (ok, error):
promql
sum by (kind) (increase(orbit_api_alert_notifications_total{result="error"}[1h]))
  • 403 ou 404 do webhook: o webhook foi apagado ou o seu workflow foi desligado; crie um novo e cole no canal.
  • 429: a plataforma está limitando a taxa; o orbit-api espera e tenta de novo sozinho.
  • Erros de rede em toda entrega: confira alerting.notifications.enabled e qualquer firewall ou proxy de saída entre o cluster e a plataforma.