En mi cluster EKS, los pods de una API se reiniciaban solos. Algunos clientes esperaban hasta 69 segundos por una respuesta. Y en CloudWatch, tres de mis cuatro alarmas decían que todo estaba bien.

La única que saltó fue la de errores en los logs. CPU: OK. Memoria: OK. Reinicios: OK.

Le pedí a AWS DevOps Agent que investigara. En unos 5 minutos encontró lo que ninguna de esas métricas podía ver.

En este artículo te muestro cómo armé el pipeline completo, de la app a la causa raíz, los detalles de configuración que hacen la diferencia y qué descubrió el agente. Todo el código está en GitHub para que lo rompas tú también.

En resumen

  • Qué construyes: un cluster EKS con Auto Mode, CloudWatch Container Insights, cuatro alarmas y AWS DevOps Agent con acceso de lectura al cluster.
  • Tiempo: 45 a 60 minutos. Costo: unos $3-5 si borras todo en menos de 2 horas, más el tiempo del agente.
  • La lección: las métricas de infraestructura no ven un pod bloqueado. Un agente con acceso al cluster, sí.
  • Código: github.com/BnkTCh/aws-devops-labs

El pipeline

La observabilidad no es tener dashboards bonitos: un dashboard que nadie mira cuando algo se rompe no observó nada. Es un ciclo completo: detectar, alertar e investigar. Muchos equipos tienen las dos primeras partes, y cuando la alarma suena, la investigación sigue siendo una persona revisando logs a las 3 de la mañana.

El lab paso a paso

Necesitas: AWS CLI v2, eksctl y kubectl, y la región us-east-1.

git clone https://github.com/BnkTCh/aws-devops-labs.git cd aws-devops-labs/lab3-observability-e2e ./scripts/00-check-prereqs.sh 

1. Crear el Agent Space

En la consola de AWS DevOps Agent (us-east-1), crea un espacio de agente (Create Agent Space):

  • Nombre: demo-devops-agent
  • Idioma de respuesta: Spanish (Latin America)
  • Acceso a recursos y aplicación web: creación automática del rol en los dos casos
  • Acciones del agente: desactivado. Así el agente solo lee: investiga y propone, pero no cambia nada.

AWS crea un rol llamado DevOpsAgentRole-AgentSpace-xxxx. Guárdalo en mente: en el paso 6 le vamos a abrir la puerta del cluster.

2. Crear el cluster

./scripts/01-setup-cluster.sh 

Crea demo-automode, un cluster con EKS Auto Mode, en unos 15 minutos. Con Auto Mode no gestionas nodos: AWS levanta los que hagan falta cuando llegan tus pods.

3. Activar Container Insights

./scripts/02-enable-observability.sh 

Instala el add-on de observabilidad, que pone el CloudWatch Agent y Fluent Bit en cada nodo para recolectar CPU, memoria, red, reinicios y logs de cada pod.

La clave está en los permisos. EKS Auto Mode no le da permisos de CloudWatch a los nodos, así que el script crea un rol IAM y lo asocia solo a la service account del agente con Pod Identity. Es mínimo privilegio: ningún otro pod del nodo puede escribir en CloudWatch.

Lo que hace el script por debajo

aws iam create-role --role-name demo-automode-cloudwatch-agent \ --assume-role-policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow", "Principal":{"Service":"pods.eks.amazonaws.com"},"Action":["sts:AssumeRole","sts:TagSession"]}]}' aws iam attach-role-policy --role-name demo-automode-cloudwatch-agent \ --policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy aws eks create-addon --cluster-name demo-automode \ --addon-name amazon-cloudwatch-observability \ --pod-identity-associations serviceAccount=cloudwatch-agent,roleArn=<arn-del-rol> 

El script terminó con el aviso "El addon no llegó a ACTIVE": tardó más de los 5 minutos que espera. Pero los pods ya estaban en Running y las métricas llegaron igual. Si te pasa, revisa los pods antes de volver a correrlo.

4. Desplegar una app con problemas

./scripts/03-generate-traffic.sh 

Despliega slow-api, una API en Python con fallas a propósito, y un generador de tráfico que le pega sin parar:

  • /api/process: 30% de las veces tarda 3 a 8 segundos, y 20% devuelve error 500.
  • /api/heavy: simula una fuga de memoria.
  • /api/order: 25% de las veces falla con un timeout simulado.

Hay un detalle del código que todavía no parece importante: el servidor es http.server.HTTPServer. Guárdalo para más adelante.

5. Crear las alarmas

./scripts/04-create-alarms.sh 

Cuatro alarmas, una por síntoma:

Alarma Qué mide Salta con
eks-demo-app-errors-high Líneas [ERROR] en los logs 10 o más por minuto
eks-demo-pod-restarts-high Reinicios de contenedores 3 en 5 minutos
eks-demo-cpu-high CPU respecto al límite del pod 80%
eks-demo-memory-high Memoria respecto al límite del pod 40%

