La Arquitectura de Referencia del Infrastructure Hub

El Problema

Has construido ocho cosas. Un catálogo de Terraform, plantillas golden path, gestión multi-tenant de clientes, orquestación de pipelines con flujos CAB, secretos quantum-safe, aprobaciones firmadas, un chat de infraestructura y detección de drift.

Cada artículo mostraba una pieza. Ahora necesitas la imagen completa: cómo encajan estas piezas, cómo se ve la base de datos con todo funcionando, cómo ha crecido el servicio de IA, y cómo desplegar la plataforma completa.

La arquitectura de referencia de la serie IDP cubría la plataforma orientada a aplicaciones: enriquecimiento del catálogo, scaffolding con IA, revisión de código, TechDocs RAG, gobernanza y respuesta a incidentes. Este artículo extiende esa arquitectura con todo lo de la serie Infrastructure Hub.

La Solución

El Infrastructure Hub añade tres capas a la plataforma IDP existente:

Catálogo de infraestructura — Módulos Terraform como entidades de primera clase, con plantillas golden path y scoping multi-tenant
Operaciones de infraestructura — Orquestación de pipelines, flujos CAB con aprobaciones firmadas, y detección de drift
Inteligencia de infraestructura — Escaneo de secretos con IA, resúmenes de planes, diagnóstico de fallos, y acceso conversacional a todos los datos de infraestructura

Todo esto corre en la misma instancia de Backstage, el mismo servicio de IA en .NET, y la misma base de datos PostgreSQL que el IDP. No hay servicios nuevos que desplegar — solo plugins, endpoints y tablas nuevas.

Ejecución

La Arquitectura Completa

graph TB
    subgraph "Developer / Platform Team"
        Browser[Browser]
    end

    subgraph "Backstage"
        FE[Frontend - React]
        BE[Backend - Node.js]

        subgraph "IDP Plugins (series 1)"
            P1[Catalog Enricher]
            P2[AI Scaffolder]
            P3[Code Review]
            P4[TechDocs RAG]
            P5[Governance]
            P6[Incident Response]
        end

        subgraph "Infra Hub Plugins (series 2)"
            I1[TF Module Templates]
            I2[Secret Scanner]
            I3[Pipeline Dashboard]
            I4[CAB Workflow]
            I5[Infra Chat]
            I6[Drift Dashboard]
        end
    end

    subgraph "AI Service (.NET)"
        API[".NET Minimal API :5100"]
        E_IDP["/api/enrich, /api/scaffold,\n/api/review, /api/ask,\n/api/incident/analyze"]
        E_INFRA["/api/scan-secrets,\n/api/scaffold-terraform,\n/api/pipeline/*,\n/api/cab/*,\n/api/infra/chat,\n/api/drift/*,\n/api/ssh/issue"]
    end

    subgraph "Data"
        PG[(PostgreSQL + pgvector)]
        QV[QuantumVault - Secrets]
        QS[QuantumAPI - Signing]
        QC[QuantumAPI - SSH Certs]
        AI[AI Provider]
    end

    subgraph "External"
        GH[GitHub API]
        ADO[Azure DevOps]
        GHA[GitHub Actions]
        GL[GitLab CI]
        AZ[Azure / Scaleway / AWS]
    end

    Browser --> FE --> BE
    BE --> P1 & P2 & P3 & P4 & P5 & P6
    BE --> I1 & I2 & I3 & I4 & I5 & I6
    P1 & P2 & P3 & P4 & P5 & P6 --> API
    I2 & I3 & I4 & I5 & I6 --> API
    API --> E_IDP & E_INFRA
    API --> PG
    API --> AI
    API --> QV & QS & QC
    I3 --> ADO & GHA & GL
    I6 --> AZ

Nuevos Endpoints en el Servicio de IA

El Infrastructure Hub añade estos endpoints al servicio de IA existente:

Endpoint	Artículo	Propósito
`POST /api/scaffold-terraform`	2	Generar módulo Terraform a partir de una descripción
`POST /api/pipeline/summarize-plan`	4	Resumen legible del plan de Terraform
`POST /api/pipeline/diagnose`	4	Diagnóstico con IA de fallos en pipelines
`POST /api/pipeline/risk-assessment`	4	Evaluación de riesgo para solicitudes de cambio
`POST /api/pipeline/rollback-plan`	4	Generar plan de rollback para un cambio
`POST /api/scan-secrets`	5	Escanear archivos Terraform en busca de secretos
`POST /api/ssh/issue`	5	Emitir certificado SSH ML-DSA
`POST /api/cab/approve`	6	Firmar aprobación CAB con ML-DSA
`GET /api/cab/verify/{id}`	6	Verificar firma de aprobación
`POST /api/cab/seal-evidence`	6	Sellar paquete de evidencia con firma
`GET /api/cab/report`	6	Generar informe de cumplimiento
`POST /api/infra/chat`	7	Conversación multi-turno sobre infraestructura
`POST /api/drift/analyze`	8	Analizar plan de Terraform para detectar drift
`GET /api/drift/results`	8	Obtener todos los resultados de escaneo de drift

