Actualización a 1.58

Próxima versión — Zylon 1.58Esta documentación se publica antes del lanzamiento para que puedas preparar tus integraciones de API. La imagen de la versión todavía no está disponible. Para instalaciones con 1.57, consulta la documentación de 1.57.

Se requiere Zylon CLI 2.9.0 o posterior. Los comandos de esta guía no están disponibles en versiones anteriores de la CLI.

Si mantienes una integración por API, revisa la guía de migración de API 1.57 → 1.58 antes de actualizar. Los IDs de creador ahora identifican cuentas; las operaciones de miembros siguen usando IDs de miembro del espacio de trabajo. Para clientes que dependan de esos IDs, migra las llamadas afectadas a la API actual y actualiza los mapeos de IDs guardados. Las URLs antiguas no conservan todo el contrato de identidad de 1.57.

Qué ha cambiado

1.58 requiere dos pasos manuales que la CLI no ejecuta por sí sola. Ejecuta ambos cuando 1.58 esté instalado y todos los pods estén listos:

Backfill de Skills y Documentos. Las Skills y los Documentos existentes deben procesarse con zylon-cli backfill-projections.
Límite de pods más alto en el nodo. El nodo de Kubernetes debe permitir hasta 200 pods. Las instalaciones nuevas lo aplican automáticamente; las existentes lo aplican con zylon-cli configure --max-pods 200. Esto reinicia k0s, por lo que todos los servicios de Zylon estarán brevemente no disponibles.

Si usas el preset baseline-96g, hay un paso más antes de instalar:

Nuevo modelo en baseline-96g. baseline-96g ahora usa nvidia/Qwen3.8-27B-NVFP4 en lugar de cyankiwi/qwen3.5-27b-awq-4bit. Descárgalo antes de instalar 1.58. Para mantener el modelo anterior, configura ai.preset: "deprecated.96g.20261008".

Cómo actualizar

Si necesitas ayuda, abre un ticket de soporte y nuestro equipo de ingeniería te ayudará.

Paso 1: Instala 1.58

Sigue los pasos según tu tipo de instalación.

Online
Semi-Airgap
Airgap Completo

Actualiza la CLI (obligatorio)

sudo zylon-cli self-update

Si el comando falla o la versión no cambia, ejecuta el instalador de respaldo:

curl -sL get.zylon.ai | sudo -E bash

sudo zylon-cli version  # Debería mostrar 2.9.0 o posterior

Descarga el nuevo modelo de 96g (solo para baseline-96g)

Omite este paso si no usas el preset baseline-96g.

sudo zylon-cli models download nvidia/Qwen3.8-27B-NVFP4

Instala 1.58

sudo zylon-cli list-versions
sudo zylon-cli install 1.58.X

Para detalles completos del entorno y troubleshooting, consulta la guía de actualización online.

Actualiza la CLI (obligatorio)

sudo zylon-cli self-update

Si el comando falla o la versión no cambia, ejecuta el instalador de respaldo:

curl -sL get.zylon.ai | sudo -E bash

sudo zylon-cli version  # Debería mostrar 2.9.0 o posterior

Rehabilita acceso a internet

Permite temporalmente operaciones online en tu configuración y aplícala:

airgap:
  offlineOperation: false

sudo zylon-cli sync

Verifica conectividad

sudo zylon-cli preflight --network -v

Descarga el nuevo modelo de 96g (solo para baseline-96g)

Omite este paso si no usas el preset baseline-96g.

sudo zylon-cli models download nvidia/Qwen3.8-27B-NVFP4

Instala 1.58

sudo zylon-cli list-versions
sudo zylon-cli install 1.58.X

Vuelve a activar modo offline

airgap:
  offlineOperation: true

sudo zylon-cli sync

Para red/proxy y más detalle operativo, consulta la guía de actualización semi-airgap.

Estos pasos se ejecutan en dos máquinas: una con internet para descarga y la máquina destino offline.

Máquina online: actualiza la CLI (obligatorio)

sudo zylon-cli self-update

Si el comando falla o la versión no cambia, ejecuta el instalador de respaldo:

curl -sL get.zylon.ai | sudo -E bash

sudo zylon-cli version  # Debería mostrar 2.9.0 o posterior

Máquina online: prepara el paquete de transferencia de la CLI

sudo tar -czf zylon-update.tar.gz \
  /usr/local/bin/zylon-cli \
  /usr/local/bin/zylon-forge-cli

Máquina online: descarga y exporta el nuevo modelo de 96g (solo para baseline-96g)

Omite este paso si no usas el preset baseline-96g.

sudo zylon-cli models download --no-install nvidia/Qwen3.8-27B-NVFP4
sudo zylon-cli models export

Máquina online: exporta el bundle de plataforma 1.58

sudo zylon-cli list-versions

# Usa --from si conoces tu versión actual (bundle más pequeño)
sudo zylon-cli export 1.58.X --from CURRENT_VERSION

# Si no, exporta un bundle completo
sudo zylon-cli export 1.58.X

Transfiere artefactos a la máquina offline

Transfiere los archivos necesarios:

zylon-*.tar
zylon-update.tar.gz
zylon-models-<timestamp>.tar (solo para baseline-96g). Colócalo en su propia carpeta en la máquina offline, por ejemplo /tmp/models, para que zylon-cli import zylon-*.tar no lo incluya.

