Qué hace este módulo #

Una instancia tiene muchas cosas que contar: fail2ban ha baneado una IP, aide ha visto cambiar un fichero del sistema, la copia de seguridad de anoche falló, el disco raíz va por el 95 %. Si cada módulo avisa a su manera —un correo aquí, una línea de log allá— nadie se entera de nada, y con diez instancias el problema se multiplica por diez.

El módulo global-alerts es el bus central de alertas de imaxe: un único comando por el que pasan todos esos avisos y un único destino al que llegan, un tema de Amazon SNS compartido por toda tu flota. Desde ahí SNS reparte como quieras: correo, SMS, una función Lambda, una cola SQS, tu sistema de guardias. Publica con el rol IAM de la instancia (permiso sns:Publish), así que no hay ninguna credencial que guardar. Y filtra el ruido antes de mandarlo: un umbral de severidad descarta lo que no llega al nivel que te interesa y una ventana de deduplicación evita que la misma alerta te despierte cuarenta veces.

Si SNS no está disponible —red caída, rol sin permisos todavía, región inaccesible— la alerta no se pierde: se encola en disco y un timer de systemd la reintenta cada 5 minutos.

Antes de empezar

Necesitas el ARN de un tema SNS (arn:aws:sns:región:cuenta:tema) y que la instancia pueda publicar en él. Si lanzaste la AMI desde el lanzador, la plantilla de CloudFormation ya crea el tema, suscribe tu correo, crea el rol IAM con sns:Publish y pasa el ARN a la instancia como tag: el módulo se configura solo y no hay nada que hacer aquí.

Guía rápidatareas paso a paso

Tareas comunes #

Elige lo que quieres hacer. Cada receta trae el comando ya escrito — cambia el ARN y el texto por los tuyos, y pulsa Copiar.

Configurar el tema SNS Enviar una alerta de prueba Enviar una alerta desde un script Ver el estado del bus Bajar el ruido Ver la cola y reintentar Silenciar el módulo

1

Configurar el tema SNS

Dile a la instancia dónde tiene que publicar sus avisos.

Conéctate por SSH a tu servidor con el usuario ubuntu.

Apunta el módulo al ARN de tu tema. La región se deduce del propio ARN, así que normalmente no hace falta indicarla:

terminal

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

¿Varias instancias publicando en el mismo tema? Ponle a cada una una etiqueta de origen reconocible con --source (por defecto se usa el hostname):

terminal

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

La configuración queda en /etc/imaxe/global-alerts.yml y el envío queda habilitado. Continúa con la receta Enviar una alerta de prueba.

2

Enviar una alerta de prueba

Comprueba que el rol IAM publica de verdad antes de fiarte del canal.

Publica una alerta de prueba en el tema configurado:

terminal

$ sudo imaxe global-alerts test

La prueba se salta el umbral y la deduplicación —siempre sale— y, si algo falla, te devuelve el error real de AWS en vez de encolar en silencio. Revisa la bandeja del correo suscrito al tema (y la carpeta de spam).

Si ves el MessageId y te llega el aviso, el canal funciona. Si sale AuthorizationError, a la instancia le falta el permiso sns:Publish sobre ese tema.

3

Enviar una alerta desde un script

El mismo canal que usan los módulos, disponible para lo tuyo.

Una alerta con su severidad y su origen:

terminal

$ sudo imaxe global-alerts send --severity critical \
    --source backup --subject "copia fallida" \
    "la copia nocturna de la base de datos terminó con error"

Si el texto lo genera otro comando, pásalo por stdin usando - como mensaje:

terminal

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

En algo que se ejecuta cada pocos minutos, dale una clave de deduplicación estable: dentro de la ventana configurada solo saldrá la primera:

terminal

$ sudo imaxe global-alerts send --severity warning \
    --dedup-key disco-raiz-lleno "disco raíz al 95%"

La alerta viaja como JSON al tema, con la instancia, la región y la marca de tiempo ya incluidas. Sin --dedup-key el módulo deriva una de origen + severidad + asunto.

