Federação Multi-Cluster

A Federação Multi-Cluster permite que um operator do ChatCLI enxergue além do próprio cluster. Você registra os outros clusters com uma ClusterRegistration; o operator verifica a saúde deles, correlaciona Issues novas com as Issues que estão rodando lá, marca cascatas de staging para produção e aplica uma política de remediação baseada no tier do seu próprio cluster.

A federação não requer um service mesh ou ferramentas externas. O operator se conecta diretamente a cada cluster registrado com um kubeconfig guardado num Secret.

A federação lê outros clusters; ela não os remedia. Detecção e remediação continuam locais: cada cluster que deve se curar sozinho roda o próprio operator (e a própria Instance do ChatCLI; só uma Instance por cluster dirige o AIOps). Pelo kubeconfig registrado o operator apenas lista nodes, namespaces, Issues e RemediationPlans, e atualiza Issues remotas quando as correlaciona.

Por que Federação Multi-Cluster?

Em ambientes de produção modernos, a infraestrutura raramente se limita a um único cluster:

Multi-Região

Clusters em us-east-1, eu-west-1 e ap-southeast-1 para latência e compliance regionais.

Multi-Ambiente

Staging, production e DR em clusters separados com diferentes políticas de segurança.

Multi-Tenant

Clusters dedicados por equipe ou produto com isolamento forte de workloads.

Sem federação, cada cluster é um silo. A AIOps perde a capacidade de:

Detectar que o mesmo problema afeta 5 clusters simultaneamente
Correlacionar um deploy em staging com uma falha em produção
Aplicar políticas de remediação diferenciadas por importância do cluster
Agregar a saúde dos clusters em uma visão global

ClusterRegistration CRD

A CRD ClusterRegistration é o ponto de entrada para adicionar clusters à federação. Crie-a no cluster onde o operator roda, em qualquer namespace; o Secret do kubeconfig precisa estar no mesmo namespace.

Especificação Completa

apiVersion: platform.chatcli.io/v1alpha1
kind: ClusterRegistration
metadata:
  name: prod-us-east-1
  namespace: chatcli-system
spec:
  displayName: prod-us-east-1
  # Secret no mesmo namespace; o kubeconfig precisa estar na chave "kubeconfig"
  kubeconfigSecretRef:
    name: cluster-prod-us-east-1-kubeconfig

  # Metadados do cluster
  region: us-east-1
  environment: prod       # prod | staging | dev
  tier: critical          # critical | standard | non-critical

  # Configuração de monitoramento
  healthCheckInterval: 30s

  # Informativos (armazenados, não aplicados)
  capabilities:
    - metrics-server
    - prometheus
  maxConcurrentRemediations: 2

status:
  # Preenchido pelo controller
  connected: true
  lastHealthCheck: "2026-03-19T14:30:00Z"
  kubernetesVersion: "v1.29.2"
  nodeCount: 12
  namespaceCount: 34
  activeIssues: 2
  activeRemediations: 1

Campos do Spec

Campo	Tipo	Obrigatório	Descrição
`displayName`	string	Sim	Nome legível; também aceito por `clusterName` na barreira por tier
`kubeconfigSecretRef.name`	string	Sim	Secret no mesmo namespace com o kubeconfig na chave fixa `kubeconfig`
`region`	string	Não	Região geográfica do cluster (informativo)
`environment`	string	Sim (padrão `dev`)	`prod`, `staging` ou `dev`. A detecção de cascata usa `staging` e `prod`
`tier`	string	Sim (padrão `standard`)	`critical`, `standard` ou `non-critical`
`labels`	map	Não	Metadados livres (informativo)
`healthCheckInterval`	duration	Não	Intervalo do health check (padrão `30s`; um valor inválido volta para `30s`)
`capabilities`	[]string	Não	Lista livre de recursos do cluster, por exemplo `metrics-server`, `prometheus`, `istio`. Só é armazenada; nenhum código a lê
`maxConcurrentRemediations`	int	Não	Padrão `3`. Só é armazenado; o operator não o aplica

