Receita: Monitoramento K8s com IA

Nesta receita, você vai configurar o ChatCLI para monitorar um deployment Kubernetes e usar IA para diagnosticar problemas em tempo real.

Cenário

Aplicação em Produção

Aplicação “myapp” rodando em produção no Kubernetes

Diagnóstico Rápido

Equipe precisa diagnosticar problemas rapidamente

Análise com IA

Usar IA para analisar logs, eventos e métricas

Contexto Automático

Contexto K8s automático em todas as perguntas

Opção 1: Monitoramento Local

Use esta opção quando você tem acesso direto ao cluster via kubectl.

Verificar Acesso ao Cluster

# Verificar conectividade
kubectl get pods -n production

# Verificar permissões
kubectl auth can-i get pods -n production
kubectl auth can-i get pods/log -n production
kubectl auth can-i list events -n production

Iniciar o Watcher

chatcli watch --deployment myapp --namespace production

Você verá:

K8s Watcher starting...
  Deployment: myapp
  Namespace:  production
  Interval:   30s
  Window:     2h

Collecting initial data...
Initial data collected. Starting interactive mode.
[watch] chatcli>

Fazer Perguntas

[watch] chatcli> O deployment está saudável?

Com base nos dados coletados do Kubernetes:
- O deployment myapp tem 3/3 replicas disponíveis
- Todos os pods estão no estado Running e Ready
- Não há alertas ativos
- CPU média em 35%, memória em 120Mi
O deployment está saudável e operando normalmente.

[watch] chatcli> /watch status

K8s Watcher Active
  Deployment:  myapp
  Namespace:   production
  Snapshots:   5
  Pods:        3
  Alerts:      0

Diagnosticar Problemas

Quando algo dá errado:

[watch] chatcli> Por que o pod myapp-abc12 está reiniciando?

Analisando os dados do pod myapp-abc12:
- O pod teve 5 restarts na última hora
- Motivo do último restart: OOMKilled
- Container estava usando 490Mi de 512Mi de limite
- Logs mostram: "java.lang.OutOfMemoryError: Java heap space"

Diagnóstico: O container está excedendo o limite de memória.
Recomendações:
1. Aumente resources.limits.memory para 1Gi
2. Ajuste a JVM: -Xmx384m para caber no limite
3. Investigue possível memory leak nos logs anteriores

Opção 2: Servidor com Watcher (Equipe)

Use esta opção para que toda a equipe tenha acesso ao monitoramento via servidor centralizado.

Deploy no Kubernetes

Via Helm (single-target)
Via Operator (AIOps)

helm install chatcli oci://ghcr.io/diillson/charts/chatcli \
  --namespace monitoring --create-namespace \
  --set llm.provider=CLAUDEAI \
  --set secrets.anthropicApiKey=sk-ant-xxx \
  --set server.token=equipe-token \
  --set watcher.enabled=true \
  --set watcher.deployment=myapp \
  --set watcher.namespace=production \
  --set watcher.interval=15s

apiVersion: platform.chatcli.io/v1alpha1
kind: Instance
metadata:
  name: chatcli-prod
spec:
  provider: CLAUDEAI
  apiKeys:
    name: chatcli-api-keys
  server:
    port: 50051
  watcher:
    enabled: true
    interval: "15s"
    maxContextChars: 32000
    targets:
      - deployment: frontend
        namespace: production
        metricsPort: 3000
      - deployment: backend
        namespace: production
        metricsPort: 9090
        metricsFilter: ["http_*", "db_*"]
      - deployment: worker
        namespace: batch

Em produção, habilite TLS no server (campo tls: com secretName). O Secret precisa conter tls.crt, tls.key e ca.crt com SANs corretos — o passo-a-passo está em AIOps Production Setup §2.1.

Com o Operator, além do monitoramento via watcher, você ganha o pipeline AIOps completo: detecção automática de anomalias, correlação em incidentes, análise de causa raiz por IA e remediação autônoma (scale, restart, rollback). Veja K8s Operator e AIOps Platform para documentação completa.

Equipe Conecta

# Cada dev configura
export CHATCLI_REMOTE_ADDR=chatcli.monitoring.svc:50051
export CHATCLI_REMOTE_TOKEN=equipe-token

# Via port-forward (desenvolvimento)
kubectl port-forward -n monitoring svc/chatcli 50051:50051
chatcli connect localhost:50051 --token equipe-token

Contexto Automático

Qualquer pergunta feita por qualquer dev já inclui automaticamente o contexto K8s:

> O que está acontecendo com o deployment?

[O servidor injeta automaticamente os dados do K8s Watcher]

Fluxo de Trabalho: Incidente em Produção

Alerta Disparado

Você recebe um alerta do Grafana/PagerDuty/Slack sobre problemas no deployment.

Conectar ao ChatCLI

chatcli connect prod-chatcli:50051 --token ops-token

