Compilar Imágenes IoT de Fedora Personalizadas con image-builder

image-builder es una herramienta de línea de comando para compilar imágenes de sistema operativo personalizado para Fedora, CentOS, y RHEL. Esta guía explica como utilizar a image-builder para crear imágenes personalizadas de Fedora IoT con sus propias selecciones de paquetes, configuraciones de usuario, y ajustes.

Para imágenes de pre-compilación de Fedora IoT sin personalización, consulte Obtener Imágenes.

Instalar image-builder

Para instalar image-builder en Fedora:

$ sudo dnf install image-builder ostree

Tipos de Imagen Disponibles de Fedora IoT

image-builder admite varios tipos de imágenes específicas de IoT para las arquitecturas x86_64 y aarch64:

  • iot-commit - OSTree commit tarball (la fundación para personalizar imágenes)

  • iot-installer - ISO del Instalador Anaconda para instalación interactiva

  • iot-simplified-installer - Instalador Zero-touch utilizando FDO o Ignition

  • iot-raw-xz - Imagen de disco en crudo comprimida para dispositivos físicos (p.e., Raspberry Pi)

  • iot-qcow2 - Imagen de disco QCOW2 para máquinas virtuales

  • iot-container - Contenedor OCI con commit OSTree

  • iot-bootable-container - Imagen de contenedor arrancable

Para listar todos los tipos de imagen IoT disponible:

$ image-builder list | grep iot

Compilar Imágenes Adaptadas de Fedora IoT

El flujo típico para crear imágenes adaptadas de Fedora IoT es:

  1. Crear un blueprint describiendo sus adaptaciones

  2. Compila un commit OSTree personalizado con sus cambios

  3. Servir el commit OSTree localmente

  4. Compila el medio de instalación o imágenes de disco desde su commit personal

Paso 1: Crear un Blueprint

Blueprints son archivos TOML que describe personalizaciones para su imagen. Te concede hacer:

  • Instalar o desinstalar paquetes

  • Configurar usuarios y grupos

  • Configurar claves SSH

  • Configurar ajustes del sistema

Crear un archivo blueprint (ejemplo: iot-custom.toml):

name = "iot-custom"
description = "Imagen Adaptada de Fedora IoT"
version = "0.0.1"

[[packages]]
name = "vim-enhanced"

[[packages]]
name = "htop"

[[packages]]
name = "tmux"

[[customizations.user]]
name = "admin"
description = "Usuario Admin"
password = "$6$rounds=4096$saltsalt$encrypted_password_hash"
groups = ["wheel"]

[[customizations.sshkey]]
user = "admin"
key = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExample admin@workstation"
Genera contraseñas cifradas con openssl passwd -6 (solicitará la contraseña interactivamente)

Paso 2: Compila un Commit OSTree Personalizado

Compila un tarball de commit OSTree con sus adaptaciones. Utilice la ref oficial nombrando patrón (fedora/stable), fedora/devel, o fedora/rawhide):

$ sudo image-builder build iot-commit \
  --distro fedora-43 \
  --blueprint iot-custom.toml \
  --ostree-ref fedora/stable/x86_64/iot \
  --output-dir ./iot-commit-output

# Nota Para aarch64 utiliza `fedora/stable/aarch64/iot`

Esto crea un tarball conteniendo su commit del OSTree personalizado.

Paso 3: Configurando un Repositorio de OSTre Local

Extrae el tarball de commit y servir el repositorio de OSTree:

$ tar -xf ./iot-commit-output/*.tar
$ mv repo ostree-repo
$ cd ostree-repo
$ python3 -m http.server 8000

El tarball contiene un directorio repo/ con el repositorio completo de OSTree. Para ejecutar el servidor HTTP en el segundo plano, añada & el final:

$ python3 -m http.server 8000 &

Su repositorio OSTree personal ahora está disponible en http://localhost:8000

Para verificar el repositorio es apropiado configurar:

$ ostree --repo=./ostree-repo refs
$ curl http://localhost:8000/refs/heads/fedora/stable/x86_64/iot

Compilar Imágenes desde Su OSTree Personalizado

Con su commit de OSTree personalizado servidor localmente, ahora puede compilar varios tipos de imágenes.

Compilando un ISO del Installer

Crea un instalador ISO de Anaconda que instalará su Fedora IoT personalizado:

$ sudo image-builder build iot-installer \
  --distro fedora-43 \
  --ostree-url http://localhost:8000 \
  --ostree-ref fedora/stable/x86_64/iot \
  --output-dir ./images

Compilando un Instalador Simplificado

El instalador simplificado proporciona suministro zero-touch utilizando FDO o Ignition:

$ sudo image-builder build iot-simplified-installer \
  --distro fedora-43 \
  --ostree-url http://localhost:8000 \
  --ostree-ref fedora/stable/x86_64/iot \
  --output-dir ./images

Consulte Arrancar el Proveedor Simplificado para más detalles.

Compilar Imágenes de Disco en Crudo

Para equipos de tarjeta única como Raspberry Pi, cree una imagen de disco en crudo comprimida:

$ sudo image-builder build iot-raw-xz \
  --distro fedora-43 \
  --arch aarch64 \
  --ostree-url http://localhost:8000 \
  --ostree-ref fedora/stable/aarch64/iot \
  --output-dir ./images

Estas imágenes pueden ser escritas directamente a tarjetas SD u otro medio de almacenaje.

Compilando Imágenes QCOW2 para las MV

Para probar en máquinas virtuales:

$ sudo image-builder build iot-qcow2 \
  --distro fedora-43 \
  --ostree-url http://localhost:8000 \
  --ostree-ref fedora/stable/x86_64/iot \
  --output-dir ./images

Creación de Imágenes de Contenedor

Cree un contenedor OCI con su commit OSTree:

$ sudo image-builder build iot-container \
  --distro fedora-43 \
  --ostree-url http://localhost:8000 \
  --ostree-ref fedora/stable/x86_64/iot \
  --output-dir ./images

Cree un contenedor arrancable para flujos de trabajos de contenedor-nativo moderno:

$ sudo image-builder build iot-bootable-container \
  --distro fedora-43 \
  --ostree-url http://localhost:8000 \
  --ostree-ref fedora/stable/x86_64/iot \
  --output-dir ./images

Consulte Fedora IoT Bootc para más información sobre contenedores arrancables.

Servir Su Repositorio de OSTree a Otras Máquinas

Para que esté disponible su repositorio OSTree personalizado en otras máquinas en su red:

$ cd ostree-repo
$ python3 -m http.server 8000 --bind 0.0.0.0 &
El & ejecuta el servidor en segundo plano. Para detenerlo más tarde, utilice pkill -f "http.server 8000"

Después utilice su dirección IP de la máquina cuando compile imágenes sobre otros sistemas:

$ sudo image-builder build iot-installer \
  --distro fedora-43 \
  --ostree-url http://192.168.1.100:8000 \
  --ostree-ref fedora/stable/x86_64/iot \
  --output-dir ./images

Opciones Avanzadas

Añadir Repositorios Adicionales

Añada repositorios de paquetes adicionales durante la compilación de OSTree (no incluido en la imagen final):

$ sudo image-builder build iot-commit \
  --distro fedora-43 \
  --blueprint iot-custom.toml \
  --ostree-ref fedora/stable/x86_64/iot \
  --extra-repo "https://example.com/repo/fedora/43/x86_64" \
  --output-dir ./iot-commit-output
Repositorios adicionales no se compruebe el GPG y solo se utilizados durante el commit de compilación.

Personalizar Nombres de Salida

Personaliza la salida del nombre de archivo para sus imágenes:

$ sudo image-builder build iot-installer \
  --distro fedora-43 \
  --ostree-url http://localhost:8000 \
  --ostree-ref fedora/stable/x86_64/iot \
  --output-name my-custom-installer \
  --output-dir ./images

Salida Verbosa para Depuración

Habilita modo verborreo para ver información de compilación detallada:

$ sudo image-builder build iot-commit \
  --distro fedora-43 \
  --blueprint iot-custom.toml \
  --ostree-ref fedora/stable/x86_64/iot \
  --verbose \
  --output-dir ./iot-commit-output

Exportar Compilación de Artefacto

Exporta la declaración OSBuild y bitácora de compilación para solución de problemas:

$ sudo image-builder build iot-commit \
  --distro fedora-43 \
  --blueprint iot-custom.toml \
  --ostree-ref fedora/stable/x86_64/iot \
  --with-manifest \
  --with-buildlog \
  --output-dir ./iot-commit-output

Descripción de Tipos de Imagen

Para ver información detallada sobre cualquier tipo de imagen IoT:

$ image-builder describe iot-installer --distro fedora-43
$ image-builder describe iot-qcow2 --distro fedora-43 --arch aarch64
$ image-builder describe iot-simplified-installer --distro fedora-43

Esto muestra los paquetes, conductos, y las opciones de configuración por cada tipo de imagen.

Mejores prácticas

  1. Probar Primero con QCOW2 - Compila y testea imágenes iot-qcow2 en las MV antes de crear medio de instalación

  2. Utilizar el Control de Versión para Blueprints - Conserva los archivos blueprint en el git para seguimiento de adaptaciones

  3. Minimizar las Adiciones de Paquete - Solo añade paquetes esenciales; utiliza contenedores para aplicaciones

  4. Utilizar Contraseñas Cifradas - Nunca utilices contraseñas en texto plano en los blueprint

  5. Habilita Modo Verborreo para Solución de Problemas - utilice --verbose cuando depure los asuntos de compilación

Soluciones

Fallo de Compilación con Errores OSTree

Verifique su repositorio local de OSTree esté apropiadamente configurado y existe las referencias:

$ ostree --repo=./ostree-repo refs # referencias
$ ostree --repo=./ostree-repo show fedora/stable/x86_64/iot

Asegure su servidor HTTP esté en ejecución y accesible:

$ curl http://localhost:8000/config
$ curl http://localhost:8000/refs/heads/fedora/stable/x86_64/iot

Errores de denegación de permisos

Muchas operaciones del compilador de imagen requiere privilegios de root:

$ sudo image-builder build iot-installer ...

Espacio de Disco Insuficiente

Compilar imágenes requiere un espacio de disco significante. Asegúrese que al menos tenga libre 10GB:

  • /var/cache/image-builder/ (caché de compilación)

  • Directorio de salida

Vaciar la caché si es necesario:

$ sudo rm -rf /var/cache/image-builder/store/*

Recursos Adicionales

Want to help? Learn how to contribute to Fedora Docs ›