Cloner — Playbook Operacional¶

Versão concisa em português. Para mergulho profundo (estados, recovery completo, métricas detalhadas) consulte CLONER_OPERATIONS.md (inglês).

Status do escopo (pós-congelamento de escopo 2026-05-10) — Cloner agora é MÓDULO CLONER.Art com 9 funções. Runbook de troubleshooting de egress em runbooks/cloner-egress-troubleshoot.md. Ver modules/cloner-art.md para detalhamento canônico.

1. Operações de rotina¶

Criar um job de clonagem¶

ADMIN_PASS=$(grep '^ADMIN_BASIC_AUTH=' .env | cut -d= -f2- | cut -d: -f2)
curl -s -X POST https://<dashboard-host>/api/clone/jobs \
  -H "Authorization: Basic $(echo -n admin:$ADMIN_PASS | base64)" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com","personaName":"shop"}'

personaName precisa coincidir com o nome de uma Synthetic Persona existente (validação no endpoint).

Vincular slot¶

curl -s -X PATCH https://<dashboard-host>/api/clone/persona-slots/3 \
  -H "Authorization: Basic $(echo -n admin:$ADMIN_PASS | base64)" \
  -H 'Content-Type: application/json' \
  -d '{"siteName":"shop","replicas":1}'

O dashboard: 1. Atualiza ConfigMap clone-persona-3-config (SITE_NAME=shop) → Stakater Reloader reinicia pod. 2. Escala Deployment caddy no namespace clone-persona-3 para 1 réplica. 3. Upsert na tabela targets: URL https://cloned-3.persona.internal/ vira target automaticamente.

Liberar slot¶

curl -s -X PATCH https://<dashboard-host>/api/clone/persona-slots/3 \
  -H "Authorization: Basic $(echo -n admin:$ADMIN_PASS | base64)" \
  -H 'Content-Type: application/json' \
  -d '{"replicas":0}'

Target correspondente é desabilitado (não deletado — preserva histórico de runs).

2. Diagnóstico rápido¶

# Cloner pod
kubectl get pod -n web-agents -l app.kubernetes.io/name=cloner -o wide

# NFS server (deve estar no mesmo nó do cloner em multi-node)
kubectl get pod -n web-agents -l app.kubernetes.io/name=nfs-server -o wide

# DHCP daemon (Ready em todos os nós)
kubectl get ds cni-dhcp-daemon -n web-agents

# IP da VLAN 40 + internet
kubectl exec -n web-agents deploy/cloner -- ip addr show net1
kubectl exec -n web-agents deploy/cloner -- ping -c 3 8.8.8.8

# PVCs cloned-sites
kubectl get pvc -A | grep cloned-sites

# Logs do cloner
kubectl logs -n web-agents -l app.kubernetes.io/name=cloner -f

3. Tabela de problemas¶

Sintoma	Causa	Solução
`ImagePullBackOff`	Imagem não publicada	Build local ou aguardar CI
PVC `cloned-sites` `Pending` (qualquer namespace)	NFS server não pronto OU `volumeName` inválido	Cheque `kubectl describe pv cloned-sites-writer`
Slot `MountVolume.SetUp failed: mount.nfs: Connection refused`	NFS server caiu	`kubectl -n web-agents rollout restart deploy/nfs-server`. Conteúdo persiste no hostPath.
Slot Ready mas servindo `404`/`503`	Cloner ainda não terminou job pra aquele `personaName`	Ver `clone_jobs` no dashboard
Slot servindo conteúdo antigo	Reloader não reiniciou pod	`kubectl rollout restart deploy/caddy -n clone-persona-N`
Cloner sem IP em `net1`	DHCP daemon ausente do nó OU upstream sem DHCP	`kubectl get ds cni-dhcp-daemon -n web-agents`; checar VLAN 40 no Nexus + roteador
`Init:Error` no cloner	routing-init falhou	`kubectl logs -n web-agents <pod> -c routing-init`
Sem internet (ping 8.8.8.8 falha)	Policy routing quebrado OU upstream offline	`kubectl exec deploy/cloner -- ip rule list`; checar `ip route show table 100`
Job timeout 60s	Site bloqueia anti-bot OU timeout do browser engine	Verificar log do cloner, tentar URL mais simples

4. Multi-node — verificações específicas¶

# Cloner deve estar em UCS-4 (role=infra)
kubectl get pod -n web-agents -l app.kubernetes.io/name=cloner -o wide
# NODE deve ser UCS-4

# NFS server deve estar no MESMO nó do cloner
kubectl get pod -n web-agents -l app.kubernetes.io/name=nfs-server -o wide
# NODE deve ser UCS-4

# Slots devem estar em UCS-1
kubectl get pod -A -l app.kubernetes.io/part-of=web-agent-cluster,cloned-persona -o wide
# Todos NODE = UCS-1

# VLAN 40 no UCS-4
kubectl debug node/<ucs4> -it --image=alpine -- ip link show eth1.40

# VLANs 200-209 no UCS-1
for v in $(seq 200 209); do
  kubectl debug node/<ucs1> -it --image=alpine -- ip link show eth1.$v
done

Se cloner e NFS server estiverem em nós diferentes em multi-node:

# Forçar afinidade — geralmente PreferredDuringScheduling resolve sozinho
# após restart, mas em pinch:
kubectl rollout restart deploy/nfs-server -n web-agents

5. Notas operacionais¶

Uma réplica de cloner — jobs executam sequencialmente. Pra paralelismo aumentar replicas no Deployment.
Sobrescrita — clonar mesma personaName substitui o clone anterior (mesmo diretório).
Storage NFS RWX — em multi-node o NFS server roda no UCS-4 (mesmo nó do cloner). O hostPath subjacente fica em /var/lib/agent-cluster/cloned-sites no UCS-4. Slots em UCS-1 leem via NFS sobre OOBI (eth0). Capacidade depende do disco do UCS-4.
OOBI vs data plane — todo I/O de storage usa OOBI. As VLANs 200-209 (slots) e VLAN 40 (cloner) carregam APENAS tráfego de teste agente↔NGFW↔persona, nunca NFS.
SPAs — sites que exigem interação do usuário pra renderizar conteúdo podem ter clone incompleto.
robots.txt — ignorado (uso interno de lab).
Tabela targets — slots vinculados aparecem automaticamente como https://cloned-N.persona.internal/. Não é necessário POST /api/admin/targets.