Monitoramento Kubernetes (K8s Watcher)

O K8s Watcher permite que o ChatCLI monitore múltiplos deployments simultaneamente, coletando métricas de infra e aplicação, logs, eventos e status de pods. O contexto é automaticamente injetado nos prompts do LLM com gestão inteligente de budget para não estourar a janela de contexto.

Arquitetura

Single-Target (legado)
Multi-Target (atual)

ChatCLI -> ResourceWatcher -> 6 Collectors -> ObservabilityStore -> Summarizer -> LLM

                        |-> ResourceWatcher[0] -> Store[0] --|
ChatCLI -> MultiWatcher-|-> ResourceWatcher[1] -> Store[1] --|-> MultiSummarizer -> LLM
                        +-> ResourceWatcher[N] -> Store[N] --+   (budget-controlled)

Cada ResourceWatcher possui seus próprios collectors (incluindo PrometheusCollector opcional) e todos compartilham um único clientset Kubernetes, minimizando conexões.

Modos de Uso

Recurso Único
Múltiplos Recursos (YAML)
Servidor com Watcher

# Deployment (padrão)
chatcli watch --deployment myapp --namespace production

# StatefulSet
chatcli watch --deployment postgres --kind StatefulSet --namespace production

# DaemonSet
chatcli watch --deployment fluentd --kind DaemonSet --namespace logging

# CronJob
chatcli watch --deployment etl-pipeline --kind CronJob --namespace data

# One-shot com prompt
chatcli watch --deployment myapp -p "O deployment está saudável?"

chatcli watch --config targets.yaml
chatcli watch --config targets.yaml -p "Quais deployments precisam de atenção?"

# Multi-target
chatcli server --watch-config targets.yaml

# Single-target (legado)
chatcli server --watch-deployment myapp --watch-namespace production

Clientes conectados via chatcli connect recebem o contexto K8s automaticamente.

Arquivo de Configuração Multi-Target

# targets.yaml
interval: "30s"           # Intervalo de coleta
window: "2h"              # Janela temporal de dados mantidos
maxLogLines: 100          # Linhas de log por pod por ciclo
maxContextChars: 32000     # Budget máximo de caracteres para contexto LLM

targets:
  - deployment: api-gateway                                  # Deployment (kind padrão)
    namespace: production
    metricsPort: 9090                                        # Porta Prometheus
    metricsFilter: ["http_requests_total", "http_request_duration_*"]

  - deployment: auth-service
    namespace: production
    metricsPort: 9090

  - deployment: worker
    namespace: batch
    # Sem metricsPort = Prometheus desabilitado para este target

  - deployment: postgres                                     # StatefulSet (banco de dados)
    kind: StatefulSet
    namespace: production

  - deployment: fluentd                                      # DaemonSet (logging)
    kind: DaemonSet
    namespace: logging

  - deployment: etl-pipeline                                 # CronJob (batch agendado)
    kind: CronJob
    namespace: data

Campos do Target

Campo	Descrição	Obrigatório
`deployment`	Nome do recurso a monitorar	Sim
`kind`	Tipo do recurso: `Deployment`, `StatefulSet`, `DaemonSet`, `Job`, `CronJob` (padrão: `Deployment`)	Não
`namespace`	Namespace (padrão: `default`)	Não
`metricsPort`	Porta do endpoint Prometheus (0 = desabilitado)	Não
`metricsPath`	Path HTTP das métricas (padrão: `/metrics`)	Não
`metricsFilter`	Filtros glob para métricas (vazio = todas)	Não

Flags Completas

`chatcli watch`

Flag	Descrição	Padrão	Env Var
`--config`	Arquivo YAML multi-target
`--deployment`	Nome do recurso a monitorar		`CHATCLI_WATCH_DEPLOYMENT`
`--kind`	Tipo do recurso: `Deployment`, `StatefulSet`, `DaemonSet`, `Job`, `CronJob`	`Deployment`
`--namespace`	Namespace do recurso	`default`	`CHATCLI_WATCH_NAMESPACE`
`--interval`	Intervalo entre coletas	`30s`	`CHATCLI_WATCH_INTERVAL`
`--window`	Janela temporal de dados	`2h`	`CHATCLI_WATCH_WINDOW`
`--max-log-lines`	Linhas de log por pod	`100`	`CHATCLI_WATCH_MAX_LOG_LINES`
`--kubeconfig`	Caminho do kubeconfig	Auto-detectado	`CHATCLI_KUBECONFIG`
`--provider`	Provedor de LLM	`.env`	`LLM_PROVIDER`
`--model`	Modelo de LLM	`.env`
`-p <prompt>`	One-shot: envia e sai
`--max-tokens`	Limite de tokens na resposta

