stratumiops/docs/es/ops/ops-stratumiops-projects.md

# Portfolio Ops/DevOps: Infraestructura Moderna de Principio a Fin

## El Problema

Los equipos de DevOps y plataformas enfrentan desafíos críticos al gestionar infraestructura moderna:

- **Herramientas fragmentadas**: Terraform para IaC, Ansible para configuración, Vault para secretos, todo desconectado
- **YAML sin tipos**: Errores de configuración que explotan en runtime, no en compilación
- **Criptografía estática**: Sin preparación para amenazas cuánticas futuras
- **Orquestación manual**: Scripts imperativos frágiles sin rollback ni recuperación
- **Costos ocultos**: Sin visibilidad de gastos en LLMs para generación de infraestructura
- **Multi-cloud complejo**: Diferentes APIs, configuraciones y herramientas por proveedor

## La Solución: Un Ecosistema Integrado

Cinco proyectos diseñados para trabajar juntos, cubriendo el ciclo completo de operaciones.

---

## Provisioning: Infraestructura como Código Declarativa

### IaC Tipado con Generación Asistida por IA

Provisioning combina la precisión de configuración tipada (Nickel) con generación asistida por IA, eliminando el YAML frágil y los scripts imperativos.

**Capacidades únicas**:

- **Nickel IaC**: Configuración tipada con lazy evaluation, validación pre-runtime
- **MCP Server**: Consultas en lenguaje natural sobre infraestructura
- **RAG integrado**: 1,200+ documentos de dominio para respuestas contextuales
- **Multi-cloud**: AWS, UpCloud, local (LXD) desde la misma definición

**Orquestación híbrida**:

- Orquestador Rust para workflows críticos (performance 10-50x vs Python)
- Scripts Nushell para flexibilidad y prototipado rápido
- Resolución automática de dependencias (topological sorting)
- Checkpoints y rollback automático ante fallos

**El flujo de trabajo**:

```text
"Necesito un cluster K8s en AWS con 3 nodos y Cilium"
                    ↓
              MCP Server (NLP)
                    ↓
          RAG busca configuraciones similares
                    ↓
          Genera Nickel + valida tipos
                    ↓
          Orchestrator despliega:
            1. containerd (dependency)
            2. etcd (dependency)
            3. kubernetes (core)
            4. cilium (CNI)
          Con checkpoints y rollback automático
```

**Seguridad enterprise**:

- JWT + MFA (TOTP + WebAuthn)
- Cedar policy engine para RBAC/ABAC
- 7 años retención de audit logs
- 5 backends KMS (RustyVault, Age, AWS KMS, Vault, Cosmian)
- SOPS/Age para cifrado de configuración en reposo

**Para quién**:

- Equipos DevOps que quieren IaC tipado, no YAML frágil
- Organizaciones multi-cloud (AWS + UpCloud + on-premise)
- Equipos que necesitan audit, compliance y seguridad enterprise

**Resultados esperados**:

- Errores de configuración detectados en compilación, no en runtime
- Infraestructura generada desde lenguaje natural (MCP + RAG)
- Rollback automático ante fallos con state management

---

## SecretumVault: Gestión de Secretos con Post-Quantum Crypto

### Vault Rust con PQC en Producción

SecretumVault es un sistema de gestión de secretos que implementa **criptografía post-cuántica lista para producción** (ML-KEM-768, ML-DSA-65), proporcionando agilidad criptográfica para organizaciones que despliegan hoy.

**Criptografía agnóstica**:

- **OpenSSL**: RSA, ECDSA, AES-256-GCM (compatibilidad clásica)
- **OQS (Post-Quantum)**: ML-KEM-768, ML-DSA-65 (NIST FIPS 203/204)
- **AWS-LC**: Experimental PQC (testing)
- **RustCrypto**: Pure-Rust implementations (testing)
- **Backends conectables**: Cambia algoritmos sin modificar código

**Motores de secretos**:

| Motor | Capacidad | Casos de uso |
| ------- | ----------- | -------------- |
| **KV** | Almacenamiento versionado de secretos | Credenciales, API keys, configuraciones sensibles |
| **Transit** | Encryption-as-a-service con rotación de claves | Cifrado de datos en aplicaciones, key rotation |
| **PKI** | Generación de certificados X.509 | mTLS, service mesh, infraestructura interna |
| **Database** | Credenciales dinámicas con TTL | PostgreSQL, MySQL, MongoDB credentials on-demand |

