AIOps Platform (Deep-Dive)

​

Componentes da Plataforma v2

​

REST API e Dashboard

• Autenticação: header X-API-Key. As chaves vêm do Secret chatcli-operator-secrets, chave api-keys (fallback: ConfigMap chatcli-operator-config), no namespace do operator, como uma lista YAML de {key, role, description}. Os papéis são viewer < operator < admin; qualquer outro valor de role é negado. Alterações são aplicadas em cerca de 30 segundos; uma entrada api-keys que não é YAML válido mantém em vigor o último conjunto de chaves válido, e um Secret sem a entrada cai para o ConfigMap. Crie-o você mesmo, ou deixe o chart do operator renderizá-lo (apiKeys.create: true com apiKeys.entries). Sem chaves configuradas, toda chamada em /api/ retorna 401, a menos que CHATCLI_OPERATOR_DEV_MODE=true (admin sem chave, só para desenvolvimento).
• Rate limit: 30 requisições por minuto por host de cliente sem API key válida, 600 por minuto por chave válida (429 com Retry-After).
• CORS: deny-all, a menos que CHATCLI_CORS_ALLOWED_ORIGINS / CHATCLI_CORS_ORIGIN estejam definidos. TLS: defina CHATCLI_AIOPS_TLS_CERT e CHATCLI_AIOPS_TLS_KEY para servir HTTPS (TLS 1.3).
• Preview local: make dash-preview em operator/ serve o dashboard com dados sintéticos, sem cluster, em http://127.0.0.1:8085 com a API key preview.

​

Visão Geral do Pipeline

​

Componentes Internos

​

1. WatcherBridge (watcher_bridge.go)

hash = SHA256(alertType | deployment | namespace | resourceUID)

• Sem componente temporal: Um problema contínuo (e.g. CrashLoopBackOff) gera apenas uma Anomaly
• UID do recurso: um workload apagado e recriado ganha outro UID, então seus alertas não são engolidos pela entrada antiga
• TTL: 30 minutos por padrão (Instance spec.aiops.dedupTTLMinutes, 5–1440) — hashes expirados são podados automaticamente
• Invalidação: Quando um Issue é resolvido, contido ou escalado, as entradas de dedup para o recurso afetado são invalidadas, permitindo detecção imediata de recorrências
• Resultado: Evita duplicatas durante problema ativo; detecta recorrência após resolução

​

2. AnomalyReconciler (anomaly_controller.go)

​

3. CorrelationEngine (correlation.go)

Para cada nova anomalia:
  1. Procura um Issue não terminal no mesmo recurso (kind + nome + namespace)
  2. Se existe -> anexa a anomalia (risk score recalculado, nunca reduzido)
  3. Senão -> soma os pesos das anomalias não correlacionadas desse recurso
     nos últimos 10 minutos e cria um novo Issue
  4. O incident ID INC-YYYYMMDD-NNN é uma sequência por namespace e por dia (label, não o nome do Issue)

sinal oom_kill   -> Critical (sempre)
risk_score >= 80 -> Critical
risk_score >= 60 -> High
risk_score >= 30 -> Medium
risk_score <  30 -> Low

​

4. IssueReconciler (issue_controller.go)

• Cada retry dispara re-análise do AI com contexto de falhas anteriores
• O AI recebe previous_failure_context com evidência das tentativas que falharam
• O prompt instrui: “Não repita as mesmas ações. Analise por que falharam e sugira uma abordagem fundamentalmente diferente”
• Gera um novo Runbook auto-gerado quando a nova análise é diferente (o nome carrega um hash da análise)

1. Runbook existente (match tiered: SignalType+Severity+Kind -> Severity+Kind)
2. Runbook auto-gerado pela IA (materializado como CR reutilizável)
3. Plano agêntico (a IA decide cada passo)
4. Escalonamento depois de maxRemediationAttempts tentativas falhas

​

5. AIInsightReconciler (aiinsight_controller.go)

• Resource Status: replicas, conditions, containers, images + resources (cada tipo tem context builder dedicado)
• StatefulSet: replicas, update strategy, partition, PodManagementPolicy, VolumeClaimTemplates
• DaemonSet: desired/current/ready/available/unavailable, nodeSelector, tolerations
• Job/CronJob: active/succeeded/failed, completions, parallelism, schedule, lastSuccessful
• HPA: min/max replicas, current/desired, target utilization, current metrics, maxed-out detection
• Pod Details (até 5 pods, unhealthy primeiro): phase, restart count, container states
• Recent Events (últimos 15): tipo, reason, message, count
• Revision History: Últimas 5 revisões (ReplicaSets) com diff de imagens

