Wetopi Platform — Master Architecture, Operating Model & Implementation Plan¶

Memoria ejecutiva, arquitectura técnica general y plan de construcción¶

Fecha: 28 de agosto de 2026
Estado: Documento maestro para revisión e implementación
Organización GitHub: wetopi-platform
Audiencia: Platform Engineering, SRE, DevOps, Development, Security, Network Engineering y agentes Codex/Hermes/ADK
Propósito: servir como documento principal para explicar, revisar, construir y operar la nueva plataforma Wetopi.

0. Cómo usar este documento¶

Este documento consolida y sustituye como referencia principal a las memorias parciales creadas durante el diseño inicial:

wetopi-ai-first-kubernetes-project-memory.md
wetopi-platform-bootstrap-plan.md
wetopi-rke2-network-hosting-architecture.md
wetopi-platform-decisions-argocd-infisical-rke2.md

Cuando exista una contradicción con documentos anteriores, prevalece este documento, especialmente en decisiones posteriores como:

Argo CD como GitOps.
Infisical self-hosted como Wetopi Vault.
SOPS + age únicamente como bootstrap/recovery de secretos declarativos.
OpenBao queda fuera de v1.

No todas las decisiones están cerradas. Las cuestiones aún abiertas se marcan explícitamente como OPEN y no deben ser inventadas por Codex ni por un ingeniero durante la implementación.

1. Resumen ejecutivo¶

Wetopi va a reconstruir su plataforma de Managed WordPress Hosting sobre una nueva foundation basada en RKE2, desplegada en su cloud privado sobre Proxmox + Ceph + OVH vRack.

La migración será greenfield y progresiva. Docker Swarm seguirá dando servicio mientras se construye, prueba y estabiliza la nueva plataforma.

La arquitectura inicial queda resumida en:

Proxmox + Ceph + OVH vRack
        │
        ▼
       RKE2
        │
  Cilium + Hubble
        │
      Ceph CSI
        │
      Argo CD
        │
 SOPS bootstrap
        │
    Infisical
        │
 Docs / Memory / Work Coordination
        │
 Hermes + ADK + Codex workflows
        │
 Edge RKE2 + Traefik + Gateway API
        │
 Hosting workers + WordPress sites

La entrada WAN conservará inicialmente la arquitectura probada de Wetopi:

Internet
   ↓
VRRP VIP
   ↓
IPVS
   ↓
DSR
   ↓
RKE2 Edge nodes
   ↓
Traefik
   ↓
Gateway API
   ↓
Services / EndpointSlices
   ↓
WordPress workloads

La salida será deliberadamente sencilla:

site/customer/workload
        ↓
selected internal gateway
        ↓
192.168.88.100 / .101 / .102 / ...
        ↓
Ubuntu NATGW
        ↓
selected WAN public IP
        ↓
Internet

La plataforma será AI-first, pero no se permitirá que la autonomía de los agentes degrade la operabilidad o seguridad. Git, Vault, Work Ledger, Memory Plane, documentación y tools compartidas serán servicios de primera clase tanto para humanos como para agentes.

2. Objetivos de negocio y plataforma¶

2.1 Objetivos de negocio¶

La nueva plataforma debe permitir a Wetopi:

migrar desde Docker Swarm sin big-bang;
operar cientos y posteriormente miles de workloads WordPress;
mantener la eficiencia y capacidad WAN actual;
reducir configuración artesanal y componentes legacy;
ofrecer mejor aislamiento por cliente;
permitir IPs de salida dedicadas o fácilmente rotables;
mejorar observabilidad y seguridad;
incorporar automatización y agentes de forma nativa;
mantener un modelo operativo entendible por ingenieros humanos.

2.2 Objetivos técnicos¶

La plataforma debe proporcionar:

Kubernetes HA;
IaC reproducible;
GitOps declarativo;
CNI moderno;
observabilidad de flujos;
CSI para Ceph;
Vault operativo con API;
secrets materializados en Kubernetes;
documentación Markdown versionada;
memoria institucional común;
coordinación de trabajo entre agentes y humanos;
trazabilidad;
separación clara de security domains;
recuperación desde pérdida parcial o total del cluster.

3. Principios de diseño¶

3.1 Greenfield antes que migración in-place¶

La nueva plataforma se construye en paralelo al Swarm existente.

PRODUCCIÓN ACTUAL                 NUEVA PLATAFORMA
Docker Swarm                     RKE2 greenfield
      │                                │
      │                                │
      └──────── coexistencia ──────────┘

No se reutilizan nodos de producción hasta que RKE2 haya demostrado estabilidad.

3.2 Git es source of truth del estado declarativo¶

Git
 ↓
review
 ↓
Argo CD / IaC
 ↓
real infrastructure

La shell history no es source of truth.

3.3 La fuente viva gana a la memoria¶

Para infraestructura real:

API autoritativa / sistema vivo
>
Fleet Memory
>
Docs históricas
>
LLM inference

3.4 Simplicidad antes que sofisticación¶

No desplegar v1 con:

Istio;
BGP WAN obligatorio;
service mesh global;
Cilium egress controller complejo;
Suricata inline global;
WAF distribuido avanzado;
PKI dinámica compleja;
automatización de reputación completa.

La arquitectura debe permitir añadirlo después.

3.5 Human-compatible, agent-native¶

Todos los servicios importantes deben disponer de:

API/CLI/Git para agentes;
UI cuando aporte valor a humanos;
identidad y permisos;
auditabilidad.

3.6 Least privilege¶

Cada workload, tool runtime y agente recibe únicamente los permisos necesarios.

3.7 Secrets usados, no necesariamente vistos¶

Cuando sea posible:

LLM
 ↓ tool call
Tool Runtime
 ↓ secret
External API

El modelo no necesita recibir el valor del secret.

