OpenClaw Control Plane em Kubernetes: instalação, arquitetura e topologias

Introdução

Executar um agente de Inteligência Artificial em Kubernetes é relativamente simples. Um Deployment, um Service, algumas credenciais e armazenamento persistente podem ser suficientes para um primeiro laboratório.

O problema começa quando a organização passa de um agente para dezenas ou centenas deles.

Nesse cenário surgem questões que Kubernetes, sozinho, não responde:

• quem pode criar e administrar cada agente;
• qual configuração pertence a cada tenant;
• qual credencial de modelo o agente pode utilizar;
• como manter histórico imutável de revisões;
• como separar o gateway do ambiente de execução;
• como reconciliar mudanças de configuração;
• como impedir acesso entre agentes;
• como armazenar workspace e estado;
• como controlar o ciclo de vida de uma revisão;
• como registrar auditoria das mudanças;
• como provisionar toda essa infraestrutura de maneira reproduzível.

O OpenClaw Enterprise, por meio do OpenClaw Control Plane (OCC), adiciona justamente essa camada de controle. O OCC mantém o estado desejado de Namespaces, Agents, Configurations, Secrets e AgentRevisions, enquanto Drivers traduzem esse estado para recursos concretos de infraestrutura.

A arquitetura possui semelhanças conceituais com um Kubernetes Operator:

Estado desejado
      ↓
Controller
      ↓
Reconciliation Loop
      ↓
Infraestrutura
      ↓
Estado observado

Mas existe uma distinção importante.

No OCC oficial, Agent, AgentRevision, Configuration e os demais objetos da plataforma não são Custom Resource Definitions (CRDs) Kubernetes. Esses recursos pertencem à API do OpenClaw e são persistidos no PostgreSQL. O worker do OCC reconcilia esse estado através de Drivers, principalmente o KubernetesComputeDriver.

Isso evita um erro comum ao estudar a arquitetura: imaginar que o OCC funciona internamente como:

apiVersion: openclaw.io/v1
kind: Agent

Esse não é o modelo do Control Plane oficial.

Os CRDs diretamente relevantes ao caminho Kubernetes oficial são principalmente os da Kubernetes Gateway API, utilizada para recursos como Gateway e HTTPRoute. O cluster também precisa de Envoy Gateway e cert-manager para a topologia recomendada de roteamento privado.

O que é o OpenClaw Control Plane

O OpenClaw Control Plane, ou OCC, é o componente responsável por administrar o estado de uma instalação OpenClaw Enterprise. Ele atua como a camada de controle entre:

Usuário / automação
        ↓
OpenClaw API
        ↓
IAM + PostgreSQL
        ↓
Controller Worker
        ↓
Drivers
        ↓
Kubernetes / runtime

O OCC controla o desired state, enquanto os Drivers realizam as operações concretas necessárias para transformar esse estado em workloads.

A arquitetura oficial possui pelo menos quatro elementos centrais:

API
PostgreSQL
Controller Worker
Drivers

• a API recebe operações administrativas e realiza autenticação e autorização;
• o PostgreSQL mantém recursos, políticas IAM, fila de trabalho e evidências de auditoria;
• o Controller Worker processa operações pendentes;
• os Drivers traduzem essas operações para sistemas externos, como Kubernetes.

Principais conceitos

Installation

Uma instalação representa uma instância do OpenClaw Enterprise. A arquitetura atual trabalha com uma Installation selecionada pelo servidor por deployment. Dentro dela existem os tenants, representados pelos Namespaces da plataforma.

Namespace OpenClaw

Não deve ser confundido diretamente com um Namespace Kubernetes. Um Namespace OpenClaw representa uma fronteira lógica de tenant.

Quando o Kubernetes Compute Driver é utilizado, essa fronteira pode resultar em mais de um Namespace físico no cluster. Na topologia dedicada temos, por exemplo:

OpenClaw Namespace
│
├── Kubernetes data-plane namespace
│
│     └── Harness
│
└── Kubernetes gateway namespace
      └── Gateway