**Storage multi-backend**:

- **Filesystem**: Desarrollo, single-node, rápido prototipado
- **etcd**: Kubernetes, alta disponibilidad, consistencia fuerte
- **SurrealDB**: Queries complejas, time-series, multi-tenant scopes
- **PostgreSQL**: Enterprise, ACID, auditoría completa

**Seguridad enterprise**:

- Shamir Secret Sharing para unsealing (threshold configurable)
- Cedar policy engine (ABAC, compatible AWS)
- TLS/mTLS nativo con certificados X.509
- Audit logging completo con retención configurable
- Token management con TTL y renovación

**Ops/DevOps workflow**:

```bash
# Inicializar vault con Shamir (5 shares, threshold 3)
svault operator init --shares 5 --threshold 3

# Unseal con 3 shares
svault operator unseal --share <share-1>
svault operator unseal --share <share-2>
svault operator unseal --share <share-3>

# Habilitar motor Database para PostgreSQL
svault secret engine enable database
svault secret database config postgres-prod \
  plugin_name=postgresql-database-plugin \
  connection_url="postgresql://{{username}}:{{password}}@postgres:5432/mydb" \
  username="vault" password="vaultpass"

# Crear rol para credenciales dinámicas
svault secret database role create myapp-role \
  db_name=postgres-prod \
  creation_statements="CREATE USER '{{name}}' WITH PASSWORD '{{password}}' VALID UNTIL '{{expiration}}'; GRANT SELECT ON ALL TABLES IN SCHEMA public TO '{{name}}';" \
  default_ttl=1h max_ttl=24h

# Obtener credenciales dinámicas (se generan on-demand)
svault secret read database/creds/myapp-role
# Key                Value
# ---                -----
# lease_id           database/creds/myapp-role/abc123
# lease_duration     3600
# username           v-myapp-role-xyz789
# password           A1b2C3d4E5f6G7h8

# Credenciales se revocan automáticamente tras 1h TTL
```

**Para quién**:

- Equipos desplegando criptografía post-cuántica hoy
- Organizaciones con requisitos de agilidad criptográfica
- Plataformas multi-cloud que necesitan gestión de secretos Rust-native
- Equipos de seguridad evaluando amenazas cuánticas futuras

**Resultados esperados**:

- Preparación para amenazas cuánticas sin cambiar arquitectura
- Gestión de secretos con garantías de memoria de Rust
- Integración nativa con Provisioning (KMS) y Vapora (credenciales de agentes)

---

## Vapora: Orquestación de Agentes con Control de Costos

### Agentes Inteligentes para Operaciones

Vapora no es solo para desarrollo de features. Es una plataforma de orquestación que puede coordinar agentes especializados para operaciones DevOps.

**Agentes disponibles para Ops**:

- **DevOps**: CI/CD, pipelines, deployment automation
- **Monitor**: Health checks, alerting, métricas en tiempo real
- **Security**: Auditoría, compliance, vulnerability scanning
- **ProjectManager**: Roadmap, tracking, coordinación de tareas

**Control de costos real para LLMs**:

- Presupuestos por rol (mensual/semanal)
- Tres niveles: normal → cerca del límite → excedido
- Fallback automático a proveedores más baratos sin intervención manual
- Métricas Prometheus: `vapora_budget_utilization`, `vapora_fallback_triggers`

**Coordinación NATS JetStream**:

```text
┌──────────────────────────────────────────────────────┐
│             NATS JetStream Messaging                 │
├──────────────────────────────────────────────────────┤
│                                                      │
│  vapora.tasks.assign    → Asignación de tareas      │
│  vapora.tasks.results   → Resultados de ejecución   │
│  vapora.agents.heartbeat → Health check de agentes  │
│                                                      │
│  Persistencia: JetStream streams                     │
│  Delivery: At-least-once con acknowledgment         │
│  Ordering: Per-subject message ordering             │
└──────────────────────────────────────────────────────┘
```

**Orquestación de pipelines Ops**:

