Kubernetes Operator (AIOps)

​

Como as peças se encaixam

• Uma Instance é um servidor gRPC do ChatCLI (chatcli server) que o operator implanta e mantém em ordem: um Deployment, um Service, ConfigMaps, uma ServiceAccount e, opcionalmente, um PVC e RBAC do watcher.
• O operator sempre conecta no servidor com TLS 1.3. Não existe caminho em texto puro do operator até uma Instance. O endereço discado é <name>.<namespace>.svc.cluster.local:<port>, então o certificado do servidor precisa valer para esse nome.
• Toda Instance precisa de uma credencial. Dentro do cluster o servidor escuta em todas as interfaces e se recusa a subir sem token compartilhado, material JWT ou CA de cliente. O operator confere isso antes e não cria o Deployment quando o spec não tem nenhum.
• Uma Instance por cluster conduz o AIOps. O WatcherBridge lista todas as Instances do cluster e se conecta à primeira pronta que encontrar. Você pode rodar outras Instances para chat, mas só uma alimenta o pipeline de incidentes, e qual delas não é algo em que se possa confiar.
• A API REST e o dashboard web são servidos pelo operator, não pela Instance: Service chatcli-operator, porta 8090, autenticados por API key.

​

API group e CRDs

​

Pré-requisitos

​

Instalar o operator

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

cd operator
make deploy

​

Verificar a instalação

kubectl get crd -o name | grep -c 'platform.chatcli.io'   # 17
kubectl -n chatcli-system get deploy,svc,pods
kubectl -n chatcli-system logs deploy/chatcli-operator | grep -E 'starting manager|REST|allowlist'

​

Sua primeira Instance

kubectl create namespace chatcli

kubectl -n chatcli create secret generic chatcli-api-keys \
  --from-literal=ANTHROPIC_API_KEY='<sua-chave-anthropic>'

kubectl -n chatcli create secret generic chatcli-server-token \
  --from-literal=token="$(openssl rand -hex 32)"

NAME=chatcli NS=chatcli

cat > ca.cnf <<EOF
[req]
distinguished_name = dn
prompt = no
x509_extensions = v3_ca
[dn]
CN = chatcli-internal-ca
[v3_ca]
basicConstraints = critical, CA:TRUE
keyUsage = critical, keyCertSign, cRLSign
subjectKeyIdentifier = hash
EOF

cat > server.cnf <<EOF
[req]
distinguished_name = dn
prompt = no
req_extensions = v3_req
[dn]
CN = ${NAME}.${NS}.svc.cluster.local
[v3_req]
basicConstraints = critical, CA:FALSE
keyUsage = critical, digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names
[alt_names]
DNS.1 = ${NAME}.${NS}.svc.cluster.local
DNS.2 = ${NAME}.${NS}.svc
DNS.3 = ${NAME}.${NS}
DNS.4 = ${NAME}
DNS.5 = localhost
IP.1  = 127.0.0.1
EOF

# 1. A CA (guarde bem o ca.key: ele assina todo certificado em que você confia)
openssl req -x509 -new -nodes -newkey rsa:4096 -sha256 -days 1825 \
  -keyout ca.key -out ca.crt -config ca.cnf

# 2. Chave, CSR e certificado do servidor assinado pela CA
openssl req -new -nodes -newkey rsa:2048 \
  -keyout tls.key -out tls.csr -config server.cnf
openssl x509 -req -in tls.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out tls.crt -days 825 -sha256 -extfile server.cnf -extensions v3_req

# 3. Confira os SANs
openssl x509 -in tls.crt -noout -ext subjectAltName

# 4. O Secret: tls.crt e tls.key para o servidor, ca.crt para o operator
kubectl -n chatcli create secret generic chatcli-tls \
  --from-file=tls.crt --from-file=tls.key --from-file=ca.crt

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: chatcli-selfsigned
  namespace: chatcli
spec:
  selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: chatcli-ca
  namespace: chatcli
spec:
  isCA: true
  commonName: chatcli-internal-ca
  secretName: chatcli-ca
  duration: 43800h   # 5 anos
  privateKey:
    algorithm: ECDSA
    size: 256
  issuerRef:
    name: chatcli-selfsigned
    kind: Issuer
