Instalación Online

Esta guía cubre la instalación estándar de Zylon para entornos con acceso completo a internet. El sistema descargará automáticamente todas las dependencias requeridas, imágenes de contenedores y modelos de IA. Lista de Prerrequisitos:

Máquina Linux limpia (Ubuntu 22/24) que cumpla con los requisitos de hardware
Acceso root y SSH a la máquina
Un nombre de dominio para Zylon (por ejemplo, zylon.company.com)
Capacidad para reiniciar la máquina cuando sea necesario
La máquina tiene curl instalado

Acceso completo y sin restricciones a internet en la máquina objetivo
El firewall permite conexiones salientes a registros de Docker y repositorios de paquetes
Ya sea:
- Puertos 80 y 443 abiertos para la generación automática de certificados SSL de Let’s Encrypt, O
- Certificado SSL válido listo para configuración manual

Instalando Zylon

Instalar Zylon CLI

Tiempo estimado: 2 minLa CLI de Zylon acelerará el tiempo necesario para tener todo listo, se encargará de instalar controladores, actualizar Zylon y configurar el sistema. Para instalarla, conéctate por SSH a la máquina donde quieres instalar Zylon y ejecuta:

# ssh <user>@<host-ip>
sudo curl -sL get.zylon.ai | sh

Verifica la instalación:

sudo zylon-cli version

Se requiere acceso root para las operaciones de la CLI, ya que gestiona dependencias y configuraciones a nivel de sistema.

Verificar requisitos mínimos de Zylon

Asegúrate de que tu máquina cumple con los requisitos de hardware para Zylon.Para validar automáticamente si tu instalación cumple con los requisitos mínimos, ejecuta:

sudo zylon-cli preflight --network --fresh-system -v

Resuelve cualquier problema reportado antes de proceder con la instalación. No podrás continuar hasta que todas las comprobaciones previas pasen.

¿Tienes problemas con la conectividad de red? Considera cambiar a una Instalación Semi-Airgap o Instalación Airgap.

Zylon requiere que todas las comprobaciones pasen antes de proporcionar soporte de instalación.

Configurar Zylon

Tiempo estimado: 10minZylon se configura mediante un archivo YAML ubicado en /etc/zylon/zylon-conf.yaml.Generar Configuración InicialUsa la CLI para generar un archivo de configuración inicial:

sudo zylon-cli config init

Esto abre un prompt interactivo que te guía a través de las opciones de configuración.

Si por alguna razón te quedas atascado durante el prompt interactivo, puedes omitirlo añadiendo la bandera -y para auto-generar una configuración por defecto:

sudo zylon-cli config init -y

Después necesitarás editar manualmente /etc/zylon/zylon-conf.yaml para establecer tu configuración deseada basándote en la sección de configuración manual.

Configuración Automática
Configuración Manual

Si ejecutaste sudo zylon-cli config init, toda la configuración está establecida. Revisa /etc/zylon/zylon-conf.yaml para confirmar la configuración. Puedes obtener más información sobre qué configuraciones son requeridas en la sección Configuración Manual.

Si necesitas volver a ejecutar el asistente de configuración, ejecuta:

sudo zylon-cli config init

Puedes

Edita /etc/zylon/zylon-conf.yaml para ajustar la configuración según sea necesario.Define tu distribución del sistema operativoEstablece node.distro para que coincida con tu versión de Ubuntu:

node:
  distro: "ubuntu22"  # para Ubuntu 22.04
  # distro: "ubuntu24"  # para Ubuntu 24.04

Define tu arquitectura de CPUEstablece node.arch para que coincida con tu hardware:

node:
  arch: "amd64"  # para procesadores Intel/AMD

Establece tus controladores de hardware (si aplica)Establece node.drivers a generic (esta es la única opción soportada):

node:
  drivers: "generic"

Configura el tipo de clústerEstablece cluster.type a k0s (esta es la única opción soportada para instalaciones de instancia única):

cluster:
  type: "k0s"

Selecciona tu canal de lanzamientoEstablece channel a stable (recomendado para producción y uso normal) o unstable (disponible bajo solicitud para pruebas):

channel: "stable"

Añade tu información de licenciaEstablece license.email a la dirección de correo electrónico asignada a tu licencia (proporcionada durante el registro).Establece license.id al ID de licencia compartido contigo por el equipo de Zylon por correo electrónico:

license:
  email: "champion@company.com"
  id: "2oq..."

Elige tu preset de IAEstablece ai.preset basándote en tu memoria GPU disponible. Consulta Presets de IA para más detalles.

ai:
  preset: "baseline-48g"

