Receita: Monitoramento K8s com IA

Esta receita coloca o K8s Watcher para trabalhar numa aplicação myapp no namespace production, em três montagens:

Opção	Roda	Bom para
1. Local	`chatcli watch` na sua máquina, com seu kubeconfig	uma pessoa, diagnóstico pontual
2. Servidor do time	`chatcli server` com watcher, instalado com Helm	um time dividindo um contexto e um conjunto de chaves de API
3. AIOps	uma `Instance` gerenciada pelo operator	alertas viram Issues, análise por IA e remediação

Opção 1: monitoramento local

Confira o acesso ao cluster

kubectl config current-context
kubectl get deploy myapp -n production
kubectl auth can-i list pods -n production
kubectl auth can-i get pods/log -n production
kubectl auth can-i list events -n production

O watcher usa ~/.kube/config com o contexto atual (ou --kubeconfig); ele não lê KUBECONFIG.

Inicie o watcher

chatcli watch --deployment myapp --namespace production

Starting K8s watcher: 1 targets (interval: 30s, window: 2h0m0s)
Initial data collected. K8s context will be injected into all prompts.
Type your questions about the deployments. K8s context is automatically included.
Use /watch to see current status.

Pergunte

> O deployment está saudável?
> Por que o pod myapp-7d9f-abcde está reiniciando?
> Que eventos de warning aconteceram nos últimos 30 minutos?
> Mostre os logs de erro mais recentes e o que eles têm em comum

Todo prompt leva o status do deployment, pods, eventos, logs de erro recentes, HPA, saúde dos nodes e alertas ativos. O /watch status imprime o estado numa linha.

Ajustes

Flag	Padrão	Quando mudar
`--interval`	`30s`	`10s` durante uma depuração ativa; `60s` num ambiente tranquilo
`--window`	`2h`	`30m` para uma olhada rápida; `6h` ou mais para comparar com antes
`--max-log-lines`	`100`	menos para apps verbosos; mais para depuração profunda

chatcli watch --deployment myapp --namespace production --interval 10s --window 6h --max-log-lines 300

Vários workloads, outros tipos, métricas Prometheus

# targets.yaml
interval: "15s"
window: "2h"
maxContextChars: 32000
targets:
  - deployment: frontend
    namespace: production
    metricsPort: 3000
    metricsFilter: ["http_*"]
  - deployment: backend
    namespace: production
    metricsPort: 9090
    metricsFilter: ["http_requests_*", "db_*", "cache_*"]
  - deployment: postgres
    kind: StatefulSet
    namespace: production
  - deployment: nightly-report
    kind: CronJob
    namespace: batch

chatcli watch --config targets.yaml

Alvos com problema recebem detalhe completo e os saudáveis uma única linha, dentro de maxContextChars. A coleta Prometheus lê os IPs dos pods por HTTP puro, então de um notebook só funciona se a sua rede roteia para os IPs dos pods; do contrário os outros dados continuam chegando e a seção de métricas simplesmente não aparece.

One-shot para handlers de alerta

#!/usr/bin/env bash
# alert-handler.sh <deployment> <namespace>
set -euo pipefail
ANALYSIS=$(chatcli watch --deployment "$1" --namespace "$2" \
  -p "Analise o estado atual deste deployment e identifique a causa raiz mais provável. Responda em Markdown.")

jq -n --arg text "*Análise do ChatCLI para $2/$1*"$'\n\n'"$ANALYSIS" '{text: $text}' \
  | curl -sS -X POST -H 'Content-Type: application/json' --data @- "$SLACK_WEBHOOK_URL"

Cada execução coleta uma vez (até 10 segundos) antes de perguntar, então a resposta reflete o estado atual.

Opção 2: servidor do time com watcher (Helm)

Instale o servidor com um watcher

helm install chatcli oci://ghcr.io/diillson/charts/chatcli \
  --version 1.212.1 \
  --namespace monitoring --create-namespace \
  --set llm.provider=CLAUDEAI \
  --set secrets.anthropicApiKey="$ANTHROPIC_API_KEY" \
  --set server.token="$(openssl rand -hex 32)" \
  --set watcher.enabled=true \
  --set watcher.deployment=myapp \
  --set watcher.namespace=production \
  --set watcher.interval=15s

