> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zylon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Instalación Semi-Airgap

> Instala Zylon en entornos con acceso restringido a internet

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](/es/operator-manual/installation/hardware-requirements)
* [ ] 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](/es/operator-manual/installation/semi-airgap#required-network-access))
- [ ] 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

<Info>
  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](/es/operator-manual/installation/airgap).
</Info>

**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

<Steps>
  <Step title="Instalar Zylon CLI">
    *Tiempo estimado: 2 min*

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

      ```bash theme={null}
      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.
    </Warning>

    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:

    ```bash theme={null}
    # ssh <user>@<host-ip>
    sudo curl -sL get.zylon.ai | sh
    ```

    Verifica la instalación:

    ```bash theme={null}
    sudo zylon-cli version
    ```

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

  <Step title="Verificar requisitos mínimos de Zylon">
    Asegúrate de que tu máquina cumple con los [requisitos de hardware](/es/operator-manual/installation/hardware-requirements) para Zylon.

    Para validar automáticamente si tu instalación cumple con los requisitos mínimos, ejecuta:

    ```bash theme={null}
    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.

    <Info>
      ¿Tienes problemas con la conectividad de red? Considera cambiar a una [Instalación Airgap](/es/operator-manual/installation/airgap).
    </Info>

    <Note>
      Zylon requiere que todas las comprobaciones pasen antes de proporcionar soporte de instalación.
    </Note>
  </Step>

  <Step title="Configurar Zylon">
    *Tiempo estimado: 10min*

    Zylon se configura mediante un archivo YAML ubicado en `/etc/zylon/zylon-conf.yaml`.

    **Generar Configuración Inicial**

    Usa la CLI para generar un archivo de configuración inicial:

    ```bash theme={null}
    sudo zylon-cli config init
    ```

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

    <Info>
      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:

      ```bash theme={null}
      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](#manual-configuration).
    </Info>

    <Tabs>
      <Tab title="Configuración Automática">
        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](#manual-configuration).

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

          ```bash theme={null}
          sudo zylon-cli config init
          ```
        </Info>

        Puedes
      </Tab>

      <Tab title="Configuración Manual">
        Edita `/etc/zylon/zylon-conf.yaml` para ajustar la configuración según sea necesario.

        **Define tu distribución del sistema operativo**

        Establece `node.distro` para que coincida con tu versión de Ubuntu:

        ```yaml theme={null}
        node:
          distro: "ubuntu22"  # para Ubuntu 22.04
          # distro: "ubuntu24"  # para Ubuntu 24.04
        ```

        **Define tu arquitectura de CPU**

        Establece `node.arch` para que coincida con tu hardware:

        ```yaml theme={null}
        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):

        ```yaml theme={null}
        node:
          drivers: "generic"
        ```

        **Configura el tipo de clúster**

        Establece `cluster.type` a `k0s` (esta es la única opción soportada para instalaciones de instancia única):

        ```yaml theme={null}
        cluster:
          type: "k0s"
        ```

        **Selecciona tu canal de lanzamiento**

        Establece `channel` a `stable` (recomendado para producción y uso normal) o `unstable` (disponible bajo solicitud para pruebas):

        ```yaml theme={null}
        channel: "stable"
        ```

        **Añade tu información de licencia**

        Establece `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:

        ```yaml theme={null}
        license:
          email: "champion@company.com"
          id: "2oq..."
        ```

        **Elige tu preset de IA**

        Establece `ai.preset` basándote en tu memoria GPU disponible. Consulta [Presets de IA](/es/operator-manual/ai-presets/getting-started) para más detalles.

        ```yaml theme={null}
        ai:
          preset: "baseline-48g"
        ```

        **Establece tu identificador de empresa**

        Establece `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`):

        ```yaml theme={null}
        companyIdentifier: "tu-empresa"
        ```

        **Desactiva telemetría e informes de errores**

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

        ```yaml theme={null}
        observability:
            crashReporting: false
            usageMetrics: false
        ```

        **Configura el ingress de red**

        Establece `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`

        ```yaml theme={null}
        ingress:
          host: "zylon.tu-empresa.com"
          enabled: true
          tlsEnabled: true
        ```

        **Configura la generación de certificado SSL**

        Si tu servidor es accesible desde internet, Let's Encrypt generará y renovará automáticamente los certificados SSL. Mantén el `certManagerAnnotations` por defecto:

        ```yaml theme={null}
        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](#disable-lets-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:

        ```yaml theme={null}
        license:
          email: "champion@company.com"
          id: "2xo..."
          type: "Zylon"
          data: |-
            [eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...]
        ```

        <Warning>
          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...`.
        </Warning>

        **Configuración de proxy (Si es Necesario)**

        Consulta la [Guía de Configuración de Proxy](/es/operator-manual/configuration/network/proxy) para configurar los ajustes de proxy en tu configuración.

        **Desactivar Let's Encrypt**

        Edita `/etc/zylon/zylon-conf.yaml` y **elimina** estas líneas:

        ```yaml theme={null}
        certManagerAnnotations:
          cert-manager.io/cluster-issuer: "letsencrypt-prod"
        ```
      </Tab>
    </Tabs>

    **Ver Configuración Actual**

    ```bash theme={null}
    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`):

    ```bash theme={null}
    # 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](/es/operator-manual/configuration/index).
  </Step>

  <Step title="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 y se descargarán desde los dominios de Hugging Face.

    Asegúrate de que tu firewall permita acceso a:

    * `huggingface.co`
    * `xet.huggingface.co`

    Verifica los modelos disponibles y compara con tu preset de IA:

    ```bash theme={null}
    sudo zylon-cli models list
    ```

    Más detalles de preset en la [documentación de Presets de IA](/es/operator-manual/ai-presets/presets).

    Descarga los modelos basados en tu configuración:

    ```bash theme={null}
    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:

    ```bash theme={null}
    sudo zylon-cli models list
    sudo zylon-cli models download model-a model-b model-c
    ```

    Por ejemplo, para el preset `baseline-48g`:

    ```bash theme={null}
    sudo zylon-cli models download qwen/qwen3-14b-awq mixedbread-ai/mxbai-embed-large-v1
    ```
  </Step>

  <Step title="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:

    ```bash theme={null}
    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](https://k0sproject.io/))
    * 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)

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

    **Monitorear la instalación**

    Supervisa el progreso de la instalación:

    ```bash theme={null}
    # 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`.

    <Tip>
      **Reinicia después de la instalación** para asegurarte de que los drivers de GPU se carguen correctamente.
    </Tip>

    <Danger>
      **Las actualizaciones del kernel pueden romper los drivers de NVIDIA!**

      Verifica los drivers con: `nvidia-smi`

      Solución de problemas: [Guía de Drivers de NVIDIA](/es/operator-manual/troubleshooting/nvidia-drivers)
    </Danger>

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

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

  <Step title="Crear Organización">
    *Tiempo estimado: 5 min*

    Después de que Zylon esté instalado y en funcionamiento, crea tu organización y cuenta de administrador root.

    **Prepara la Información**

    Necesitará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**

    ```bash theme={null}
    sudo zylon-cli seed \
      --org-name "Mi Organización" \
      --email-regex ".*@tuempresa\.com"
    ```

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

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

    **Credenciales de Inicio de Sesión**

    Después de hacer el seed, obtén la contraseña de un solo uso para la cuenta de administrador:

    ```bash theme={null}
    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.

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

  <Step title="Configurar Operación Offline">
    *Tiempo estimado: 5 min*

    Despué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:

    ```yaml theme={null}
    airgap:
      offlineOperation: true
    ```

    Y sincroniza la configuración:

    ```bash theme={null}
    sudo zylon-cli sync
    ```

    Esto desactivará la conectividad en IA, K8s y otros subsistemas.
  </Step>

  <Step title="Configurar SSL (Opcional)">
    *Tiempo estimado: 10 min*

    Para despliegues en VPN o red privada, necesitas instalar manualmente certificados SSL.

    **Eliminar Generación Automática de Certificado**

    Edita `/etc/zylon/zylon-conf.yaml` y **elimina** estas líneas:

    ```yaml theme={null}
    certManagerAnnotations:
      cert-manager.io/cluster-issuer: "letsencrypt-prod"
    ```

    **Prepara los Archivos de Certificado**

    Kubernetes 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:

    ```bash theme={null}
    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**

    ```bash theme={null}
    # 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 Cambios**

    Recarga la configuración de Zylon:

    ```bash theme={null}
    sudo zylon-cli sync
    ```

    **Verificar**

    Accede 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

    <Tip>
      La renovación del certificado debe hacerse manualmente repitiendo este proceso con archivos de certificado actualizados.
    </Tip>
  </Step>
</Steps>

***

## 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:

```yaml theme={null}
airgap:
  offlineOperation: false