4. Arquitectura general de componentes¶

flowchart TB
    Internet((Internet))
    OVH[OVH / vRack]
    PVE[Proxmox Cluster]
    Ceph[(Ceph)]

    subgraph RKE2[Wetopi RKE2 Production]
      CP[3x RKE2 Control Plane\nembedded etcd]
      Platform[Platform Workers]
      Edge[Edge Workers]
      Hosting[Hosting Workers]
      Agents[Agent Workers / Platform Workers]

      Cilium[Cilium CNI]
      Hubble[Hubble]
      Argo[Argo CD]
      Vault[Infisical Vault]
      Docs[MkDocs / Docs]
      Memory[Memory Plane]
      Work[Work Coordination Plane]
      Hermes[Hermes Fleet]
      ADK[ADK Fleet]
      Traefik[Traefik / Gateway API]
      CSI[Ceph CSI]
    end

    Internet --> OVH
    OVH --> PVE
    PVE --> RKE2
    PVE --- Ceph
    CSI --> Ceph

    CP --- Cilium
    Platform --- Cilium
    Edge --- Cilium
    Hosting --- Cilium
    Agents --- Cilium
    Cilium --> Hubble

    Argo --> Platform
    Vault --> Platform
    Docs --> Hermes
    Memory --> Hermes
    Memory --> ADK
    Work --> Hermes
    Work --> ADK
    Hermes --> Agents
    ADK --> Agents
    Traefik --> Hosting

5. Operating Model: todos los “Ops” de Wetopi¶

La plataforma se divide en dominios operativos. Cada dominio tiene un propósito, source of truth y responsabilidades.

Área	Responsabilidad principal	Source of truth principal
BootstrapOps	crear/reparar la foundation	Git + `wetopi-ops01`
InfraOps	VMs, Proxmox, RKE2 nodes	OpenTofu + Ansible
GitOps	estado declarativo Kubernetes	Git + Argo CD
NetOps	CNI, routing, CIDR, policies	Git + APIs de red
EdgeOps	IPVS/DSR, proxies WAN, Gateway API	Git + IPVS state
EgressOps	NATGW, rutas, WAN IPs	Git/config + gateway state
StorageOps	Ceph CSI/PVC/storage	Ceph + Kubernetes
VaultOps / SecretOps	credentials y secrets	Infisical
SecOps	RBAC, policies, security controls	Git + audit logs
ObservabilityOps	métricas, logs, traces, flows	observability stack
DevOps	CI/build/release/app lifecycle	Git + CI + Argo CD
AgentOps	runtimes Hermes/ADK y capability bundles	`agents` + `ai-hub`
MemoryOps	memoria institucional	Memory Plane
WorkOps	coordinación, tickets, leases	Work Ledger
DocOps	docs/runbooks/ADR	Markdown Git
BackupOps	backups y restore	backup repositories
RecoveryOps	cluster/Vault/etcd disaster recovery	runbooks + backups
HostingOps	WordPress/customer workloads	Kubernetes + business control plane

6. BootstrapOps¶

6.1 Propósito¶

BootstrapOps existe para que la plataforma pueda construirse y repararse sin depender de la propia plataforma.

6.2 Componentes¶

flowchart LR
    Laptop[Engineer Laptop\nCodex]
    GH[GitHub\nwetopi-platform]
    Ops[wetopi-ops01]
    Tofu[OpenTofu]
    Ansible[Ansible]
    PVE[Proxmox API]
    RKE[RKE2]

    Laptop --> GH
    Laptop --> Ops
    GH --> Ops
    Ops --> Tofu
    Ops --> Ansible
    Tofu --> PVE
    Ansible --> RKE

6.3 `wetopi-ops01`¶

VM externa al cluster Kubernetes.

Responsabilidades:

bootstrap;
bastion operativo;
OpenTofu;
Ansible;
kubectl/helm;
herramientas de recovery;
acceso a backups;
reparación cuando GitOps/Cilium/Vault estén caídos.

No ejecuta workloads productivos.

Sizing inicial orientativo:

4 vCPU
8 GB RAM
40–80 GB disk
Ubuntu 24.04
1 NIC LAN

7. InfraOps¶

7.1 RKE2 inicial¶

3 x control-plane
3 x platform worker
1 x ops VM externa

Nombres:

wetopi-ops01

rke-cp01
rke-cp02
rke-cp03

rke-platform01
rke-platform02
rke-platform03

7.2 Distribución física¶

Ideal:

pve01 -> rke-cp01 + rke-platform01
pve02 -> rke-cp02 + rke-platform02
pve03 -> rke-cp03 + rke-platform03

Debe respetarse failure domain.

7.3 Control plane¶

RKE2 con:

embedded etcd;
quorum 2/3;
API endpoint estable;
snapshots;
restore probado;
sin customer workloads.

Sizing orientativo:

8 vCPU
16 GB RAM
50–100 GB disk

El almacenamiento de etcd debe priorizar baja latencia.

7.4 IaC¶

OpenTofu -> Proxmox resources / VMs
Ansible  -> OS / RKE2 / host configuration
Argo CD  -> Kubernetes workloads

No mezclar responsabilidades.

8. GitHub y repositorios¶

Organización:

wetopi-platform

Repositorios iniciales:

wetopi-platform/
├── infrastructure
├── agent-services
├── ai-hub
├── agents
└── docs

8.1 `infrastructure`¶

infrastructure/
├── tofu/
│   └── proxmox/
├── ansible/
│   ├── inventories/
│   ├── roles/
│   └── playbooks/
├── clusters/
│   └── production/
├── apps/
├── platform/
├── networking/
├── storage/
├── security/
├── observability/
├── bootstrap/
└── docs/

8.2 `agent-services`¶

Servicios compartidos:

