Inicio · Documentación de Oktavia

Qué es Oktavia

Oktavia es la plataforma de automatización de redes de Oktanet. Combina un motor de automatización, el Engine (NAE, Network Automation Engine), con una interfaz web que funciona como fuente de verdad de la red. Con ella un equipo de operaciones audita sus equipos, verifica que cumplan el estándar declarado, genera la configuración deseada, propone cambios contra esa intención y, con aprobación humana, los aplica y comprueba que el hallazgo cerró.

Para quién es esta documentación

Para quien implementa u opera Oktavia: ingenieros de red, equipos de NOC, socios que la instalan en un cliente y desarrolladores que la integran por API. Si lo que buscas es entender el producto o evaluarlo, empieza por la ficha técnica o por el curso gratuito Oktavia Fundamentos.

Lo que hace

Discovery multivendor desde un inventario declarado: recolecta estado y configuración por SSH, NETCONF o API y lo normaliza a un mismo formato.
Inventario por organización, con sitios, tipos de sitio, roles y plataformas; se carga por CSV o se da de alta en la UI.
Compliance de configuración y de estado contra reglas declaradas, con puntaje por sitio, categoría y severidad.
Config Generator: la intención se declara por alcances (organización, sitio, rol, plataforma, equipo) y se renderiza con plantillas por fabricante.
Digital Twin: snapshots, detección de drift y solicitudes de cambio con vista previa, aprobación y ejecución controlada.
Topología, enrutamiento, capa 2, IPAM y seguridad de red, todo a partir del mismo snapshot.
Telemetría SNMP y syslog con Telegraf e InfluxDB, y reglas que disparan acciones ante eventos.
Argos, el asistente de operación, y un servidor MCP de solo lectura para asistentes de IA.

Fabricantes en producción

Cisco IOS e IOS-XE, Fortinet FortiGate y FortiSwitch, y Juniper Junos tienen discovery, respaldo, generación de configuración, compliance, telemetría y carril de cambios. Cisco Meraki y Cisco SD-WAN se integran por sus APIs de gestión con intención estructurada, sin generación de CLI. El detalle por función está en Integraciones.

Una regla que atraviesa toda la plataforma: Oktavia nunca aplica un cambio sin aprobación humana. Argos propone, el Gemelo previsualiza, una persona aprueba, el Engine ejecuta y una nueva auditoría verifica.

Arquitectura general

Oktavia se entrega como dos componentes que se despliegan juntos, cada uno con su propio conjunto de contenedores: el componente de interfaz (la UI, que es la fuente de verdad) y el motor de automatización (el Engine, que toca los equipos). Alrededor de ellos hay servicios de apoyo que el cliente aprovisiona o que vienen incluidos en los contenedores.

Componente	Responsabilidad
Interfaz (UI)	Fuente de verdad por organización: inventario, intención, reglas, catálogo de servicios, bóveda de credenciales, tableros, Gemelo Digital y Argos. Incluye dos procesos de fondo: el evaluador de reglas de automatización y el que avanza los ciclos de Argos.
Base de datos relacional	PostgreSQL, con alcance por organización en cada fila.
Caché	Compartida entre los procesos de la interfaz.
Motor (Engine)	API de automatización: auditorías como jobs, discovery, respaldos, inventario canónico, generación de configuración, compliance, topología, métricas, Gemelo y servidor MCP. Incluye un ejecutor de jobs y un programador de tareas.
Cola de jobs	Los jobs se encolan y un ejecutor dedicado los corre de forma asíncrona.
Series de tiempo	InfluxDB, para las métricas del plano de datos con retención configurable.
Recolector	Telegraf, para SNMP y syslog, con una instancia por organización.

Cómo se hablan

La UI llama al Engine por una API REST autenticada con una credencial de integración compartida.
El Engine llama a la UI para leer la fuente de verdad de la organización y para entregar los resultados de cada job, con una segunda credencial de integración.
Comparten un almacenamiento: la UI deja ahí la intención, las reglas y la bóveda cifrada; el Engine las lee y deja los artefactos de auditoría por organización. La clave de cifrado de la bóveda debe ser idéntica en ambos lados.
El Engine llega a los equipos por SSH (Cisco, FortiSwitch), NETCONF (Junos) o API REST (FortiGate, Meraki, SD-WAN, CML) con las credenciales de la bóveda.

El detalle de qué hace cada componente y por qué se separan está en UI vs Engine.

Quickstart

El camino más corto hasta una primera auditoría con contenedores. Cada etapa tiene su guía en Guías de instalación; aquí sólo está el orden y el porqué. Los comandos exactos están en la guía de instalación que se entrega con el software.

Antes de empezar

Docker con Compose v2, Git y Python 3 en la máquina donde se instala.
Acceso de gestión a por lo menos un equipo soportado, con un usuario de solo lectura para el primer discovery.
Los dos componentes de Oktavia, la interfaz y el motor, que Oktanet entrega a socios y clientes.