O Compute Driver cria políticas de isolamento, quotas e recursos específicos em cada destino.

Agent

Representa um agente administrado pelo Control Plane. Criar um Agent registra sua definição, mas isso ainda não significa que um workload Kubernetes esteja pronto. O deploy cria uma revisão que precisa ser reconciliada.

AgentRevision

Uma AgentRevision representa um snapshot imutável da configuração admitida para uma determinada implantação. O fluxo pode ser representado por:

Agent
  ↓
Configuration
  ↓
Deploy
  ↓
AgentRevision #1
  ↓
alteração
  ↓
AgentRevision #2

Editar o draft do Agent não modifica automaticamente a revisão que já está executando. Essa separação é importante para rastreabilidade, auditoria e rollback operacional.

Configuration

Contém a configuração utilizada pelo Agent. Quando uma revisão é admitida, a configuração correspondente é congelada junto com outras decisões importantes do runtime.

Controller Worker

O Worker executa a reconciliação propriamente dita. Ele roda separadamente da API HTTP e consulta trabalho durável armazenado no PostgreSQL. Entre suas responsabilidades estão:

provisionar Namespace
preparar AgentRevision
verificar readiness
ativar revisão
parar Agent
remover Agent
retirar revisão anterior

Antes de executar efeitos na infraestrutura, o Worker revalida autorização e propriedade dos recursos envolvidos.

O OCC é um Kubernetes Operator?

Conceitualmente, o comportamento é semelhante: desired state, reconciliation, observed state. Porém, o OCC não utiliza os objetos principais da plataforma como CRDs.

Em vez de:

kubectl apply Agent
        ↓
Kubernetes API
        ↓
Operator

o fluxo oficial é:

OCC API
   ↓
PostgreSQL
   ↓
durable work queue
   ↓
Controller Worker
   ↓
ComputeDriver
   ↓
Kubernetes API

Essa diferença é arquiteturalmente relevante. O Kubernetes é o data plane e runtime provider, mas não é a fonte primária de verdade do Control Plane.

E os CRDs?

Na instalação oficial, o principal conjunto de CRDs que precisa existir antecipadamente vem da Gateway API. O OpenClaw utiliza recursos como Gateway e HTTPRoute para manter rotas privadas dos gateways dos Agents.

A documentação exige, antes da instalação do OCC:

Gateway API CRDs
Envoy Gateway
GatewayClass
cert-manager

O Helm chart do OCC não instala esses controllers automaticamente. Quando private gateway routing está habilitado, o Kubernetes Compute Driver reconcilia um HTTPRoute pertencente ao Agent e o associa ao Gateway configurado.

Operadores OpenClaw baseados em CRD

Existe também uma abordagem diferente, mantida fora do Control Plane Enterprise: operadores Kubernetes que representam uma instância OpenClaw através de CRDs. Um exemplo utiliza kind: OpenClawInstance e reconcilia esse recurso para StatefulSet, Service, RBAC, NetworkPolicy, PVC, PDB e outros objetos Kubernetes.

apiVersion: openclaw.rocks/v1alpha1
kind: OpenClawInstance
metadata:
  name: support-agent
  namespace: openclaw-agents
spec:
  envFrom:
    - secretRef:
        name: openclaw-api-keys

  storage:
    persistence:
      enabled: true
      size: 10Gi

Nesse modelo:

OpenClawInstance CR
        ↓
Kubernetes Operator
        ↓
StatefulSet
Service
PVC
NetworkPolicy
RBAC
...

Essa abordagem é válida para quem deseja administrar instâncias OpenClaw diretamente pelo Kubernetes, mas não deve ser confundida com a arquitetura interna do OpenClaw Enterprise Control Plane. Temos, portanto, dois modelos:

Para ambientes corporativos que precisam de IAM próprio, AgentRevision, auditoria, tenant lifecycle e Drivers, o OCC oferece uma camada de controle mais ampla.