`chatcli server` (flags do watcher)

Flag	Descrição	Padrão	Env Var
`--watch-config`	Arquivo YAML multi-target		`CHATCLI_WATCH_CONFIG`
`--watch-deployment`	Deployment único (legado)		`CHATCLI_WATCH_DEPLOYMENT`
`--watch-namespace`	Namespace	`default`	`CHATCLI_WATCH_NAMESPACE`
`--watch-interval`	Intervalo de coleta	`30s`	`CHATCLI_WATCH_INTERVAL`
`--watch-window`	Janela de observação	`2h`	`CHATCLI_WATCH_WINDOW`
`--watch-max-log-lines`	Max linhas de log	`100`	`CHATCLI_WATCH_MAX_LOG_LINES`
`--watch-kubeconfig`	Caminho do kubeconfig	Auto-detectado	`CHATCLI_KUBECONFIG`

O que e Coletado

Collectors por Target

Collector	Dados Coletados
Deployment	Replicas (ready/available/updated), strategy, conditions
Pod Status	Fase, readiness, restarts, termination info, container status
Events	Eventos K8s (Warning/Normal), mensagem, razao, timestamp
Logs	Ultimas N linhas por container por pod
Metrics	CPU e memória por pod (via metrics-server)
HPA	Min/max replicas, métricas atuais, replicas desejadas
Prometheus	Métricas de aplicação do endpoint `/metrics` dos pods
Node Health	Condições do node (Ready, DiskPressure, MemoryPressure, PIDPressure, NetworkUnavailable), cordoned, CPU/mem usage, pod count vs capacity, versão kubelet

Node Health Collector

O NodeCollector monitora automaticamente a saude dos nodes onde os pods do target estão rodando:

Descobre nodes — via label selector dos pods do target, identifica em quais nodes eles estão schedulados
Coleta condições — todas as 5 condições oficiais do Kubernetes (Ready, DiskPressure, MemoryPressure, PIDPressure, NetworkUnavailable)
Coleta métricas — CPU e memória do node via metrics-server (quando disponível)
Pod capacity — conta pods ativos vs capacidade máxima do node
Cordoned — detecta nodes marcados como unschedulable

Alertas emitidos:

Condição	Severidade	Exemplo de mensagem
NotReady	CRITICAL	`Node worker-1 is NotReady`
DiskPressure	CRITICAL	`Node worker-1 has DiskPressure`
MemoryPressure	CRITICAL	`Node worker-1 has MemoryPressure`
PIDPressure	WARNING	`Node worker-1 has PIDPressure`
NetworkUnavailable	CRITICAL	`Node worker-1 has NetworkUnavailable`
Cordoned	WARNING	`Node worker-1 is cordoned (unschedulable)`
Pod capacity >90%	WARNING	`Node worker-1 pod capacity at 95/110 (>90%)`

O contexto do node e incluido no summary enviado ao LLM, permitindo que a IA correlacione problemas de pod com infraestrutura:

## Nodes (2)
  - worker-1: Ready cpu=1200m/4 mem=3Gi/8Gi pods=45/110 k8s=v1.31.4
  - worker-2: NOT READY [MemoryPressure] cpu=3800m/4 mem=7.8Gi/8Gi pods=98/110 k8s=v1.31.4
    MemoryPressure: kubelet has insufficient memory available

Prometheus Collector (Novo)

O PrometheusCollector scrapa métricas Prometheus diretamente dos pods:

Descobre pods do deployment e seleciona 1 pod Ready
Faz HTTP GET em http://podIP:port/path (timeout: 5s)
Parseia o formato Prometheus text exposition (stdlib, sem dependências)
Filtra por glob patterns configurados
Ignora NaN, Inf e linhas de comentario