Campos do Status

Campo	Tipo	Descrição
`connected`	bool	Se o último health check teve sucesso
`lastHealthCheck`	timestamp	Horário do último health check, com sucesso ou não
`kubernetesVersion`	string	Versão do kubelet do primeiro node do cluster remoto
`nodeCount`	int	Número de nodes
`namespaceCount`	int	Número de namespaces
`activeIssues`	int	Issues não terminais no cluster remoto (0 quando as CRDs não estão instaladas lá)
`activeRemediations`	int	RemediationPlans em `Pending`, `Executing` ou `Verifying` no cluster remoto
`conditions`	[]Condition	`Connected` (`True`/`HealthCheckPassed` enquanto o health check passa; `False` com reason `KubeconfigUnusable`, `NodeListFailed` ou `NamespaceListFailed` e o erro) e `Degraded` (`True`/`NodesNotReady` quando o cluster responde mas alguns nodes não estão Ready, `False`/`AllNodesReady`, `Unknown`/`Disconnected` enquanto ele está inacessível)

Como a Federação Funciona

Kubeconfig e cache de clients

A cada reconcile o FederationReconciler lê data.kubeconfig do Secret indicado em kubeconfigSecretRef, no namespace da ClusterRegistration, monta um client do controller-runtime com ele e guarda esse client em cache pelo nome do registro. O cache é descartado quando um health check falha ou o registro é apagado, então um kubeconfig rotacionado é assumido depois do próximo health check com falha (ou de um restart do operator). A identidade do kubeconfig precisa, no cluster remoto: list em nodes e namespaces para o health check; list em issues e remediationplans (grupo platform.chatcli.io) para os contadores e a correlação; e update em issues para a correlação anotá-las.

Loop de Health Check

Listar Nodes

Lista os nodes remotos para verificar a conectividade, contá-los e ler a versão do kubelet do primeiro node.

Listar Namespaces

Lista os namespaces remotos e os conta.

Contar o trabalho de AIOps

Lista Issues e RemediationPlans remotos, quando essas CRDs existem lá, para preencher activeIssues e activeRemediations.

Atualizar Status

Grava connected, lastHealthCheck, kubernetesVersion, nodeCount, namespaceCount, activeIssues, activeRemediations e as conditions Connected/Degraded, atualiza o gauge chatcli_operator_federation_clusters_total e agenda o próximo ciclo após healthCheckInterval. Uma falha em qualquer passo anterior define connected: false, atualiza lastHealthCheck e registra a falha na condition Connected.

Correlação Cross-Cluster

Quando uma Issue é detectada, o IssueReconciler pede ao controller de federação que procure o mesmo problema em outros lugares. As duas verificações abaixo rodam só contra ClusterRegistrations connected cujo client do kubeconfig está em cache; sem registros elas custam duas listagens em cache e não mudam nada.

Elevação Automática de Severidade

O controller lista as Issues ativas (não terminais) com o mesmo signalType no cluster local e em cada cluster conectado. Quando elas abrangem 3 ou mais clusters (o local conta como um), toda Issue correspondente, local e remota, é anotada e elevada a critical:

apiVersion: platform.chatcli.io/v1alpha1
kind: Issue
metadata:
  name: api-gateway-error-rate-1790368432
  namespace: production
  annotations:
    platform.chatcli.io/cross-cluster-correlation: "xcluster-7f8a2b3c"
    platform.chatcli.io/affected-clusters: "3"
spec:
  severity: critical   # elevada de medium
  signalType: error_rate

Uma Issue elevada a critical também recebe platform.chatcli.io/elevated-severity: "true". Uma correlação mantém um id: quando chega uma Issue nova que casa e uma das Issues do grupo já traz um id de correlação, o grupo o reutiliza em vez de rerotular tudo, e affected-clusters é atualizado. O contador chatcli_operator_federation_cross_cluster_issues_total incrementa uma vez por id de correlação novo. Uma Issue que mudou por baixo do update (conflito) é pulada e não há nova tentativa; a próxima correlação do grupo a anota.