Establece tu identificador de empresaEstablece companyIdentifier a cualquier identificador para el seguimiento anónimo de métricas (por ejemplo, acme-corp). Si tienes múltiples instalaciones, usa identificadores diferentes (por ejemplo, company y company-test):

companyIdentifier: "tu-empresa"

Desactiva telemetría e informes de erroresPara desactivar la telemetría y los informes de errores, añade la siguiente sección:

observability:
    crashReporting: false
    usageMetrics: false

Configura el ingress de redEstablece ingress.host al dominio que has preparado para Zylon. Debe ser un nombre de dominio completamente cualificado (FQDN) que apunte a la dirección IP de tu servidor.Ejemplos:

zylon.company.com
ai.acme-corp.com
zylon-prod.yourcompany.io

ingress:
  host: "zylon.tu-empresa.com"
  enabled: true
  tlsEnabled: true

Configura la generación de certificado SSLSi tu servidor es accesible desde internet, Let’s Encrypt generará y renovará automáticamente los certificados SSL. Mantén el certManagerAnnotations por defecto:

ingress:
  certManagerAnnotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"

Si estás en una red privada o necesitas usar un certificado personalizado, consulta Desactivar Let’s Encrypt a continuación.

Ver Configuración Actual

sudo cat /etc/zylon/zylon-conf.yaml

Puedes editar el archivo de configuración directamente usando tu editor de texto preferido (por ejemplo, nano, vim):

# Elige uno de los siguientes comandos:
sudo nano /etc/zylon/zylon-conf.yaml
sudo vim /etc/zylon/zylon-conf.yaml

Para información detallada sobre todas las opciones de configuración disponibles, consulta la Guía de Configuración.

Descargar Modelos de IA

Tiempo estimado: 10min a 1h, dependiendo de la velocidad de red y modelos.Antes de instalar Zylon, debes descargar los modelos de IA. Los modelos están determinados por tu configuración de preset de IA.Verifica los modelos disponibles y compara con tu preset de IA:

sudo zylon-cli models list

Más detalles de preset en la documentación de Presets de IA.Descarga los modelos basados en tu configuración:

sudo zylon-cli models download

Esto descargará e instalará los modelos de IA que has especificado en el Wizard.Si por alguna razón necesitas descargar modelos específicos, puedes hacerlo con:

sudo zylon-cli models list
sudo zylon-cli models download model-a model-b model-c

Por ejemplo, para el preset baseline-96g:

sudo zylon-cli models download txn545/qwen3.5-35b-a3b-nvfp4 mixedbread-ai/mxbai-embed-large-v1

Instalar Zylon

Tiempo estimado: 15min a 1hora, dependiendo del rendimiento del sistema y velocidad de red.Ejecuta el comando de instalación con tu versión deseada:

sudo zylon-cli list-versions
# Elige tu versión deseada de la lista
sudo zylon-cli install <version>

Reemplaza <version> con tu versión objetivo (por ejemplo, 1.50.0).Qué se InstalaEl proceso de instalación maneja:

Dependencias del sistema (gcc, git, etc.)
Distribución de Kubernetes (k0s)
Controladores NVIDIA y CUDA (si aplica)
Runtime de contenedores y herramientas (kubectl, helm)
Imágenes de contenedores de Zylon
Generación de certificados SSL (si usas Let’s Encrypt)

Nota que los modelos de IA no están incluidos en este paso—fueron instalados en el paso anterior.

Monitorear la instalaciónSupervisa el progreso de la instalación:

# Ver pods de Zylon
watch sudo k0s kubectl get pods -n zylon

# Ver validación de GPU (si aplica)
watch sudo k0s kubectl get pods -n nvidia

Espera hasta que todos los pods muestren estado listo 1/1.

Reinicia después de la instalación para asegurarte de que los drivers de GPU se carguen correctamente.

Las actualizaciones del kernel pueden romper los drivers de NVIDIA!Verifica los drivers con: nvidia-smiSolución de problemas: Guía de Drivers de NVIDIA

Si los servicios permanecen en ContainerCrashLoopBackOff durante más de 1 hora, contacta con soporte y comparte los logs.

Crear Organización

Tiempo estimado: 5 minDespués de que Zylon esté instalado y en funcionamiento, crea tu organización y cuenta de administrador root.Prepara la InformaciónNecesitarás:

Nombre de organización: El nombre de tu empresa o equipo (se puede cambiar más tarde)
Regex de correo electrónico: Patrón para permitir automáticamente que los usuarios se unan
- Para correos name@company.com, usa: .*@company\.com
- Para SSO (Microsoft Entra, Google), puedes usar: .*