```text
Pipeline: "Deploy microservice to K8s"

1. Security Agent:  Scan de vulnerabilidades en imagen Docker
2. DevOps Agent:    Validar manifests K8s + Helm charts
3. Monitor Agent:   Setup de métricas Prometheus + alertas
4. DevOps Agent:    Deploy con kubectl apply + health check
5. Monitor Agent:   Validar health endpoints + smoke tests

Si falla cualquier paso: rollback automático coordinado
```

**Métricas y observabilidad**:

- Prometheus metrics endpoint (`/metrics`)
- OpenTelemetry integration (traces, spans)
- SurrealDB para almacenamiento de ejecuciones
- Grafana dashboards para visualización

**Para quién**:

- Equipos DevOps que coordinan múltiples agentes LLM para operaciones
- Organizaciones que necesitan controlar gastos LLM en automation
- Plataformas con pipelines complejos (CI/CD, deployment, monitoring)

**Resultados esperados**:

- Reducción de costos LLM mediante routing inteligente
- Orquestación automática de tareas operativas complejas
- Visibilidad completa de gastos y rendimiento por agente

---

## TypeDialog: Formularios Multi-Backend para Configuración

### Una Definición, Seis Interfaces (Incluye prov-gen)

TypeDialog unifica la captura de configuración en CLI, TUI, Web, y tiene un backend especializado para generación de IaC multi-cloud.

**Backends operacionales**:

| Backend | Uso típico en Ops/DevOps |
| --------- | -------------------------- |
| **CLI** | Scripts de automatización, CI/CD pipelines |
| **TUI** | Herramientas de administración, dashboards terminal |
| **Web** | Portales de self-service, formularios para equipos |
| **Prov-gen** | **Generación de infraestructura multi-cloud** |

**Prov-gen Backend: IaC Generation**

El backend `prov-gen` genera configuraciones de infraestructura Nickel para múltiples clouds desde formularios tipados:

```toml
# cluster-setup.toml
[form]
id = "k8s_cluster"
title = "Kubernetes Cluster Setup"

[[sections]]
id = "cloud"
title = "Cloud Provider"

[[sections.fields]]
id = "provider"
type = "select"
label = "Provider"
required = true
options = [
    { value = "aws", label = "AWS" },
    { value = "upcloud", label = "UpCloud" },
    { value = "local", label = "Local LXD" },
]

[[sections.fields]]
id = "region"
type = "text"
label = "Region"
required = true

[[sections]]
id = "cluster"
title = "Cluster Configuration"

[[sections.fields]]
id = "node_count"
type = "number"
label = "Node Count"
default = 3
validation.min = 1
validation.max = 20

[[sections.fields]]
id = "node_size"
type = "select"
label = "Node Size"
options = [
    { value = "small", label = "Small (2 CPU, 4GB RAM)" },
    { value = "medium", label = "Medium (4 CPU, 8GB RAM)" },
    { value = "large", label = "Large (8 CPU, 16GB RAM)" },
]

[output]
backend = "prov-gen"
format = "nickel"
validation = "nickel://schemas/kubernetes_cluster.ncl"
```

Ejecutar con prov-gen:

```bash
typedialog execute cluster-setup.toml --backend prov-gen --output k8s-cluster.ncl
```

Genera Nickel IaC:

```nickel
# k8s-cluster.ncl (generado automáticamente)
{
  provider = "aws",
  region = "us-east-1",

  servers = [
    {
      name = "k8s-control-plane-01",
      plan = "medium",
      role = "control-plane",
      provider = "aws",
    },
    {
      name = "k8s-worker-01",
      plan = "medium",
      role = "worker",
      provider = "aws",
    },
    {
      name = "k8s-worker-02",
      plan = "medium",
      role = "worker",
      provider = "aws",
    },
  ],

  taskservs = [
    "containerd",
    "etcd",
    "kubernetes",
    "cilium",
  ],

  networking = {
    vpc_cidr = "10.0.0.0/16",
    pod_cidr = "10.244.0.0/16",
    service_cidr = "10.96.0.0/12",
  },
}
```

**Validación Nickel contracts**:

```rust
// Validación automática con Nickel schemas
let validator = NickelValidator::new();
let result = validator.validate(&generated_iac, "schemas/kubernetes_cluster.ncl")?;

if result.errors.is_empty() {
    // IaC válido, listo para Provisioning
    provisioning_client.apply(&generated_iac).await?;
} else {
    // Errores de validación, mostrar al usuario
    eprintln!("Validation errors: {:?}", result.errors);
}
```