O id de correlação é uma annotation, então encontre as Issues relacionadas com:

kubectl get issues -A -o json \
  | jq -r '.items[] | select(.metadata.annotations["platform.chatcli.io/cross-cluster-correlation"]=="xcluster-7f8a2b3c") | "\(.metadata.namespace)/\(.metadata.name)"'

GET /api/v1/federation/correlations lista as correlações a partir das Issues locais, uma entrada por id de correlação, com correlationId, issue, namespace, severity, signalType, correlatedClusters (de affected-clusters), elevated (de elevated-severity) e cascade. Ele também lê as chaves antigas platform.chatcli.io/correlation-id / correlated-clusters, então Issues anotadas com elas continuam aparecendo.

Detecção de Cascata

A detecção de cascata marca uma Issue recém-detectada cujo recurso (mesmo nome) já falhou antes num cluster de staging: o mesmo problema está rolando pelos ambientes.

Staging para Produção

A verificação precisa de pelo menos um registro conectado com environment: staging e um com environment: prod. Ela roda para toda Issue que o operator local detecta (o environment do próprio cluster local não é consultado); para essa Issue, o controller lista as Issues de cada cluster de staging e procura uma num recurso com o mesmo nome cujo detectedAt seja anterior ao da Issue local. A primeira correspondência anota a Issue local:

metadata:
  annotations:
    platform.chatcli.io/cascade-detected: "true"
    platform.chatcli.io/cascade-source-cluster: "staging-us-east-1"
    platform.chatcli.io/cascade-source-issue: "checkout-crashloop-1790360001"

e incrementa chatcli_operator_federation_cascade_detected_total.

A annotation é todo o efeito: severidade, notificações e o prompt da IA não mudam por causa de uma cascata. Roteie a partir dela numa NotificationPolicy ou num filtro do dashboard se uma cascata deve acionar diferente.

Agregação de Status Global

Não existe CRD de status da federação. A visão agregada é calculada sob demanda pela API REST do operator a partir das ClusterRegistrations e das Issues locais:

Endpoint	Retorna
`GET /api/v1/federation/status` (também `GET /api/v1/federation`)	`totalClusters`, `connectedClusters` (inclui os degradados), `degradedClusters`, `disconnectedClusters` e `totalActiveIssues` (Issues locais que não estão `Resolved` nem `Failed`)
`GET /api/v1/federation/clusters?tier=critical`	Os registros, opcionalmente filtrados por tier
`GET /api/v1/clusters/global-status`	`totalClusters`, `healthyClusters` (conectados, todos os nodes Ready), `degradedClusters` (conectados, com a condition `Degraded`), `offlineClusters` e a lista de clusters (cada um com `connected` e `degraded`)
`GET /api/v1/federation/correlations`	Correlações cross-cluster (veja acima)

{
  "apiVersion": "v1",
  "kind": "FederationStatus",
  "spec": {
    "totalClusters": 5,
    "connectedClusters": 4,
    "degradedClusters": 1,
    "disconnectedClusters": 1,
    "totalActiveIssues": 12
  }
}

kubectl
API REST

# Listar todos os clusters registrados (a coluna CONNECTED vem de status.connected)
kubectl get clusterregistrations -A

# Ver clusters desconectados
kubectl get clusterregistrations -A \
  -o jsonpath='{range .items[?(@.status.connected==false)]}{.metadata.namespace}/{.metadata.name}{"\n"}{end}'

# A API é servida pelo operator (Service chatcli-operator, porta 8090)
kubectl -n chatcli-system port-forward svc/chatcli-operator 8090:8090 &

# Status global
curl -s -H "X-API-Key: $CHATCLI_API_KEY" http://localhost:8090/api/v1/federation/status | jq .