Arquitetura oficial do Control Plane

                 Users / Automation
                         │
                         ▼
                ┌─────────────────┐
                │    OCC API      │
                │ Console + Auth  │
                └────────┬────────┘
                         │
                 Authorization
                         │
                         ▼
                ┌─────────────────┐
                │       IAM       │
                └─────────────────┘

                         │
                         ▼

                ┌─────────────────┐
                │   PostgreSQL    │
                │                 │
                │ resources       │
                │ revisions       │
                │ work queue      │
                │ audit           │
                └────────┬────────┘
                         │
                         ▼
                ┌─────────────────┐
                │ Controller      │
                │ Worker          │
                └────────┬────────┘
                         │
                         ▼
                ┌─────────────────┐
                │ Compute Driver  │
                │ Kubernetes      │
                └────────┬────────┘
                         │
             ┌───────────┴──────────┐
             ▼                      ▼
       Agent Gateway             Harness

Essa divisão é importante porque requisições HTTP não precisam permanecer abertas esperando o Kubernetes concluir toda a operação. A API registra a intenção; o Worker converge o ambiente posteriormente.

Fluxo de reconciliação

Imagine um deploy:

POST deploy Agent
       ↓
OCC autoriza
       ↓
cria AgentRevision
       ↓
grava trabalho no PostgreSQL
       ↓
Worker reivindica trabalho
       ↓
Worker reautoriza operação
       ↓
ComputeDriver.prepareRevision()
       ↓
Kubernetes resources
       ↓
readiness
       ↓
activateRevision()
       ↓
retira predecessor

O OCC utiliza trabalho durável no PostgreSQL, incluindo mecanismos para recuperação de claims abandonados ou workers interrompidos.

Pré-requisitos Kubernetes

Para a instalação atual em produção, a documentação exige Kubernetes 1.35 ou superior, conectividade IPv4 e um CNI que efetivamente aplique NetworkPolicy. Além disso:

Kubernetes >= 1.35
Helm
kubectl
Envoy Gateway
Gateway API CRDs
GatewayClass
cert-manager
PostgreSQL externo
Container Registry
StorageClass RWO

O PostgreSQL precisa usar TLS verificado e papéis separados para application e migration. O Control Plane não deve receber credenciais administrativas do banco durante a operação normal.

Node pools

A documentação recomenda separar nodes destinados ao Control Plane dos nodes utilizados pelos Agents. Uma convenção apresentada é oce-role=control e oce-role=agents:

Kubernetes Cluster
│
├── Control Plane Node Pool
│    label: oce-role=control
│
│    ├── OCC API
│    ├── Worker
│    └── componentes de controle
│
└── Agent Node Pool
     label: oce-role=agents

     ├── Agent Harness
     ├── Embedded OpenClaw
     └── runtimes

Separar apenas Namespaces não equivale a isolamento de nodes. A própria arquitetura recomenda pools distintos para gateways confiáveis e Harnesses menos confiáveis em produção.

Storage

Existem três categorias importantes.

O storage do Gateway precisa ser adequado a SQLite, incluindo locking e fsync. NFS e SMB/CIFS não são recomendados para esse banco, pois SQLite WAL depende de semânticas que filesystems de rede compartilhados podem não fornecer adequadamente.

Instalação do Control Plane

A instalação de produção utiliza Helm. O namespace convencional da documentação é openclaw-system. Comece verificando o cluster:

kubectl version

kubectl get nodes -L oce-role

kubectl get storageclasses

Valide também Gateway API e cert-manager:

kubectl get gatewayclass

kubectl api-resources | grep -E 'Gateway|HTTPRoute'

kubectl get pods -n cert-manager

Namespace do Control Plane

apiVersion: v1
kind: Namespace
metadata:
  name: openclaw-system
  labels:
    app.kubernetes.io/part-of: openclaw-enterprise

kubectl apply -f namespace.yaml

O namespace contém os componentes centrais da instalação. Em produção, evite misturar workloads de usuário nesse mesmo namespace.

Configuração do Kubernetes Compute Driver

