O que faz este módulo #

Uma instância tem muita coisa para contar: o fail2ban baniu um IP, o aide viu mudar um ficheiro do sistema, a cópia de segurança de ontem à noite falhou, o disco raiz vai nos 95 %. Se cada módulo avisa à sua maneira —um email aqui, uma linha de log ali— ninguém dá por nada, e com dez instâncias o problema multiplica-se por dez.

O módulo global-alerts é o barramento central de alertas do imaxe: um único comando por onde passam todos esses avisos e um único destino onde chegam, um tópico Amazon SNS partilhado por toda a tua frota. A partir daí o SNS distribui como quiseres: email, SMS, uma função Lambda, uma fila SQS, o teu sistema de piquete. Publica com a função IAM da instância (permissão sns:Publish), por isso não há nenhuma credencial a guardar. E filtra o ruído antes de enviar: um limiar de severidade descarta o que não chega ao nível que te interessa e uma janela de desduplicação evita que o mesmo alerta te acorde quarenta vezes.

Se o SNS não estiver disponível —rede em baixo, função ainda sem permissões, região inacessível— o alerta não se perde: fica em fila no disco e um timer do systemd repete-o a cada 5 minutos.

Antes de começar

Precisas do ARN de um tópico SNS (arn:aws:sns:região:conta:tópico) e que a instância possa publicar nele. Se lançaste a AMI a partir do lançador, o modelo de CloudFormation já cria o tópico, subscreve o teu email, cria a função IAM com sns:Publish e passa o ARN à instância como tag: o módulo configura-se sozinho e não há nada a fazer aqui.

Guia rápidotarefas passo a passo

Tarefas comuns #

Escolhe o que queres fazer. Cada receita traz o comando já escrito — troca o ARN e o texto pelos teus, e carrega em Copiar.

Definir o tópico SNS Enviar um alerta de teste Enviar um alerta a partir de um script Ver o estado do barramento Baixar o ruído Ver a fila e repetir Silenciar o módulo

1

Definir o tópico SNS

Diz à instância onde tem de publicar os seus avisos.

Liga-te por SSH ao teu servidor com o utilizador ubuntu.

Aponta o módulo ao ARN do teu tópico. A região deduz-se do próprio ARN, por isso normalmente não é preciso indicá-la:

terminal

$ sudo imaxe global-alerts configure \
    --topic-arn arn:aws:sns:eu-west-1:123456789012:imaxe-alerts

Várias instâncias a publicar no mesmo tópico? Dá a cada uma uma etiqueta de origem reconhecível com --source (por omissão usa-se o hostname):

terminal

$ sudo imaxe global-alerts configure --source web-producao-1

A configuração fica em /etc/imaxe/global-alerts.yml e o envio fica ativado. Continua com a receita Enviar um alerta de teste.

2

Enviar um alerta de teste

Confirma que a função IAM publica mesmo antes de confiares no canal.

Publica um alerta de teste no tópico configurado:

terminal

$ sudo imaxe global-alerts test

O teste salta o limiar e a desduplicação —sai sempre— e, se algo falhar, devolve-te o erro real da AWS em vez de pôr em fila em silêncio. Vê a caixa do endereço subscrito ao tópico (e a pasta de spam).

Se vires o MessageId e o aviso te chegar, o canal funciona. Se sair AuthorizationError, falta à instância a permissão sns:Publish sobre esse tópico.

3

Enviar um alerta a partir de um script

O mesmo canal que os módulos usam, disponível para o que é teu.

Um alerta com a sua severidade e a sua origem:

terminal

$ sudo imaxe global-alerts send --severity critical \
    --source backup --subject "cópia falhada" \
    "a cópia noturna da base de dados terminou com erro"

Se o texto for gerado por outro comando, passa-o por stdin usando - como mensagem:

terminal

$ df -h / | sudo imaxe global-alerts send --severity warning -

Em algo que corre de poucos em poucos minutos, dá-lhe uma chave de desduplicação estável: dentro da janela configurada só sai o primeiro:

terminal

$ sudo imaxe global-alerts send --severity warning \
    --dedup-key disco-raiz-cheio "disco raiz a 95%"