Instala los dos componentes juntos, en el mismo directorio padre: sus contenedores comparten almacenamiento y la instalación lo da por hecho.
Prepara el motor: crea su entorno, instala dependencias y genera su configuración. La herramienta del motor genera también los tres secretos compartidos y fija el token de la base de series de tiempo antes del primer arranque.
Prepara la interfaz: parte de su configuración de ejemplo, corre el script de datos iniciales y asegúrate de que la clave de cifrado de la bóveda sea la misma que en el motor.
Verifica las tres parejas: la credencial de integración UI→Engine, la credencial Engine→UI y la clave de cifrado de la bóveda deben coincidir en los dos componentes.
Carga un inventario mínimo: un CSV con las columnas de Inventario base, desde la UI o con la herramienta del motor.
Levanta el motor y confirma que su verificación de salud responde.
Levanta la interfaz y espera a que la base de datos esté sana y la aplicación en marcha.
Crea el usuario administrador e inicia sesión. Es un punto de control obligatorio: sin usuario no hay forma de seguir.
Da de alta las credenciales de los equipos en Integraciones → Credenciales. Cada cambio se entrega cifrado al motor.
Sincroniza la intención de la organización: guarda cualquier regla desde la UI para que exista su archivo de reglas. Sin él, la auditoría se rechaza.
Lanza la primera auditoría desde el botón «Run Audit» del tablero. Al terminar, la UI ingiere los artefactos y el tablero muestra el puntaje de cumplimiento.

Si algo no sale, Troubleshooting recoge los síntomas frecuentes de instalación con su corrección.

Glosario

Los términos que aparecen en toda la documentación, con la definición que usa la plataforma.

Oktavia: La plataforma completa: Engine más UI.
NAE: Network Automation Engine, el motor de automatización. Expone una API REST autenticada.
UI / SoT: El componente de interfaz, que actúa como fuente de verdad (Source of Truth) del inventario y de la intención.
Tenant / organización: Unidad de aislamiento de datos. Toda fila de la UI y todo job del Engine llevan una organización; se identifica por organization_slug.
Inventario base: La semilla declarada: qué equipos existen, dónde están y cómo se accede a ellos. Viene de un CSV o de la UI.
Discovery: Recolección de estado y configuración desde el inventario declarado. No descubre equipos nuevos: observa los que ya están dados de alta.
Collector: El carril de recolección según el tipo de acceso: SSH, NETCONF o API REST, con un collector por fabricante.
Snapshot normalizado: El JSON por equipo con la misma forma sin importar el fabricante: facts, interfaces, vecinos, protocolos, rutas, configuración y capacidades.
Capabilities: Banderas por equipo (inventory, config_backup, config_render, topology, compliance) que deciden qué pasos del pipeline corren para él.
Intención / intended: El estado deseado declarado en el Configurador. Se materializa como service_vars.json (variables por alcance), configuraciones renderizadas e intended.json (reglas).
Observado / running: Lo que el equipo tiene en realidad: la configuración en ejecución y el estado recolectado.
Drift: La diferencia entre lo deseado y lo observado, o entre dos snapshots.
Alcance (scope): El nivel al que se declara una variable de intención: defaults, by_site, by_site_type, by_role, by_platform, by_model, by_tag, by_filter, by_device. El último gana.
Servicio: Una unidad de configuración con nombre (ntp, snmp, bgp, fgt_dns…) que tiene plantilla por plataforma, campos en el Configurador y checks de compliance asociados.
Manifest v2: El registro de servicios por plataforma en el Engine. Es la fuente de verdad del catálogo; la UI y los checks sembrados son proyecciones y la integración continua falla si divergen.
Carril (vendor lane): La ruta de remediación por fabricante: cli (Cisco), fortigate, juniper, fortiswitch, meraki, sdwan. Las plataformas de API no generan CLI: su intención se evalúa como objetos.
Job: Una ejecución asíncrona del Engine, con estados queued, running, completed, completed_with_errors, failed, timeout, y artefactos descargables.
Artefacto: Un archivo que deja un job: JSON, CSV o CFG. Todo lo que Oktavia afirma está respaldado por uno.
Latest del tenant: La copia vigente y fusionada de los artefactos de cada organización, que es lo que la UI y el MCP consultan.
Digital Twin / Gemelo: La capa de operación de cambios: snapshots congelados, diff y solicitudes de cambio con vista previa, aprobación, ejecución y, en Junos, confirmación.
Cerrar el ciclo: Auditar, ver el cumplimiento, proponer, revisar el diff, aprobar, aplicar y verificar con una nueva auditoría.
Argos: El asistente de operación de la UI. Enruta intenciones a flujos deterministas (marca «IAOps») o a un modelo de lenguaje (marca «IA»). Nunca aplica sin aprobación.
MCP: Model Context Protocol. El Engine expone un servidor MCP de solo lectura sobre los artefactos del tenant; Argos y Claude Desktop lo consumen.
Bóveda de credenciales: Las credenciales de los equipos cifradas en la UI y entregadas al Engine por el volumen compartido. Resolución: equipo, luego sitio, luego global.
Red de pruebas: Un laboratorio en Cisco Modeling Labs que Oktavia administra para validar cambios antes de producción. Encender nodos es siempre del operador.