```

Valida si Zylon tiene conectividad nuevamente ejecutando:

```bash theme={null}
sudo zylon-cli preflight --network -v
```

Si todas las comprobaciones pasan, procede a descargar e instalar la actualización:

```bash theme={null}
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:

```bash theme={null}
sudo zylon-cli upgrade
```

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

```yaml theme={null}
airgap:
  offlineOperation: 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.

<Info>
  **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
</Info>

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

1. **Asegurar conectividad**: Verifica que la máquina objetivo tenga conectividad con los dominios mencionados arriba.
2. **Actualizar configuración**: Ejecuta `sudo zylon-cli config init` para actualizar la configuración para operación online. Asegúrate de configurar según describe el paso [Configurar Zylon](#configure-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.

4. **Desactivar modo offline**: Edita `/etc/zylon/zylon-conf.yaml` y establece:
   ```yaml theme={null}
   airgap:
     offlineOperation: false
   ```
5. **Refrescar configuración**: Ejecuta `sudo zylon-cli sync` para aplicar los nuevos ajustes de configuración.
6. **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](/es/operator-manual/ai-presets) para optimizar según tu hardware
* [Configurar Copias de Seguridad](/es/operator-manual/operations/backup) para protección de datos
* [Revisar Manual de Usuario](/es/user-manual/quick-start-guide) para comenzar