Obter Visão Geral

> Resuma o estado atual do deployment para um post-mortem

Investigar Causa Raiz

> Quais eventos de Warning ocorreram nos últimos 30 minutos?
> Mostre os logs de erro mais recentes
> O que mudou desde o último deploy?

Receber Recomendações

> Baseado nos dados, qual a causa raiz mais provável e o que
  devo fazer para resolver?

Validar Resolução

> Após aplicar o fix, os pods estão voltando ao normal?
> Compare o estado atual com 10 minutos atrás

Ajuste Fino dos Parâmetros

Intervalo de Coleta

Cenário	Intervalo Recomendado
Produção estável	`30s` (padrão)
Investigação ativa	`10s`
Desenvolvimento	`60s`
CI/CD monitoring	`15s`

chatcli watch --deployment myapp --interval 10s

Janela de Observação

Cenário	Janela Recomendada
Debugging rápido	`30m`
Análise normal	`2h` (padrão)
Post-mortem	`6h`
Análise histórica	`24h`

chatcli watch --deployment myapp --window 6h

Linhas de Log

Cenário	Linhas Recomendadas
Apps verbosas	`50`
Normal	`100` (padrão)
Debugging profundo	`500`

chatcli watch --deployment myapp --max-log-lines 500

One-Shot para Scripts e Alertas

Integre o ChatCLI com seu sistema de alertas:

#!/bin/bash
# alert-handler.sh - Chamado quando um alerta dispara

DEPLOYMENT=$1
NAMESPACE=$2

# Gerar análise automática
ANALYSIS=$(chatcli watch \
  --deployment "$DEPLOYMENT" \
  --namespace "$NAMESPACE" \
  -p "Análise o estado atual do deployment e identifique a causa raiz do problema. Formato: markdown.")

# Enviar para Slack
curl -X POST "$SLACK_WEBHOOK" \
  -H 'Content-type: application/json' \
  -d "{\"text\": \"*ChatCLI K8s Analysis*\n\n$ANALYSIS\"}"

Ou via servidor remoto:

chatcli connect prod-server:50051 --token ops-token \
  -p "O deployment myapp está com problemas. Análise e sugira solução." --raw

Dicas Avançadas

Combinar com Contextos Persistentes

Salve documentação do projeto como contexto e anexe ao usar com o watcher:

# Salvar documentação do projeto como contexto
/context create myapp-docs ./docs --mode full --tags "k8s,ops"

# Anexar ao usar com o watcher
/context attach myapp-docs

# Agora a IA tem contexto do K8s + documentação do projeto
> Com base na documentação e no estado do cluster, o que pode estar errado?

Múltiplos Deployments

Use o modo multi-target para monitorar tudo em uma única instância:

# targets.yaml
interval: "15s"
window: "2h"
maxContextChars: 32000
targets:
  - deployment: frontend
    namespace: production
    metricsPort: 3000
    metricsFilter: ["next_*", "http_*"]
  - deployment: backend
    namespace: production
    metricsPort: 9090
    metricsFilter: ["http_requests_*", "db_*", "cache_*"]
  - deployment: database
    namespace: production

# Local
chatcli watch --config targets.yaml

# Ou via servidor (toda a equipe tem acesso)
chatcli server --watch-config targets.yaml

A IA recebe contexto detalhado dos targets com problemas e resumos compactos dos saudáveis, respeitando o budget de maxContextChars.

Métricas Prometheus

Quando metricsPort está configurado, o watcher scrapa automaticamente o endpoint /metrics dos pods e inclui as métricas na análise. Use metricsFilter com glob patterns para selecionar apenas métricas relevantes:

metricsFilter:
  - "http_requests_total"        # Métrica exata
  - "http_request_duration_*"    # Todas de duração HTTP
  - "process_*"                  # Métricas de processo
  - "*_errors_total"             # Qualquer contador de erros

Opção 3: AIOps Autônomo (Operator)

Use esta opção para remediação automática de problemas sem intervenção humana.

Instalar o Operator

# Instalar Operator via Helm (CRDs + RBAC + Controllers + Dashboard)
helm install chatcli-operator \
  oci://ghcr.io/diillson/charts/chatcli-operator \
  --namespace chatcli-system \
  --create-namespace

Criar Instance com Watcher

apiVersion: platform.chatcli.io/v1alpha1
kind: Instance
metadata:
  name: chatcli-aiops
  namespace: monitoring
spec:
  provider: CLAUDEAI
  apiKeys:
    name: chatcli-api-keys
  server:
    port: 50051
  watcher:
    enabled: true
    interval: "15s"
    targets:
      - deployment: api-gateway
        namespace: production
        metricsPort: 9090
      - deployment: backend
        namespace: production
        metricsPort: 9090
      - deployment: worker
        namespace: batch

Monitorar o Pipeline

# Verificar anomalias detectadas
kubectl get anomalies -A --watch