---
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: chatcli-ca
  namespace: chatcli
spec:
  ca:
    secretName: chatcli-ca
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: chatcli-tls
  namespace: chatcli
spec:
  secretName: chatcli-tls
  duration: 2160h     # 90 dias
  renewBefore: 360h   # 15 dias
  usages: ["digital signature", "key encipherment", "server auth"]
  dnsNames:
    - chatcli.chatcli.svc.cluster.local
    - chatcli.chatcli.svc
    - chatcli.chatcli
    - chatcli
    - localhost
  ipAddresses:
    - 127.0.0.1
  issuerRef:
    name: chatcli-ca
    kind: Issuer

apiVersion: platform.chatcli.io/v1alpha1
kind: Instance
metadata:
  name: chatcli
  namespace: chatcli
spec:
  provider: CLAUDEAI
  model: claude-sonnet-5
  apiKeys:
    name: chatcli-api-keys
  server:
    token:
      name: chatcli-server-token
      key: token
    tls:
      enabled: true
      secretName: chatcli-tls
  resources:            # o operator não aplica nenhum por padrão
    requests:
      cpu: 250m
      memory: 256Mi
    limits:
      cpu: "1"
      memory: 1Gi

kubectl apply -f instance.yaml

kubectl -n chatcli get instance chatcli

NAME      READY   REPLICAS   PROVIDER   VERSION             AGE
chatcli   true    1          CLAUDEAI   v1.212.1   2m

kubectl -n chatcli get instance chatcli \
  -o jsonpath='{range .status.conditions[*]}{.type}={.status} {.reason}: {.message}{"\n"}{end}'

TLSConfigured=True SecretConfigured: server certificate from Secret chatcli-tls
AuthenticationConfigured=True CredentialConfigured: server has a credential, or binds loopback only
OperatorCredentialConfigured=True CredentialAvailable: operator authenticates with spec.server.token
Available=True DeploymentReady: All replicas are ready
ServerReachable=True Serving: server v1.212.1 serving (CLAUDEAI/claude-sonnet-5)

​

Condições da Instance

kubectl -n chatcli annotate instance chatcli chatcli.io/reprobe="$(date +%s)" --overwrite

​

Logs que valem a leitura

# O servidor: endereço de bind, TLS, modo de autenticação, recusas na subida
kubectl -n chatcli logs deploy/chatcli

# Os pods: falhas de probe, pull de imagem, volumes de Secret ausentes
kubectl -n chatcli describe pod -l app.kubernetes.io/instance=chatcli

# O operator: "instance not provisioned: ...", "Connected to Instance", estado do stream de alertas
kubectl -n chatcli-system logs deploy/chatcli-operator

​

Conectar a CLI

kubectl -n chatcli port-forward svc/chatcli 50051:50051

TOKEN=$(kubectl -n chatcli get secret chatcli-server-token -o jsonpath='{.data.token}' | base64 -d)
chatcli connect localhost:50051 --tls --ca-cert ca.crt --token "$TOKEN"

# One-shot
chatcli connect localhost:50051 --tls --ca-cert ca.crt --token "$TOKEN" -p "resuma o último deploy"

• Certificado de cliente (mTLS): não há flag. Defina CHATCLI_TLS_CLIENT_CERT e CHATCLI_TLS_CLIENT_KEY; elas só são usadas junto com --tls.
• Texto puro: sem --tls a CLI continua discando TLS com as CAs do sistema, a menos que CHATCLI_ALLOW_INSECURE=true esteja definida. Servidor em texto puro só serve para desenvolvimento local; o operator não o alcança.
• A referência completa do cliente está em Remote Connect.

​

Expor o servidor fora do cluster