server.token é obrigatório: num pod o servidor escuta em todas as interfaces e se recusa a subir sem credencial.
O log do servidor chega ao kubectl logs sozinho: num pod o servidor também o escreve no stderr, em linhas JSON. A cópia em arquivo no pod roda a cada 20 MB com 3 backups (logging.*), o que cabe no volume de dados de 200Mi do pod.
Um watcher.namespace vazio observa o default. Um namespace diferente do release (production aqui, fora de monitoring) faz o chart criar uma ClusterRole automaticamente. Para vários workloads, ou um StatefulSet, DaemonSet, Job ou CronJob (kind), use watcher.targets num arquivo de valores (veja valores do watcher no Helm).

Confira

kubectl -n monitoring rollout status deploy/chatcli
kubectl -n monitoring logs deploy/chatcli | grep -E 'listening|watcher active'
# 🚀 ChatCLI server listening on 0.0.0.0:50051
# K8s watcher active: 1 targets (interval: 15s)

Conecte

export CHATCLI_REMOTE_TOKEN="$(kubectl -n monitoring get secret chatcli \
  -o jsonpath='{.data.CHATCLI_SERVER_TOKEN}' | base64 -d)"

kubectl -n monitoring port-forward svc/chatcli 50051:50051 &
CHATCLI_ALLOW_INSECURE=true chatcli connect localhost:50051 --token "$CHATCLI_REMOTE_TOKEN"

Connected to ChatCLI server (version: 1.212.1, provider: CLAUDEAI, model: claude-sonnet-5)
K8s watcher active: multi/1 targets (context injected into all prompts)

O servidor soma o contexto do watcher a todo prompt, então cada pessoa do time só pergunta. CHATCLI_ALLOW_INSECURE=true é necessário porque este servidor é texto puro; para qualquer coisa além de um port-forward ligue o TLS e conecte com --tls --ca-cert.

Para dar um acesso por pessoa, troque para JWTs (security.jwtSecretRef), assim cada chamador tem identidade e bucket de rate limit próprios; veja Autenticação do servidor.

Fluxo de incidente

chatcli connect localhost:50051 --token "$CHATCLI_REMOTE_TOKEN"   # acrescente CHATCLI_ALLOW_INSECURE=true para texto puro

> Resuma o estado atual do myapp para o canal do incidente
> Que eventos de warning aconteceram nos últimos 30 minutos?
> Mostre os logs de erro mais recentes
> Qual a causa raiz mais provável e o que devo fazer primeiro?
> Depois da correção: os pods voltaram ao normal? Compare com 20 minutos atrás.

A comparação funciona dentro de watcher.window (padrão 2 horas). O /watch status nesta sessão consulta o watcher do servidor (K8s Watcher (remote): …). Para scripts contra o servidor:

CHATCLI_ALLOW_INSECURE=true chatcli connect localhost:50051 --token "$CHATCLI_REMOTE_TOKEN" \
  -p "O myapp está falhando. Analise e sugira uma correção." --raw

Opção 3: AIOps autônomo (operator)

O operator provisiona o servidor a partir de uma Instance, lê os alertas do watcher via StreamAlerts e conduz Anomaly → Issue → AIInsight → RemediationPlan. Ele disca o servidor por TLS com uma credencial, então a Instance precisa das duas coisas.

Instale o operator

helm install chatcli-operator oci://ghcr.io/diillson/charts/chatcli-operator \
  --version 1.212.1 \
  -n chatcli-system --create-namespace

Crie os Secrets

Siga Sua primeira Instance para os três Secrets no namespace chatcli: chatcli-api-keys (chave do provedor), chatcli-server-token (chave token) e chatcli-tls (tls.crt, tls.key, ca.crt, válido para chatcli.chatcli.svc.cluster.local).

Crie a Instance com watcher

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

kubectl apply -f instance.yaml
kubectl -n chatcli get instance chatcli