# Listar clusters filtrados por tier
curl -s -H "X-API-Key: $CHATCLI_API_KEY" "http://localhost:8090/api/v1/federation/clusters?tier=critical" | jq .

Veja a visão geral da API para API keys e roles (viewer basta para esses endpoints).

Política de Remediação por Tier

Cada cluster tem uma política de remediação baseada no tier da sua ClusterRegistration, que controla quanta autonomia o operator rodando naquele cluster concede antes de o Motor de Decisão avaliar a confiança.

Definição de Políticas

Tier	Severidade	Política	Justificativa
critical	Qualquer	Manual com aprovação	Zero risco de ação automática em infra crítica
standard	critical/high	Manual com aprovação	Conservadorismo para severidades altas
standard	medium/low	Auto-remediação	Automação para problemas de menor impacto
non-critical	Qualquer	Auto-remediação	Máxima automação em dev/test
qualquer outro valor	Qualquer	Manual com aprovação	Fallback seguro (o enum da CRD normalmente impede; o tier é comparado sem diferenciar maiúsculas)

Fiação

Diga ao operator qual registro é o seu próprio cluster:

# Helm values (chatcli-operator)
clusterName: prod-us-east-1      # nome ou displayName da ClusterRegistration

ou CHATCLI_OPERATOR_CLUSTER_NAME no Deployment. O operator procura esse valor entre as ClusterRegistrations do seu próprio cluster (qualquer namespace), comparando com metadata.name ou spec.displayName, então registre também o cluster local; só o tier é lido, então a barreira funciona mesmo enquanto esse registro não está connected. Se nenhum registro corresponder, o tier é desconhecido e a barreira falha fechada: todo plano que chega a ela espera aprovação manual sob a política sintética cluster-tier, com o motivo Cluster name "<name>" (CHATCLI_OPERATOR_CLUSTER_NAME) is not registered: ... no plano, até o registro existir. Se as ClusterRegistrations não puderem ser listadas, o plano continua Pending e o reconcile é tentado de novo. Vazio (o padrão) desliga a barreira por tier. Com ele definido, todo plano que chega a Pending e não foi segurado por uma ApprovalPolicy é comparado com a tabela: quando o tier diz “manual”, o plano espera em WaitingApproval sob a política sintética cluster-tier (um aprovador, timeout de 30 minutos, decidido como qualquer ApprovalRequest) e suas annotations carregam decision-mode: approval e o motivo, por exemplo Cluster prod-us-east-1 tier policy "manual" requires approval for high severity.

A barreira por tier roda antes do Motor de Decisão e independe dele: um plano que o tier segura não é avaliado por confiança, e um plano que o tier libera ainda passa pelo motor quando ele está habilitado.

Exemplos YAML

Registrar um Cluster de Produção

kubectl -n chatcli-system create secret generic cluster-prod-us-east-1-kubeconfig \
  --from-file=kubeconfig=./prod-us-east-1.kubeconfig

apiVersion: platform.chatcli.io/v1alpha1
kind: ClusterRegistration
metadata:
  name: prod-us-east-1
  namespace: chatcli-system
  labels:
    environment: prod
    region: us-east-1
spec:
  displayName: prod-us-east-1
  kubeconfigSecretRef:
    name: cluster-prod-us-east-1-kubeconfig
  region: us-east-1
  environment: prod
  tier: critical
  healthCheckInterval: 30s

Registrar um Cluster de Staging

apiVersion: platform.chatcli.io/v1alpha1
kind: ClusterRegistration
metadata:
  name: staging-us-east-1
  namespace: chatcli-system
  labels:
    environment: staging
    region: us-east-1
spec:
  displayName: staging-us-east-1
  kubeconfigSecretRef:
    name: cluster-staging-us-east-1-kubeconfig
  region: us-east-1
  environment: staging
  tier: non-critical
  healthCheckInterval: 60s

Setup Multi-Região Completo

# Produção US
apiVersion: platform.chatcli.io/v1alpha1
kind: ClusterRegistration
metadata:
  name: prod-us-east-1
  namespace: chatcli-system