Memory Plane;
Work Ledger adapter;
Hermes Memory Provider;
identidad/approval cuando sea necesario.

8.3 `ai-hub`¶

skills/
tools/
components/
contracts/
schemas/
sdk/
evals/
tests/

Regla:

Una tool utilizada por más de un agente deja de pertenecer al agente y pasa a ai-hub.

8.4 `agents`¶

Monorepo inicial de:

Hermes;
ADK;
configs;
capability bundles;
deployments;
tests.

8.5 `docs`¶

Markdown + MkDocs Material.

9. GitOps — Argo CD¶

9.1 Decisión¶

Argo CD será el sistema GitOps de Wetopi.

9.2 Modelo¶

flowchart LR
    Dev[Human / Agent]
    Git[GitHub]
    Argo[Argo CD]
    K8s[RKE2 API]
    Apps[Applications]

    Dev -->|PR / merge| Git
    Git --> Argo
    Argo --> K8s
    K8s --> Apps

9.3 Principios¶

CI no hará kubectl apply en producción como mecanismo normal.
Git describe estado deseado.
Argo CD reconcilia.
Drift manual debe ser visible.
Aplicaciones deben agruparse por AppProject/dominio.
Human UI se considera una ventaja operativa importante.

9.4 Layout GitOps¶

OPEN: decidir entre:

App-of-Apps;
ApplicationSet;
combinación por environments/domains.

No bloquear bootstrap del cluster por esta decisión, pero cerrarla antes de escalar apps.

10. SecretOps / VaultOps¶

10.1 Decisión¶

El Vault operativo de Wetopi será:

Infisical self-hosted

OpenBao no forma parte de v1.

10.2 Requisito real¶

El Vault debe permitir que un agente o humano pueda:

create
read
update
rotate
delete
list

credentials como:

username/password;
API token;
SSH key;
deploy token;
client secret;
customer credential.

Ejemplo conceptual:

/platform/proxmox/api
/customers/837/wp-admin
/development/github/token
/agents/hermes-sre/private

10.3 Source of truth¶

Infisical = source of truth operativo
Kubernetes Secret = materialización runtime
SOPS = bootstrap/recovery declarativo

10.4 Arquitectura¶

flowchart TB
    Humans[Humans\nWeb UI / CLI]
    Agents[Hermes / ADK / Codex]
    Tools[Tool runtimes]
    Vault[Infisical]
    Operator[Infisical Kubernetes Integration]
    KSec[Kubernetes Secrets]
    Pods[Applications / Pods]

    Humans --> Vault
    Agents -->|vault contract| Vault
    Agents --> Tools
    Tools --> Vault
    Vault --> Operator
    Operator --> KSec
    KSec --> Pods

10.5 Wetopi Vault Contract¶

Los agentes no deben quedar fuertemente acoplados a la API concreta de Infisical.

ai-hub debe exponer:

vault.get()
vault.put()
vault.update()
vault.delete()
vault.list()
vault.exists()

10.6 Infisical validation¶

OPEN / REQUIRED BEFORE PRODUCTION: verificar:

features self-hosted requeridas;
modelo de licensing;
machine identities;
Kubernetes integration;
audit;
versioning;
backup/restore;
límites que puedan afectar a una flota de agentes grande.

11. SOPS + age¶

SOPS no será el Vault.

Su responsabilidad es resolver el problema inevitable de bootstrap:

¿Dónde guardamos los secretos necesarios para arrancar el sistema que guarda secretos?

Modelo:

flowchart LR
    Git[Git]
    SOPS[SOPS encrypted files]
    Age[age keys]
    Bootstrap[Bootstrap process]
    Vault[Infisical]

    Git --> SOPS
    Age --> Bootstrap
    SOPS --> Bootstrap
    Bootstrap --> Vault

Se utilizarán al menos:

clave age de bootstrap/automation;
clave age de recovery offline.

Nunca almacenar claves privadas age en Git.

12. Kubernetes Secrets¶

Una vez Infisical está operativo:

Infisical
 ↓
Kubernetes integration/operator
 ↓
Kubernetes Secret
 ↓
Pod/container

RKE2 debe tener Secrets Encryption at Rest habilitado para proteger la copia persistida en etcd.

13. Agent Secret Model¶

13.1 Regla principal¶

Un agente puede necesitar permiso para usar una credencial sin tener permiso para leer su contenido.

13.2 Tool runtime model¶

sequenceDiagram
    participant LLM as Hermes / ADK
    participant Tool as Platform Tool Runtime
    participant Vault as Infisical
    participant API as External API

    LLM->>Tool: proxmox.restart_vm(vm=123)
    Tool->>Vault: get /platform/proxmox/api
    Vault-->>Tool: credential
    Tool->>API: authenticated request
    API-->>Tool: result
    Tool-->>LLM: sanitized result

13.3 Capability domains¶

No crear un sidecar por tool.

Agrupar por dominio:

platform-tools
├── kubernetes
├── proxmox
├── ceph
└── networking

wordpress-tools
├── wordpress
├── database
└── backups

marketing-tools
├── intercom
└── analytics

13.4 Coding agents¶

Hermes/Codex de desarrollo o SRE pueden necesitar acceso más amplio.

Debe otorgarse por paths/roles, no con acceso global al Vault.

14. NetOps¶

14.1 NICs¶

Cada VM tendrá inicialmente una sola NIC LAN:

VM
 └── eth0
      └── LAN / OVH vRack

14.2 Ceph network¶

Red existente:

192.168.96.0/20

Estado:

EXISTING
DO NOT MODIFY

Está hiperconvergida con Proxmox/Ceph.

No renumerar ni rediseñar como parte de RKE2.

14.3 CIDRs propuestos¶

Node LAN:      OPEN — pendiente inventario
Pod CIDR:      10.64.0.0/14
Service CIDR:  10.68.0.0/16
Ceph:          192.168.96.0/20 existente