La de errores es la más interesante de armar, porque los errores viven en los logs, no en una métrica. Un metric filter convierte cada línea [ERROR] en un punto de una métrica nueva:

aws logs put-metric-filter \ --log-group-name "/aws/containerinsights/demo-automode/application" \ --filter-name "slow-api-errors" \ --filter-pattern '"[ERROR]"' \ --metric-transformations \ metricName=SlowApiErrors,metricNamespace=CustomEKSMetrics,metricValue=1 aws cloudwatch put-metric-alarm \ --alarm-name "eks-demo-app-errors-high" \ --namespace CustomEKSMetrics --metric-name SlowApiErrors \ --statistic Sum --period 60 --threshold 10 \ --comparison-operator GreaterThanOrEqualToThreshold \ --evaluation-periods 1 --treat-missing-data notBreaching \ --alarm-actions <sns-topic-arn> 

Esas comillas dentro de las comillas no son un error de tipeo. Más abajo explico por qué.

6. Darle ojos al agente dentro del cluster

Este es el paso que casi nadie hace, y el que más cambió el resultado.

./scripts/04b-grant-agent-eks-access.sh 

El rol del Agent Space ya trae permisos IAM sobre EKS. Pero EKS tiene dos puertas: IAM decide si puedes llamar a la API de EKS, y las access entries deciden qué puedes ver dentro del cluster. Sin una access entry, el agente investiga a ciegas: ve la alarma y los logs de CloudWatch, pero no los pods, ni los eventos, ni por qué se reinició algo.

El script le da AmazonEKSViewPolicy: puede leer pods, eventos y deployments, pero no cambiar nada ni leer Secrets.

aws eks create-access-entry --cluster-name demo-automode \ --principal-arn arn:aws:iam::<cuenta>:role/service-role/DevOpsAgentRole-AgentSpace-xxxx aws eks associate-access-policy --cluster-name demo-automode \ --principal-arn arn:aws:iam::<cuenta>:role/service-role/DevOpsAgentRole-AgentSpace-xxxx \ --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSViewPolicy \ --access-scope type=cluster 

7. Romperlo

./scripts/05-trigger-incident.sh 

El script quintuplica el tráfico: escala el generador de 1 a 5 réplicas y manda cientos de peticiones extra al endpoint lento y al de la fuga de memoria.

Esperaba que se encendieran varias alarmas. Solo saltó la de errores. Así se veía Container Insights antes y después:

Los gráficos se mueven, pero la CPU y la memoria quedan muy lejos de los límites. Si solo hubiera mirado este dashboard, habría dicho que la app estaba bien.

8. Pedirle al agente que investigue

La investigación no arranca sola cuando salta una alarma: la inicias tú desde el chat de la aplicación web del agente (o la conectas a una herramienta como PagerDuty). Le escribí:

Investiga por qué la app slow-api del namespace demo-observability está degradada. La alarma eks-demo-app-errors-high está en ALARM.

Abrió una investigación formal y, unos 5 minutos después, estaba completa.

Lo que encontró el agente

El resumen lo dice en una línea: "alarma de errores por quintuplicar el tráfico de prueba".

Pero lo bueno está debajo. La causa raíz tiene dos capas:

1. El desencadenante: a las 18:26, alguien escaló traffic-generator de 1 a 5 réplicas. El agente lo sacó de un evento ScalingReplicaSet de Kubernetes y midió el efecto: las peticiones a slow-api pasaron de 77-133 a 247-326 cada 3 minutos.

2. La causa de fondo: ¿te acuerdas del HTTPServer? Atiende una sola petición a la vez. Cuando una petición se queda 3 a 8 segundos en un sleep, todas las demás esperan en la fila, incluido el health check. Con 5 veces más tráfico:

  • /health deja de responder a tiempo: 65 a 70 fallos de readiness por pod.
  • El liveness probe mata los pods (exit 137, no por falta de memoria).
  • El balanceador saca y vuelve a meter los pods.
  • Los clientes esperan hasta 69 segundos.

Y eso explica el misterio del principio. El pod no estaba sin recursos: la CPU estaba por debajo del 2,3% de su límite y la memoria cerca del 8,5%. Estaba bloqueado esperando. Ninguna alarma de CPU o memoria iba a ver eso. Y los reinicios fueron 2, justo por debajo del umbral de 3.

Cómo llegó ahí

El timeline muestra el razonamiento paso a paso. Graficó la métrica de errores y siguió su origen hasta el metric filter y los logs:

También revisó CloudTrail buscando cambios manuales (no había) y fue descartando hipótesis con datos: límites de recursos, una base de datos o un servicio externo caído (los mensajes de error hablaban de RDS, Redis y una pasarela de pagos) y un despliegue reciente.

¿Sirvió el paso 6?