• Load balancer L4 (por exemplo um NLB da AWS): crie um Service do tipo LoadBalancer selecionando app.kubernetes.io/name: chatcli e app.kubernetes.io/instance: chatcli, porta 50051 para targetPort: grpc, em passthrough TCP. O TLS fica de ponta a ponta, que também é o único jeito de certificados de cliente (mTLS) chegarem ao servidor.
• ingress-nginx: o backend fala TLS, então use nginx.ingress.kubernetes.io/backend-protocol: "GRPCS", ou TLS passthrough (nginx.ingress.kubernetes.io/ssl-passthrough: "true", que exige a flag --enable-ssl-passthrough no controller). Um ingress que termina o TLS não consegue levar certificados de cliente mTLS até o servidor.
• Os clientes então conectam com chatcli connect chatcli.example.com:443 --tls --token "$TOKEN" (acrescente --ca-cert para uma CA privada).

​

Dashboard e API REST

KEY=$(openssl rand -hex 32)
kubectl -n chatcli-system create secret generic chatcli-operator-secrets \
  --from-literal=api-keys="$(printf -- '- key: "%s"\n  role: admin\n  description: time de plataforma\n' "$KEY")"

apiVersion: v1
kind: Secret
metadata:
  name: chatcli-operator-secrets   # nome fixo
  namespace: chatcli-system        # o namespace do operator
type: Opaque
stringData:
  api-keys: |
    - key: "<openssl rand -hex 32>"
      role: admin
      description: time de plataforma
    - key: "<openssl rand -hex 32>"
      role: viewer
      description: painel somente leitura

apiKeys:
  create: true
  entries:
    - key: "<openssl rand -hex 32>"
      role: admin
      description: time de plataforma

kubectl -n chatcli-system port-forward svc/chatcli-operator 8090:8090
# Dashboard: http://127.0.0.1:8090/  (cole a key; o navegador a guarda no local storage)
curl -s -H "X-API-Key: $KEY" http://127.0.0.1:8090/api/v1/incidents

• Rate limit: 30 requisições por minuto por host de cliente para requisições sem key válida (o que limita adivinhação de keys) e 600 por minuto por key válida. Passar disso devolve 429 com Retry-After.
• Publicar: coloque um Ingress na frente do Service na raiz de um host só dele. A página chama /api/v1/... com caminho absoluto, então um sub-path (/chatcli, com rewrite ou strip-path) carrega a página e quebra todos os painéis. Exemplos e notas por controller: Web Dashboard: Acessar e publicar.
• TLS: defina security.apiTLS.certFile/keyFile e monte o Secret com extraVolumes/extraVolumeMounts; a API passa a servir HTTPS só com TLS 1.3.
• Dev mode: security.devMode: true (CHATCLI_OPERATOR_DEV_MODE, lida como booleano: true, TRUE, 1 ou t) aceita toda chamada como admin quando não há keys configuradas; o log de startup informa o mesmo modo que a API aplica. Existe para experimentos locais; nunca ligue em cluster compartilhado.
• Endpoints, códigos de erro e paginação: Referência da API REST. Tour do dashboard: Web Dashboard.

​

Ligar o AIOps

spec:
  watcher:
    enabled: true
    interval: "30s"
    window: "2h"
    maxLogLines: 100
    maxContextChars: 32000
    targets:
      - name: api-gateway            # kind padrão: Deployment
        namespace: production
        metricsPort: 9090
        metricsFilter: ["http_requests_*", "http_request_duration_*"]
      - name: postgres
        kind: StatefulSet
        namespace: production
      - name: fluentd
        kind: DaemonSet
        namespace: logging
      - name: nightly-etl
        kind: CronJob
        namespace: data

1. Detecção. O WatcherBridge (no líder do operator) mantém aberto o stream StreamAlerts do servidor (heartbeat a cada 15s; um servidor sem essa RPC, anterior à 1.211.0, é consultado com GetAlerts a cada 30s, e o stream é tentado de novo a cada 10 minutos ou assim que esse servidor sai; alertTransport: poll força o polling) e cria recursos Anomaly, deduplicados por aiops.dedupTTLMinutes (padrão 30).
2. Correlação. Anomalias no mesmo recurso são agrupadas numa Issue com risk score e severidade.
3. Análise. Um AIInsight é criado e a RPC AnalyzeIssue do servidor pede ao LLM a causa raiz, enriquecida com contexto do Kubernetes, logs, métricas, estado de GitOps e código-fonte vinculado.
4. Remediação. Um RemediationPlan executa um Runbook compatível, um runbook gerado pela IA ou um loop agêntico observar-decidir-agir (RPC AgenticStep), com 54 ações tipadas (mais Custom, que as verificações de segurança rejeitam), snapshot antes das ações e rollback automático. ApprovalPolicies, o decision engine e o tier do cluster podem segurar um plano para um humano.
5. Resolução. A Issue é resolvida ou escalada depois de aiops.maxRemediationAttempts, e um PostMortem é gerado. Notificação e escalação ficam por conta de NotificationPolicy e EscalationPolicy.