4

Ver el estado del bus

Tema, región, CLI de AWS y alertas pendientes, de un vistazo.

Resumen del estado actual:

terminal

$ sudo imaxe global-alerts status

Para verificar qué configuración manda de verdad —incluida la que llega por tags de la instancia, que tiene prioridad sobre el fichero—:

terminal

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

Sabrás si hay tema configurado, en qué región se publica y cuántas alertas esperan en la cola. Con --json, listo para un panel o un script.

5

Bajar el ruido

Sube el umbral de severidad y amplía la ventana de deduplicación.

Si solo quieres enterarte de lo que importa, descarta todo lo que esté por debajo de warning:

terminal

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

La ventana de deduplicación no tiene flag: se ajusta en el fichero de configuración. Súbela si una misma alerta se repite mucho:

/etc/imaxe/global-alerts.yml

dedup_window: 1h   # 30s, 5m, 1h… (por defecto 5m)

Las alertas por debajo del umbral se descartan antes de salir (no se encolan) y las repetidas dentro de la ventana se suprimen. test sigue publicando siempre, así que no pierdes la forma de comprobar el canal.

6

Ver la cola y reintentar

Qué quedó pendiente cuando SNS no respondió, y cómo forzar el envío.

Mira lo pendiente y las últimas claves enviadas:

terminal

$ sudo imaxe global-alerts history

El reintento ya lo hace un timer de systemd cada 5 minutos, pero puedes forzarlo tras arreglar el permiso o la red:

terminal

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

Verás cuántas salieron y cuántas siguen esperando. Si la primera vuelve a fallar, la pasada se detiene ahí y lo deja para el siguiente intento: no se descarta nada.

7

Silenciar el módulo

Deja de publicar sin perder la configuración.

Deshabilita el envío de alertas y retira el timer de reintento:

terminal

$ sudo imaxe global-alerts remove

El tema, la región y el resto de ajustes se conservan en el fichero: para volver a activarlo basta con un configure, que rehabilita el módulo.

La instancia deja de publicar. Los send siguientes no fallan: avisan por stderr de que el módulo está deshabilitado y terminan con código 0.

Sin rol IAM no hay alertas

El módulo publica con las credenciales del rol de la instancia, no con claves guardadas. Si el rol no permite sns:Publish sobre ese tema, las alertas se encolarán una tras otra sin llegar nunca. Un imaxe global-alerts test te lo dice en el momento, con el error tal cual lo devuelve AWS.

Referencia CLIcomandos, flags y ficheros

Sinopsis #

uso

imaxe global-alerts <subcomando> [--topic-arn ARN] [--severity NIVEL] [flags]

Todos los subcomandos requieren privilegios de root (usa sudo) porque escriben en /etc/imaxe/, mantienen el estado en /var/lib/imaxe/ y gestionan una unidad de systemd. No hay secretos que manejar: la publicación va con el rol IAM de la instancia. Añade --json a status, show, history o flush para obtener salida legible por máquina.

Subcomandos #

Subcomando	Qué hace	Flags relevantes
status	Estado: tema configurado, región efectiva, CLI de AWS disponible y alertas en cola.	--json
configure	Fija el tema SNS y las opciones de envío. Rehabilita el módulo si estaba deshabilitado.	--topic-arn, --region, --source, --min-severity
send	Publica una alerta. Es el canal que usan el operador y el resto de módulos.	--severity, --source, --subject, --dedup-key
test	Publica una alerta de prueba saltándose umbral y deduplicación, y reporta el error real si falla.	--severity
show	Muestra la configuración efectiva (fichero + tags de la instancia ya aplicadas).	--json
history	Alertas pendientes en cola y claves de deduplicación enviadas recientemente.	--json
flush	Reintenta las alertas encoladas. Lo ejecuta también el timer de systemd.	--json
remove	Deshabilita el envío y retira el timer. Conserva la configuración.	—

