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)

Início

Primeiros Passos

Conceitos Fundamentais

Funcionalidades

Segurança

Suporte

Monitoramento Kubernetes (K8s Watcher)

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

Modo Servidor

K8s Operator

AIOps Platform

Deploy no Kubernetes

​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

Modo Servidor

K8s Operator

AIOps Platform

Deploy no Kubernetes

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