O alerta viaja como JSON para o tópico, com a instância, a região e a marca temporal já incluídas. Sem --dedup-key o módulo deriva uma a partir de origem + severidade + assunto.

4

Ver o estado do barramento

Tópico, região, CLI da AWS e alertas pendentes, num relance.

Resumo do estado atual:

terminal

$ sudo imaxe global-alerts status

Para verificar que configuração manda mesmo —incluindo a que chega pelas tags da instância, que têm prioridade sobre o ficheiro—:

terminal

$ sudo imaxe global-alerts show
$ sudo imaxe global-alerts status --json

Saberás se há tópico configurado, em que região se publica e quantos alertas esperam na fila. Com --json, pronto para um painel ou um script.

5

Baixar o ruído

Sobe o limiar de severidade e alarga a janela de desduplicação.

Se só queres saber do que importa, descarta tudo o que esteja abaixo de warning:

terminal

$ sudo imaxe global-alerts configure --min-severity warning

A janela de desduplicação não tem flag: ajusta-se no ficheiro de configuração. Sobe-a se um mesmo alerta se repetir muito:

/etc/imaxe/global-alerts.yml

dedup_window: 1h   # 30s, 5m, 1h… (5m por omissão)

Os alertas abaixo do limiar são descartados antes de saírem (não vão para a fila) e os repetidos dentro da janela são suprimidos. O test continua a publicar sempre, por isso não perdes a forma de verificar o canal.

6

Ver a fila e repetir

O que ficou pendente quando o SNS não respondeu, e como forçar o envio.

Vê o que está pendente e as últimas chaves enviadas:

terminal

$ sudo imaxe global-alerts history

A repetição já é feita por um timer do systemd a cada 5 minutos, mas podes forçá-la depois de corrigires a permissão ou a rede:

terminal

$ sudo imaxe global-alerts flush
$ systemctl status imaxe-global-alerts-flush.timer

Verás quantos saíram e quantos continuam à espera. Se o primeiro voltar a falhar, a passagem para aí e deixa o resto para a tentativa seguinte: não se descarta nada.

7

Silenciar o módulo

Deixa de publicar sem perder a configuração.

Desativa o envio de alertas e retira o timer de repetição:

terminal

$ sudo imaxe global-alerts remove

O tópico, a região e o resto dos ajustes ficam no ficheiro: para voltar a ativá-lo basta um configure, que reabilita o módulo.

A instância deixa de publicar. Os send seguintes não falham: avisam por stderr que o módulo está desativado e terminam com código 0.

Sem função IAM não há alertas

O módulo publica com as credenciais da função da instância, não com chaves guardadas. Se a função não permitir sns:Publish sobre esse tópico, os alertas vão ficando em fila uns atrás dos outros sem nunca chegar. Um imaxe global-alerts test diz-to na hora, com o erro tal como a AWS o devolve.

Referência CLIcomandos, flags e ficheiros

Sinopse #

uso

imaxe global-alerts <subcomando> [--topic-arn ARN] [--severity NÍVEL] [flags]

Todos os subcomandos exigem privilégios de root (usa sudo) porque escrevem em /etc/imaxe/, mantêm o estado em /var/lib/imaxe/ e gerem uma unidade do systemd. Não há segredos a manusear: a publicação vai pela função IAM da instância. Junta --json a status, show, history ou flush para obteres saída legível por máquina.

Subcomandos #

Subcomando	O que faz	Flags relevantes
status	Estado: tópico configurado, região efetiva, CLI da AWS disponível e alertas em fila.	--json
configure	Fixa o tópico SNS e as opções de envio. Reabilita o módulo se estava desativado.	--topic-arn, --region, --source, --min-severity
send	Publica um alerta. É o canal que o operador e os restantes módulos usam.	--severity, --source, --subject, --dedup-key
test	Publica um alerta de teste saltando limiar e desduplicação, e reporta o erro real se falhar.	--severity
show	Mostra a configuração efetiva (ficheiro + tags da instância já aplicadas).	--json
history	Alertas pendentes em fila e chaves de desduplicação enviadas recentemente.	--json
flush	Repete os alertas em fila. O timer do systemd também o executa.	--json
remove	Desativa o envio e retira o timer. Conserva a configuração.	—

