Introducción · Documentación de Oktavia

Conceptos clave

Oktavia separa con cuidado cuatro cosas que en la operación manual se confunden: lo que se declara, lo que se observa, lo que se genera y lo que se ejecuta. Casi todo el diseño de la plataforma se entiende a partir de esa separación.

Intención (intended): El estado deseado, declarado por una persona en el Configurador. Se guarda como variables por alcance en service_vars.json y se traduce a dos cosas: configuraciones renderizadas por equipo y reglas de cumplimiento en intended.json. El Configurador es la única fuente de verdad de la intención; el discovery sólo observa y sugiere.
Observado (running): Lo que el equipo tiene en realidad cuando el Engine lo visita: configuración en ejecución, interfaces, vecinos, protocolos, rutas, CPU y memoria. Queda en el snapshot normalizado, con la misma forma para todos los fabricantes.
Renderizado: La configuración que resulta de aplicar las plantillas a la intención y al inventario canónico de un equipo. En Cisco, FortiGate, FortiSwitch y Junos es texto por equipo; en Meraki y SD-WAN no hay render, la intención se evalúa como objetos contra la API.
Drift: La diferencia entre lo deseado y lo observado. Un check de compliance que falla es un drift con nombre, severidad y puntaje. El Gemelo lo muestra como diff y propone cerrarlo.
Fuente de verdad (SoT): La UI, por organización. Guarda el inventario operativo, la intención, las reglas, el catálogo de servicios habilitados y la bóveda de credenciales. El Engine la consulta al inicio de cada job y vuelve a ella con los resultados.
Inventario base y canónico: El inventario base es la semilla declarada (CSV o UI): nombre, dirección de gestión, plataforma, sitio, rol. El inventario canónico (device_inventory.json) es el que construye el Engine después del discovery, con modelo, versión, interfaces, etiquetas y capacidades; es el que alimenta el render y compliance.
Job y artefacto: Toda acción del Engine es un job asíncrono con identificador, estado y artefactos descargables (JSON, CSV, CFG). La UI no muestra nada que no venga de un artefacto.
Carril por fabricante: La forma en que un cambio llega al equipo: SSH con diff previo en Cisco, API REST con operaciones idempotentes en FortiGate, NETCONF con commit confirmed en Junos, SSH en FortiSwitch, Dashboard API en Meraki y Config Groups en SD-WAN. Cada carril tiene su bandera de habilitación y sus guardas.
Aprobación humana: Ningún carril aplica sin un cambio aprobado por una persona. Argos y el Gemelo preparan y previsualizan; aplicar es una decisión explícita, registrada con quién y con qué ticket.

UI vs Engine

Son dos componentes con responsabilidades distintas. Entender el reparto evita buscar una función en el lugar equivocado.

	Interfaz (UI)	Motor (Engine)
Qué es	Aplicación web con base de datos relacional	Servicio de automatización con API REST, ejecutor de jobs y programador
Guarda	Organizaciones y usuarios, inventario operativo, sitios, tipos de sitio y roles, intención, reglas, catálogo de servicios, bóveda de credenciales, integraciones, cambios del Gemelo, conversaciones y ciclos de Argos, costos (FinOps)	Snapshots crudos y normalizados, respaldos, inventario canónico, configuraciones generadas, resultados de compliance, topología, jobs y sus artefactos, snapshots y cambios del Gemelo
Hace	Presenta, edita, aprueba, orquesta jobs e ingiere resultados. Expone la fuente de verdad de cada organización al motor.	Toca los equipos. Ejecuta discovery, respaldo, generación, compliance, topología, vulnerabilidades, telemetría, remediación y la red de pruebas.
Autenticación	Sesión de usuario, local o con SSO; credencial de integración para las llamadas que recibe del motor	Credencial de integración maestra y claves por organización con acceso de lectura o escritura
Documentación de su API	Especificación OpenAPI generada, consultable dentro de la instalación	Especificación OpenAPI con interfaz interactiva, dentro de la instalación

Lo que comparten

Un almacenamiento común: intención, reglas, bóveda cifrada y, por organización, la copia vigente de los artefactos de auditoría.
Tres secretos que deben coincidir: la credencial de integración UI→Engine, la credencial Engine→UI y la clave de cifrado de la bóveda.
El catálogo de servicios: el registro del motor es la fuente de verdad; los formularios de la UI y los checks sembrados son proyecciones, y la integración continua de Oktanet falla si divergen.

Por qué se instalan juntos. Los contenedores de un componente montan el almacenamiento del otro. Si no se instalan en el mismo directorio padre, ese almacenamiento no existe y el primer síntoma es un error de archivo o directorio inexistente al arrancar.

Flujo de punta a punta

Así recorre la plataforma un hallazgo desde que se detecta hasta que se comprueba que cerró. Es el ciclo que todas las guías operativas dan por sabido.