Exemplos de filtros glob:

metricsFilter:
  - "http_requests_*"          # Todas as métricas HTTP
  - "process_*"                # Métricas de processo
  - "go_goroutines"            # Métrica específica
  - "*_duration_seconds_*"     # Qualquer métrica de duração

Gestão de Budget de Contexto (MultiSummarizer)

Com múltiplos targets, o MultiSummarizer garante que o contexto não estoure a janela do LLM:

Algoritmo

Pontua cada target

0 = healthy, 1 = warning, 2 = critical

Critical: CrashLoopBackOff, OOMKilled, alerts criticos
Warning: replicas < desired, error logs, alerts warning
Healthy: tudo ok

Ordena por prioridade

Critical primeiro, depois warning, depois healthy.

Aloca contexto

Score >= 1 — contexto completo (~1-3 KB por target)
Score == 0 — one-liner compacto (~80 chars por target)

Comprime se excede maxContextChars

Comprime targets saudáveis primeiro.

Omite se ainda excede

Omite targets saudáveis quando necessário.

Exemplo com 20 Targets (2 com problemas)

[K8s Multi-Watcher: 20 targets monitored]

--- Targets Requiring Attention ---

[K8s Context: deployment/api-gateway in namespace/production]
Collected at: 2026-02-15T10:30:00Z

## Deployment Status
  Replicas: 2/3 ready, 3 updated, 2 available
  Strategy: RollingUpdate

## Pods (3 total)
  Total restarts: 12 (delta in window: 8)
  - api-gateway-abc12: Running [Ready] restarts=0 cpu=45m mem=128Mi
  - api-gateway-def34: Running [Ready] restarts=0 cpu=52m mem=135Mi
  - api-gateway-ghi56: Running [NOT READY] restarts=8 cpu=12m mem=95Mi
    Last terminated: OOMKilled (exit code 137) at 2026-02-15T10:28:00Z

## Application Metrics (4)
  http_request_duration_seconds_sum: 8453
  http_requests_total: 1.542e+06
  process_resident_memory_bytes: 1.34e+08
  go_goroutines: 245

## Active Alerts (2)
  [CRITICAL] CrashLoopBackOff: pod/api-gateway-ghi56
  [CRITICAL] OOMKilled: pod/api-gateway-ghi56

## Recent Error Logs (3)
  [10:27:45] api-gateway-ghi56/app: OutOfMemoryError: heap space
  [10:27:46] api-gateway-ghi56/app: Shutting down...
  [10:28:00] api-gateway-ghi56/app: Process exited with code 137

--- Healthy Targets ---
- production/auth-service: 3/3 pods ready | healthy | 0 alerts | 42 snapshots
- production/frontend: 2/2 pods ready | healthy | 0 alerts | 42 snapshots
- production/backend: 5/5 pods ready | healthy | 0 alerts | 42 snapshots
- batch/worker: 3/3 pods ready | healthy | 0 alerts | 42 snapshots
... (16 targets compactos)

Budget total: ~2 KB (detail) + 18 x 80 chars (compact) = ~3.5 KB, dentro do limite de 8 KB.

Detecção de Anomalias

Anomalia	Condição	Severidade
CrashLoopBackOff	Pod com mais de 5 restarts	Critical
OOMKilled	Container terminado por falta de memória	Critical
PodNotReady	Pod não está no estado Ready	Warning
DeploymentFailing	Deployment com Available=False	Critical

Os alertas são incluidos no contexto enviado ao LLM e influenciam a prioridade de budget do MultiSummarizer.

Observability Store

Os dados coletados são armazenados em um ring buffer por target com janela temporal configurável:

Snapshots: Estado completo periodico (pods, deployment, HPA, events, metrics, app metrics)
Logs: Logs recentes de cada pod com classificação (info/warning/error)
Alertas: Anomalias detectadas com severidade e timestamps

Rotação Automática

Dados mais antigos que a janela temporal (--window) são automaticamente descartados, mantendo o uso de memória constante independente do número de targets.

Comando `/watch`

Dentro do ChatCLI interativo (local ou remoto), use /watch para ver o estado:

Single-Target
Multi-Target