Máquina offline: extrae el paquete de actualización CLI

cd /tmp
sudo tar -xzf zylon-update.tar.gz -C /
sudo chmod +x /usr/local/bin/zylon-cli /usr/local/bin/zylon-forge-cli
sudo zylon-cli version  # Debería mostrar 2.9.0 o posterior

Máquina offline: importa el nuevo modelo de 96g (solo para baseline-96g)

Omite este paso si no usas el preset baseline-96g.

cd /tmp/models
sudo zylon-cli models import zylon-models-<timestamp>.tar
sudo zylon-cli models download --offline
sudo zylon-cli models list --installed

Máquina offline: importa e instala

# Importa el bundle de Zylon, verifica la versión y luego instala
sudo zylon-cli import zylon-*.tar
sudo zylon-cli list-versions --offline
sudo zylon-cli install 1.58.X --airgap

Para bundles diferenciales y transferencia, consulta la guía de actualización airgap.

Paso 2: Espera a que todos los pods estén listos

Espera hasta que todos los pods del namespace zylon tengan todos sus contenedores listos (por ejemplo 1/1) y estén en Running (o Completed en el caso de jobs):

watch sudo kubectl get pods -n zylon

Paso 3: Aplica los cambios de 1.58

Ejecuta los mismos comandos en todos los tipos de instalación. No necesita acceso a internet.

El backfill reescribe las Skills y Documentos existentes y no se puede deshacer. Ejecútalo siempre primero con --dry-run y revisa la salida antes de ejecutarlo de verdad.

# Comprueba que se pueden ejecutar comandos dentro del backend. Debe terminar sin salida.
# Justo después de un reinicio puede fallar unos minutos aunque el pod muestre 1/1; espera y reintenta.
sudo kubectl -n zylon exec deploy/zylon-zylon-backend -- true

# Previsualiza el backfill de las Skills y Documentos existentes. No se cambia nada.
# Revisa la última línea: debe mostrar failures=0. "planned" es cuántos se escribirán.
sudo zylon-cli backfill-projections --dry-run

# Solo si el dry run ha ido bien: backfill de las Skills y Documentos existentes para que aparezcan en 1.58.
# Este cambio es irreversible.
sudo zylon-cli backfill-projections

# Muestra el límite de pods actual del nodo. Si muestra 110 (el valor por defecto de Kubernetes), nunca se ha aumentado.
sudo kubectl get nodes -o jsonpath='{.items[*].status.capacity.pods}{"\n"}'

# Aumenta el límite de pods de Kubernetes a 200 (las instalaciones nuevas ya lo tienen).
# Reinicia k0s, por lo que todos los servicios de Zylon estarán no disponibles durante unos minutos.
# Si el límite ya es 200, no cambia nada y k0s no se reinicia.
sudo zylon-cli configure --max-pods 200

# Cuando k0s vuelva a estar en marcha, comprueba el nuevo límite. Debe mostrar 200.
sudo kubectl get nodes -o jsonpath='{.items[*].status.capacity.pods}{"\n"}'

La última línea de cada ejecución del backfill muestra el resultado. Los números dependen de tus datos; failures siempre debe ser 0:

# --dry-run: "planned" es lo que se escribirá, todavía no se cambia nada
Projection backfill complete: processed=178 content-migrated=0 projections-written=0 planned=43 skipped=135 failures=0

# Ejecución real: lo planificado ya se ha escrito ("projections-written")
Projection backfill complete: processed=178 content-migrated=43 projections-written=43 planned=0 skipped=135 failures=0

Ejecuta el backfill antes de aumentar el límite de pods: el backfill necesita la plataforma en marcha y el reinicio de k0s lo interrumpiría.

Solución de problemas

backfill-projections falla

Si el error dice container not found ("zylon-backend"), el nodo se ha reiniciado hace poco y aún no está listo para ejecutar comandos. Espera unos minutos hasta que sudo kubectl -n zylon exec deploy/zylon-zylon-backend -- true funcione y reintenta. No se ha cambiado nada.Si no, comprueba que todos los pods del namespace zylon están listos, vuelve a ejecutarlo con --dry-run y revisa la salida. Si el dry run también falla, abre un ticket de soporte antes de ejecutar el backfill real.

configure --max-pods no puede actualizar la configuración de k0s

El comando solo edita /etc/k0s/k0s.yaml cuando coincide con el formato generado por la Zylon CLI. Si no, se detiene y muestra los pasos manuales:

Añade maxPods: 200 en spec.workerProfiles → default → values dentro de /etc/k0s/k0s.yaml.
Reinicia k0s:

sudo k0s stop && sudo k0s start

Comprueba que el nuevo límite está activo:

sudo grep maxPods /run/k0s/kubelet/config.yaml

​Qué ha cambiado

​Cómo actualizar

​Paso 1: Instala 1.58

​Paso 2: Espera a que todos los pods estén listos

​Paso 3: Aplica los cambios de 1.58

​Solución de problemas

Qué ha cambiado

Cómo actualizar

Paso 1: Instala 1.58

Paso 2: Espera a que todos los pods estén listos

Paso 3: Aplica los cambios de 1.58

Solución de problemas