Declarar. El inventario base está cargado y la intención, declarada en el Configurador. Guardar la intención deja las variables de servicio y el archivo de reglas de la organización listos para el motor.
Auditar. La UI (o el programador) pide una auditoría. El motor resuelve el inventario de la organización desde la fuente de verdad, encola el job y el ejecutor corre el pipeline: discovery, respaldo, sincronización del caché, inventario canónico, topología, generación, compliance y vulnerabilidades. Cada paso corre sólo en los equipos cuyas capacidades lo permiten.
Producir artefactos. El job deja el inventario canónico, los resultados de compliance, el resumen por sitio, el snapshot de topología, los respaldos y las configuraciones generadas. Al terminar se fusionan con la copia vigente de la organización, por equipo y por sitio.
Ingerir. El motor avisa a la UI, o el operador pulsa «Sincronizar resultados». La UI espeja inventario, resultados y topología en su base de datos.
Revisar. Tableros de cumplimiento por sitio, categoría y severidad; compliance de configuración con el diff entre lo deseado y lo observado; topología, enrutamiento, capa 2 e IPAM desde el mismo snapshot.
Proponer. Desde un hallazgo, desde el Gemelo o desde Argos se crea una solicitud de cambio con destino, carril y diff. La vista previa calcula la remediación: en Cisco, la configuración CLI línea a línea; en los carriles de API, un plan de operaciones determinista.
Aprobar. Una persona aprueba, con su nombre y un ticket. Sólo un cambio aprobado y con alcance de un equipo se puede ejecutar.
Aplicar. El motor ejecuta por el carril del fabricante, siempre con su bandera de remediación encendida: SSH en Cisco, API en FortiGate, commit confirmed en Junos (que una persona confirma o que el vigilante revierte), Dashboard API en Meraki, Config Groups en SD-WAN.
Verificar. Una nueva auditoría (completa, en seco o de un solo equipo) confirma que el check pasa. Argos puede encadenar la verificación en vivo con service_check: interfaz arriba, ping, adyacencia OSPF, ruta por defecto.

Las guías de Auditorías, Compliance y Digital Twin detallan los pasos 2, 5 y 6 a 9.

Multi-tenant

Oktavia opera varias organizaciones en una sola instalación. La organización (tenant) es la unidad de aislamiento: tiene nombre, un identificador corto (slug) único, y todo dato de negocio lleva su identificador.

En la UI

Todo modelo de negocio tiene alcance por organización: las consultas filtran por la organización activa.
Un usuario puede pertenecer a varias organizaciones con un rol por cada una (member o admin) y una marcada como predeterminada. Cambia de organización desde el menú de usuario sin ser superusuario.
Las mutaciones sensibles (integraciones, catálogo, credenciales) exigen ser administrador de la organización o superusuario.
Hay comandos de gestión para crear organizaciones y asignar usuarios; las importaciones aceptan la organización destino.
Un paquete de organización exporta la organización completa a un ZIP (con passphrase opcional) e importa en la misma o en otra instalación, con vista previa antes de aplicar.

En el almacenamiento y en el motor

La UI mantiene por organización sus reglas, intención, inventario, resultados, topología e insights.
El motor recibe organization_slug (u organization_id) en cada job. Con él resuelve el inventario desde la fuente de verdad y, al terminar, guarda los artefactos en el almacenamiento de esa organización.
Telegraf genera una configuración por organización y etiqueta cada serie con tenant; el servidor MCP exige una organización permitida en cada llamada.

Seguridad y credenciales

Quién entra y cómo

Mecanismo	Para qué	Notas
Sesión de usuario	Toda la UI	Caducidad configurable por tiempo de vida e inactividad; cookies seguras en producción; política de contraseñas
SSO con OIDC (Okta)	Inicio de sesión federado con MFA exigible	Se puede obligar a reautenticar y a presentar MFA en cada inicio
Login local	Acceso de respaldo cuando el SSO no está disponible	Se desactiva cuando el SSO está en producción
Credenciales de integración	Las llamadas entre la UI y el motor, en ambos sentidos	Compartidas entre los dos componentes; si faltan, el acceso queda cerrado
Claves por organización (motor)	Integraciones externas con el motor	Una organización, acceso de lectura o escritura y un conjunto acotado de operaciones; nunca se guardan en claro
Lista blanca por IP o red	Limitar desde dónde se usa la plataforma	Modos monitor y estricto; la misma lista aplica a la UI y al motor
Auditoría de seguridad	Quién hizo qué	Eventos con acción, objeto, resultado, origen y agente de usuario

La bóveda de credenciales

Las credenciales de los equipos viven en la UI, cifradas con cifrado simétrico autenticado. Cada credencial tiene un tipo (ssh, snmp, fortigate, meraki, bgp, sdwan, cml), un alcance (device, site o global), usuario, secreto y metadatos como URL base, verificación TLS o permiso de escritura. Se resuelve de lo más específico a lo más general: equipo, luego sitio, luego global.

El secreto nunca vuelve al navegador: en la UI se muestra enmascarado.
Cada cambio se entrega cifrado al motor, que lo descifra con la misma clave. Si las claves difieren, las conexiones a los equipos fallan: es el primer lugar donde mirar.
En producción la UI no arranca sin la clave de cifrado. Rotarla invalida todos los secretos; no hay recifrado automático.
El motor puede configurarse para usar únicamente la bóveda y rechazar credenciales legadas en archivos o variables de entorno.
Los secretos de integraciones (SMTP, proveedor de IA, eventos push) se cifran con la misma clave en la configuración por organización.

Reglas que protegen la evidencia

Los diffs, respaldos y reportes se redactan antes de guardarse o mostrarse: contraseñas, comunidades SNMP y claves se sustituyen.
El servidor MCP es de solo lectura, no tiene acceso a equipos ni a la bóveda, redacta por clave y por línea, y registra cada llamada en un registro de evidencia por organización.
Las remediaciones por API están apagadas por omisión en cada carril y se encienden con una bandera de configuración más un permiso de escritura en la credencial.
La IA local corre en el mismo servidor y no envía nada fuera. Su índice nunca guarda secretos: se descartan las líneas con comunidades, llaves o contraseñas, y el estándar de configuración se genera con los campos secretos enmascarados.
Los parches de seguridad que llevan un secreto no se escriben en la intención: quedan pendientes para la bóveda.

El alta de credenciales y la migración desde configuraciones anteriores están en Bóveda de credenciales.