**Para quién**:

- Equipos DevOps que mantienen wizards de configuración en CLI y Web
- Organizaciones con self-service infrastructure portals
- Equipos que necesitan generación de IaC desde formularios

**Resultados esperados**:

- Una sola definición TOML para CLI, TUI, Web y generación de IaC
- Validación tipada antes de runtime con Nickel contracts
- Reducción de errores de configuración manual

---

## Kogral: Base de Conocimiento para Equipos de Plataforma

### Tu Base de Conocimiento Ops, Queryable

Kogral captura decisiones arquitectónicas, runbooks, postmortems y procedimientos operativos en un formato que tanto humanos como agentes IA pueden consultar.

**6 tipos de nodo especializados para Ops**:

| Tipo | Uso en Ops/DevOps |
| ------ | ------------------- |
| **Note** | Runbooks, procedimientos, guías de troubleshooting |
| **Decision** | ADRs de infraestructura (por qué AWS vs UpCloud, etcd vs Consul) |
| **Guideline** | Standards de deployment, políticas de seguridad |
| **Pattern** | Patrones de infraestructura reutilizables (multi-AZ, HA) |
| **Journal** | Logs de cambios, daily stand-up notes |
| **Execution** | Historial de deployments, rollbacks, incidentes |

**Git-native + MCP para Claude Code**:

- Todo en markdown versionado (`.kogral/` directory)
- MCP server para Claude Code: agentes consultan runbooks antes de ejecutar
- Búsqueda semántica con fastembed (local) o embeddings cloud

**El flujo Ops**:

```text
Incidente de producción → Captura postmortem en Kogral como Execution
                                    ↓
            Claude Code consulta via MCP → "¿Cómo resolvimos este error antes?"
                                    ↓
                   Kogral responde con postmortems similares + runbooks
                                    ↓
              Agente aplica solución documentada en lugar de adivinar
```

**MCP Tools para Ops**:

```bash
# Buscar runbooks de troubleshooting
kogral-mcp search "nginx 502 error troubleshooting"

# Añadir postmortem de incidente
kogral-mcp add-execution \
  --title "2026-01-22 PostgreSQL Connection Pool Exhaustion" \
  --context "Production database connections maxed out" \
  --resolution "Increased max_connections from 100 to 200, added PgBouncer" \
  --tags "database,incident,postgresql"

# Obtener guidelines de deployment
kogral-mcp get-guidelines "kubernetes deployment" --include-shared true
```

**Para quién**:

- Equipos de plataforma que necesitan preservar conocimiento operativo
- SRE teams con rotación que pierden contexto de incidentes previos
- DevOps usando Claude Code que quieren runbooks contextualizados

**Resultados esperados**:

- Onboarding de nuevos SREs en días, no semanas
- Resolución de incidentes informada por postmortems previos
- Decisiones de infraestructura preservadas y buscables

---

## El Ecosistema en Acción: Escenarios Ops

### Escenario 1: Nuevo Cluster Kubernetes Multi-Cloud

```text
1. TypeDialog (prov-gen): Wizard para configuración de cluster
   - Cloud provider, región, node count, tamaño de nodos
   - Genera Nickel IaC validado

2. Provisioning: Despliega infraestructura
   - Crea servidores en AWS/UpCloud
   - Instala containerd, etcd, kubernetes, cilium
   - Checkpoints por paso, rollback automático si falla

3. SecretumVault: Genera certificados PKI
   - Certificados etcd, kube-apiserver, kubelet
   - Rotación automática cada 90 días

4. Kogral: Documenta decisión de arquitectura
   - ADR: "Por qué Cilium sobre Calico"
   - Runbook: "Cómo escalar cluster de 3 a 10 nodos"

5. Vapora: Orquesta post-deployment
   - Monitor Agent: Setup Prometheus + Grafana
   - Security Agent: Escaneo de vulnerabilidades
   - DevOps Agent: Deploy aplicaciones de prueba
```

### Escenario 2: Incidente de Producción (Database Outage)