O installation.yaml seleciona e configura os Drivers. Um fragmento representativo do Compute Driver segue o formato documentado:

drivers:
  compute:
    id: compute-kubernetes

    configuration:
      authentication:
        mode: inCluster

      images:
        gateway: registry.example.com/openclaw/runtime@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
        agent: registry.example.com/openclaw/runtime@sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
        requireImmutableDigest: true

      resources:
        gateway:
          requests:
            cpu: 100m
            memory: 128Mi
          limits:
            cpu: "4"
            memory: 256Mi

        agent:
          requests:
            cpu: 100m
            memory: 128Mi
          limits:
            cpu: "4"
            memory: 256Mi

        namespace:
          quota:
            pods: "10"

      network:
        dns:
          namespace: kube-system
          podLabels:
            k8s-app: kube-dns

        gatewayPort: 8080

        gatewayTrustedProxyCidrs:
          - "10.20.0.0/24"

      servicePrincipalCredentials:
        mode: projectedServiceAccountToken
        audience: openclaw-enterprise
        expirationSeconds: 900

      runtime:
        gatewayStorageClassName: premium-rwo

        nodeSelector:
          oce-role: agents

        gatewayNodeSelector:
          oce-role: control

O exemplo acima precisa ser adaptado ao ambiente. Os pontos críticos são:

• `requireImmutableDigest`: em produção, as imagens devem ser referenciadas por digest (@sha256:...) e não por :latest. A configuração oficial exige imagens imutáveis no caminho produtivo;
• `nodeSelector`: determina onde Harnesses e runtimes serão executados;
• `gatewayNodeSelector`: permite manter Gateways em nodes diferentes dos workloads executores;
• `projectedServiceAccountToken`: utiliza tokens de ServiceAccount com audience definida e curta duração.

Instalação Helm

Depois de gerar ou preparar values.yaml e installation.yaml, o procedimento oficial utiliza um Secret contendo a configuração de startup:

kubectl -n openclaw-system \
  create secret generic occ-installation-startup \
  --from-file=installation.yaml=installation.yaml

Também são criados Secrets distintos para banco, autenticação e demais credenciais. A instalação então segue o modelo:

helm upgrade --install oce \
  ./deploy/helm/openclaw-enterprise \
  --namespace openclaw-system \
  -f values.yaml \
  --wait \
  --timeout 5m

Releases publicadas do chart também podem ser consumidas pelo registry OCI oficial.

Um ponto operacional importante: Helm Ready não significa necessariamente OCC funcional. É necessário validar autenticação da API e, depois, executar uma chamada real de modelo através de um Agent.

Topologia 1 — Embedded OpenClaw

Na topologia embedded, Gateway e Harness vivem juntos no mesmo Pod:

                 OCC
                  │
                  ▼
          Kubernetes Compute
                  │
                  ▼
        Tenant Kubernetes NS
                  │
                  ▼
        ┌──────────────────┐
        │ OpenClaw Pod     │
        │                  │
        │ Gateway          │
        │ +                │
        │ Harness          │
        └──────────────────┘

Vantagens: menos recursos, arquitetura mais simples, menos comunicação entre Pods, menor consumo de storage e bom ponto de entrada.

Desvantagens: menor separação de blast radius; gateway e workload compartilham runtime; menos adequado para execução mais sensível ou potencialmente arriscada.

Topologia 2 — Gateway e Harness dedicados

              OCC Control Plane
                      │
                      ▼
                Compute Driver
                      │
        ┌─────────────┴─────────────┐
        ▼                           ▼

Gateway Namespace              Data Namespace

┌──────────────┐               ┌──────────────┐
│ Gateway Pod  │◄─────────────►│ Harness Pod  │
│              │               │              │
│ identidade   │               │ workspace    │
│ state        │               │ model key    │
└──────────────┘               └──────────────┘

Gateway e Harness possuem ServiceAccounts, storage, namespaces e identidades separados. A credencial do modelo é entregue somente ao componente que realmente precisa executar inferência; um Gateway dedicado não recebe a credencial do modelo. Essa é uma melhoria importante do ponto de vista de segurança.