Los rangos Pod/Service deben verificarse contra todo el direccionamiento existente antes de aplicarse.

14.4 Cilium¶

Cilium será CNI.

Baseline inicial:

Cilium
VXLAN encapsulation
Hubble enabled

No exigir native routing/BGP inicialmente.

14.5 Hubble¶

Objetivos:

flow visibility;
pod identity;
namespace identity;
source/destination;
policy verdicts;
futuras correlaciones con site/customer.

15. StorageOps¶

Ceph seguirá siendo storage principal.

RKE2 consumirá Ceph mediante CSI.

flowchart LR
    Pod[Pod]
    PVC[PVC]
    CSI[Ceph CSI]
    Node[RKE2 Node]
    Ceph[(Ceph Cluster)]

    Pod --> PVC
    PVC --> CSI
    CSI --> Node
    Node --> Ceph

Tests obligatorios antes de hosting:

crear PVC;
mount;
pod delete/recreate;
persistencia;
failure básico;
snapshot si se adopta;
rendimiento aceptable.

16. Endpoint HA de la API RKE2¶

RKE2 necesita un endpoint estable:

rke2-api.<internal-domain>
          ↓
        VIP
          ↓
cp01 / cp02 / cp03

Propuesta actual:

2 x HAProxy + Keepalived
private VIP

Estado:

OPEN — debe cerrarse antes de instalar el cluster definitivo.

La propuesta se considera conservadora y compatible con el conocimiento operativo existente, pero todavía no está aprobada como decisión final.

17. EdgeOps — ingress WAN¶

17.1 Decisión¶

Conservar inicialmente:

VRRP
+
IPVS
+
DSR

17.2 Motivo¶

Los WAN nodes están distribuidos sobre varios hosts Proxmox, y cada host físico dispone de capacidad de salida OVH propia.

DSR permite:

request:
client -> IPVS -> edge

response:
edge -> client DIRECT

Por tanto se preserva la agregación de bandwidth domains.

17.3 Arquitectura¶

flowchart TB
    Client[Internet Client]
    VIP[Public VIP / VRRP]
    LVS[IPVS Directors]
    Edge1[RKE2 Edge 1\nTraefik]
    Edge2[RKE2 Edge 2\nTraefik]
    Edge3[RKE2 Edge 3\nTraefik]
    Gateway[Gateway API]
    Service[Kubernetes Service]
    Site[WordPress Pod]

    Client --> VIP
    VIP --> LVS
    LVS -->|DSR| Edge1
    LVS -->|DSR| Edge2
    LVS -->|DSR| Edge3
    Edge1 --> Gateway
    Edge2 --> Gateway
    Edge3 --> Gateway
    Gateway --> Service
    Service --> Site

    Edge1 -. direct response .-> Client
    Edge2 -. direct response .-> Client
    Edge3 -. direct response .-> Client

17.4 DSR PoC¶

Required before production:

packet capture request;
packet capture response;
verify response bypasses IPVS;
verify source public IP;
verify real client IP at proxy;
verify health removal/reinsertion;
verify node drain procedure.

18. Proxy — Traefik¶

Traefik será el proxy inicial.

Responsabilidades:

TLS termination;
HTTP routing;
Gateway API;
client IP forwarding;
metrics;
health;
base futura para WAF integration.

Estado de detalles:

OPEN: definir deployment exacto:

DaemonSet;
hostNetwork sí/no según PoC DSR;
puertos;
VIP handling;
health endpoint;
trusted proxies.

19. Gateway API¶

Gateway API será el modelo declarativo L7.

Domain
 ↓
HTTPRoute
 ↓
Service
 ↓
EndpointSlice
 ↓
Pod

Esto elimina del path Kubernetes:

Registrator;
Consul service discovery de websites;
consul-template;
regeneración/reload de nginx config.

20. EgressOps¶

20.1 Filosofía¶

Egress v1 debe ser simple.

No se construye inicialmente un controlador sofisticado de reputación/IPAM.

20.2 NATGW¶

Ejemplo:

gw100
LAN: 192.168.88.100
WAN: PUBLIC_IP_A

gw101
LAN: 192.168.88.101
WAN: PUBLIC_IP_B

gw102
LAN: 192.168.88.102
WAN: PUBLIC_IP_C

VM Ubuntu con:

routing;
nftables/iptables;
SNAT;
logging;
health.

20.3 Selección lógica¶

site/customer/workload
   ↓
egress profile / label
   ↓
gw100 / gw101 / gw102

Ejemplo lógico:

wetopi.io/egress-gateway: gw101

20.4 Enforcement¶

Estado:

OPEN.

Baseline propuesto:

policy routing;
automatización ligera que observe Pods/labels;
no depender de Pod IP estática;
no construir todavía controller complejo.

Evolución posible:

Cilium Egress Gateway

sin cambiar el contrato lógico.

20.5 Pools iniciales¶

Separar al menos:

hosting-general
hosting-premium
platform
agents-crawlers

Los crawlers nunca deben compartir egress WAN IP con hosting general.

21. ObservabilityOps¶

21.1 Fuentes¶

La observabilidad futura debe combinar:

Kubernetes metrics
application logs
Hubble flows
Traefik access logs
NATGW logs
Kubernetes audit
Infisical audit
Argo CD events
agent/tool audit

Posteriormente:

Suricata
WAF events
DNS telemetry
reputation signals

21.2 Correlación deseada¶

Una observación de red debería poder acabar enriquecida con:

customer_id
site_id
pod
namespace
node
proxmox_host
egress_gateway
egress_public_ip
destination
protocol
verdict

22. SecOps¶

Security foundation v1:

Kubernetes RBAC;
ServiceAccounts;
namespace isolation;
NetworkPolicies;
Infisical paths/identities;
RKE2 Secrets Encryption at Rest;
SOPS bootstrap keys offline;
least privilege;
audit trails.

No asumir que cannot get Secret equivale a no poder acceder a secretos: un usuario con capacidad de crear Pods en un namespace puede potencialmente montar Secrets de ese namespace.

Por tanto RBAC de Pods y Vault/Secrets debe diseñarse conjuntamente.

23. Namespaces¶

Propuesta inicial orientativa:

wetopi-platform
wetopi-edge
wetopi-hosting
wetopi-agents-sre
wetopi-agents-development
wetopi-agents-marketing
wetopi-observability
wetopi-security

Estado:

OPEN: modelo definitivo de namespaces y AppProjects/RBAC.

24. DevOps¶

DevOps cubre lifecycle de software, no infraestructura física.

Pipeline conceptual:

flowchart LR
    Code[Application Code]
    CI[CI / Tests / Build]
    Registry[Container Registry]
    Config[GitOps Repo]
    Argo[Argo CD]
    RKE[RKE2]

    Code --> CI
    CI --> Registry
    CI -->|version bump / PR| Config
    Config --> Argo
    Argo --> RKE

Principios:

build artifacts inmutables;
manifests/version changes en Git;
Argo CD despliega;
no despliegues manuales silenciosos.

25. AgentOps¶

25.1 Actores¶

Actor
├── Human
├── Hermes
├── ADK Agent
└── future runtime

Campos de identidad:

actor_id
actor_type
runtime
crew
role
user_id
environment

25.2 Hermes¶

Hermes personales:

developer/coding;
SRE/DevOps;
marketing;
otros empleados cuando proceda.

Cada Hermes tendrá:

local personal memory
+
Fleet Memory
+
Work Ledger
+
role-specific tools
+
Vault permissions

25.3 ADK¶

ADK fleet:

observers;
specialists;
managers;
domain agents.

Todos consumen servicios compartidos.

26. MemoryOps¶

Memory Plane es memoria institucional, no source of truth de infraestructura viva.

Clases:

factual;
operational con TTL;
procedural;
decisions;
shared episodic.

Debe soportar:

scopes;
provenance;
confidence;
temporalidad;
contradictions;
candidate facts.

Hermes combina:

Local Memory
+
Wetopi Fleet Memory

27. WorkOps¶

Work Coordination Plane evita conflictos entre agentes/humanos.

No es solo un Kanban.

Debe manejar:

tasks;
ownership;
claims;
resource scopes;
shared/exclusive locks;
TTL leases;
intents;
activity journal;
dependencies;
conflict detection.

Contrato mínimo:

work.list()
work.get()
work.create()
work.claim()
work.release()
work.update()
work.comment()
work.complete()
work.find_conflicts()
work.acquire()
work.renew()
work.release_resources()

Backend aún desacoplado.

28. DocOps¶

Documentación:

Markdown
+
Git
+
MkDocs Material

Roles:

README del repo
= cómo funciona el componente

wetopi-platform/docs
= cómo Wetopi lo diseña, opera y gobierna

Flujo:

incident / project
 ↓
Work Ledger
 ↓
validated knowledge
 ↓
Memory
 ↓
ADR / runbook / architecture doc
 ↓
Docs repo

29. BackupOps y RecoveryOps¶

Debe existir recuperación fuera del cluster.

Objetos a proteger:

Git repos
etcd snapshots
Infisical database/state
SOPS/age recovery material
Ceph configuration/data policies
Argo configuration (also in Git)
critical application databases

OPEN: destino externo definitivo de backups.

Principio:

un backup no se considera válido hasta haber probado un restore.

30. HostingOps¶

30.1 Primera migración¶

No refactorizar todo wepod a la vez.

Inicialmente:

Docker wepod
 ↓
Pod / StatefulSet

manteniendo cuando convenga:

s6
nginx
php-fpm
mysql

La separación de DB/frontend puede llegar después.

30.2 Hosting workers¶

Se crean después de estabilizar Platform y Edge.

rke-host01
rke-host02
rke-host03
...

Primera cohorte:

~10 sites

Después escalar progresivamente.

30.3 Futuro `WordPressSite` CRD¶

Posible modelo futuro:

apiVersion: wetopi.io/v1
kind: WordPressSite
metadata:
  name: site-12345
spec:
  domains:
    - example.com
  network:
    egressGateway: gw100
  storage:
    size: 20Gi

No es requisito de v1.

31. Arquitectura de data planes y control planes¶

flowchart TB
    subgraph Control[CONTROL PLANES]
      Git[GitHub]
      Tofu[OpenTofu]
      Ansible[Ansible]
      Argo[Argo CD]
      Vault[Infisical]
      Work[Work Ledger]
      Memory[Memory Plane]
      Docs[Docs]
    end

    subgraph K8s[KUBERNETES CONTROL]
      API[RKE2 API]
      ETCD[(etcd)]
      Cilium[Cilium control]
    end

    subgraph Data[DATA PLANES]
      IPVS[IPVS / DSR]
      Edge[Traefik Edge]
      Pods[Hosting Pods]
      NATGW[NAT Gateways]
      Ceph[(Ceph)]
    end

    Git --> Tofu
    Git --> Ansible
    Git --> Argo
    Tofu --> API
    Ansible --> API
    Argo --> API
    API --> ETCD
    API --> Cilium
    Vault --> Pods
    IPVS --> Edge
    Edge --> Pods
    Pods --> NATGW
    Pods --> Ceph

32. Dependency graph del bootstrap¶

