Cloner — Playbook Operativo¶

Versión concisa en español. Para una inmersión profunda (estados, recovery completo, métricas detalladas) consulte CLONER_OPERATIONS.md (inglés).

Estado del alcance (post-congelación de alcance 2026-05-10) — Cloner ahora es MÓDULO CLONER.Art con 9 funciones. Runbook de troubleshooting de egress en runbooks/cloner-egress-troubleshoot.md. Vea modules/cloner-art.md para el desglose canónico.

1. Operaciones de rutina¶

Crear un job de clonación¶

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 debe coincidir con el nombre de una Synthetic Persona existente (validación en el endpoint).

Asignar 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}'

El dashboard: 1. Actualiza ConfigMap clone-persona-3-config (SITE_NAME=shop) → Stakater Reloader reinicia pod. 2. Escala Deployment caddy en namespace clone-persona-3 a 1 réplica. 3. Upsert en la tabla targets: URL https://cloned-3.persona.internal/ se vuelve target automáticamente.

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}'

El target correspondiente queda deshabilitado (no eliminado — preserva el histórico de runs).

2. Diagnóstico rápido¶

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

# Servidor NFS (debe estar en el mismo nodo que el cloner en multi-node)
kubectl get pod -n web-agents -l app.kubernetes.io/name=nfs-server -o wide

# DHCP daemon (Ready en todos los nodos)
kubectl get ds cni-dhcp-daemon -n web-agents

# IP de 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 del cloner
kubectl logs -n web-agents -l app.kubernetes.io/name=cloner -f

3. Tabla de problemas¶

Síntoma	Causa	Solución
`ImagePullBackOff`	Imagen no publicada	Build local o esperar CI
PVC `cloned-sites` `Pending` (cualquier namespace)	Servidor NFS no listo O `volumeName` inválido	Revise `kubectl describe pv cloned-sites-writer`
Slot `MountVolume.SetUp failed: mount.nfs: Connection refused`	Servidor NFS caído	`kubectl -n web-agents rollout restart deploy/nfs-server`. Contenido persiste en el hostPath.
Slot Ready pero sirviendo `404`/`503`	Cloner aún no terminó job para ese `personaName`	Ver `clone_jobs` en el dashboard
Slot sirviendo contenido antiguo	Reloader no reinició pod	`kubectl rollout restart deploy/caddy -n clone-persona-N`
Cloner sin IP en `net1`	DHCP daemon ausente del nodo O upstream sin DHCP	`kubectl get ds cni-dhcp-daemon -n web-agents`; revisar VLAN 40 en Nexus + router
`Init:Error` en el cloner	routing-init falló	`kubectl logs -n web-agents <pod> -c routing-init`
Sin internet (ping 8.8.8.8 falla)	Policy routing roto O upstream offline	`kubectl exec deploy/cloner -- ip rule list`; revisar `ip route show table 100`
Job timeout 60s	El sitio bloquea anti-bot O timeout del browser engine	Verificar log del cloner, intentar URL más simple

4. Multi-node — verificaciones específicas¶

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

# Servidor NFS debe estar en el MISMO nodo que el cloner
kubectl get pod -n web-agents -l app.kubernetes.io/name=nfs-server -o wide
# NODE debe ser UCS-4

# Slots deben estar en 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 en UCS-4
kubectl debug node/<ucs4> -it --image=alpine -- ip link show eth1.40

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

Si el cloner y el servidor NFS terminan en nodos diferentes en multi-node:

# Forzar afinidad — generalmente PreferredDuringScheduling se resuelve solo
# tras un restart, pero en apuro:
kubectl rollout restart deploy/nfs-server -n web-agents

5. Notas operativas¶

Una réplica de cloner — los jobs corren secuencialmente. Para paralelismo, aumentar replicas en el Deployment.
Sobrescritura — clonar el mismo personaName reemplaza el clone anterior (mismo directorio).
Storage NFS RWX — en multi-node el servidor NFS corre en UCS-4 (mismo nodo que el cloner). El hostPath subyacente está en /var/lib/agent-cluster/cloned-sites en UCS-4. Slots en UCS-1 leen vía NFS sobre OOBI (eth0). Capacidad depende del disco del UCS-4.
OOBI vs data plane — todo I/O de storage usa OOBI. Las VLANs 200-209 (slots) y VLAN 40 (cloner) llevan SOLO tráfico de prueba agente↔NGFW↔persona, nunca NFS.
SPAs — sitios que requieren interacción del usuario para renderizar contenido pueden tener clone incompleto.
robots.txt — ignorado (uso interno de lab).
Tabla targets — los slots asignados aparecen automáticamente como https://cloned-N.persona.internal/. No es necesario POST /api/admin/targets.