spec:
  displayName: prod-us-east-1
  kubeconfigSecretRef:
    name: kubeconfig-prod-us
  region: us-east-1
  environment: prod
  tier: critical
  healthCheckInterval: 15s
---
# Produção EU
apiVersion: platform.chatcli.io/v1alpha1
kind: ClusterRegistration
metadata:
  name: prod-eu-west-1
  namespace: chatcli-system
spec:
  displayName: prod-eu-west-1
  kubeconfigSecretRef:
    name: kubeconfig-prod-eu
  region: eu-west-1
  environment: prod
  tier: critical
  healthCheckInterval: 15s
---
# Produção APAC
apiVersion: platform.chatcli.io/v1alpha1
kind: ClusterRegistration
metadata:
  name: prod-ap-southeast-1
  namespace: chatcli-system
spec:
  displayName: prod-ap-southeast-1
  kubeconfigSecretRef:
    name: kubeconfig-prod-ap
  region: ap-southeast-1
  environment: prod
  tier: critical
  healthCheckInterval: 15s
---
# Staging (compartilhado)
apiVersion: platform.chatcli.io/v1alpha1
kind: ClusterRegistration
metadata:
  name: staging-global
  namespace: chatcli-system
spec:
  displayName: staging-global
  kubeconfigSecretRef:
    name: kubeconfig-staging
  region: us-east-1
  environment: staging
  tier: non-critical
  healthCheckInterval: 60s
---
# DR (Disaster Recovery): o enum de environment não tem o valor "dr"
apiVersion: platform.chatcli.io/v1alpha1
kind: ClusterRegistration
metadata:
  name: dr-us-west-2
  namespace: chatcli-system
  labels:
    role: dr
spec:
  displayName: dr-us-west-2
  kubeconfigSecretRef:
    name: kubeconfig-dr
  region: us-west-2
  environment: prod
  tier: standard
  healthCheckInterval: 60s

Monitoramento da Federação

Métricas Prometheus

Servidas na porta de métricas do operator (8080, /metrics):

Métrica	Tipo	Labels	Descrição
`chatcli_operator_federation_clusters_total`	Gauge	`status` (`connected`, `degraded`, `disconnected`)	Número de clusters registrados em cada estado. Definido para todos os estados a partir das ClusterRegistrations que existem, então um cluster que muda de estado ou é apagado passa de uma série para outra
`chatcli_operator_federation_cross_cluster_issues_total`	Counter	-	Correlações cross-cluster levantadas (uma por id de correlação novo)
`chatcli_operator_federation_cascade_detected_total`	Counter	-	Cascatas de staging para produção detectadas

Os três estados são exclusivos: degraded é um cluster que responde ao health check com alguns nodes não Ready; no gauge ele não conta como connected (o connectedClusters da REST o inclui).

Dashboards Recomendados

Grafana Dashboard: Federation Overview

{
  "panels": [
    {
      "title": "Clusters Desconectados",
      "type": "stat",
      "targets": [{
        "expr": "chatcli_operator_federation_clusters_total{status='disconnected'}"
      }]
    },
    {
      "title": "Correlações Cross-Cluster (24h)",
      "type": "stat",
      "targets": [{
        "expr": "increase(chatcli_operator_federation_cross_cluster_issues_total[24h])"
      }]
    },
    {
      "title": "Cascatas Detectadas (24h)",
      "type": "stat",
      "targets": [{
        "expr": "increase(chatcli_operator_federation_cascade_detected_total[24h])"
      }]
    }
  ]
}

Alertas Recomendados