Combinado con los endpoints de la serie IDP, el servicio de IA tiene ahora 22 endpoints en un solo Program.cs. El patrón es el mismo para cada endpoint: leer config, crear cliente, construir prompt con contexto, llamar al modelo, devolver JSON estructurado.

Nuevas Tablas en la Base de Datos

Tres tablas añadidas en esta serie:

-- Article 6: Signed CAB approvals
CREATE TABLE cab_approvals (
    id SERIAL PRIMARY KEY,
    change_request_id VARCHAR(100) NOT NULL UNIQUE,
    approved_by VARCHAR(255) NOT NULL,
    approved_at TIMESTAMPTZ NOT NULL,
    module VARCHAR(255) NOT NULL,
    client VARCHAR(100),
    risk_level VARCHAR(20) NOT NULL,
    plan_hash VARCHAR(64) NOT NULL,
    payload_json TEXT NOT NULL,
    signature TEXT NOT NULL,
    key_id VARCHAR(100) NOT NULL
);

CREATE INDEX idx_approvals_module ON cab_approvals(module);
CREATE INDEX idx_approvals_client ON cab_approvals(client);
CREATE INDEX idx_approvals_date ON cab_approvals(approved_at);

-- Article 8: Drift detection results
CREATE TABLE drift_results (
    id SERIAL PRIMARY KEY,
    module VARCHAR(255) NOT NULL UNIQUE,
    client VARCHAR(100),
    drift_detected BOOLEAN NOT NULL,
    resource_count INTEGER NOT NULL DEFAULT 0,
    risk VARCHAR(20) NOT NULL DEFAULT 'none',
    summary TEXT,
    analysis_json TEXT,
    detected_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_drift_module ON drift_results(module);
CREATE INDEX idx_drift_client ON drift_results(client);
CREATE INDEX idx_drift_risk ON drift_results(risk);

Combinado con las tablas de la serie IDP:

Tabla	Serie	Propósito
`doc_chunks`	IDP art. 5	Embeddings vectoriales para RAG
`ai_usage_log`	IDP art. 6	Gobernanza — tracking de uso
`ai_policies`	IDP art. 6	Gobernanza — políticas por equipo
`cab_approvals`	Infra art. 6	Aprobaciones CAB firmadas
`drift_results`	Infra art. 8	Último escaneo de drift por módulo

Cinco tablas. Una instancia de PostgreSQL (con la extensión pgvector). Backstage usa sus propias tablas para el catálogo, y el servicio de IA usa estas cinco para inteligencia y operaciones.

Registro de Nuevos Plugins en Backstage

Añade los plugins de infraestructura a packages/backend/src/index.ts:

// --- Infrastructure Hub plugins (series 2) ---

// Modules (extend existing plugins)
import { secretScannerModule } from '@internal/plugin-secret-scanner';
backend.add(secretScannerModule);                       // Article 5

// Standalone plugins (own routes)
import { aiIncidentPlugin } from '@internal/plugin-ai-incident';
backend.add(aiIncidentPlugin);                          // IDP Article 7

// Frontend-only plugins (registered in App.tsx, not here):
// - Infra Chat (/infra-chat)                           // Article 7
// - Drift Dashboard (/drift)                           // Article 8
// - CAB Review (/cab)                                  // Article 4+6
// - Governance Dashboard (/ai-governance)              // IDP Article 6

Los plugins de infraestructura siguen la misma distinción que los del IDP:

Modules (createBackendModule): el secret scanner extiende el catálogo
Standalone plugins (createBackendPlugin): el pipeline dashboard y el CAB workflow tienen sus propias rutas
Frontend-only: infra chat, drift dashboard y governance dashboard leen del servicio de IA a través del proxy

Mapa de Integración con QuantumAPI

QuantumAPI aparece en tres roles a lo largo del Infrastructure Hub:

QuantumVault (Secrets)
├── Pipeline credentials (art. 5) — ARM_CLIENT_SECRET, DB_PASSWORD, etc.
├── Terraform state encryption keys (art. 5) — ML-KEM wrapped AES keys
├── Cosign signing keys (quantum-05) — for image signing
└── Bootstrap: only QUANTUMAPI_KEY in CI/CD platforms

QuantumAPI Signing (ML-DSA)
├── CAB approval signatures (art. 6) — every approval cryptographically signed
├── Evidence package sealing (art. 6) — tamper-proof audit trail
└── Verification endpoint — auditors can verify without internal access

QuantumAPI SSH (ML-DSA Certificates)
├── Short-lived certificates (art. 5) — 8h validity, auto-expire
├── CA trust model — hosts trust QuantumAPI CA, not individual keys
└── Backstage widget — engineers request access from the catalog

Instalación Local de QuantumAPI

Para sovereign cloud, entornos aislados (air-gapped), u organizaciones que no pueden enviar datos a APIs externas, QuantumAPI ofrece una opción de instalación local.

La instalación local ejecuta los mismos servicios — Vault, Signing, SSH CA, Encryption — dentro de tu propia infraestructura. La API es idéntica. Tu código no cambia. Solo apuntas los endpoints a https://quantumapi.internal en lugar de https://api.quantumapi.eu.

Cambio de configuración en el servicio de IA:

# Cloud (default)
QUANTUMAPI__APIKEY=qid_your_key
# Endpoints default to api.quantumapi.eu

# Local installation
QUANTUMAPI__APIKEY=qid_your_local_key
QUANTUMAPI__ENDPOINT=https://quantumapi.internal

Para el CLI qapi en pipelines:

# Cloud
export QAPI_API_KEY=qid_your_key

# Local
export QAPI_API_KEY=qid_your_local_key
export QAPI_ENDPOINT=https://quantumapi.internal

Todo en esta serie — cifrado de estado, aprobaciones firmadas, certificados SSH, escaneo de secretos — funciona igual con una instalación local. Las garantías criptográficas (ML-KEM, ML-DSA, QRNG) son las mismas porque los algoritmos se ejecutan localmente.

Casos de uso para la instalación local:

Gobierno / defensa — los datos no pueden salir de la red
Servicios financieros — requisito regulatorio de mantener todo el material de claves on-premise
EU sovereign cloud — requisitos de residencia de datos más allá de lo que ofrece QuantumAPI en la nube
Entornos air-gapped — sin acceso a internet desde la red de infraestructura

Las Variables de Entorno Completas

# === AI Provider ===
AI_PROVIDER=openai            # or "azure"
AI_ENDPOINT=https://api.scaleway.ai/v1
AI_KEY=your-key
AI_CHAT_MODEL=mistral-small-3.2-24b-instruct-2506
AI_EMBEDDING_MODEL=bge-multilingual-gemma2

# === PostgreSQL (shared) ===
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=forge
POSTGRES_PASSWORD=your-password

# === QuantumAPI ===
QUANTUMAPI_KEY=qid_your_key
# QUANTUMAPI_ENDPOINT=https://quantumapi.internal  # Only for local install

# === GitHub ===
GITHUB_TOKEN=ghp_your-token

# === OIDC (Backstage auth) ===
OIDC_METADATA_URL=https://auth.quantumapi.eu/.well-known/openid-configuration
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret
BACKEND_SECRET=change-this

# === Webhooks ===
AI_CODE_REVIEW_WEBHOOK_SECRET=your-webhook-secret

Las mismas variables que en la serie IDP, más QUANTUMAPI_KEY (y opcionalmente QUANTUMAPI_ENDPOINT). Los plugins de infraestructura no necesitan variables de entorno adicionales — leen de la misma configuración del servicio de IA.

Las Dos Series Juntas

#	Serie IDP	Serie Infra Hub
1	Why Your IDP Doesn’t Help	Your Infrastructure Has No Catalog
2	Teaching Your Catalog to Think	Golden Path Terraform Modules
3	AI-Powered Software Templates	Multi-tenant Infrastructure
4	The AI Code Review Plugin	Pipelines from Backstage
5	TechDocs RAG	Secrets & Post-Quantum Identities
6	The AI Governance Dashboard	CAB Automation
7	AI-Assisted Incident Response	Chat with Your Infrastructure
8	The Reference Architecture	Drift Detection
9	—	Este artículo

La serie IDP construye la plataforma para aplicaciones — servicios, APIs, código. La serie Infra Hub la extiende para infraestructura — módulos Terraform, pipelines, recursos cloud. El mismo Backstage. El mismo servicio de IA. La misma filosofía: IA como motor, humanos con el control.

Coste con los Plugins de Infraestructura

Añadiendo las funcionalidades de infraestructura a la estimación de coste del artículo 8 del IDP:

Funcionalidad	Frecuencia	Tokens/llamada	Coste mensual
Funcionalidades IDP (serie 1)	—	—	~$9
Scaffolding de Terraform	~5 módulos/mes	~2K input, ~3K output	~$0.11
Resúmenes de planes	~100 planes/mes	~4K input, ~1K output	~$1.30
Escaneo de secretos	Ciclo 12h, ~30 módulos	~3K input, ~500 output	~$0.95
Análisis de drift	Diario, ~30 módulos	~4K input, ~1K output	~$4.50
Chat de infraestructura	~300 preguntas/mes	~5K input, ~1K output	~$4.80
Firma CAB	~50 aprobaciones/mes	N/A (llamada QuantumAPI)	~$0 (incluido en el tier)

Total: ~$21/mes para un equipo de 20 desarrolladores gestionando ~30 módulos Terraform en varios clientes. Las llamadas a QuantumAPI (firma, certificados SSH, vault) están incluidas en el tier business.

Recordatorio de Seguridad

Los mismos gaps de seguridad del artículo 8 del IDP aplican aquí, más:

Sin auth en los endpoints de drift/chat/CAB — el servicio de IA no tiene autenticación. En producción, añade validación JWT o comprobación de API keys.
El output del plan de Terraform puede contener secretos — el texto del plan que se envía al modelo de IA puede incluir valores secretos (por ejemplo, contraseña antigua vs nueva). Considera limpiar el output del plan antes de enviarlo a la IA. El PII scrubber de la serie AI in Production también funciona aquí.
Las firmas CAB dependen de la disponibilidad de QuantumAPI — si QuantumAPI está caído, las aprobaciones no se pueden firmar. El endpoint de firma devuelve 503 y la UI bloquea la aprobación. Esto es intencionado (sin firma = sin aprobación), pero ten en cuenta la disponibilidad de QuantumAPI en tus cálculos de SLA.

La Serie

Artículo	Qué hace	Nuevo Plugin / Endpoint
1. Your Infra Has No Catalog	Módulos Terraform como entidades del catálogo	Entidades del catálogo
2. Golden Path Terraform Modules	Scaffolding de módulos con IA	`/api/scaffold-terraform`
3. Multi-tenant Infrastructure	Sistemas, equipos y config por cliente	Modelo del catálogo
4. Pipelines from Backstage	UI unificada de pipelines + flujo CAB	`/api/pipeline/*`
5. Secrets & PQ Identities	QuantumVault, certificados SSH, secret scanner	`/api/scan-secrets`, `/api/ssh/issue`
6. CAB Automation	Aprobaciones firmadas, informes de cumplimiento	`/api/cab/*`
7. Chat with Your Infra	Acceso conversacional a la infraestructura	`/api/infra/chat`
8. Drift Detection	Detectar y explicar drift de infraestructura	`/api/drift/*`
9. Reference Architecture	Este artículo — todo conectado	—

Troubleshooting

Además de la sección de troubleshooting del IDP:

El secret scanner no encuentra nada — Comprueba que los módulos tienen spec.type: terraform-module en el catálogo. El scanner filtra por este tipo.
Las firmas CAB fallan — Verifica que QuantumApi:ApiKey está configurado en el servicio de IA. El endpoint de firma devuelve 503 con un mensaje de error claro.
El escaneo de drift no muestra resultados — El workflow de GitHub Actions necesita que terraform init funcione, lo que requiere credenciales de cloud. Comprueba los secret IDs de QuantumVault en las variables del workflow.
El chat de infraestructura da respuestas vacías — El chat recoge contexto de la base de datos del catálogo y la tabla cab_approvals. Si están vacías, la IA no tiene datos con los que trabajar. Ejecuta el catalog enricher y aprueba al menos un cambio primero.
PIPESTATUS no funciona — Si tu CI runner usa sh en lugar de bash, PIPESTATUS no existe. Usa bash de forma explícita: shell: bash en GitHub Actions.

Qué Viene Después

Dos series completadas. Una instancia de Backstage. Un servicio de IA. 22 endpoints. 5 tablas custom. La plataforma gestiona tanto aplicaciones como infraestructura, con asistencia de IA en cada paso y seguridad post-quantum en todo el sistema.

¿Qué falta? Las cosas que dejamos fuera a propósito:

Control de admisión en Kubernetes. La serie Quantum-Safe Cloud mencionó este gap: las imágenes sin firmar todavía se pueden desplegar manualmente. Un admission webhook con Ratify rechazaría pods con imágenes sin firmar a nivel de cluster.

Dashboards de gestión de costes. El governance dashboard controla los costes de IA. Pero ¿y los costes de infraestructura? Gasto cloud por cliente, por módulo, por entorno. Eso es un plugin de Backstage que lee de Azure Cost Management, AWS Cost Explorer, o las APIs de facturación de Scaleway.

Policy as code. El flujo CAB es manual (con asistencia de IA). Open Policy Agent o Kyverno podrían automatizar la aplicación de políticas: “no storage accounts públicos”, “todos los clusters AKS deben tener RBAC activado”, “no módulos sin bloques de cifrado.”

Cada uno de estos podría ser un artículo independiente o una mini-serie. Si hay interés, dímelo.

El código está en GitHub: victorZKov/forge.

Victor

Si esta serie te ayuda, considera invitarme a un café.

Este es el artículo 9 — el artículo final de la serie Infrastructure Hub. Anterior: Drift Detection.