Ejecuta el Comando Seed

sudo zylon-cli seed \
  --org-name "Mi Organización" \
  --email-regex ".*@tuempresa\.com"

El comando esperará si Zylon no está completamente listo.

Ejecutar el comando seed BORRARÁ TODOS LOS DATOS. Solo ejecútalo una vez durante la configuración inicial de Zylon.

Credenciales de Inicio de SesiónDespués de hacer el seed, obtén la contraseña de un solo uso para la cuenta de administrador:

sudo zylon-cli admin-password

Luego inicia sesión con:

Usuario: admin@zylon.ai
Contraseña: [la contraseña de un solo uso impresa arriba]

El correo electrónico del administrador root siempre es admin@zylon.ai y no se puede cambiar.

Después del primer inicio de sesión, puedes crear administradores adicionales y configurar la autenticación SSO.

Configurar SSL (Opcional)

Tiempo estimado: 10 min

Omite este paso si usas certificados automáticos de Let’s Encrypt (por defecto para instancias públicas).

Para despliegues en VPN o nube privada, necesitas instalar manualmente certificados SSL.Eliminar Generación Automática de CertificadoEdita /etc/zylon/zylon-conf.yaml y elimina estas líneas:

certManagerAnnotations:
  cert-manager.io/cluster-issuer: "letsencrypt-prod"

Prepara los Archivos de CertificadoKubernetes requiere que el certificado se divida en dos archivos:

tls.crt - El archivo de certificado
tls.key - El archivo de clave privada

Convertir desde PFX (si aplica):Si tienes un archivo .pfx, conviértelo:

openssl pkcs12 -in <tu-certificado.pfx> -clcerts -nokeys -out tls.crt
openssl pkcs12 -in <tu-certificado.pfx> -nocerts -out tls.key

Importar Certificado en Kubernetes

# Elimina cualquier certificado existente
sudo k0s kubectl delete secret tls zylon-tls --ignore-not-found -n zylon

# Importa tu certificado
sudo k0s kubectl create secret tls zylon-tls \
  --key tls.key \
  --cert tls.crt \
  -n zylon

# Verifica la creación
sudo k0s kubectl describe secret zylon-tls -n zylon

Aplicar CambiosRecarga la configuración de Zylon:

sudo zylon-cli sync

VerificarAccede a tu instancia de Zylon en https://zylon.tu-empresa.com y confirma:

La conexión usa HTTPS
El navegador muestra un certificado válido
No aparecen advertencias de certificado

La renovación del certificado debe hacerse manualmente repitiendo este proceso con archivos de certificado actualizados.

Actualizando Zylon

Las actualizaciones siguen el mismo proceso que la instalación:

sudo zylon-cli list-versions
# Elige tu versión deseada de la lista
sudo zylon-cli install <new-version>

Alternativamente, puedes actualizar directamente a la última versión usando el comando de actualización:

sudo zylon-cli upgrade

Migrando a Online

Si tienes una instalación existente de Zylon (semi-airgap o airgap) y quieres migrarla a un entorno completamente online, sigue esta guía. Este proceso preserva tus datos y configuración, mientras realiza la transición a operación online.

La migración difiere de la instalación nueva:

Tu configuración y datos existentes serán preservados
La organización y usuarios ya existen

Para migrar una instalación existente de Zylon (Semi-Airgap, o Airgap) a una instalación Online, sigue estos pasos:

Asegurar conectividad: Verifica que la máquina objetivo tenga acceso completo a internet.
Actualizar configuración: Ejecuta sudo zylon-cli config init para actualizar la configuración para operación online.
Refrescar configuración: Ejecuta sudo zylon-cli sync para aplicar los nuevos ajustes de configuración.
Verificar operación: Confirma que todos los servicios funcionan correctamente con acceso a internet.

Próximos Pasos

Después de completar la instalación, considera los siguientes próximos pasos para optimizar tu despliegue de Zylon:

Configurar Presets de IA para optimizar según tu hardware
Configurar Copias de Seguridad para protección de datos
Revisar Manual de Usuario para comenzar

Primeros pasos

Instalación

Mantenimiento y Operaciones

Backoffice

Configuración

Solución de Problemas

Seguridad

Auditabilidad y gobernanza de IA

Instalación Online

Instalando Zylon

Actualizando Zylon

Migrando a Online

Próximos Pasos

​Instalando Zylon

​Actualizando Zylon

​Migrando a Online

​Próximos Pasos

Instalando Zylon

Actualizando Zylon

Migrando a Online

Próximos Pasos