```text
1. Vapora Monitor Agent: Detecta PostgreSQL down
   - Alerta vía NATS JetStream
   - Trigger pipeline de incident response

2. Kogral: Claude Code consulta vía MCP
   - "¿Postmortems de PostgreSQL outages?"
   - Retorna 3 incidentes similares con resoluciones

3. Vapora DevOps Agent: Ejecuta runbook
   - Reinicia PostgreSQL con parámetros ajustados
   - Verifica health checks

4. SecretumVault: Rota credenciales de DB
   - Genera nuevas credenciales dinámicas
   - Actualiza aplicaciones vía Database engine

5. Kogral: Documenta postmortem
   - Execution node con root cause, resolución, action items
   - Linked a ADRs de configuración de PostgreSQL
```

### Escenario 3: Migración a Criptografía Post-Cuántica

```text
1. Kogral: Documenta decisión de migración
   - ADR: "Migración a ML-KEM-768 para preparar amenazas cuánticas"
   - Timeline, risks, mitigation strategies

2. SecretumVault: Migra secretos
   - Cambio de backend: openssl → oqs
   - Re-encripta secretos con ML-KEM-768
   - Mantiene compatibilidad con clientes clásicos

3. Provisioning: Actualiza infraestructura
   - Genera nuevos certificados PKI con ML-DSA-65
   - Despliega certificados a servicios (etcd, K8s API)
   - Rollback automático si fallan health checks

4. Vapora: Orquesta validación
   - Security Agent: Verifica criptografía correcta
   - Monitor Agent: Valida latencia no degradada
   - DevOps Agent: Ejecuta integration tests

5. TypeDialog: Portal self-service para equipos
   - Formulario: "Migrar servicio a PQC"
   - Backend prov-gen genera configuración actualizada
```

### Escenario 4: CI/CD con Validación IA

```text
1. Developer: Push a repositorio Git (Gitea)

2. Vapora DevOps Agent (trigger via webhook):
   - Ejecuta linting, tests unitarios
   - Build de imagen Docker
   - Scan de vulnerabilidades con Security Agent

3. TypeDialog: Formulario de deployment
   - Environment (staging/production)
   - Canary rollout percentage
   - Genera configuración K8s validada

4. Provisioning: Despliega con Tekton
   - Apply manifests K8s con kubectl
   - Health checks automáticos
   - Rollback si health check falla

5. SecretumVault: Inyecta secretos
   - Credenciales de DB dinámicas (TTL 1h)
   - API keys desde KV engine
   - Certificados TLS desde PKI engine

6. Kogral: Registra deployment
   - Execution node con versión, timestamp, autor
   - Link a commit SHA, PR, cambios
```

---

## Por Qué Elegir Este Ecosistema (Perspectiva Ops)

### Frente a Alternativas

| Nosotros | Terraform + Ansible + Vault |
| ---------- | ---------------------------- |
| **Configuración tipada**: Nickel con validación pre-runtime | YAML/HCL sin tipos, errores en runtime |
| **Orquestación integrada**: Provisioning orchestrator con rollback | Scripts imperativos, sin recuperación automática |
| **Post-Quantum crypto**: SecretumVault con ML-KEM/ML-DSA hoy | Vault sin roadmap PQC |
| **Multi-cloud unificado**: Una configuración Nickel para AWS/UpCloud/Local | Configuraciones separadas por cloud |
| **IA-native**: MCP + RAG para generación asistida | Sin asistencia IA, configuración manual |
| **Full Rust stack**: Performance, memory-safety | Mix Python/Go/Shell con overhead |

### Inversión Técnica (Ops Focus)

| Métrica | Valor |
| --------- | ------- |
| **Provisioning**: Nickel IaC, 80+ CLI shortcuts | ~40K LOC |
| **SecretumVault**: 4 crypto backends, 4 storage backends | ~11K LOC |
| **Vapora**: NATS JetStream, 12 agent roles | ~50K LOC |
| **TypeDialog**: 6 backends incluido prov-gen | ~90K LOC |
| **Kogral**: 6 node types, MCP server | ~15K LOC |
| **Tests totales** | 4,360+ |
| **Backends crypto** | OpenSSL, OQS (PQC), AWS-LC, RustCrypto |
| **Storage backends** | FS, etcd, SurrealDB, PostgreSQL |

---

## Comenzar (Adopción para Equipos Ops)