​

ExecDiagnostic Allowlist

helm upgrade chatcli-operator oci://ghcr.io/diillson/charts/chatcli-operator \
  --version 1.212.1 -n chatcli-system -f operator-values.yaml \
  --set security.allowedDiagnosticCommands="curl -s localhost:5678/health\,nc -zv redis.default.svc.cluster.local 6379"

kubectl -n chatcli-system logs deploy/chatcli-operator | grep 'Effective ExecDiagnostic allowlist loaded'

​

Repositórios de código

ssh-keyscan github.com > known_hosts
kubectl -n production create secret generic api-server-git \
  --from-file=ssh-key=./deploy_key --from-file=known_hosts=./known_hosts

​

Acompanhar o pipeline

kubectl get anomalies -A            # SOURCE  SIGNAL  CORRELATED  AGE
kubectl get issues -A               # SEVERITY  STATE  RISK  AGE
kubectl get aiinsights -A           # ISSUE  PROVIDER  CONFIDENCE  AGE
kubectl get remediationplans -A     # ISSUE  ATTEMPT  STATE  AGE
kubectl get postmortems -A          # ISSUE  SEVERITY  STATE  AGE
kubectl get approvalrequests -A     # ISSUE  PLAN  STATE  RULE  AGE

​

Opções de autenticação

kubectl -n chatcli create secret generic chatcli-jwt --from-literal=secret="$(openssl rand -hex 48)"

spec:
  server:
    security:
      jwtSecretRef:
        name: chatcli-jwt
        key: secret
      jwtIssuer: "https://auth.example.com"   # opcional: iss obrigatório
      jwtAudience: "chatcli"                  # opcional: aud obrigatório

spec:
  server:
    security:
      jwtPublicKeyRef:            # chave(s) pública(s) PEM que o servidor usa para validar
        name: chatcli-jwt-public
        key: public.pem
      operatorTokenRef:           # um JWT que seu IdP emitiu para o operator
        name: chatcli-operator-jwt
        key: token

spec:
  server:
    tls:
      enabled: true
      secretName: chatcli-tls
      clientCASecretName: chatcli-client-ca   # Secret com ca.crt
    security:
      mtlsRole: user                          # papel de quem chega só com certificado
      operatorClientCertSecretName: chatcli-operator-client   # tls.crt + tls.key assinados por essa CA

​

Referência do spec da Instance

​

Nível raiz

​

spec.server

​

spec.server.security

​

spec.watcher

​

spec.fallback

spec:
  provider: CLAUDEAI
  model: claude-sonnet-5
  fallback:
    enabled: true
    providers:            # cadeia efetiva: CLAUDEAI, OPENAI, GOOGLEAI
      - name: OPENAI
        model: gpt-6-sol
      - name: GOOGLEAI
        model: gemini-3.8-flash

​

spec.aiops

​

spec.features e spec.pipeline

​

spec.mcp, spec.agents, spec.plugins

​

Status

​

O que o operator cria