flowchart TD
    Git[GitHub org + repos]
    Inventory[Proxmox / Network Inventory]
    IaC[OpenTofu + Ansible]
    Ops[wetopi-ops01]
    VMs[3 CP + 3 Platform VMs]
    RKE[RKE2 HA]
    Cilium[Cilium]
    Hubble[Hubble]
    CSI[Ceph CSI]
    Argo[Argo CD]
    SOPS[SOPS + age bootstrap]
    Vault[Infisical]
    Docs[Docs]
    Memory[Memory Plane]
    Work[Work Ledger]
    AI[AI Hub]
    Agents[Hermes + ADK]
    Edge[Edge workers + Traefik]
    Egress[NATGW]
    Hosting[Hosting workers]
    Sites[First sites]

    Git --> Inventory
    Inventory --> IaC
    IaC --> Ops
    Ops --> VMs
    VMs --> RKE
    RKE --> Cilium
    Cilium --> Hubble
    Cilium --> CSI
    CSI --> Argo
    Argo --> SOPS
    SOPS --> Vault
    Vault --> Docs
    Vault --> Memory
    Vault --> Work
    Docs --> AI
    Memory --> Agents
    Work --> Agents
    AI --> Agents
    Agents --> Edge
    Edge --> Egress
    Egress --> Hosting
    Hosting --> Sites

33. Plan de implementación por fases¶

Fase 0 — Gobierno y repos¶

Deliverables:

organización wetopi-platform;
repos iniciales;
README;
CODEOWNERS;
branch protection;
convenciones;
permisos de Codex.

Fase 1 — Discovery / inventario¶

Inventariar:

hosts Proxmox;
CPU/RAM;
bridges;
VLANs;
vRack;
direccionamiento;
storage;
Ceph;
IPVS;
VIPs;
NATGW;
failure domains;
bandwidth domains.

No crear ranges nuevos hasta completar este inventario.

Fase 2 — IaC foundation¶

Ubuntu 24.04 template/cloud-init;
OpenTofu Proxmox modules;
Ansible baseline;
automation account Proxmox.

Fase 3 — Bootstrap node¶

Crear/provisionar wetopi-ops01.

Fase 4 — RKE2 control plane¶

Crear:

rke-cp01
rke-cp02
rke-cp03

Cerrar previamente endpoint HA.

Fase 5 — Platform workers¶

Crear:

rke-platform01
rke-platform02
rke-platform03

Fase 6 — RKE2 acceptance¶

quorum;
fail one CP;
snapshot etcd;
restore test;
node drain;
reboot tests.

Fase 7 — Cilium / Hubble¶

VXLAN;
Pod CIDR;
Service CIDR;
Hubble;
DNS;
NetworkPolicy baseline.

Fase 8 — Ceph CSI¶

connectivity;
CSI;
PVC acceptance.

Fase 9 — Argo CD¶

install;
projects;
first Git reconciled app;
drift test;
rollback test.

Fase 10 — SOPS bootstrap¶

age keys;
recovery key offline;
encrypted bootstrap values;
recovery procedure.

Fase 11 — Infisical Vault¶

self-hosted deploy;
persistence;
backup;
identities;
Kubernetes integration;
Wetopi vault.* contract.

Fase 12 — AI-first services¶

Docs;
Memory Plane;
Work Coordination Plane;
AI Hub.

Fase 13 — Hermes / ADK¶

Deploy definitive agents after shared services are healthy.

Fase 14 — Edge PoC¶

edge RKE2 nodes;
Traefik;
Gateway API;
DSR PoC;
health integration with IPVS.

Fase 15 — Egress PoC¶

gw100/gw101/gw102;
policy routing selection;
WAN IP rotation;
crawler isolation.

Fase 16 — Hosting pilot¶

3 initial hosting workers;
~10 sites;
storage/network/performance validation.

Fase 17 — Progressive migration¶

Increase cohorts while shrinking Swarm.

34. Migration strategy¶

flowchart LR
    Swarm[Docker Swarm\nCurrent Production]
    New[RKE2 Platform]
    Pilot[10 Sites]
    Batch1[50 Sites]
    Batch2[100+ Sites]
    Final[Swarm Retirement]

    Swarm --> New
    New --> Pilot
    Pilot --> Batch1
    Batch1 --> Batch2
    Batch2 --> Final

Principio:

RKE2 failure during early phases
!=
customer outage

35. Criterios de aceptación¶

35.1 Infra / RKE2¶

[ ] pérdida de un CP no rompe API;
[ ] etcd quorum correcto;
[ ] snapshot funciona;
[ ] restore probado;
[ ] nodes reproducibles desde IaC;
[ ] no customer workloads en CP.

35.2 Network¶

[ ] Pod-to-Pod;
[ ] Pod-to-Service;
[ ] DNS;
[ ] Hubble visibility;
[ ] no CIDR collision;
[ ] Ceph reachable desde nodes;
[ ] DSR demostrado por packet capture.

35.3 Storage¶

[ ] PVC create;
[ ] persistence;
[ ] pod recreation;
[ ] failure test;
[ ] rendimiento aceptable.

35.4 GitOps¶

[ ] Argo reconcilia desde Git;
[ ] drift detectable;
[ ] rollback probado;
[ ] Git conserva estado deseado.

35.5 Vault¶

[ ] agente puede crear credential;
[ ] humano puede consultar credential autorizado;
[ ] workload puede recibir secret;
[ ] secret no aparece plaintext en Git;
[ ] backup/restore Infisical probado;
[ ] path permissions validados;
[ ] raw secrets no llegan al LLM cuando se usa tool runtime.

35.6 Egress¶

[ ] workload A sale por gw100;
[ ] workload B sale por gw101;
[ ] cambio de gateway no requiere mover workload;
[ ] cambio de WAN IP verificable;
[ ] crawlers aislados de hosting general.

35.7 Edge¶

[ ] IPVS health funciona;
[ ] DSR funciona;
[ ] client IP preservada;
[ ] TLS correcto;
[ ] HTTPRoute dinámico;
[ ] drain seguro.

