Instalación Semi-Airgap

Esta guía cubre la instalación de Zylon para entornos con acceso limitado a internet debido a restricciones de firewall o requisitos de proxy. El sistema requiere conectividad a internet única vez durante la instalación y actualizaciones. 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

Servidor proxy configurado con credenciales (si es requerido)
El equipo de red ha añadido a lista blanca los dominios y puertos requeridos (ver Acceso de Red Requerido)
Las reglas del firewall permiten conexiones a través del proxy
Certificado SSL válido para tu dominio (Let’s Encrypt típicamente no funcionará en redes restringidas)

Acceso de Red Requerido

Tu firewall debe permitir acceso a estos dominios: Servicios Esenciales (Obligatorios):

get.zylon.ai - Instalación de CLI
zylon-cli.s3.us-east-1.amazonaws.com - Binarios de CLI y dependencias
zylon-artifacts.s3.us-east-1.amazonaws.com - Archivos de instalación y actualizaciones de Zylon

Registros de Contenedores Públicos:

quay.io - Imágenes de contenedores de terceros
ghcr.io - Registro de contenedores de GitHub
docker.io - Imágenes de Docker Hub
registry.k8s.io - Imágenes de Kubernetes
reg.kyverno.io - Motor de políticas Kyverno
nvcr.io - Registro de Contenedores NVIDIA

Dado que Zylon requiere imágenes de código abierto públicas, se requiere acceso de red a los registros originales durante la instalación y actualizaciones. Si tus políticas de seguridad restringen el acceso a registros de contenedores públicos, considera cambiar a una instalación airgap usando la Guía de Instalación Airgap de Zylon.

Modelos de IA y Dependencias (Solo aplicable si necesitas modelos de IA personalizados):

huggingface.co - Repositorio de modelos de IA
xet.huggingface.co - Protocolo XET de Hugging Face

Validación de Licencia (Solo aplicable si se usa licencia Replicated):

replicated.app - Plataforma de distribución de Zylon
api.replicated.com - Validación de licencia
proxy.replicated.com - Imágenes de contenedores de Zylon

Instalando Zylon

Instalar Zylon CLI

Tiempo estimado: 2 min

Antes de comenzar la instalación, valida que tu máquina puede alcanzar get.zylon.ai:

curl -sLv get.zylon.ai -m 3 | exit 1

Si la conexión está dando errores, trabaja con tu equipo de red para resolverlos. Una vez que la conectividad esté verificada, puedes proceder.

La 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 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 --force

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-24g"

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.Licencia Local (Si es Necesario)Si api.replicated.com está bloqueado durante la operación, necesitas una licencia local. Contacta con el soporte de Zylon para obtenerla, luego añade:

license:
  email: "champion@company.com"
  id: "2xo..."
  type: "Zylon"
  data: |-
    [eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...]

Reemplaza el campo data con los datos reales de licencia proporcionados por el equipo de Zylon. Por favor, ten cuidado con el formato y la indentación. Solo copia el token que comienza con eyJ....

Configuración de proxy (Si es Necesario)Consulta la Guía de Configuración de Proxy para configurar los ajustes de proxy en tu configuración.Desactivar Let’s EncryptEdita /etc/zylon/zylon-conf.yaml y elimina estas líneas:

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

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.

Instalar Zylon

Tiempo estimado: 15min a 1hora, dependiendo del rendimiento del sistema y velocidad de red.Ejecuta la 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>

El 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
Modelos de IA de tu configuración
Generación de certificados SSL (si usas Let’s Encrypt)

La instalación puede tomar 15-60 minutos dependiendo de la velocidad de red y restricciones del firewall.

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)
Contraseña de administrador: Contraseña segura para el administrador root (se puede cambiar más tarde)
- Usa caracteres alfanuméricos debido a limitaciones de codificación con símbolos especiales
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" \
  --admin-password "contraseña-segura" \
  --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, usa estas credenciales para iniciar sesión:

Usuario: admin@zylon.ai
Contraseña: [la contraseña que estableciste]

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 Operación Offline

Tiempo estimado: 5 minDespués de validar que Zylon está funcionando correctamente, puedes habilitar la operación offline. Esto configurará Zylon para funcionar sin acceso a internet. Edita /etc/zylon/zylon-conf.yaml y añade:

airgap:
  offline_operation: true

Y sincroniza la configuración:

sudo zylon-cli sync

Esto desactivará la conectividad en IA, K8s y otros subsistemas.

Configurar SSL (Opcional)

Tiempo estimado: 10 minPara despliegues en VPN o red 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

Para actualizar la instancia, necesitaremos eliminar temporalmente las restricciones de red en una máquina conectada para descargar paquetes de actualización. Contacta con tu equipo de seguridad de red para añadir a lista blanca los dominios requeridos durante este proceso. Después de descargar, puedes volver a aplicar las restricciones. Antes de actualizar, asegúrate de desactivar el modo offline editando /etc/zylon/zylon-conf.yaml y estableciendo:

airgap:
  offline_operation: false

Valida si Zylon tiene conectividad nuevamente ejecutando:

sudo zylon-cli preflight --network -v

Si todas las comprobaciones pasan, procede a descargar e instalar la actualizació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

Cuando el proceso esté completo, vuelve a habilitar el modo offline estableciendo:

airgap:
  offline_operation: true

Migrando a Semi-Airgap

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

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

Tu configuración y datos existentes serán preservados
Los certificados SSL serán migrados
La organización y usuarios ya existen

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

Asegurar conectividad: Verifica que la máquina objetivo tenga conectividad con los dominios mencionados arriba.
Actualizar configuración: Ejecuta sudo zylon-cli config init --force para actualizar la configuración para operación online. Asegúrate de configurar según describe el paso Configurar Zylon.

Asegúrate de seleccionar Semi-Airgap cuando ejecutes el asistente de configuración.
Si no tienes conectividad con los dominios de replicated, asegúrate de solicitar una licencia local al equipo de soporte de Zylon.

Desactivar modo offline: Edita /etc/zylon/zylon-conf.yaml y establece:
```
airgap:
  offline_operation: false
```
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.

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

Configuración

Mantenimiento y Operaciones

Solución de Problemas

Instalación Semi-Airgap

Acceso de Red Requerido

Instalando Zylon

Actualizando Zylon

Migrando a Semi-Airgap

Próximos Pasos

Primeros pasos

Instalación

Configuración

Mantenimiento y Operaciones

Solución de Problemas

​Acceso de Red Requerido

​Instalando Zylon

​Actualizando Zylon

​Migrando a Semi-Airgap

​Próximos Pasos

Acceso de Red Requerido

Instalando Zylon

Actualizando Zylon

Migrando a Semi-Airgap

Próximos Pasos