# Verificar issues criados
kubectl get issues -A --watch

# Verificar análises da IA
kubectl get aiinsights -A

# Verificar remediações
kubectl get remediationplans -A

# Verificar runbooks (manuais e auto-gerados)
kubectl get runbooks -A

# Verificar post-mortems (gerados após resolução agêntica)
kubectl get postmortems -A

Fluxo Autônomo em Ação

Quando um pod começa a crashar:

1. WatcherBridge detecta HighRestartCount -> cria Anomaly
2. AnomalyReconciler correlaciona -> cria Issue (risk: 20, severity: Low, signalType: pod_restart)
3. Se OOMKilled também -> Issue atualizado (risk: 50, severity: Medium)
4. IssueReconciler cria AIInsight
5. AIInsightReconciler coleta contexto K8s (pods, eventos, revisões)
   -> chama LLM com contexto enriquecido -> retorna: "restart + scale to 4"
6. IssueReconciler busca Runbook manual (tiered matching)
   -> se não encontra, gera Runbook auto da IA (reutilizável)
   -> se nenhum Runbook e nenhuma ação IA -> modo Agential
   -> cria RemediationPlan com ações
7. RemediationReconciler executa:
   -> Modo normal: executa ações do plano (restart, scale, etc.)
   -> Modo agential: loop observe-decide-act (IA decide cada passo)
     - Cada reconcile = 1 step (max 10 steps, timeout 10min)
     - IA observa estado K8s -> decide ação -> executa -> próximo step
     - Ações: Scale, Restart, Rollback, PatchConfig, AdjustResources, DeletePod
8. Issue -> Resolved (dedup invalidado para detecção de recorrência)
   -> Se modo agential: PostMortem CR auto-gerado (timeline, root cause, lições)
   -> Runbook gerado automaticamente dos steps agentiais bem-sucedidos
   Se falhar -> re-análise com contexto de falha -> estratégia diferente

Tudo acontece automaticamente sem intervenção humana. Runbooks auto-gerados são reutilizados para futuras ocorrências do mesmo tipo. No modo agêntico, a IA atua como agente autônomo com “skills” K8s, e ao resolver o problema gera um PostMortem CR com timeline completa e um Runbook reutilizável para futuras ocorrências.

(Opcional) Adicionar Runbooks

Para cenários específicos onde você quer controlar exatamente o que fazer:

apiVersion: platform.chatcli.io/v1alpha1
kind: Runbook
metadata:
  name: oom-standard-procedure
  namespace: production
spec:
  description: "Standard OOMKill recovery for production"
  trigger:
    signalType: oom_kill
    severity: critical
    resourceKind: Deployment
  steps:
    - name: Restart pods
      action: RestartDeployment
      description: "Restart to reclaim leaked memory"
    - name: Scale up
      action: ScaleDeployment
      description: "Add replicas for redundancy"
      params:
        replicas: "5"
  maxAttempts: 2

Prioridade de remediação: Runbook manual > Runbook auto-gerado > Remediação agêntica > Escalação. Quando não há Runbook manual, a IA gera automaticamente um Runbook CR reutilizável. Se nem Runbook nem ações de IA estão disponíveis, o operator entra em modo agêntico: a IA atua como agente autônomo num loop observe-decide-act, e ao resolver gera um PostMortem CR e um Runbook reutilizável.

Cookbook

Receita: Monitoramento K8s com IA

Cenário

Aplicação em Produção

Diagnóstico Rápido

Análise com IA

Contexto Automático

Opção 1: Monitoramento Local

Opção 2: Servidor com Watcher (Equipe)

Fluxo de Trabalho: Incidente em Produção

Ajuste Fino dos Parâmetros

Intervalo de Coleta

Janela de Observação

Linhas de Log

One-Shot para Scripts e Alertas

Dicas Avançadas

Opção 3: AIOps Autônomo (Operator)

Checklist de Implantação

​Cenário

Aplicação em Produção

Diagnóstico Rápido

Análise com IA

Contexto Automático

​Opção 1: Monitoramento Local

​Opção 2: Servidor com Watcher (Equipe)

​Fluxo de Trabalho: Incidente em Produção

​Ajuste Fino dos Parâmetros

​Intervalo de Coleta

​Janela de Observação

​Linhas de Log

​One-Shot para Scripts e Alertas

​Dicas Avançadas

​Opção 3: AIOps Autônomo (Operator)

​Checklist de Implantação

Cenário

Opção 1: Monitoramento Local

Opção 2: Servidor com Watcher (Equipe)

Fluxo de Trabalho: Incidente em Produção

Ajuste Fino dos Parâmetros

Intervalo de Coleta

Janela de Observação

Linhas de Log

One-Shot para Scripts e Alertas

Dicas Avançadas

Opção 3: AIOps Autônomo (Operator)

Checklist de Implantação