inicializ/k8s-incident-triage

Triage de Incidentes Kubernetes

Realiza triagem somente leitura de workloads e namespaces Kubernetes usando kubectl.

Suporta:

• Entrada em linguagem natural (modo humano)
• Entrada JSON estruturada (modo automação)

Esta skill NUNCA altera o estado do cluster.

---

Uso de Ferramentas

Esta skill usa cli_execute exclusivamente com comandos kubectl. Nunca use http_request ou web_search para interagir com Kubernetes. Todas as operações de cluster DEVEM passar pelo kubectl via ferramenta cli_execute.

---

Ferramenta: k8s_triage

Diagnostique workloads, pods ou namespaces Kubernetes não saudáveis.

---

Modos de Entrada

1) Modo Humano (Linguagem Natural)

A entrada é uma string simples.

Exemplos:

• 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

Comportamento:

• Interpreta namespace, workload, pod ou intenção de seletor.
• Se namespace omitido, usa $DEFAULT_NAMESPACE se definido.
• Se houver ambiguidade, padrão é triagem em nível de namespace.
• Nunca obriga o usuário a lembrar campos JSON.

---

2) Modo Automação (JSON Estruturado)

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" }

Regras:

• namespace é obrigatório.
• Se pod_name fornecido → triagem em nível de pod.
• Se campos de workload fornecidos → triagem em nível de workload.
• Caso contrário → varredura de namespace.

---

Processo de Triagem

Passo 0 — Pré-condições

Verificar acesso ao cluster:

kubectl version --client kubectl cluster-info

Se RBAC negar acesso:

• Continuar com operações permitidas.
• Relatar explicitamente comandos negados na saída.

---

Passo 1 — Snapshot Rápido de Saúde

Escopo do namespace:

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

Escopo do workload:

kubectl get -n kubectl rollout status / -n --timeout=10s

Selecionar pods nos estados:

• CrashLoopBackOff
• ImagePullBackOff
• ErrImagePull
• Pending / Unschedulable
• Error
• NotReady
• OOMKilled
• Alta contagem de reinicializações

Limitar triagem profunda a $TRIAGE_MAX_PODS (padrão 5).

---

Passo 2 — Linha do Tempo de Eventos

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

Procurar por:

• FailedScheduling
• FailedMount
• Unhealthy (falhas de sonda)
• Back-off pulling image
• Evicted
• Sinais de pressão no nó

---

Passo 3 — Descrever Pods e Workloads

Para cada pod selecionado:

kubectl describe pod -n

Capturar:

• Estado do contêiner e motivo
• Contagem de reinicializações
• Motivo da última terminação
• Falhas de sonda
• Problemas de montagem de volume
• Atribuição de nó
• Taints / tolerations
• Restrições de afinidade

Se triagem em nível de workload:

kubectl describe -n

---

Passo 4 — Diagnóstico de Nós (Opcional)

kubectl get nodes -o wide kubectl describe node

Verificar:

• NotReady
• MemoryPressure
• DiskPressure
• PIDPressure
• Evicções

---

Passo 5 — Logs (Opcional)

kubectl logs -n --all-containers --tail=

Se houver loops de reinicialização e include_previous_logs=true:

kubectl logs -n --previous --all-containers --tail=

Regras:

• Preferir logs anteriores para CrashLoopBackOff.
• Ofuscar padrões sensíveis óbvios.
• Nunca imprimir valores de Secrets.

---

Passo 6 — Métricas Opcionais

Se habilitado:

kubectl top pods -n kubectl top node

Pular graciosamente se o metrics-server estiver indisponível.

---

Heurísticas de Detecção

Classificar problemas detectados em:

• CrashLoop / Falha de Aplicação
• OOMKilled / Limites de Recursos
• Falha na Obtenção de Imagem
• Restrição de Agendamento
• Falha na Sonda
• Falha de PVC / Volume
• Pressão no Nó / Evicção
• Rollout Travado
• Desconhecido / Necessidade de Escalação

Para cada problema fornecer:

• Hipótese
• Evidência de suporte
• Pontuação de confiança (0.0–1.0)
• Próximos comandos recomendados

---

Estrutura de Saída

1) Sumário do Incidente

• Namespace
• Escopo (pod/workload/namespace)
• Contagem de recursos afetados
• Timestamp

2) Principais Descobertas

Resumo conciso em marcadores.

3) Causas Raiz Prováveis (Top 3)

Para cada:

• Descrição
• Excerto da evidência
• Confiança
• Ações recomendadas

4) Próximos Comandos

Comandos kubectl para copiar e colar.

5) Apêndice de Evidências

• Eventos (recentes)
• Excertos de descrição
• Excertos de logs

---

Restrições de Segurança

Esta skill DEVE:

• Realizar apenas operações somente leitura do kubectl.
• Nunca executar:
  • apply
  • patch
  • delete
  • exec
  • port-forward
  • scale
  • rollout restart
• Nunca imprimir valores de Secrets.
• Evitar despejar variáveis de ambiente completas.

---

Compatibilidade Autônoma

Esta skill foi projetada para ser invocada por:

• k8s_alert_handler (triagem acionada por alerta)
• k8s_patrol (varreduras programadas de patrulha)
• Humanos via CLI de linguagem natural

Ela deve:

• Ser idempotente
• Produzir impressões digitais determinísticas
• Evitar carga excessiva no cluster
• Limitar o escopo de triagem profunda