Argumentos e flags #

Flag	Tipo	Por omissão	Descrição
--topic-arn obrig.	string	—	ARN do tópico SNS de destino (`arn:aws:sns:região:conta:tópico`). Sem ele o módulo não pode publicar.
--region	string	do ARN	Região da AWS. Se for omitida, deriva-se do ARN do tópico; se também não, do IMDS ou de `AWS_REGION`.
--source	string	hostname	Etiqueta de origem. Em `configure`, a da instância; em `send`, a desse alerta em concreto (p. ex. o módulo que o emite).
--min-severity	string	info	Limiar: descarta os alertas abaixo deste nível. Valores: `info`, `warning`, `critical`.
--severity	string	info	Em `send`/`test`: nível deste alerta. Aceitam-se as formas curtas `warn` e `crit`.
--subject	string	da mensagem	Assunto curto. Se for omitido, deriva-se da própria mensagem.
--dedup-key	string	derivada	Chave de desduplicação: suprime repetições dentro de `dedup_window`. Por omissão calcula-se com origem + severidade + assunto.
<mensagem> obrig.	posicional	—	Em `send`: o texto do alerta, ou `-` para o ler do `stdin`.
--json	bool	false	Em `status`, `show`, `history` e `flush`, emite o resultado como JSON no `stdout`.

Descartar não é falhar

Quando um alerta é descartado —módulo desativado, severidade abaixo do limiar ou duplicado dentro da janela— o send explica-o pelo stderr e termina com código 0. Assim o script que o emitiu não se parte por causa de um filtro que tu próprio configuraste.

Configuração por tags da instância #

Cada implantação precisa de apontar para o seu tópico, e reconstruir a AMI por causa disso não faria sentido. Por isso o módulo lê, além do ficheiro, as tags da instância com prefixo imaxe.global-alerts. por IMDSv2: se existirem, mandam sobre o YAML. É o que faz o modelo de CloudFormation do lançador, que além disso exige MetadataOptions.InstanceMetadataTags: enabled para que possam ser lidas.

Tag	Equivale a	Valores
imaxe.global-alerts.topic_arn	topic_arn	ARN do tópico SNS de destino.
imaxe.global-alerts.region	region	Região da AWS; vazia = deriva-se do ARN ou do IMDS.
imaxe.global-alerts.source	source	Etiqueta de origem; vazia = hostname.
imaxe.global-alerts.min_severity	min_severity	`info` · `warning` · `critical`
imaxe.global-alerts.dedup_window	dedup_window	Duração: `30s`, `5m`, `1h`…
imaxe.global-alerts.enabled	enabled	`true`/`false` (também `1`/`0`, `yes`/`no`, `on`/`off`).

Fora da AWS, ou com o IMDS bloqueado, a leitura falha em milissegundos e o módulo continua com o que diz o ficheiro. Para ver o que ficou mesmo ativo, imaxe global-alerts show.

Ficheiros e caminhos #

Caminho	Conteúdo
/etc/imaxe/global-alerts.yml	Configuração do módulo: tópico, região, origem, limiar e janela de desduplicação.
/var/lib/imaxe/state/global-alerts/spool/	Fila de alertas pendentes, um por ficheiro `.json`, por ordem cronológica.
/var/lib/imaxe/state/global-alerts/sent.json	Registo de chaves de desduplicação com a hora do último envio.
/etc/systemd/system/imaxe-global-alerts-flush.timer	Timer de repetição: arranca 2 min após o início e repete a cada 5 min.

Exemplo de global-alerts.yml:

/etc/imaxe/global-alerts.yml

enabled: true
topic_arn: arn:aws:sns:eu-west-1:123456789012:imaxe-alerts
region: ""            # vazia = deriva-se do ARN ou do IMDS
source: ""            # vazia = hostname da instância
min_severity: info
dedup_window: 5m

O estado (fila e registo de desduplicação) vive em /var/lib/imaxe/ e não em /etc/ de propósito: é estado, não configuração. Ambos os caminhos podem ser movidos com as variáveis de ambiente IMAXE_CONFIG_DIR e IMAXE_STATE_DIR.