• estratégia Recreate quando persistence.enabled (o PVC de sessões é ReadWriteOnce, então o pod antigo o libera antes de o novo subir; cada rollout tem uma breve indisponibilidade), senão RollingUpdate;
• probes em GET /healthz da porta metrics (HTTP puro, sem credencial): startup a cada 5s por até 5 minutos, readiness a cada 10s (sai do Service após 30s de falhas), liveness a cada 20s (reinicia após 2 minutos);
• security context do pod runAsNonRoot, UID 1000, fsGroup: 1000 com fsGroupChangePolicy: OnRootMismatch (para que um volume de sessões novo seja gravável seja qual for o provisioner), seccompProfile: RuntimeDefault (a menos que haja spec.securityContext) e, em todo container, inclusive o init container plugin-loader, allowPrivilegeEscalation: false, readOnlyRootFilesystem: true e todas as capabilities removidas: o pod passa no Pod Security Standard restricted;
• emptyDirs graváveis /tmp (100Mi) e /home/chatcli/.chatcli (200Mi); tudo o que estiver fora do PVC de sessões se perde quando o pod reinicia;
• HOME=/home/chatcli, o ConfigMap <name> e o Secret de apiKeys como envFrom, depois extraEnv, depois as variáveis tipadas de credencial e features. As referências a Secret são opcionais, então um Secret ausente não trava o pod: ele sobe sem o valor.

​

Gatilhos de rollout

​

Rodando em produção

​

Checklist

• O certificado TLS cobre <name>.<namespace>.svc.cluster.local (mais os nomes curtos e, se exposto, o nome externo), e o Secret tem ca.crt para CA privada.
• TLSConfigured, AuthenticationConfigured, OperatorCredentialConfigured, Available e ServerReachable estão todas True.
• Uma credencial por público: token compartilhado só para automações que você confia como admin; JWTs (HS256 ou RS256) ou mTLS para pessoas.
• spec.resources com requests e limits em toda Instance.
• As API keys do dashboard estão em chatcli-operator-secrets, uma por time com o menor papel necessário, e security.devMode está desligado.
• NetworkPolicies restringem os pods da Instance e do operator, inclusive as portas de métricas em HTTP puro.
• Imagens fixadas (versão do chart do operator; spec.image.tag só se quiser desacoplar o servidor da release do operator).
• Só uma Instance no cluster deve conduzir o AIOps.
• O allowlist do ExecDiagnostic cobre as portas de health dos seus workloads.
• Recursos customizados e Secrets referenciados estão no backup.

​

TLS e RBAC

• TLS em tudo que o operator conversa. O operator disca nas Instances só com TLS 1.3, validando o certificado contra o ca.crt da Instance (ou as CAs do sistema, ou security.grpcTLS.caFile). O servidor também só aceita TLS 1.3. Faça a rotação com o cert-manager ou trocando o Secret: os pods reiniciam (chatcli.io/tls-hash) e o operator confia no novo ca.crt na próxima conexão.
• RBAC do operator. A ClusterRole do operator é ampla por necessidade: acesso total aos seus 17 CRDs; Deployments, Services, ConfigMaps, ServiceAccounts e PVCs; leitura e escrita de Secrets em todo o cluster (ele lê os Secrets referenciados e executa RotateSecret); pods (inclusive create, para os pods de stress do chaos), eviction de pods (o DrainNode usa a Eviction API), logs, e eventos do core e de events.k8s.io; nodes (cordon/drain); create e update em todo kind que o allowlist do ApplyManifest admite (workloads, Jobs, CronJobs, Services, ConfigMaps, HPAs, PDBs, Ingresses e os kinds do Prometheus Operator e do Istio; regras para um API group não instalado ficam inertes), além de NetworkPolicies, para remediação; ReplicaSets só leitura; leases para o leader election.
• Sem escalada de RBAC em tempo de execução. O operator nunca cria nem altera ClusterRoles. Ele só pode fazer bind das pré-provisionadas chatcli-watcher e chatcli-role-{viewer,operator,admin,superadmin} (restrito por resourceNames), então um operator comprometido não consegue vincular uma ClusterRole mais privilegiada. As ClusterRoles chatcli-role-* existem para você vincular a pessoas; o operator não vincula nada a usuários.
• Barreiras da remediação. O ApplyManifest só cria ou atualiza os 16 kinds permitidos (Deployment, StatefulSet, DaemonSet, Service, ConfigMap, HorizontalPodAutoscaler, PodDisruptionBudget, Ingress, CronJob, Job, ServiceMonitor, PrometheusRule, PodMonitor, ServiceEntry, VirtualService, DestinationRule; estenda com security.allowedResourceTypes) no namespace da Issue. O RBAC do operator (chart e kustomize) concede create e update em cada um deles, inclusive os kinds ServiceMonitor, PodMonitor, PrometheusRule, ServiceEntry, VirtualService e DestinationRule; um kind que você acrescenta com security.allowedResourceTypes também precisa de uma regra de ClusterRole que você adicione. ReplicaSet não está na lista: o Deployment dono dele reverteria uma escrita direta. O ExecDiagnostic fica limitado ao allowlist. Os logs passam por 18 padrões de limpeza (chaves de nuvem e de API, JWTs, tokens bearer, senhas, strings de conexão, chaves privadas, endereços IPv4, e-mails, segredos longos em base64/hex) antes de chegarem ao LLM.