Topologia 3 — Pools de nodes separados

Para produção, podemos adicionar isolamento físico de scheduling:

Cluster
│
├── trusted-pool
│    oce-role=control
│
│    ├── OCC API
│    ├── Worker
│    └── Gateways
│
└── agent-pool
     oce-role=agents

     ├── Harness A
     ├── Harness B
     ├── Harness C
     └── Embedded workloads

Isso reduz o risco de um workload de Agent competir diretamente com o Control Plane. É especialmente importante quando os Agents possuem ferramentas de execução de comandos ou manipulação de código.

Topologia 4 — Dois clusters

O Kubernetes Compute Driver possui uma configuração experimental que permite apontar a execução para outra API Kubernetes. O desenho conceitual seria:

Cluster A
Control Plane
│
├── OCC
├── PostgreSQL access
├── Worker
└── Gateways
       │
       │
       ▼
Cluster B
Execution
│
├── Agent Harness
├── workspaces
└── runtime

Essa arquitetura é atraente para isolamento forte. Porém, o suporte atual de dois clusters é explicitamente tratado como experimental e a documentação indica que a aceitação completa do runtime ainda está pendente. Portanto, não deve ser apresentada como topologia produtiva padrão.

Exemplo do dia a dia

Considere uma empresa que possui cinco squads: Payments, Customer Experience, Security, Platform e Data. Cada equipe começa a construir agentes internos.

Sem Control Plane, o ambiente rapidamente se transforma em:

deployment-agent-a.yaml
deployment-agent-b.yaml
secret-agent-a.yaml
secret-agent-b.yaml
config-agent-v3-final-final.yaml

Cada equipe administra manualmente Secrets, PVCs, Ingress, NetworkPolicy, ServiceAccounts, model keys e deployments. Não existe uma visão central das revisões.

Com OCC

Installation
│
├── Namespace Payments
│     ├── Agent fraud-review
│     └── Agent chargeback
│
├── Namespace Platform
│     ├── Agent incident-triage
│     └── Agent deployment-review
│
└── Namespace Data
      └── Agent sql-review

O fluxo passa a ser:

Developer
   ↓
OCC API
   ↓
Authorization
   ↓
AgentRevision
   ↓
Worker
   ↓
Kubernetes Compute Driver
   ↓
runtime

O resultado é um modelo declarativo e auditável sem obrigar cada time de aplicação a conhecer a implementação Kubernetes completa.

Ambiente de produção

Uma arquitetura mais próxima de produção seria:

                       ┌────────────────────┐
                       │ Internal LB /      │
                       │ trusted ingress    │
                       └─────────┬──────────┘
                                 │
                                 ▼
                       ┌────────────────────┐
                       │ OCC API            │
                       └─────────┬──────────┘
                                 │
                   ┌─────────────┴─────────────┐
                   ▼                           ▼
              PostgreSQL                    Worker
                                                │
                                                ▼
                                         Compute Driver
                                                │
                           ┌────────────────────┼─────────────┐
                           ▼                    ▼             ▼
                     Gateway NS          Tenant NS      Tenant NS
                           │                    │             │
                        Gateway             Harness       Harness
                           │                    │             │
                           └──────── Envoy Gateway ───────────┘

Componentes externos: cert-manager, Gateway API, Envoy Gateway, Prometheus, log collector, container registry, PostgreSQL gerenciado e block storage persistente.

NetworkPolicy e isolamento

A arquitetura do Kubernetes Compute Driver começa os tenants com default-deny de ingress e egress, e adiciona somente fluxos explicitamente necessários. Entre os acessos bloqueados por padrão estão:

cross-tenant
Agent → outro Agent
Kubernetes API
cloud metadata

Políticas específicas liberam DNS, Gateway/Harness e destinos necessários.

