inicializ/k8s-incident-triage

Triage de Incidentes de Kubernetes

Realiza triage de solo lectura de cargas de trabajo y namespaces de Kubernetes usando kubectl.

Soporta:

• Entrada en lenguaje natural (modo humano)
• Entrada JSON estructurada (modo automatización)

Este skill NUNCA muta el estado del clúster.

---

Uso de Herramientas

Este skill utiliza cli_execute exclusivamente con comandos kubectl. NUNCA uses http_request o web_search para interactuar con Kubernetes. Todas las operaciones con el clúster DEBEN realizarse a través de kubectl mediante la herramienta cli_execute.

---

Herramienta: k8s_triage

Diagnostica cargas de trabajo, pods o namespaces de Kubernetes no saludables.

---

Modos de Entrada

1) Modo Humano (Lenguaje Natural)

La entrada es una cadena de texto simple.

Ejemplos:

• triage payments-prod
• triage deployment payments-api in payments-prod
• why are pods pending in checkout-prod?
• investigate crashloop in payments-prod
• triage pod api-7c9f6d7f86-abcde in payments-prod
• check rollout of deployment payments-api in prod

Comportamiento:

• Analiza la intención de namespace, carga de trabajo, pod o selector.
• Si se omite el namespace, usa $DEFAULT_NAMESPACE si está definido.
• Si hay ambigüedad, por defecto realiza triage a nivel de namespace.
• Nunca obliga al usuario a recordar campos JSON.

---

2) Modo Automatización (JSON Estructurado)

Esquema JSON de entrada:

{
  "namespace": "payments-prod",
  "workload_kind": "deployment",
  "workload_name": "payments-api",
  "pod_name": null,
  "label_selector": null,
  "include_logs": true,
  "logs_tail_lines": 200,
  "include_previous_logs": true,
  "events_limit": 50,
  "include_node_diagnostics": true,
  "include_metrics": false,
  "output_format": "markdown"
}

Reglas:

• namespace es obligatorio.
• Si se proporciona pod_name → triage a nivel de pod.
• Si se proporcionan campos de carga de trabajo → triage a nivel de carga de trabajo.
• De lo contrario → escaneo de namespace.

---

Proceso de Triage

Paso 0 — Precondiciones

Verifica el acceso al clúster:

kubectl version --client
kubectl cluster-info

Si RBAC deniega el acceso:

• Continúa con las operaciones permitidas.
• Reporta explícitamente los comandos denegados en la salida.

---

Paso 1 — Snapshot Rápido de Salud

Ámbito de namespace:

kubectl get pods -n <ns> -o wide
kubectl get deploy,sts,ds,job,cronjob -n <ns>

Ámbito de carga de trabajo:

kubectl get <kind> <name> -n <ns>
kubectl rollout status <kind>/<name> -n <ns> --timeout=10s

Selecciona pods en estados:

• CrashLoopBackOff
• ImagePullBackOff
• ErrImagePull
• Pending / Unschedulable
• Error
• NotReady
• OOMKilled
• Alto número de reinicios

Limita el triage profundo a $TRIAGE_MAX_PODS (por defecto 5).

---

Paso 2 — Línea de Tiempo de Eventos

kubectl get events -n <ns> --sort-by=.lastTimestamp | tail -n <events_limit>

Busca:

• FailedScheduling
• FailedMount
• Unhealthy (fallos de sonda)
• Back-off pulling image
• Evicted
• Señales de presión en el nodo

---

Paso 3 — Describe Pods y Cargas de Trabajo

Para cada pod seleccionado:

kubectl describe pod <pod> -n <ns>

Captura:

• Estado del contenedor y motivo
• Número de reinicios
• Último motivo de terminación
• Fallos de sonda
• Problemas de montaje de volúmenes
• Asignación de nodo
• Taints / tolerations
• Restricciones de afinidad

Si es triage a nivel de carga de trabajo:

kubectl describe <kind> <name> -n <ns>

---

Paso 4 — Diagnóstico de Nodo (Opcional)

kubectl get nodes -o wide
kubectl describe node <node>

Verifica:

• NotReady
• MemoryPressure
• DiskPressure
• PIDPressure
• Evictions

---

Paso 5 — Logs (Opcional)

kubectl logs <pod> -n <ns> --all-containers --tail=<N>

Si hay bucles de reinicio y include_previous_logs=true:

kubectl logs <pod> -n <ns> --previous --all-containers --tail=<N>

Reglas:

• Prefiere logs anteriores para CrashLoopBackOff.
• Enmascara patrones sensibles obvios.
• Nunca imprime valores de Secret.

---

Paso 6 — Métricas Opcionales

Si está habilitado:

kubectl top pods -n <ns>
kubectl top node

Omite elegantemente si metrics-server no está disponible.

---

Heurísticas de Detección

Clasifica los problemas detectados en:

• CrashLoop / Caída de Aplicación
• OOMKilled / Límites de Recursos
• Fallo de Extracción de Imagen
• Restricción de Scheduling
• Fallo de Sonda
• Fallo de PVC / Volumen
• Presión en Nodo / Evicción
• Rollout Estancado
• Desconocido / Escalamiento Necesario

Para cada problema proporciona:

• Hipótesis
• Evidencia de respaldo
• Puntuación de confianza (0.0–1.0)
• Comandos siguientes recomendados

---

Estructura de Salida

1) Resumen del Incidente

• Namespace
• Ámbito (pod/carga de trabajo/namespace)
• Cantidad de recursos afectados
• Marca de tiempo

2) Principales Hallazgos

Resumen conciso en viñetas.

3) Causas Raíz Probables (Top 3)

Para cada una:

• Descripción
• Extracto de evidencia
• Confianza
• Acciones recomendadas

4) Comandos Siguientes

Comandos kubectl listos para copiar y pegar.

5) Apéndice de Evidencia

• Eventos (recientes)
• Extractos de describe
• Extractos de logs

---

Restricciones de Seguridad

Este skill DEBE:

• Realizar únicamente operaciones kubectl de solo lectura.
• Nunca ejecutar:
  • apply
  • patch
  • delete
  • exec
  • port-forward
  • scale
  • rollout restart
• Nunca imprimir valores de Secret.
• Evitar volcar variables de entorno completas.

---

Compatibilidad Autónoma

Este skill está diseñado para ser invocado por:

• k8s_alert_handler (triage desencadenado por alertas)
• k8s_patrol (escaneos programados de patrulla)
• Humanos mediante CLI en lenguaje natural

Debe:

• Ser idempotente
• Producir huellas digitales deterministas
• Evitar carga excesiva en el clúster
• Limitar el alcance del triage profundo