Sí, y mucho. El evento de escalado, los fallos de readiness y el exit 137 vienen de la API de Kubernetes, no de CloudWatch. Sin la access entry, el agente habría visto que había errores, pero no qué se escaló ni por qué se reiniciaban los pods.

Hubo una sola cosa que no pudo responder: quién hizo el escalado. Los logs de auditoría del control plane de EKS estaban apagados, y el agente lo marcó como un gap en lugar de inventar una respuesta. Si quieres esa trazabilidad, activa los logs audit de tu cluster.

El plan de mitigación

Propone volver traffic-generator a 1 réplica y, opcionalmente, subir slow-api de 2 a 4, con pasos de preparación, validación, aplicación, verificación y rollback, cada uno con su comando. Y un detalle que me gustó: antes de bajar las réplicas, advierte que si la carga era una prueba intencional la va a cortar, y pide confirmarlo con el dueño.

Para que no vuelva a pasar, recomienda cambiar a ThreadingHTTPServer, hacer los probes más tolerantes, agregar un HPA con PodDisruptionBudget y alarmar sobre la tasa de error, no el conteo.

5 detalles de configuración que hacen la diferencia

Cada uno de estos puntos es algo que, hecho de la forma "obvia", no funciona. El lab ya los resuelve, y vale la pena saber por qué.

1. Mide la CPU y la memoria contra el límite del pod, no contra el nodo.
pod_cpu_utilization y pod_memory_utilization comparan contra la capacidad del nodo completo: en un nodo de 4 vCPU, un pod al 100% de su límite de 250m marca apenas un 6%. Una alarma sobre esas métricas casi nunca salta.
→ El lab usa pod_cpu_utilization_over_pod_limit y pod_memory_utilization_over_pod_limit, que miden contra el límite del pod.

2. Pon entre comillas el término del metric filter.
Con --filter-pattern '[ERROR]', CloudWatch lee los corchetes como un patrón de campos y cuenta todas las líneas de log, así que la alarma saltaría desde el primer minuto.
→ El lab usa '"[ERROR]"', que busca el texto [ERROR] tal cual.

3. Haz público el balanceador si el tráfico viene de afuera.
En EKS Auto Mode, un Service LoadBalancer sin anotaciones crea un NLB interno, solo accesible desde la VPC.
→ El lab agrega service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing, para que el tráfico del incidente pueda llegar desde tu máquina.

4. Desactiva el buffer de salida de Python.
Cuando no corre en una terminal, Python guarda los print() en un buffer. Los logs llegan tarde a CloudWatch, o se pierden si el pod se reinicia, y la alarma de errores depende de ellos.
→ El lab define la variable de entorno PYTHONUNBUFFERED=1.

5. Usa el ARN completo del rol del agente, con su path.
El rol del Agent Space vive bajo /service-role/. Si lo omites, EKS rechaza la access entry con invalid principal.
→ El script lo busca solo y usa arn:aws:iam::<cuenta>:role/service-role/DevOpsAgentRole-AgentSpace-xxxx.

Limpieza

./scripts/99-cleanup.sh 

Borra la app, las alarmas, el metric filter y el topic de SNS, y te pregunta si borrar el cluster. Si dices que sí, también borra el rol del CloudWatch Agent, y la access entry se va con el cluster.

A mano te quedan el Agent Space (Settings → Delete) y sus roles DevOpsAgentRole-* en IAM, que no se borran junto con él. Y antes de dar todo por limpio, confirma que aws eks list-clusters --region us-east-1 devuelve una lista vacía: el cluster puede quedar un rato en estado DELETING.

Llevarlo a tu empresa

En producción tienes decenas de servicios y varios clusters. El valor de este pipeline no está en un incidente aislado, sino en que cada alarma llegue con la investigación adelantada, sin depender de quién esté de guardia.

  • Alarma sobre lo que siente el usuario. Errores y latencia primero; CPU y memoria después. Este lab lo demuestra.
  • Instrumenta antes de automatizar. El agente solo ve lo que recolectas. Si puedes, suma Application Signals o X-Ray para tener latencia y trazas.
  • Dale ojos dentro de Kubernetes. Una access entry de solo lectura cuesta dos comandos y cambia la calidad de la investigación.
  • Activa los logs de auditoría. Sin ellos, nadie (ni humano ni IA) puede saber quién cambió qué.
  • El humano valida, no busca. Deja el trabajo forense al agente y reserva a la persona para decidir.

Para cerrar

Armé este pipeline esperando que las alarmas de CPU y memoria me avisaran del problema. No avisaron, porque el problema no era de recursos. Lo que funcionó fue la combinación: una alarma sobre los errores que siente el usuario, y un agente que podía ver dentro del cluster y cruzar esa alarma con los eventos, los reinicios y el código.

La observabilidad no es tener muchas alarmas. Es tener las señales correctas, y a alguien (o algo) capaz de conectarlas.

Monta el lab, rómpelo a propósito y saca tus propias conclusiones. No hay mejor forma de entender un sistema que verlo fallar.