/watch
K8s Watcher Active
  Deployment:  myapp
  Namespace:   production
  Snapshots:   42
  Pods:        3
  Alerts:      1

/watch
K8s Multi-Watcher Active
  Watching 20 targets: 18 healthy, 1 warning, 1 critical

One-Shot com Contexto K8s

# Deployment unico
chatcli watch --deployment myapp -p "O deployment está saudável?"

# Multi-target
chatcli watch --config targets.yaml -p "Resuma o status de todos os deployments"

# Via servidor remoto
chatcli connect meuservidor:50051 -p "Por que os pods estão reiniciando?"

Exemplos de Perguntas

> O deployment está saudável?
> Quais deployments precisam de atenção?
> Por que o pod xyz está reiniciando?
> Análise as métricas HTTP do api-gateway. O latency está aceitável?
> Compare o estado do auth-service com 30 minutos atrás
> Quais eventos de warning ocorreram na última hora?
> Baseado nas métricas Prometheus, preciso escalar algum deployment?
> Resuma o status de todos os targets para um report de equipe

Requisitos

Kubernetes Cluster: Acesso via kubeconfig ou in-cluster config
Permissões RBAC: Leitura de pods, eventos, logs, deployments, HPA, ingresses
metrics-server (opcional): Para coleta de CPU/memória
Prometheus endpoints (opcional): Apps que expoe /metrics no formato Prometheus text

RBAC

Single-namespace (Role + RoleBinding)
Multi-namespace (ClusterRoleBinding + ClusterRole compartilhada)

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: chatcli-watcher
  namespace: production
rules:
  - apiGroups: [""]
    resources: ["pods", "pods/log", "events", "services", "endpoints"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["apps"]
    resources: ["deployments", "replicasets", "statefulsets", "daemonsets"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["autoscaling"]
    resources: ["horizontalpodautoscalers"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["networking.k8s.io"]
    resources: ["ingresses"]
    verbs: ["get", "list"]
  - apiGroups: ["metrics.k8s.io"]
    resources: ["pods"]
    verbs: ["get", "list"]

Quando os targets estão em namespaces diferentes, o Operator cria apenas um ClusterRoleBinding por Instance, referenciando a ClusterRole compartilhada chatcli-watcher que é pré-provisionada pelo Helm chart do operator (hardening H5 — ver k8s-operator#tls-e-rbac). As regras do chatcli-watcher são as mesmas da Role acima, aplicadas cluster-wide.

Integração com AIOps

Os alertas do K8s Watcher alimentam automaticamente o pipeline AIOps do Operator. Quando o Operator detecta alertas via GetAlerts RPC, ele cria Anomaly CRs que são correlacionados em Issues, analisados por IA e remediados automaticamente.

Alertas detectados pelo Watcher -> Anomaly -> Issue -> AIInsight -> RemediationPlan -> Resolução

Veja AIOps Platform para o fluxo completo.

A partir da v2 da plataforma AIOps, os alertas do Watcher também alimentam:

NotificationPolicy para roteamento automático para Slack, PagerDuty, OpsGenie, Email, Webhook e Teams
ApprovalPolicy para gate de aprovação antes de remediações em produção
ServiceLevelObjective para cálculo de burn rate e error budget
NoiseReducer para supressão de alertas repetitivos, sazonais e flapping

Consulte a documentação completa da AIOps Platform para detalhes.

Próximo Passo

Modo Servidor

Configurar o servidor com watcher

K8s Operator

K8s Operator (AIOps)

AIOps Platform

AIOps Platform (deep-dive)

​Arquitetura

​Modos de Uso

​Arquivo de Configuração Multi-Target

​Campos do Target

​Flags Completas

​chatcli watch

​chatcli server (flags do watcher)

​O que e Coletado

​Collectors por Target

​Node Health Collector

​Prometheus Collector (Novo)

​Gestão de Budget de Contexto (MultiSummarizer)

​Algoritmo

​Exemplo com 20 Targets (2 com problemas)

​Detecção de Anomalias

​Observability Store

​Rotação Automática

​Comando /watch

​One-Shot com Contexto K8s

​Exemplos de Perguntas

​Requisitos

​RBAC

​Integração com AIOps

​Próximo Passo