groups:
  - name: federation
    rules:
      - alert: ClusterHealthCheckFailing
        expr: chatcli_operator_federation_clusters_total{status="disconnected"} > 0
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "Health checks de cluster federado falhando"
          description: >
            Pelo menos uma ClusterRegistration está falhando no health check
            há 5 minutos. Verifique a conectividade de rede e o Secret do kubeconfig.

      - alert: CrossClusterIncident
        expr: increase(chatcli_operator_federation_cross_cluster_issues_total[10m]) > 0
        labels:
          severity: critical
        annotations:
          summary: "Incidente correlacionado cross-cluster"
          description: >
            O mesmo sinal está ativo em 3+ clusters; as Issues correspondentes
            foram elevadas a critical.

      - alert: CascadeDetected
        expr: increase(chatcli_operator_federation_cascade_detected_total[1h]) > 0
        labels:
          severity: warning
        annotations:
          summary: "Cascata de staging para produção detectada"
          description: >
            Um recurso que falhou em staging agora está falhando aqui.
            Verifique se o mesmo deploy foi aplicado nos dois ambientes.

Arquitetura de Rede

O operator precisa de conectividade de rede para o API server de cada cluster registrado. Em ambientes com rede restrita, considere usar um bastion host ou VPN dedicada para o tráfego de gerenciamento.

Próximos Passos

Motor de Decisão

Entenda como a confiança é calculada e como ela se combina com a barreira por tier.

Chaos Engineering

Execute experimentos de chaos controlados para validar a remediação.

Auditoria e Compliance

Audit trail de Issues, aprovações e remediações.

AIOps Platform

Retorne à visão geral da plataforma AIOps.

Início

Primeiros Passos

Conceitos Fundamentais

Funcionalidades

Segurança

Suporte

Federação Multi-Cluster

Por que Federação Multi-Cluster?

Multi-Região

Multi-Ambiente

Multi-Tenant

ClusterRegistration CRD

Especificação Completa

Campos do Spec

Campos do Status

Como a Federação Funciona

Kubeconfig e cache de clients

Loop de Health Check

Correlação Cross-Cluster

Elevação Automática de Severidade

Detecção de Cascata

Staging para Produção

Agregação de Status Global

Política de Remediação por Tier

Definição de Políticas

Fiação

Exemplos YAML

Registrar um Cluster de Produção

Registrar um Cluster de Staging

Setup Multi-Região Completo

Monitoramento da Federação

Métricas Prometheus

Dashboards Recomendados

Alertas Recomendados

Arquitetura de Rede

Próximos Passos

Motor de Decisão

Chaos Engineering

Auditoria e Compliance

AIOps Platform

​Por que Federação Multi-Cluster?

Multi-Região

Multi-Ambiente

Multi-Tenant

​ClusterRegistration CRD

​Especificação Completa

​Campos do Spec

​Campos do Status

​Como a Federação Funciona

​Kubeconfig e cache de clients

​Loop de Health Check

​Correlação Cross-Cluster

​Elevação Automática de Severidade

​Detecção de Cascata

​Staging para Produção

​Agregação de Status Global

​Política de Remediação por Tier

​Definição de Políticas

​Fiação

​Exemplos YAML

​Registrar um Cluster de Produção

​Registrar um Cluster de Staging

​Setup Multi-Região Completo

​Monitoramento da Federação

​Métricas Prometheus

​Dashboards Recomendados

​Alertas Recomendados

​Arquitetura de Rede

​Próximos Passos

Motor de Decisão

Chaos Engineering

Auditoria e Compliance

AIOps Platform

Por que Federação Multi-Cluster?

ClusterRegistration CRD

Especificação Completa

Campos do Spec

Campos do Status

Como a Federação Funciona

Kubeconfig e cache de clients

Loop de Health Check

Correlação Cross-Cluster

Elevação Automática de Severidade

Detecção de Cascata

Staging para Produção

Agregação de Status Global

Política de Remediação por Tier

Definição de Políticas

Fiação

Exemplos YAML

Registrar um Cluster de Produção

Registrar um Cluster de Staging

Setup Multi-Região Completo

Monitoramento da Federação

Métricas Prometheus

Dashboards Recomendados

Alertas Recomendados

Arquitetura de Rede

Próximos Passos