​

Credenciais e rotação

​

Recursos

​

Alta disponibilidade

• Operator: rode replicaCount: 2 ou mais com leaderElect: true. Os controllers e o WatcherBridge rodam só no líder; a API REST e o dashboard são servidos por todas as réplicas, então o Service continua respondendo durante um failover. O chart não cria PodDisruptionBudget para o operator; crie um se você drena nós com frequência.
• Instances: replicas > 1 torna o Service headless e o operator balanceia em round-robin entre os pods. Cada pod é um servidor independente (memória, watcher e emptyDir próprios), e o stream de alertas se prende a um pod por vez. Para uma Instance de AIOps, uma réplica costuma ser o certo.
• Persistência e réplicas: o PVC de sessões é ReadWriteOnce, então com persistence.enabled o Deployment usa a estratégia Recreate: o pod antigo para e libera o volume antes de o novo subir, e cada rollout (imagem, configuração ou credencial) tem uma breve indisponibilidade. Sem persistência a estratégia é RollingUpdate. Uma segunda réplica agendada em outro nó continua sem conseguir anexar o volume (Multi-Attach error): mantenha uma réplica com persistência e fixe-a com scheduling.affinity se o storage for zonal, ou rode sem persistência quando escalar horizontalmente.
• O operator não cria PodDisruptionBudget, HorizontalPodAutoscaler nem NetworkPolicy para Instances.

​

Políticas de rede

• Operator: ligue networkPolicy.enabled no chart (ou make deploy-network-policy nos manifestos crus). A entrada é liberada na porta da API (restrinja com networkPolicy.apiIngressFrom), na de métricas (metricsIngressFrom) e na de health. Com egress: restricted, a saída fica limitada a DNS, 443, a porta da API do Kubernetes (kubernetesApiPort, 6443), a porta gRPC das Instances (instanceGrpcPort, 50051) e a porta do Prometheus tirada de prometheusUrl; acrescente egressExtraPorts para SMTP (587/465), git via SSH (22) ou webhooks em outras portas.
• Instances: o operator não cria nenhuma. Um ponto de partida:
  apiVersion: networking.k8s.io/v1
  kind: NetworkPolicy
  metadata:
    name: chatcli
    namespace: chatcli
  spec:
    podSelector:
      matchLabels:
        app.kubernetes.io/name: chatcli
        app.kubernetes.io/instance: chatcli
    policyTypes: [Ingress, Egress]
    ingress:
      - ports: [{port: 50051, protocol: TCP}]   # gRPC: o operator e seus clientes
        from:
          - namespaceSelector:
              matchLabels:
                kubernetes.io/metadata.name: chatcli-system
      - ports: [{port: 9090, protocol: TCP}]    # métricas + /healthz (probes do kubelet, Prometheus)
    egress:
      - ports: [{port: 53, protocol: UDP}, {port: 53, protocol: TCP}]
      - ports: [{port: 443, protocol: TCP}, {port: 6443, protocol: TCP}]   # APIs de LLM, API do Kubernetes (watcher)
  
  Acrescente um from para os seus clientes na 50051, e saída para o metricsPort dos alvos do watcher quando coletar métricas deles. O tráfego das probes do kubelet fica isento de NetworkPolicy na maioria dos CNIs, mas não em todos, por isso o exemplo deixa a 9090 aberta para qualquer origem.