• Stack Trace Extraction: detecta e extrai stack traces de Java (Exception/Caused by), Go (panic/goroutine), Python (Traceback), Node.js (Error at)
• Error Pattern Detection: 24+ padrões críticos categorizados (crash, connectivity, dns, auth, storage, tls, database, cache, messaging)
• Structured Log Parsing: extrai error/warn entries de logs JSON (campos level, msg, error, timestamp, logger)
• Init Container Logs: analisa logs de init containers (revela falhas de startup)
• Sidecar Logs: analisa logs de sidecars (istio-proxy, envoy, datadog-agent, etc.)
• Critical Lines: extrai linhas FATAL/PANIC com 3 linhas de contexto antes/depois
• Temporal Window: busca logs por janela temporal (10min antes do incidente), não apenas tail

• CPU/Memory: usage trends 30min antes → durante → 15min depois do incidente
• Request/Error Rate: HTTP requests e 5xx por segundo
• Latency: P50, P95, P99 histogram percentiles
• HPA Metrics: current vs desired replicas, CPU target
• Network: receive/transmit bytes/s
• Trend Analysis: detecta spikes, drops, sustained_high/low com cálculo de % de mudança
• Habilitado via: PROMETHEUS_URL env var no operator

• Helm Releases: detecta via Secrets type helm.sh/release.v1, status (deployed/failed/pending-upgrade), chart version, revisão anterior para rollback
• ArgoCD Applications: sync status (Synced/OutOfSync), health (Healthy/Degraded), conditions, last sync result
• Flux Kustomizations: ready status, source ref, conditions, last applied

• Git Correlation: encontra commits nos 30min antes do incidente
• Suspected Commit: identifica o commit mais provável (score por proximidade temporal + volume de mudanças)
• Code Extraction: extrai trechos de código referenciados em stack traces (file path + line number → código fonte)
• Config Analysis: lê Dockerfile, values.yaml, Chart.yaml para contexto de deploy
• Credenciais: chaves do Secret token, username + password, ou ssh-key + known_hosts; as credenciais HTTPS passam por um helper GIT_ASKPASS e nunca são gravadas no .git/config; o SSH confere as chaves do host contra o known_hosts (spec.sshHostKeyPolicy: acceptNew confia na primeira chave quando o Secret não tem nenhuma). Veja Repositórios de código

• Dependency Graph: descobre dependências via Services + EndpointSlices
• Temporal Correlation: encontra issues ativos no mesmo namespace e cross-namespace em janela de 15-20min
• Cascade Chain: ordena serviços por tempo de detecção (primeiro = root cause)
• Root Cause Service: identifica o serviço origem do cascade

• PDB Check: verifica se a ação violaria PodDisruptionBudgets
• Quota Check: verifica ResourceQuotas (>90% usado = warning)
• Node Capacity: conta pods no node para ações de cordon/drain
• Affected Services: descobre quais Services seriam impactados
• Risk Level: classifica como low/medium/high/critical

​

6. RemediationReconciler (remediation_controller.go)

Pending -> Snapshot -> Executing -> (checkpoint + ação, para cada ação)
  -> Verifying (90s timeout) -> Completed
  -> Se ação falha -> Rollback automático -> RolledBack
  -> Se verificação falha -> Rollback automático -> RolledBack
  -> Se rollback falha -> Failed

Pending -> Executing -> (loop agentico: AI decide -> executa -> observa -> repeat)
  -> Verifying -> Completed | Failed

Cada reconcile = 1 step do loop agentico:
  1. Refresh contexto K8s (KubernetesContextBuilder)
  2. Envia histórico + contexto -> AgenticStep RPC
  3. AI responde: {reasoning, resolved, next_action}
  4. Se resolved=true -> Verifying (+ annotations com dados do PostMortem)
  5. Se next_action -> executa -> registra observação -> requeue 5s
  6. Se observation-only -> registra -> requeue 10s
  7. Se next_action diverge do AIInsight sem divergence_reason
     -> registrado como rejeitado, não executado, a IA é consultada de novo
  Safety: max steps (Instance aiops.agenticMaxSteps, padrão 10), timeout 10 minutos,
  detector de convergência (observações repetidas, oscilação A-B-A-B, 5 falhas seguidas,
  mais de 8 minutos decorridos) falha o plano antes

​

7. ServerClient (grpc_client.go)

​

Interação Server e Operator

​

RPCs StreamAlerts e GetAlerts

rpc GetAlerts(GetAlertsRequest) returns (GetAlertsResponse);
rpc StreamAlerts(StreamAlertsRequest) returns (stream StreamAlertsResponse);

message WatcherAlert {
  string type = 1;            // HighRestartCount, OOMKilled, PodNotReady, DeploymentFailing, ...
  string severity = 2;        // info, warning, critical
  string message = 3;
  string object = 4;          // ex.: nome do pod
  string namespace = 5;
  string deployment = 6;
  int64 timestamp_unix = 7;
}

message GetAlertsRequest {
  string namespace = 1;       // filtro opcional
  string deployment = 2;      // filtro opcional
}

​

AnalyzeIssue RPC

rpc AnalyzeIssue(AnalyzeIssueRequest) returns (AnalyzeIssueResponse);

message SuggestedAction {
  string name = 1;
  string action = 2;
  string description = 3;
  map<string, string> params = 4;
}