Um ponto relevante é que criar um objeto NetworkPolicy não comprova isolamento. O CNI precisa efetivamente implementá-lo. Em um EKS, GKE ou cluster próprio, valide sempre com testes reais (kubectl exec, curl, nc) para verificar tanto conexões permitidas quanto bloqueadas.

Segurança de Pods

Os workloads gerados pelo Compute Driver utilizam práticas como:

runAsNonRoot
RuntimeDefault seccomp
drop capabilities
allowPrivilegeEscalation=false
readOnlyRootFilesystem

e identidade baseada em ServiceAccount com token projetado de curta duração. O objetivo é evitar que o runtime do Agent herde privilégios do controlador.

RBAC

O princípio deve ser:

OCC API
≠
Worker
≠
Gateway
≠
Harness

Cada componente possui responsabilidades diferentes. O Worker precisa criar e modificar determinados recursos dentro dos namespaces administrados. O Agent não deve receber as credenciais do Worker.

A documentação alerta explicitamente contra wildcard permissions, acesso cluster-wide a tenants, RoleBinding escalation e controller credentials dentro de workloads.

Secrets

Outro princípio essencial é separar controller credentials, database credentials, gateway credentials, model credentials e Agent credentials. Não utilize um único Secret contendo todas as credenciais da plataforma.

No modelo dedicado:

Gateway
    X
    │ não recebe model API key
    │
Harness
    │
    └── model credential

Isso reduz o impacto da exposição de um único componente.

Observabilidade

O OCC possui métricas privadas para API e Worker. Por padrão, o Helm chart pode expor essas métricas no Pod IP através da porta 9464. A liberação do scrape utiliza seletores de Namespace e Pod:

metrics:
  enabled: true
  port: 9464

  scraperNamespaceLabels:
    kubernetes.io/metadata.name: monitoring

  scraperPodLabels:
    app: prometheus

O chart não cria automaticamente um ServiceMonitor, um metrics Service ou um Ingress público para esse endpoint. Por isso, a descoberta recomendada é diretamente dos Pods.

Métricas importantes

occ_http_requests_total
occ_http_request_duration_seconds
occ_agents
occ_work_pending
occ_work_oldest_pending_age_seconds
occ_agent_operation_duration_seconds

Throughput:

sum by (cluster, installation) (
  rate(occ_http_requests_total[5m])
)

P95 de requests:

histogram_quantile(
  0.95,
  sum by (cluster, installation, le) (
    rate(occ_http_request_duration_seconds_bucket[5m])
  )
)

Backlog:

max by (cluster, installation) (
  occ_work_pending
)

Idade do trabalho mais antigo:

max by (cluster, installation) (
  occ_work_oldest_pending_age_seconds
)

O backlog é especialmente importante porque o funcionamento do OCC depende da reconciliação assíncrona.

Logs

API e Worker utilizam logging estruturado. O Worker produz eventos como worker.started, worker.health, worker.completed, worker.error e worker.stopped. Os eventos de deployment também incluem medições como durationMs, prepareMs, readinessWaitMs, activationMs e elapsedMs.

Isso permite construir dashboards que mostrem não apenas se um Agent falhou, mas em qual fase da reconciliação ele ficou lento. Uma stack possível:

OCC
 │
 ├── metrics → Prometheus → Grafana
 │
 └── logs → Collector → Loki

OpenTelemetry também pode ser utilizado na infraestrutura geral de coleta, dependendo do stack de observabilidade adotado.

Troubleshooting

Verificando o Control Plane

kubectl get pods \
  -n openclaw-system \
  -o wide

kubectl get events \
  -n openclaw-system \
  --sort-by=.metadata.creationTimestamp

Localizando API e Worker

kubectl get pods \
  -n openclaw-system \
  -l app.kubernetes.io/instance=oce \
  --show-labels

kubectl logs -n openclaw-system <pod-api>

kubectl logs -n openclaw-system <pod-worker>

Namespace preso em provisioning

Verifique primeiro se o Worker está funcionando (worker.started, worker.health, worker.completed). Depois valide:

kubectl get namespaces