Argumentos y flags #

Flag	Tipo	Por defecto	Descripción
--topic-arn req.	string	—	ARN del tema SNS destino (`arn:aws:sns:región:cuenta:tema`). Sin él el módulo no puede publicar.
--region	string	del ARN	Región de AWS. Si se omite, se deriva del ARN del tema; si tampoco, de IMDS o de `AWS_REGION`.
--source	string	hostname	Etiqueta de origen. En `configure`, la de la instancia; en `send`, la de esa alerta concreta (p. ej. el módulo que la emite).
--min-severity	string	info	Umbral: descarta las alertas por debajo de este nivel. Valores: `info`, `warning`, `critical`.
--severity	string	info	En `send`/`test`: nivel de esta alerta. Se aceptan las formas cortas `warn` y `crit`.
--subject	string	del mensaje	Asunto corto. Si se omite, se deriva del propio mensaje.
--dedup-key	string	derivada	Clave de deduplicación: suprime repeticiones dentro de `dedup_window`. Por defecto se calcula con origen + severidad + asunto.
<mensaje> req.	posicional	—	En `send`: el texto de la alerta, o `-` para leerlo de `stdin`.
--json	bool	false	En `status`, `show`, `history` y `flush`, emite el resultado como JSON en `stdout`.

Descartar no es fallar

Cuando una alerta se descarta —módulo deshabilitado, severidad por debajo del umbral o duplicado dentro de la ventana— send lo explica por stderr y termina con código 0. Así el script que la emitió no se rompe por un filtro que tú mismo configuraste.

Configuración por tags de instancia #

Cada despliegue necesita apuntar a su tema, y reconstruir la AMI por eso no tendría sentido. Por eso el módulo lee, además del fichero, las tags de la instancia con prefijo imaxe.global-alerts. por IMDSv2: si existen, mandan sobre el YAML. Es lo que hace la plantilla de CloudFormation del lanzador, que además exige MetadataOptions.InstanceMetadataTags: enabled para que se puedan leer.

Tag	Equivale a	Valores
imaxe.global-alerts.topic_arn	topic_arn	ARN del tema SNS destino.
imaxe.global-alerts.region	region	Región de AWS; vacía = se deriva del ARN o de IMDS.
imaxe.global-alerts.source	source	Etiqueta de origen; vacía = hostname.
imaxe.global-alerts.min_severity	min_severity	`info` · `warning` · `critical`
imaxe.global-alerts.dedup_window	dedup_window	Duración: `30s`, `5m`, `1h`…
imaxe.global-alerts.enabled	enabled	`true`/`false` (también `1`/`0`, `yes`/`no`, `on`/`off`).

Fuera de AWS, o con IMDS bloqueado, la lectura falla en milisegundos y el módulo sigue con lo que diga el fichero. Para ver qué ha quedado activo de verdad, imaxe global-alerts show.

Ficheros y rutas #

Ruta	Contenido
/etc/imaxe/global-alerts.yml	Configuración del módulo: tema, región, origen, umbral y ventana de deduplicación.
/var/lib/imaxe/state/global-alerts/spool/	Cola de alertas pendientes, una por fichero `.json`, en orden cronológico.
/var/lib/imaxe/state/global-alerts/sent.json	Registro de claves de deduplicación con la hora del último envío.
/etc/systemd/system/imaxe-global-alerts-flush.timer	Timer de reintento: arranca 2 min tras el inicio y repite cada 5 min.

Ejemplo de global-alerts.yml:

/etc/imaxe/global-alerts.yml

enabled: true
topic_arn: arn:aws:sns:eu-west-1:123456789012:imaxe-alerts
region: ""            # vacía = se deriva del ARN o de IMDS
source: ""            # vacía = hostname de la instancia
min_severity: info
dedup_window: 5m

El estado (cola y registro de deduplicación) vive en /var/lib/imaxe/ y no en /etc/ a propósito: es estado, no configuración. Ambas rutas se pueden mover con las variables de entorno IMAXE_CONFIG_DIR e IMAXE_STATE_DIR.