35.8 Agents¶

[ ] Hermes usa Vault contract;
[ ] ADK usa scoped tools;
[ ] tool runtime consume credentials;
[ ] Work Ledger evita conflictos;
[ ] Fleet Memory consultable;
[ ] docs accesibles por Git.

36. Decisiones cerradas¶

ID	Decisión
ARC-001	RKE2
ARC-002	3 CP + embedded etcd
ARC-003	greenfield paralelo a Swarm
ARC-004	`wetopi-ops01` externo
ARC-005	OpenTofu + Ansible
ARC-006	Cilium
ARC-007	Hubble
ARC-008	Ceph existente + CSI
ARC-009	Argo CD
ARC-010	Infisical self-hosted Vault
ARC-011	SOPS + age solo bootstrap/recovery
ARC-012	IPVS + VRRP + DSR inicial
ARC-013	Traefik inicial
ARC-014	Gateway API
ARC-015	NATGW Ubuntu simples
ARC-016	no Istio inicialmente
ARC-017	no BGP obligatorio inicialmente
ARC-018	agents/crawlers separados de customer egress
ARC-019	Markdown + MkDocs
ARC-020	AI Hub compartido

37. Decisiones abiertas / review board¶

Estas decisiones deben ser revisadas por Platform Engineering antes de implementación o antes de su fase correspondiente.

Tema	Estado	Cuándo debe cerrarse
Node LAN CIDR	OPEN	antes de crear VMs RKE2
Pod CIDR `10.64.0.0/14`	Proposed	antes de RKE2 install
Service CIDR `10.68.0.0/16`	Proposed	antes de RKE2 install
API HA: HAProxy+Keepalived	Proposed	antes de CP bootstrap
Traefik hostNetwork/DSR details	OPEN	antes de Edge PoC
Egress enforcement implementation	OPEN	antes de Egress PoC
Infisical licensing/feature validation	OPEN	antes de prod Vault
Argo app layout	OPEN	antes de app scale-out
OIDC provider	OPEN	antes de broad human access
Namespace model final	OPEN	antes de production RBAC
External backup destination	OPEN	antes de production data
Central observability stack	OPEN	antes de migration scale
Work Ledger backend	OPEN	antes de multi-agent operations

38. Riesgos y mitigaciones¶

38.1 Overengineering¶

Riesgo: desplegar demasiado antes de tener workloads.

Mitigación: v1 simple, roadmap posterior.

38.2 Pérdida de DSR¶

Riesgo: degradar capacidad WAN agregada.

Mitigación: PoC + packet capture + no retirar IPVS hasta equivalencia demostrada.

38.3 CIDR collision¶

Riesgo: colisión con redes legacy/OVH/Ceph.

Mitigación: inventory first.

38.4 Secrets expuestos a LLM¶

Riesgo: tokens en prompts/logs.

Mitigación: tool runtimes + Infisical + least privilege.

38.5 Vault lock-in/licensing¶

Riesgo: features críticas fuera de self-hosted assumptions.

Mitigación: validar Infisical y usar Wetopi vault.* contract.

38.6 GitOps blast radius¶

Riesgo: un merge despliega cambio erróneo global.

Mitigación: AppProjects, environments, PR review, health gates.

38.7 Ceph dependency¶

Riesgo: Kubernetes storage depende del cluster Ceph hiperconvergido.

Mitigación: no modificar Ceph en bootstrap, test de CSI y recovery independientes.

38.8 Agent conflicts¶

Riesgo: dos agentes modifican recurso simultáneamente.

Mitigación: Work Ledger + leases + resource scopes.

39. Responsabilidades por equipo¶

Platform Engineering¶

RKE2;
IaC;
Argo CD;
Cilium;
CSI;
node lifecycle;
Vault platform;
cluster reliability.

Development¶

app packaging;
containers;
GitOps manifests;
APIs;
WordPress migration tooling;
future CRDs/controllers.

Security¶

Infisical permissions;
RBAC;
NetworkPolicy;
secret usage;
audit;
future Suricata/WAF.

Agent Engineering¶

ai-hub;
Memory Plane integration;
Work Ledger;
Hermes/ADK capabilities;
tool runtimes;
safety boundaries.

Operations¶

runbooks;
incidents;
backups;
restore drills;
capacity;
production migrations.

40. Suggested first architecture review agenda¶

Para presentar este documento a otros ingenieros, la primera sesión debería revisar en este orden:

RKE2 vs constraints de Proxmox/Ceph.
Node LAN y CIDRs.
API HA endpoint.
Cilium VXLAN y Ceph connectivity.
IPVS/DSR preservation.
Traefik edge PoC.
NATGW/eject routing model.
Argo CD repository layout.
Infisical self-hosted requirements/licensing.
namespace/RBAC/security boundaries.
backup/recovery design.
migration pilot criteria.

No intentar resolver Work Ledger, WAF, BGP, CRDs y service mesh en esa primera reunión.

41. Immediate next actions¶

NOW-01¶

Crear/inicializar los cinco repos en wetopi-platform.

NOW-02¶

Dar acceso a Codex a la organización GitHub con permisos suficientes para gestionar repos, PRs y workflows.

NOW-03¶

Crear un inventario automatizado/read-only de Proxmox y networking.

NOW-04¶

Producir un network-inventory.md con todos los rangos actuales antes de fijar Node/Pod/Service CIDRs.

NOW-05¶

Cerrar el diseño del endpoint API HA.

NOW-06¶

Crear plantilla Ubuntu 24.04 y wetopi-ops01.

NOW-07¶

Implementar OpenTofu/Ansible de CP/workers sin desplegar todavía servicios de negocio.

NOW-08¶

Hacer acceptance test de RKE2 antes de Cilium/Ceph/Argo.

