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:
| Mensagem | Enviada quando |
|---|---|
| Disparado | O 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ção | Ele 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. |
| Resolvido | Ele 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ção | Padrão | Significado |
|---|---|---|
| Severidades | critical, warning | Quais entre critical, warning e info ele recebe. |
| Clusters | todos os clusters | Só estes clusters, quando houver algum na lista. |
| Namespaces | todos os namespaces | Só estes namespaces, quando houver algum na lista. |
| Espera | 2 minutos | Quanto tempo um alerta precisa se manter antes da primeira mensagem. |
| Repetição | 4 horas | A cada quanto tempo um alerta ainda disparado e aberto é publicado de novo; nunca é uma opção. |
| Mensagens de resolução | ligado | Se um alerta que sumiu é publicado. |
| Avisos de segurança | desligado | Publica 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):
@hereou@channelnas 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(ouORBIT_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. SemORBIT_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 emlogic.azure.comouenvironment.api.powerplatform.com, ou um conector legado emwebhook.office.com(a Microsoft aposentou esses conectores; eles ainda são aceitos). Oalerting.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. Peloweb, 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.deleteealerting.channel.test, sem a URL. - Saída de rede. Com
networkPolicy.enabledealerting.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
| Valor | Variável | Padrão |
|---|---|---|
alerting.notifications.enabled | (só saída de rede) | true |
alerting.interval | ORBIT_ALERTING_INTERVAL | 30s, no mínimo 10s |
alerting.allowedHosts | ORBIT_ALERTING_ALLOWED_HOSTS | nenhum |
publicUrl | ORBIT_PUBLIC_URL | derivado 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):
sum by (kind) (increase(orbit_api_alert_notifications_total{result="error"}[1h]))403ou404do 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.enablede qualquer firewall ou proxy de saída entre o cluster e a plataforma.