Formato do alerta #

O corpo da mensagem SNS é JSON versionado (schema: 1), para que o subscritor o possa tratar com uma Lambda ou uma fila além de o ler por email:

corpo da mensagem

{
  "schema": 1,
  "severity": "critical",
  "source": "backup",
  "subject": "cópia falhada",
  "message": "a cópia noturna da base de dados terminou com erro",
  "host": "web-producao-1",
  "instance_id": "i-0abc123def4567890",
  "region": "eu-west-1",
  "ts": "2026-07-25T03:14:07Z",
  "dedup_key": "9f2c1b7e44a0d513"
}

O assunto da mensagem SNS compõe-se como [imaxe][severidade] host: assunto, limpo para ASCII imprimível e cortado a 100 caracteres, que é o limite que o SNS impõe.

Códigos de saída e logs #

Cada execução devolve um código que podes verificar com echo $? — útil para encadear em scripts:

0OKOperação concluída. Também quando o alerta é descartado ou posto em fila de propósito.

1ERRErro genérico: o teste não se conseguiu publicar, ou não se conseguiu publicar nem pôr em fila.

2USAGEArgumentos inválidos: flag desconhecida, falta a mensagem ou severidade não válida.

64NO TOPICNão há tópico SNS configurado, nem por ficheiro nem por tag.

O módulo também responde à verificação de saúde do imaxe: se estiver ativado mas sem tópico, o health falha, de modo que um imaxe health o denuncia antes de ser preciso o primeiro alerta.

terminal

$ sudo imaxe global-alerts test; echo "saída: $?"
$ journalctl -u imaxe-global-alerts-flush.service -n 50

Resolução de problemas #

Sintoma	Causa provável	Solução
Sai NO TOPIC (código 64)	Nem o ficheiro nem as tags trazem um ARN de tópico.	Lança `configure --topic-arn …`, ou confirma que a instância tem a tag `imaxe.global-alerts.topic_arn` e as tags ativadas nos metadados.
«SNS indisponível; alerta em fila» uma e outra vez	À função da instância falta `sns:Publish` sobre esse tópico, ou o ARN é de outra conta ou região.	Lança `test` para ver o erro exato da AWS, corrige a política da função e depois `flush`.
«CLI aws disponível: false» no status	A instância não tem a CLI da AWS instalada; o módulo publica através dela.	Instala a CLI da AWS. As AMIs do imaxe trazem-na de série; num host teu é preciso acrescentá-la.
Configuras algo e o show continua a mostrar outro valor	Uma tag `imaxe.global-alerts.*` está a passar por cima do ficheiro: tem prioridade por desenho.	Muda a tag da instância (ou o parâmetro da pilha de CloudFormation) em vez do YAML.
Só chega o primeiro de vários alertas iguais	A janela de desduplicação está a suprimi-los.	É o esperado. Baixa `dedup_window`, ou usa `--dedup-key` diferentes se forem mesmo acontecimentos distintos.
Não chega nada e não há erros	O módulo está desativado, ou a severidade está abaixo de `min_severity`.	O `show` mostra-te `enabled` e o limiar; o `configure` reabilita o envio.
Os alertas publicam-se mas não te chegam por email	A subscrição do tópico SNS está por confirmar.	Procura o email de confirmação da AWS (vê o spam) e aceita a subscrição na consola do SNS.

Ficou bloqueado com o módulo Alertas?

Escreva-nos com a saída de «imaxe <module> status --json» e respondemos rapidamente.

Contactar o suporte

Um único ponto onde ouvir toda a tua frota

O que faz este módulo #

Tarefas comuns #

Definir o tópico SNS

Enviar um alerta de teste

Enviar um alerta a partir de um script

Ver o estado do barramento

Baixar o ruído

Ver a fila e repetir

Silenciar o módulo

Sinopse #

Subcomandos #

Argumentos e flags #

Configuração por tags da instância #

Ficheiros e caminhos #

Formato do alerta #

Códigos de saída e logs #

Resolução de problemas #

Ficou bloqueado com o módulo Alertas?