kubectl get rolebindings -A

kubectl get networkpolicies -A

Causas possíveis incluem Worker ausente, RBAC insuficiente, NetworkPolicy incorreta, Compute Driver diferente entre API e Worker e falha de acesso ao Kubernetes API.

AgentRevision não ativa

kubectl get pods -A -o wide

kubectl describe pod \
  -n <tenant-namespace> \
  <agent-pod>

Investigue ImagePullBackOff, Pending, PVC Pending, readiness failure, Secret ausente, ResourceQuota, NetworkPolicy e nodeSelector.

Gateway API

kubectl get gatewayclass

kubectl get gateway -A

kubectl get httproute -A

kubectl describe httproute \
  -n <namespace> \
  <route>

Quando CRDs da Gateway API estão ausentes ou o Worker não possui permissão para manipular as rotas necessárias, a reconciliação falha; o OCC não simplesmente desativa o roteamento silenciosamente.

Desenvolvimento x produção

O ambiente local serve para compreender o funcionamento. Não deve ser copiado integralmente para produção.

Alta disponibilidade e limitações atuais

É importante não assumir que "rodar em Kubernetes" implica automaticamente active-active. A arquitetura atual utiliza Recreate em pontos importantes.

O Deployment da API usa estratégia Recreate, evitando dois controllers servindo simultaneamente durante determinadas atualizações. Cada Gateway de Agent também possui uma réplica desejada e utiliza Recreate, podendo existir indisponibilidade durante substituições.

Portanto, Kubernetes não é igual a HA automática. Em produção, alta disponibilidade precisa ser analisada separadamente para PostgreSQL, nodes, storage, network, registry, Envoy, DNS, Control Plane e Agent gateways.

Custos e FinOps

O custo da solução não é apenas o OCC. Considere Control Plane nodes, Agent nodes, PostgreSQL, block storage, Envoy, observabilidade, container registry e uso das APIs de modelo. O custo dos próprios modelos pode facilmente ultrapassar o custo Kubernetes.

Embedded x Dedicated

• Embedded: menos Pods, menos PVCs, menor overhead;
• Dedicated: Gateway separado, Harness separado, storage adicional, isolamento maior.

Quanto maior o número de Agents, mais importante passa a ser acompanhar CPU requests, memory requests, PVC provisionado, PVC utilizado, Agent idle time e model spend.

Spot x On-Demand

Uma estratégia Kubernetes geral para ambientes tolerantes à interrupção pode ser:

Control Plane, Gateways, PostgreSQL        → On-Demand
Harnesses reconstruíveis, batch Agents,
evaluation workloads                       → Spot

Porém, é necessário avaliar o comportamento dos PVCs ReadWriteOnce, interrupções de sessão e tempo de rescheduling. Colocar indiscriminadamente todos os Agents em Spot pode economizar compute e ao mesmo tempo degradar disponibilidade e aumentar o tempo de recuperação.

Requests e Limits

Nunca dimensione os Agents apenas pela capacidade máxima teórica. Por exemplo:

requests:
  cpu: 100m
  memory: 128Mi

limits:
  cpu: "4"
  memory: 4Gi

permite grande diferença entre scheduling e consumo potencial. Com 100 Agents:

scheduler:  100 × 100m = 10 CPUs
burst:      100 × 4    = 400 CPUs

Esse cenário pode gerar contenção severa. O sizing deve considerar P50 e P95 de CPU, working set memory, CPU throttling, OOMKilled, Agent concurrency e queue depth.

Boas práticas

Uma implementação madura deveria seguir pelo menos estas diretrizes:

1. separar nodes de Control Plane e Agents;
2. utilizar imagens fixadas por SHA-256;
3. manter PostgreSQL fora dos Pods do OCC em produção;
4. separar credenciais de aplicação e migração;
5. habilitar TLS verificado no banco;
6. utilizar NetworkPolicy default-deny;
7. testar efetivamente o enforcement do CNI;
8. manter Gateway e Harness com ServiceAccounts diferentes;
9. não entregar credenciais do controller aos Agents;
10. utilizar storage block-backed compatível com SQLite para Gateways;
11. monitorar backlog e tempo de reconciliação;
12. alertar para occ_work_oldest_pending_age_seconds;
13. manter Gateway API e Envoy sob gestão explícita da plataforma;
14. validar um model turn real depois do deployment;
15. tratar AgentRevision como unidade de mudança imutável.

O que evitar

Evite considerar helm install succeeded como sinônimo de plataforma operacional. Ainda devem ser validados: autenticação OCC, Worker, acesso ao Kubernetes, Gateway routing, Agent readiness e model request.

Também evite:

• latest em imagens de produção;
• NetworkPolicies excessivamente amplas, como ipBlock com cidr: 0.0.0.0/0, sempre que o fluxo puder ser restringido;
• executar Control Plane e Agents sem separação de node placement;
• conceder cluster-admin ao runtime dos Agents apenas para resolver rapidamente problemas de RBAC.

Quando utilizar

O OCC faz sentido quando existe necessidade de múltiplos Agents, multi-tenancy, IAM centralizado, auditoria, revisões imutáveis, isolamento entre equipes, controle de Secrets, lifecycle automation, runtime Kubernetes e controle de Gateways.

É particularmente interessante para times de Platform Engineering construindo uma plataforma corporativa de agentes.

Quando não utilizar

Para um único agente interno simples, essa arquitetura pode ser excessiva. Se o requisito é apenas 1 OpenClaw, 1 API key, 1 equipe e 1 namespace, um Deployment Kubernetes convencional ou um operador baseado em OpenClawInstance pode representar uma solução operacionalmente mais simples.

Também é importante avaliar se a organização realmente necessita Kubernetes. Para pequenos ambientes, uma implantação mais simples pode reduzir consideravelmente custo, complexidade, tempo operacional e superfície de falhas.

Resumo prático

User
 ↓
OCC API
 ↓
IAM
 ↓
PostgreSQL
 ↓
Durable Work
 ↓
Controller Worker
 ↓
Compute Driver
 ↓
Kubernetes API
 ↓
Namespace / Gateway / Harness

A principal distinção arquitetural é que Agent, AgentRevision, Configuration e Namespace são recursos do OpenClaw, e não CRDs Kubernetes. Já Gateway e HTTPRoute fazem parte da Kubernetes Gateway API utilizada pela infraestrutura.

Existe ainda uma abordagem separada utilizando um Kubernetes Operator com OpenClawInstance, adequada para quem deseja administrar instâncias diretamente a partir da API Kubernetes.

Conclusão

O aspecto mais interessante do OpenClaw Control Plane não é a instalação via Helm. É o modelo de controle criado acima do Kubernetes.

Em vez de permitir que cada equipe administre diretamente Deployment, Service, Secret, PVC, NetworkPolicy, HTTPRoute e ServiceAccount, a plataforma passa a trabalhar com conceitos mais próximos do domínio: Namespace, Agent, Configuration, AgentRevision, Secret e ServiceAccount.

O OCC recebe essas intenções, autoriza a operação, persiste o estado desejado, cria trabalho durável e utiliza o Controller Worker e o Compute Driver para reconciliar Kubernetes. Essa separação transforma Kubernetes de interface consumida diretamente pelo usuário em substrato de execução da plataforma.

É exatamente o mesmo princípio utilizado por boas plataformas internas:

Desenvolvedor
      ↓
Platform API
      ↓
Policy
      ↓
Controller
      ↓
Cloud / Kubernetes

O resultado é uma arquitetura mais adequada para ambientes em que agentes deixam de ser experimentos isolados e passam a fazer parte da infraestrutura corporativa.

Para uma estratégia moderna de Platform Engineering, esse é o ponto central: não oferecer apenas Kubernetes ao time de IA, mas construir uma camada de controle capaz de padronizar identidade, isolamento, configuração, deployment, observabilidade, segurança e lifecycle dos Agents.