### Adopción Progresiva Recomendada

1. **SecretumVault**: Gestión de secretos con agilidad criptográfica (standalone)
2. **Kogral**: Establece base de conocimiento operativo (runbooks, ADRs, postmortems)
3. **TypeDialog**: Wizards de configuración para teams (CLI + Web + prov-gen)
4. **Provisioning**: IaC declarativo multi-cloud con orchestrator
5. **Vapora**: Orquesta agentes Ops con budget control (DevOps, Monitor, Security)

Cada proyecto funciona de forma independiente. Las sinergias emergen al combinarlos.

### Quick Start por Proyecto

**SecretumVault**:

```bash
# Docker Compose con etcd
docker-compose -f deploy/docker/docker-compose.yml up -d

# Inicializar vault
curl -X POST http://localhost:8200/v1/sys/init -d '{"shares": 5, "threshold": 3}'

# Unseal con 3 shares
curl -X POST http://localhost:8200/v1/sys/unseal -d '{"key": "<share-1>"}'
curl -X POST http://localhost:8200/v1/sys/unseal -d '{"key": "<share-2>"}'
curl -X POST http://localhost:8200/v1/sys/unseal -d '{"key": "<share-3>"}'

# Habilitar motor PKI para certificados
svault secret engine enable pki
```

**Kogral**:

```bash
# Inicializar repositorio de conocimiento
kogral init

# Añadir runbook
kogral add note "PostgreSQL Connection Pool Tuning" \
  --tags "database,postgresql,performance"

# Añadir ADR
kogral add decision "Elegir Cilium sobre Calico" \
  --context "Necesitamos CNI para K8s con eBPF" \
  --decision "Cilium por performance y observability" \
  --consequences "Mayor complejidad inicial, mejor performance a largo plazo"

# Servir MCP server para Claude Code
kogral serve --port 3100
```

**Provisioning**:

```bash
# Clonar repositorio
git clone https://repo.jesusperez.pro/jesus/provisioning
cd provisioning

# Configurar provider (UpCloud en este ejemplo)
cp config/providers/upcloud.example.toml config/providers/upcloud.toml
# Editar con credenciales de UpCloud

# Crear cluster K8s (definición Nickel)
cat > cluster.ncl <<EOF
{
  provider = "upcloud",
  region = "de-fra1",
  servers = [
    { name = "k8s-cp-01", plan = "medium", role = "control-plane" },
    { name = "k8s-worker-01", plan = "medium", role = "worker" },
    { name = "k8s-worker-02", plan = "medium", role = "worker" },
  ],
  taskservs = ["containerd", "etcd", "kubernetes", "cilium"],
}
EOF

# Validar configuración
nickel typecheck cluster.ncl

# Aplicar (orchestrator con checkpoints)
prov apply cluster.ncl --with-rollback
```

**TypeDialog (prov-gen)**:

```bash
# Ejecutar wizard de configuración de cluster
typedialog execute examples/ops/cluster-setup.toml \
  --backend prov-gen \
  --output my-cluster.ncl

# Configuración generada lista para Provisioning
nickel typecheck my-cluster.ncl
prov apply my-cluster.ncl
```

**Vapora**:

```bash
# Desplegar con Docker Compose (backend + NATS + SurrealDB)
docker-compose up -d

# Crear proyecto
curl -X POST http://localhost:8001/projects \
  -H "Content-Type: application/json" \
  -d '{"name": "Infrastructure Automation", "description": "DevOps pipelines"}'

# Crear tarea para DevOps Agent
curl -X POST http://localhost:8001/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Deploy Prometheus to K8s",
    "task_type": "deployment",
    "context": {"cluster": "prod-us-east-1", "namespace": "monitoring"}
  }'

# Asignar a DevOps Agent
curl -X POST http://localhost:8001/tasks/<task-id>/assign \
  -H "Content-Type: application/json" \
  -d '{"agent_role": "DevOps"}'
```

---

## Contacto

- **Repositorios**: GitHub (proyectos privados)
- **Stack**: Rust, Nickel, Nushell, SurrealDB, Axum
- **Licencia**: Propietaria / Por definir

---

*La infraestructura moderna no debería requerir 10 herramientas desconectadas.*
*Un ecosistema. Cinco proyectos. Integración real para Ops/DevOps.*