Formato de la alerta #

El cuerpo del mensaje SNS es JSON versionado (schema: 1), para que el suscriptor pueda tratarlo con una Lambda o una cola además de leerlo por correo:

cuerpo del mensaje

{
  "schema": 1,
  "severity": "critical",
  "source": "backup",
  "subject": "copia fallida",
  "message": "la copia nocturna de la base de datos terminó con error",
  "host": "web-produccion-1",
  "instance_id": "i-0abc123def4567890",
  "region": "eu-west-1",
  "ts": "2026-07-25T03:14:07Z",
  "dedup_key": "9f2c1b7e44a0d513"
}

El asunto del mensaje SNS se compone como [imaxe][severidad] host: asunto, saneado a ASCII imprimible y recortado a 100 caracteres, que es el límite que impone SNS.

Códigos de salida y logs #

Cada ejecución devuelve un código que puedes comprobar con echo $? — útil para encadenar en scripts:

0OKOperación completada. También cuando la alerta se descarta o se encola a propósito.

1ERRError genérico: la prueba no se pudo publicar, o no se pudo publicar ni encolar.

2USAGEArgumentos inválidos: flag desconocido, falta el mensaje o severidad no válida.

64NO TOPICNo hay tema SNS configurado ni por fichero ni por tag.

El módulo también responde al chequeo de salud de imaxe: si está habilitado pero sin tema, el health falla, de modo que un imaxe health lo delata antes de que haga falta la primera alerta.

terminal

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

Resolución de problemas #

Síntoma	Causa probable	Solución
Sale NO TOPIC (código 64)	Ni el fichero ni las tags traen un ARN de tema.	Lanza `configure --topic-arn …`, o revisa que la instancia tenga la tag `imaxe.global-alerts.topic_arn` y las tags habilitadas en los metadatos.
«SNS no disponible; alerta encolada» una y otra vez	Al rol de la instancia le falta `sns:Publish` sobre ese tema, o el ARN es de otra cuenta o región.	Lanza `test` para ver el error exacto de AWS, corrige la política del rol y luego `flush`.
«CLI aws disponible: false» en el status	La instancia no tiene el CLI de AWS instalado; el módulo publica a través de él.	Instala el CLI de AWS. Las AMIs de imaxe lo traen de serie; en un host propio hay que añadirlo.
Configuras algo y show sigue enseñando otro valor	Una tag `imaxe.global-alerts.*` está pisando el fichero: tiene prioridad por diseño.	Cambia la tag de la instancia (o el parámetro de la pila de CloudFormation) en vez del YAML.
Solo llega la primera de varias alertas iguales	La ventana de deduplicación las está suprimiendo.	Es lo esperado. Baja `dedup_window`, o usa `--dedup-key` distintas si de verdad son sucesos distintos.
No llega nada y no hay errores	El módulo está deshabilitado, o la severidad va por debajo de `min_severity`.	`show` te enseña `enabled` y el umbral; `configure` rehabilita el envío.
Las alertas se publican pero no te llegan por correo	La suscripción del tema SNS está sin confirmar.	Busca el correo de confirmación de AWS (revisa el spam) y acepta la suscripción en la consola de SNS.

¿Te atascaste con el módulo Alertas?

Escríbenos con la salida de «imaxe <módulo> status --json» y te respondemos rápido.

Contactar con soporte

Un único punto donde escuchar a toda tu flota

Qué hace este módulo #

Tareas comunes #

Configurar el tema SNS

Enviar una alerta de prueba

Enviar una alerta desde un script

Ver el estado del bus

Bajar el ruido

Ver la cola y reintentar

Silenciar el módulo

Sinopsis #

Subcomandos #

Argumentos y flags #

Configuración por tags de instancia #

Ficheros y rutas #

Formato de la alerta #

Códigos de salida y logs #

Resolución de problemas #

¿Te atascaste con el módulo Alertas?