message AnalyzeIssueResponse {
  string analysis = 1;
  float confidence = 2;
  repeated string recommendations = 3;
  string model = 4;
  string provider = 5;
  repeated SuggestedAction suggested_actions = 6;
  TokenUsage usage = 7;       // alimenta o ledger de custo
}

1. Contexto do Issue (nome, namespace, recurso, severidade, risk score, descrição)
2. O catálogo de ações (os 54 tipos de ação, com parâmetros e regras por tipo de recurso)
3. Instruções para retornar JSON estruturado com campos analysis, confidence, recommendations e actions

1. Remove markdown codeblocks (```json ... ```)
2. Parseia JSON em analysisResult
3. Clamp confidence entre 0.0 e 1.0
4. Se parsing falhar → usa resposta raw como analysis com confidence 0.5

​

AgenticStep RPC

rpc AgenticStep(AgenticStepRequest) returns (AgenticStepResponse);

message AgenticStepRequest {
  string issue_name = 1;
  string namespace = 2;
  string resource_kind = 3;
  string resource_name = 4;
  string signal_type = 5;
  string severity = 6;
  string description = 7;
  int32 risk_score = 8;
  string provider = 9;
  string model = 10;
  string kubernetes_context = 11;   // refreshado a cada step
  repeated AgenticHistoryEntry history = 12;
  int32 max_steps = 13;
  int32 current_step = 14;
  // Orientação do AIInsight anterior, para o loop não contradizer a própria análise
  string insight_analysis = 15;
  float insight_confidence = 16;
  repeated string insight_recommendations = 17;
  repeated SuggestedAction insight_suggested_actions = 18;
}

message AgenticStepResponse {
  string reasoning = 1;              // raciocínio da IA (registrado no histórico)
  bool resolved = 2;                 // true = problema resolvido
  SuggestedAction next_action = 3;   // null quando resolved=true
  // Campos abaixo só populados quando resolved=true:
  string postmortem_summary = 4;
  string root_cause = 5;
  string impact = 6;
  repeated string lessons_learned = 7;
  repeated string prevention_actions = 8;
  bool diverges_from_insight = 9;     // next_action contradiz o AIInsight
  string divergence_reason = 10;      // justificativa quando diverge de propósito
  TokenUsage usage = 11;
}

1. Role + Issue details: contexto do incidente (tipo, severidade, recurso)
2. Kubernetes context: estado real do cluster (refreshado a cada step via KubernetesContextBuilder)
3. Tool definitions: o catálogo de ações + “Observe” (sem ação, espera próximo contexto)
4. Conversation history: cada step anterior formatado com reasoning → action → observation
5. Instructions: respond JSON, budget (step N of M), regras de segurança

​

PostMortem Generation

​

PostMortem CR

• Trending: detecção de incidentes recorrentes (contagem nos últimos 30 dias, PostMortems relacionados)
• Cascade Chain: cadeia de cascade failure se houver issues correlacionados cross-service
• Git Correlation: commit suspeito (SHA, autor, arquivos alterados, confiança)
• GitOps Context: estado do Helm/ArgoCD/Flux no momento do incidente

​

Runbook Auto-gerado (Agentic)

• Nome: agentic-{signal}-{severity}-{kind} (sanitizado)
• Steps: apenas os passos com ação bem-sucedida
• Labels: auto-generated=true, source=agentic
• Usa CreateOrUpdate (reutilizado para incidentes futuros do mesmo tipo)

​

Prometheus Metrics do Operator

​

Testes

​

Executar Testes

cd operator
go test ./... -v          # testes unitários sobre o client fake
make test-integration    # envtest: API server real, CRDs, todos os controllers ligados

​

Diagrama de Ownership (Garbage Collection)

• Instance é owner dos recursos namespaced que cria (Deployment, Service, ConfigMaps, SA, PVC, Role/RoleBinding do watcher); um ClusterRoleBinding de watcher entre namespaces é removido pelo finalizer da Instance
• Issue é owner de AIInsight, RemediationPlan e PostMortem (cascade delete)
• Anomalies são independentes (não têm owner) para preservar histórico

​

Checklist de Implantação AIOps

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

kubectl create namespace chatcli
kubectl -n chatcli create secret generic chatcli-api-keys --from-literal=ANTHROPIC_API_KEY=<sua-chave>
kubectl -n chatcli create secret generic chatcli-server-token --from-literal=token="$(openssl rand -hex 32)"
kubectl -n chatcli create secret tls chatcli-tls --cert=tls.crt --key=tls.key

apiVersion: platform.chatcli.io/v1alpha1
kind: Instance
metadata:
  name: chatcli
  namespace: chatcli
spec:
  provider: CLAUDEAI
  apiKeys:
    name: chatcli-api-keys
  server:
    tls:
      enabled: true
      secretName: chatcli-tls
    token:
      name: chatcli-server-token
      key: token
  watcher:
    enabled: true
    targets:
      - name: my-app
        kind: Deployment
        namespace: production

​

Próximo Passo