​

Pod Security

​

Métricas e monitoramento

• O servidor expõe /metrics (e /healthz) na porta metrics do Service da Instance (9090); o operator expõe métricas de controllers e de AIOps (chatcli_operator_*) na 8080 (serviceMonitor.enabled: true no chart).
• Os dois são HTTP puro sem autenticação, e o listener de métricas do servidor escuta em todas as interfaces independentemente de bindAddress. Restrinja com NetworkPolicy.
• Para uma Instance, crie seu próprio ServiceMonitor:
  apiVersion: monitoring.coreos.com/v1
  kind: ServiceMonitor
  metadata:
    name: chatcli
    namespace: chatcli
  spec:
    selector:
      matchLabels:
        app.kubernetes.io/name: chatcli
        app.kubernetes.io/instance: chatcli
    endpoints:
      - port: metrics
        interval: 30s
  
• Nomes de métricas, dashboards do Grafana e queries úteis: Web Dashboard. Alerte em chatcli_operator_instance_ready == 0 e na condition ServerReachable.

​

Imagens, versões e upgrades

• As imagens do operator e do servidor são publicadas como ghcr.io/diillson/chatcli-operator:<version> e ghcr.io/diillson/chatcli:<version> (mais latest), multi-arch (amd64, arm64), com SBOM e provenance, assinadas keyless com cosign:
  cosign verify ghcr.io/diillson/chatcli-operator:1.212.1 \
    --certificate-oidc-issuer https://token.actions.githubusercontent.com \
    --certificate-identity-regexp '^https://github.com/diillson/chatcli/'
  
• Fixação. O chart fixa a imagem do operator no seu appVersion e passa CHATCLI_OPERATOR_APP_VERSION, então uma Instance sem spec.image.tag roda a mesma release e um helm upgrade do operator atualiza esses servidores também. Defina spec.image.tag só para desacoplar uma Instance da release do operator. Evite latest em produção.
• Upgrade e desinstalação: veja Upgrade e desinstalação.

​

Backup

• Recursos customizados, por exemplo kubectl get instances,runbooks,notificationpolicies,escalationpolicies,approvalpolicies,incidentslas,servicelevelobjectives,sourcerepositories,clusterregistrations -A -o yaml; acrescente issues,postmortems,auditevents se guarda histórico de incidentes no cluster. Ferramentas como o Velero fazem backup de namespaces com seus recursos customizados.
• Os Secrets referenciados pelas Instances, e o chatcli-operator-secrets, a partir do seu cofre de segredos.
• O PVC de sessões guarda as sessões do servidor. Ele pertence à Instance: apagar a Instance apaga o claim (o volume segue a reclaim policy da StorageClass).
• O gasto com LLM registrado pelo pipeline fica nos ConfigMaps chatcli-cost-ledger dos namespaces onde as Issues acontecem.

​

O que não existe

• Nenhum admission ou validating webhook: o schema do CRD é a única validação, e o operator informa o resto como conditions.
• Nenhuma conexão em texto puro do operator até uma Instance.
• Nenhum gRPC reflection, a menos que você defina spec.server.security.enableReflection.
• Nenhum PodDisruptionBudget, HPA, NetworkPolicy, ServiceMonitor, Ingress ou LoadBalancer criado para Instances; o Service é sempre ClusterIP ou headless.
• Nenhum TLS ou autenticação nos endpoints de métricas.
• Nenhum SSO/OIDC no dashboard: só API keys.
• Nenhum arquivo de auditoria no operator: as ações dele são recursos AuditEvent. O servidor tem o próprio arquivo de auditoria (security.auditLogPath).
• Nenhum RBAC automático para pessoas: vincule as ClusterRoles chatcli-role-* você mesmo.

​

Upgrade e desinstalação

​

Antes de começar

1. Faça backup dos recursos customizados e dos Secrets (veja Backup).
2. Salve os values com que a release roda e use esse arquivo como fonte das suas configurações daqui em diante:
   helm get values chatcli-operator -n chatcli-system -o yaml > operator-values.yaml
   
   Uma release instalada sem overrides, como o comando de instalação desta página, imprime null; o arquivo funciona assim mesmo.