Sem server.token (ou outra credencial) o operator não cria o Deployment (AuthenticationConfigured=False); sem TLS ele não alcança o servidor (ServerReachable=False). namespace é obrigatório em todo alvo. O pipeline usa a primeira Instance pronta do cluster.

Acompanhe o pipeline

kubectl get anomalies -A --watch
kubectl get issues -A
kubectl get aiinsights -A
kubectl get remediationplans -A
kubectl get runbooks -A
kubectl get postmortems -A

Um pod em crash loop dispara HighRestartCount (e OOMKilled quando essa é a causa); o operator registra uma Anomaly, correlaciona numa Issue, pede uma análise ao servidor (AnalyzeIssue) e remedia a partir de um Runbook compatível, de ações sugeridas pela IA ou de um loop agêntico observar-decidir-agir (AgenticStep, até spec.aiops.agenticMaxSteps, padrão 10). O fluxo completo, as aprovações e os limites de segurança estão em Plataforma AIOps.

(Opcional) Adicione um Runbook

apiVersion: platform.chatcli.io/v1alpha1
kind: Runbook
metadata:
  name: oom-standard-procedure
  namespace: production
spec:
  description: "Recuperação padrão de OOMKill em produção"
  trigger:
    signalType: oom_kill
    severity: critical
    resourceKind: Deployment
  steps:
    - name: Restart pods
      action: RestartDeployment
      description: "Reinicia para recuperar a memória vazada"
    - name: Scale up
      action: ScaleDeployment
      description: "Adiciona réplicas para redundância"
      params:
        replicas: "5"
  maxAttempts: 2

Um Runbook manual que casa com a Issue é usado antes das ações geradas pela IA.

Solução de problemas

Sintoma	Causa	Correção
`failed to create K8s watcher: …`	Sem kubeconfig utilizável ou cluster inacessível	Confira `kubectl get pods`; passe `--kubeconfig`
O contexto vem sem pods ou eventos e o log mostra `forbidden`	Falta RBAC	Conceda as regras do watcher
Pod do servidor em crash loop; o `kubectl logs` mostra `refusing to serve an unauthenticated API`	Sem credencial	Defina `server.token`
`tls: first record does not look like a TLS handshake` ao conectar	Servidor em texto puro	`CHATCLI_ALLOW_INSECURE=true`, ou ligue o TLS
`/watch status` depois do `chatcli connect` diz que não há watcher	O servidor não roda nenhum: sem a linha `K8s watcher active` ao conectar	Defina `watcher.enabled=true` e um alvo no chart do servidor
Sem `## Application Metrics`	IPs dos pods inacessíveis, `metricsPort`/`metricsPath` errados, ou filtro que não casa nada	Rode o watcher no cluster; confira porta e filtro
A Instance nunca ganha Deployment	`AuthenticationConfigured=False` ou `TLSConfigured=False`	Adicione `server.token` e `tls.secretName`
Nenhuma Anomaly aparece	`ServerReachable=False`, ou nenhum alerta disparou ainda	Confira as conditions da Instance; veja problemas do K8s Operator

Cookbook

Receita: Monitoramento K8s com IA

Opção 1: monitoramento local

Ajustes

Vários workloads, outros tipos, métricas Prometheus

One-shot para handlers de alerta

Opção 2: servidor do time com watcher (Helm)

Fluxo de incidente

Opção 3: AIOps autônomo (operator)

Solução de problemas

Checklist

​Opção 1: monitoramento local

​Ajustes

​Vários workloads, outros tipos, métricas Prometheus

​One-shot para handlers de alerta

​Opção 2: servidor do time com watcher (Helm)

​Fluxo de incidente

​Opção 3: AIOps autônomo (operator)

​Solução de problemas

​Checklist

Opção 1: monitoramento local

Ajustes

Vários workloads, outros tipos, métricas Prometheus

One-shot para handlers de alerta

Opção 2: servidor do time com watcher (Helm)

Fluxo de incidente

Opção 3: AIOps autônomo (operator)

Solução de problemas

Checklist