42. Arquitectura objetivo final — vista ejecutiva¶

flowchart TB
    People[Engineers / Operators / Employees]
    Git[GitHub wetopi-platform]
    Codex[Codex]
    Hermes[Hermes]
    ADK[ADK Fleet]

    subgraph OpsPlanes[Operational Planes]
      IaC[InfraOps\nOpenTofu + Ansible]
      GitOps[GitOps\nArgo CD]
      VaultOps[VaultOps\nInfisical]
      NetOps[NetOps\nCilium / IPVS / NATGW]
      ObsOps[ObservabilityOps\nHubble + logs/metrics]
      MemoryOps[MemoryOps]
      WorkOps[WorkOps]
      DocsOps[DocOps]
    end

    subgraph Infra[Private Cloud]
      PVE[Proxmox]
      Ceph[(Ceph)]
      RKE[RKE2]
      Edge[Edge]
      Host[Hosting]
    end

    People --> Git
    People --> VaultOps
    People --> DocsOps
    Codex --> Git
    Hermes --> WorkOps
    Hermes --> MemoryOps
    Hermes --> VaultOps
    ADK --> WorkOps
    ADK --> MemoryOps
    ADK --> VaultOps

    Git --> IaC
    Git --> GitOps
    IaC --> PVE
    PVE --> RKE
    Ceph --> RKE
    GitOps --> RKE
    VaultOps --> RKE
    NetOps --> RKE
    ObsOps --> RKE
    RKE --> Edge
    RKE --> Host

43. Final implementation statement¶

La nueva Wetopi no debe construirse como “un cluster Kubernetes con algunos agentes”.

Debe construirse como una plataforma operativa integrada donde:

Git           = desired state
OpenTofu      = virtual infrastructure provisioning
Ansible       = host bootstrap/configuration
RKE2          = orchestration platform
Cilium        = cluster network foundation
Hubble        = network visibility
Ceph          = persistent storage
Argo CD       = continuous declarative reconciliation
Infisical     = operational Vault
SOPS + age    = Vault/bootstrap recovery bridge
IPVS + DSR    = WAN ingress foundation v1
Traefik       = HTTP/TLS edge v1
NATGW         = simple controlled egress v1
Memory Plane  = institutional knowledge
Work Ledger   = coordination
AI Hub        = shared capabilities
Hermes/ADK    = operational agents
Docs          = institutional documentation

El orden de implementación debe preservar siempre dos propiedades:

La nueva plataforma puede fallar durante su construcción sin afectar al Swarm productivo.
La plataforma puede ser reconstruida desde Git, backups y material de recovery sin depender de servicios que solo existen dentro del cluster destruido.

Ésta es la base técnica y organizativa que debe revisarse con Platform Engineering y Development antes de iniciar la construcción del cluster definitivo.

Wetopi Platform — Master Architecture, Operating Model & Implementation Plan¶

Memoria ejecutiva, arquitectura técnica general y plan de construcción¶

0. Cómo usar este documento¶

1. Resumen ejecutivo¶

2. Objetivos de negocio y plataforma¶

2.1 Objetivos de negocio¶

2.2 Objetivos técnicos¶

3. Principios de diseño¶

3.1 Greenfield antes que migración in-place¶

3.2 Git es source of truth del estado declarativo¶

3.3 La fuente viva gana a la memoria¶

3.4 Simplicidad antes que sofisticación¶

3.5 Human-compatible, agent-native¶

3.6 Least privilege¶

3.7 Secrets usados, no necesariamente vistos¶

4. Arquitectura general de componentes¶

5. Operating Model: todos los “Ops” de Wetopi¶

6. BootstrapOps¶

6.1 Propósito¶

6.2 Componentes¶

6.3 wetopi-ops01¶

7. InfraOps¶

7.1 RKE2 inicial¶

7.2 Distribución física¶

7.3 Control plane¶

7.4 IaC¶

8. GitHub y repositorios¶

8.1 infrastructure¶

8.2 agent-services¶

8.3 ai-hub¶

8.4 agents¶

8.5 docs¶

9. GitOps — Argo CD¶

9.1 Decisión¶

9.2 Modelo¶

9.3 Principios¶

9.4 Layout GitOps¶

10. SecretOps / VaultOps¶

10.1 Decisión¶

10.2 Requisito real¶

10.3 Source of truth¶

10.4 Arquitectura¶

10.5 Wetopi Vault Contract¶

10.6 Infisical validation¶

11. SOPS + age¶

12. Kubernetes Secrets¶

13. Agent Secret Model¶

13.1 Regla principal¶

13.2 Tool runtime model¶

13.3 Capability domains¶

13.4 Coding agents¶

14. NetOps¶

14.1 NICs¶

14.2 Ceph network¶

14.3 CIDRs propuestos¶

14.4 Cilium¶

14.5 Hubble¶

15. StorageOps¶

16. Endpoint HA de la API RKE2¶

17. EdgeOps — ingress WAN¶

17.1 Decisión¶

17.2 Motivo¶

17.3 Arquitectura¶

17.4 DSR PoC¶

18. Proxy — Traefik¶

19. Gateway API¶

20. EgressOps¶

20.1 Filosofía¶

20.2 NATGW¶

20.3 Selección lógica¶

20.4 Enforcement¶

20.5 Pools iniciales¶

21. ObservabilityOps¶

21.1 Fuentes¶

21.2 Correlación deseada¶

22. SecOps¶

23. Namespaces¶

24. DevOps¶

25. AgentOps¶

25.1 Actores¶

6.3 `wetopi-ops01`¶

8.1 `infrastructure`¶

8.2 `agent-services`¶

8.3 `ai-hub`¶

8.4 `agents`¶

8.5 `docs`¶

30.3 Futuro `WordPressSite` CRD¶