3. Confira em Atravessando estas releases se algo precisa ser feito antes do upgrade.

​

Rodar o upgrade

helm upgrade chatcli-operator oci://ghcr.io/diillson/charts/chatcli-operator \
  --version 1.212.1 -n chatcli-system -f operator-values.yaml

git checkout v1.212.1
cd operator
make deploy

​

O que acontece, em ordem

1. CRDs. O Job de hook pre-upgrade reaplica os 17 CRDs (kubectl apply --server-side) antes de qualquer outra mudança.
2. Operator. O Deployment do operator faz rollout: o pod novo fica Ready antes de o antigo parar, então o dashboard e a API REST continuam no ar. Os controllers reiniciam no pod novo.
3. Instances. O operator novo renderiza de novo cada Instance. Uma Instance sem spec.image.tag recebe a imagem nova do servidor, e qualquer mudança no template do pod reinicia os pods dela. Com persistence.enabled a estratégia é Recreate: os pods antigos param antes de os novos subirem, então cada Instance assim fica um breve período fora do ar.
4. Sondagem. O operator sonda cada servidor de novo. Uma sondagem que cai no meio do rollout pode gravar ServerReachable=False / ProbeFailed com DeadlineExceeded ... while waiting for connections to become ready, connection refused ou i/o timeout, mesmo que os pods novos já sirvam normalmente logo depois. Uma sondagem que falha é repetida em 30 segundos, então a condição vira True logo depois do rollout.
5. Alertas. O WatcherBridge reconecta. Se ele alcança um servidor anterior à 1.211.0, que não tem StreamAlerts (tipicamente um pod antigo ainda rodando), ele loga Server has no StreamAlerts RPC; polling GetAlerts e faz polling a cada 30 segundos. Quando esse pod antigo sai, o próximo polling falha com Unavailable, o bridge loga Server unavailable while polling; retrying the alert stream on reconnect e abre o stream no servidor novo. Nenhum alerta se perde nesse meio-tempo.

​

Verificar

helm -n chatcli-system list                                    # CHART chatcli-operator-1.212.1
kubectl get crd -o name | grep -c 'platform.chatcli.io'        # 17
kubectl -n chatcli-system rollout status deploy/chatcli-operator
kubectl get instances -A                                       # READY true, VERSION v1.212.1
kubectl -n chatcli get instance chatcli \
  -o jsonpath='{range .status.conditions[*]}{.type}={.status} {.reason}{"\n"}{end}'

​

Atravessando estas releases

​

Desinstalar

​

Solução de problemas

​

Desenvolvimento

cd operator

make build                 # fmt, vet, go build -o bin/manager main.go
make test                  # testes unitários (fake client)
make test-integration      # envtest: kube-apiserver + etcd de verdade (Kubernetes 1.37.0), os CRDs de
                           # config/crd/bases e os controllers ligados como no main.go;
                           # binários baixados em ./bin; pulado quando KUBEBUILDER_ASSETS não está definido
make dash-preview          # o dashboard web sobre dados sintéticos, sem cluster:
                           # http://127.0.0.1:8085/, API key "preview" (DASHPREVIEW_ADDR sobrescreve)
make run                   # roda o operator localmente contra o kubeconfig atual

# Imagens (o contexto de build é a raiz do repositório)
make docker-build IMG=registry.example.com/chatcli-operator:dev
make docker-push  IMG=registry.example.com/chatcli-operator:dev
# Imagem do servidor; VERSION é o que a coluna VERSION da Instance mostra
docker build -t registry.example.com/chatcli:dev \
  --build-arg VERSION=dev-$(git rev-parse --short HEAD) ..

# Implante o seu build
make deploy IMG=registry.example.com/chatcli-operator:dev
# ou
helm install chatcli-operator ../deploy/helm/chatcli-operator -n chatcli-system --create-namespace \
  --set image.repository=registry.example.com/chatcli-operator --set image.tag=dev

​

Próximos passos