Saltar al contenido
Páginas de la documentación

Documentación

Plantillas

De dónde salen las plantillas de IsardVDI, y cómo construir una propia a partir de un solo fichero YAML con isard build.

Parte de Bastión.

Introducción

Todos los escritorios que has hecho hasta ahora salen de una plantilla, y la has elegido de una lista que ha escrito otra persona.

Esa lista es la de tu centro, es corta y es antigua.

Tarde o temprano un ejercicio necesitará algo que no está en ella: una Fedora cuando el centro solo tiene Ubuntu, una máquina con Docker ya instalado para que treinta alumnos no pasen diez minutos cada uno instalándolo, una imagen base con tu clave SSH ya incluida.

Una plantilla no tiene nada de mágico. Es un escritorio que alguien detuvo y congeló:

architecture-beta
     service iso(disk)[ISO]
     service desktop(server)[Desktop]
     service template(database)[Template]

     iso:R -- L:desktop
     desktop:R -- L:template

Tres pasos, y esta página trata esos tres:

  1. meter una ISO de instalación en Isard: la biblioteca de medios;
  2. instalar un sistema operativo en un escritorio a partir de ella;
  3. promover ese escritorio a plantilla.

Y después, hacerlos todos con un solo comando.

La biblioteca de medios

Isard llama medio a una ISO subida, y cada cuenta tiene una biblioteca de ellos.

$ isard media

-- Media --
NAME                             STATUS      SIZE   OWNER
Fedora-Server-netinst-x86_64-44  Downloaded  1049M  you
ubuntu-24.04.4-live-server       Downloaded  3052M  shared

shared significa que alguien de tu centro lo ha publicado para todos. you significa que lo has añadido tú y que cuenta para tu cuota.

Para añadir uno hace falta una URL, no un fichero:

$ isard media add ubuntu-24 --url https://releases.ubuntu.com/24.04/ubuntu-24.04.4-live-server-amd64.iso
✓ Media registered
✓ Media id: 2b8f61c4-...
✓ Downloaded: ubuntu-24

✓ Media 'ubuntu-24' ready (id: 2b8f61c4-...).

Lo descarga Isard, no tú. No hay ninguna forma de subir ficheros: le das a la plataforma una dirección https:// y su propio descargador se trae el fichero.

Eso es bueno con la conexión de un instituto, y es una limitación la primera vez que tienes una ISO en un pendrive y ningún sitio donde ponerla.

El comando espera por defecto y muestra el progreso. --no-wait vuelve inmediatamente, y luego con isard media puedes seguir su estado.

Borrar hace lo que esperas:

$ isard media delete ubuntu-24

⚠ About to delete media:
  Name : ubuntu-24
  ID   : 2b8f61c4-...
  State: Downloaded
Delete this media? [y/N] y
✓ Media deleted

A mano, en el navegador

Ahora que hay una ISO en la biblioteca, puedes arrancar un escritorio desde ella.

En la vista Medios, el icono de la fila genera un escritorio a partir de ese medio:

Abre el formulario de creación de siempre, salvo que el dispositivo de arranque es la ISO en lugar de una plantilla:

Para una Fedora Server, la configuración que importa es:
Arranque CD/DVD
Bus de disco virtio
Disco 100 GB
Red Default y Wireguard VPN

Arráncalo, abre el visor e instala el sistema operativo exactamente como lo harías en una máquina real.

Después (y este es el paso que la gente se salta) detén la máquina y edítala antes de hacer nada más:
Arranque Disco duro
Medio Ninguno
Bus de disco Por defecto

Si te lo saltas, el firmware vuelve a encontrar la ISO de instalación en el siguiente arranque y te ofrece tan tranquilo reinstalar encima de lo que acabas de construir.

Promover

Ahora tienes un escritorio con un sistema operativo. Convertirlo en plantilla es un solo comando:

$ isard template promote fedora-base --name fedora-44-base -d 'Fedora 44 Server, docker preinstalled'
✓ Resolved desktop: fedora-base

✓ Template 'fedora-44-base' created.
  Template ID : 5c1e9a07-...
  Source      : fedora-base (8d3a2f61-...)
  Enabled     : yes

Dos condiciones, y las dos las comprueba la plataforma, no la herramienta:

  • el escritorio tiene que estar Stopped (detenido);
  • su disco tiene que haberse escrito de verdad: un escritorio creado y nunca arrancado no es un origen válido.

--disabled crea la plantilla oculta, que es lo que quieres si vas a revisarla antes de que la use una clase.

Todo, en un fichero

Todo lo anterior son cuatro comandos, un formulario, una instalación y una promoción, con dos ocasiones de equivocarte con el orden de arranque.

isard build lo hace todo, descrito en un solo fichero YAML.

# ubuntu.yaml
image:
  distro: ubuntu
  variant: server
  release: lts

template:
  name: ubuntu-lts-base
  description: Ubuntu LTS with docker and the class tooling
  vcpus: 4
  memory_gb: 8
  disk_gb: 100

user:
  name: isard
  password_env: ISARD_TEMPLATE_PASSWORD
  ssh_key: ~/.ssh/id_ed25519.pub

packages: [git, curl, docker.io]
run:
  - systemctl enable --now docker
  - usermod -aG docker isard

Mira el plan antes de dedicarle una tarde:

$ isard build ubuntu.yaml --dry-run
✓ Ubuntu 26.04.1 LTS Server (live-server)

Template : ubuntu-lts-base
Image    : Ubuntu 26.04.1 LTS Server (live-server), 2.9 GB
URL      : https://releases.ubuntu.com/resolute/ubuntu-26.04.1-live-server-amd64.iso
Hardware : 4 vCPU, 8 GB RAM, 100 GB disk
User     : isard
Install  : by hand in the viewer (user, password, SSH server)
Provision: hostname/locale/timezone, 3 package(s), 0 file(s), 2 command(s) over SSH

--dry-run solo consulta el índice de versiones del distribuidor: ninguna sesión, ninguna llamada a la API, ninguna descarga.

Es el comando que hay que ejecutar después de cada cambio en el fichero, porque una errata en una clave es un error, no un aviso:

$ isard build ubuntu.yaml --dry-run
error: ubuntu.yaml: unknown key in `profile`: pakages
Allowed: files, hostname, image, keyboard, locale, packages, run, template, timezone, user

Esa rigidez es deliberada. Una clave ignorada en silencio es una clave que descubres veinte minutos después de empezar una descarga de 3 GB.

Después ejecútalo:

$ isard build ubuntu.yaml
✓ Ubuntu 26.04.1 LTS Server (live-server)
...
  URL: https://releases.ubuntu.com/resolute/ubuntu-26.04.1-live-server-amd64.iso
✓ No existing media — will register
✓ Media registered
✓ Media id: 7d41c2e8-...
✓ Downloaded: ubuntu-26.04.1-live-server-amd64
✓ Created ubuntu-lts-base (c0a9e7b2-...)
✓ Bastion armed (applies at the next boot)
✓ Bastion will log in as 'isard'
✓ Desktop starting
✓ ubuntu-lts-base is now Started

In the viewer, install the OS. Three things have to match; the rest is yours:

  1. username     isard
  2. password     una-contrasenya-llarga
  3. SSH server   tick "Install OpenSSH server" in the installer

Then shut the machine down — the build resumes by itself the moment it stops.
Nothing else is needed: hostname, locale, timezone, packages, your SSH key
and passwordless sudo are all applied automatically afterwards.

El único paso que es tuyo

El instalador del sistema operativo no se puede controlar desde fuera, y la construcción no finge lo contrario: te da el visor y espera.

Hay tres cosas que tienen que coincidir, y el resto es cosa tuya:

qué dónde
1 el nombre de usuario de user.name la pantalla de cuenta del instalador
2 la contraseña de user.password la misma pantalla
3 un servidor SSH Ubuntu: marca Install OpenSSH server. Fedora: elige el entorno Server

Después apaga la máquina. No la reinicies.

La construcción espera a que el escritorio llegue a Stopped: no te pide nada, así que puedes irte y seguirá sin ti.

✓ ubuntu-lts-base is now Stopped
✓ Booting from disk
✓ Desktop starting
✓ ubuntu-lts-base is now Started
✓ SSH is up

Applying the profile over SSH:

==> hostname ubuntu-lts-base
==> timezone Europe/Madrid
==> account isard
==> authorising the SSH key for isard
==> installing 3 package(s)
...
==> systemctl enable --now docker
==> usermod -aG docker isard
==> provisioning complete
✓ Guest account 'isard' is ready
✓ Stop requested
✓ ubuntu-lts-base is now Stopped
✓ Bastion will log in as 'isard'
✓ Deleted 'ubuntu-26.04.1-live-server-amd64'

✓ Template 'ubuntu-lts-base' is ready.
  Template ID : 4f6b0d1a-...
  Guest user  : isard
  Create one  : isard create my-box --template ubuntu-lts-base

El nombre de usuario y la contraseña importan porque el bastión entra en el sistema invitado con ellos, y así es como la construcción entra después para hacer el resto.

Si te equivocas en el instalador, la fase de configuración no puede iniciar sesión, y ese es el único fallo de este comando que te hace perder toda la instalación.

Cuando el SSH nunca responde

Casi siempre es que se pasó por alto la opción de OpenSSH en la pantalla del instalador.

La construcción sabe reconocerlo y, en lugar de agotar el tiempo de espera, muestra la solución y espera a que la ejecutes en la consola del propio escritorio:

$ curl -fsSL https://isard.xtec.dev/guest.sh | sudo sh -s isard mypassword

Es la misma línea de Bastión, y es corta a propósito: la consola en la que tienes que escribirla todavía no tiene el portapapeles operativo, y esa es una de las cosas que arregla.

Qué más puedes poner

clave qué
hostname, timezone, locale, keyboard las aburridas, aplicadas por SSH
packages una lista, instalada con el gestor de paquetes del sistema invitado
run comandos de shell, en orden, como root
files rutas y contenidos, escritos dentro del sistema invitado

Y tres opciones que conviene conocer:
--keep-media deja la ISO en la biblioteca, para que la siguiente construcción de la misma versión no vuelva a descargar 3 GB
--no-promote se detiene cuando la máquina está construida y configurada, y la deja como escritorio
--no-viewer no abre ningún visor; abres tú la máquina

Desatendida, a mano

isard build cubre el caso con el que te vas a encontrar de verdad.

Por debajo hay un camino de más bajo nivel que conviene saber que existe, porque es como una instalación pasa a ser totalmente desatendida, sin nadie delante del visor.

Tanto el instalador de Ubuntu como el de Fedora leen la configuración de un segundo CD, y lo encuentran por su etiqueta de volumen:

etiqueta fichero lo lee
isard seed cidata CIDATA user-data cloud-init: autoinstall de Ubuntu
isard seed oemdrv OEMDRV ks.cfg Anaconda: Fedora, RHEL, Rocky

Ninguno de los dos necesita un argumento en la línea de comandos del kernel, y esa es la gracia: el formulario de hardware de Isard no tiene dónde ponerlo.

Así que construyes la pequeña ISO en local:

$ isard seed oemdrv --kickstart my-ks.cfg -o seed.iso
Wrote OEMDRV seed → seed.iso
Anaconda auto-loads ks.cfg from any volume labelled OEMDRV — no
kernel command-line tweak needed. Host the ISO, register via
`isard media add`, and attach alongside the Fedora installer ISO.

La publicas en algún sitio por HTTPS y pasas la URL:

$ isard template create --seed-url https://files.example.com/seed.iso

El instalador arranca, encuentra el segundo CD, lo lee e instala sin preguntar nada.

Ejercicios

EjercicioLee la biblioteca

Lista tus medios y di, para cada uno, si es tuyo o de tu centro.

Mostrar la solución
$ isard media

-- Media --
NAME                             STATUS      SIZE   OWNER
Fedora-Server-netinst-x86_64-44  Downloaded  1049M  you
ubuntu-24.04.4-live-server       Downloaded  3052M  shared

La columna OWNER es la respuesta, y importa por dos motivos: un medio compartido no te gasta cuota, y no lo puedes borrar.

EjercicioUn perfil que falla barato

Escribe un perfil de construcción para una plantilla Fedora Server con git y htop, y compruébalo con --dry-run sin construir nada.

Después rompe una clave a propósito y vuelve a comprobarlo.

Mostrar la solución
# fedora.yaml
image:
  distro: fedora
  variant: server
  release: latest

template:
  name: fedora-class
  vcpus: 2
  memory_gb: 4
  disk_gb: 50

user:
  name: isard
  password_env: ISARD_TEMPLATE_PASSWORD

packages: [git, htop]

$ isard build fedora.yaml --dry-run
✓ Fedora 44 Server (Net Install)

Template : fedora-class
Image    : Fedora 44 Server (Net Install)
URL      : https://download.fedoraproject.org/pub/fedora/linux/releases/44/Server/x86_64/iso/Fedora-Server-netinst-x86_64-44-1.7.iso
Hardware : 2 vCPU, 4 GB RAM, 50 GB disk
User     : isard
Install  : by hand in the viewer (user, password, SSH server)
Provision: hostname/locale/timezone, 2 package(s), 0 file(s), 0 command(s) over SSH

$ isard build fedora.yaml --dry-run   # after renaming `packages` to `packge`
error: fedora.yaml: unknown key in `profile`: packge
Allowed: files, hostname, image, keyboard, locale, packages, run, template, timezone, user

La segunda ejecución es el ejercicio. Un perfil que está mal tiene que decirlo en dos segundos, no en veinte minutos.

EjercicioTres pasos a mano

Sin usar isard build, convierte un escritorio en plantilla.

Usa una máquina con la que ya hayas terminado.

Mostrar la solución
$ isard stop lab --wait
✓ Resolved desktop: lab (state: Started)
✓ lab → Stopping
✓ lab is now Stopped

$ isard template promote lab --name lab-base -d 'Class base image'
✓ Resolved desktop: lab

✓ Template 'lab-base' created.
  Template ID : 0e7d3b52-...
  Source      : lab (6a19c4f0-...)
  Enabled     : yes

$ isard template --filter lab

-- Available Templates (filtered by 'lab') --
NAME      DESCRIPTION       OS
lab-base  Class base image  ubuntu

Y ahora mira qué dice isard list de lab:

$ isard list --name lab
No desktops found.

El escritorio ya no está. Lo ha consumido la promoción, y ese es el comportamiento que tienes que recordar de esta página.

EjercicioPor qué no compartir el disco sin más

Un compañero quiere la máquina que has construido. Podrías promoverla a plantilla, o podrías darle tus credenciales para que use la tuya.

Da dos motivos por los que la plantilla es la respuesta correcta.

Mostrar la solución

Dos cualesquiera de estos:

  • Una plantilla es una copia. Diez personas tienen cada una su propia máquina y pueden romperla. Una máquina compartida es una persona trabajando y nueve mirando.
  • Gasta cuota una vez por persona, no una sola vez. Una máquina compartida ocupa tu cuota para toda la clase.
  • Es reproducible. Una máquina que has configurado a mano durante tres semanas no se puede reconstruir; una plantilla se puede volver a hacer a partir de un perfil.
  • Nadie tiene que fiarse de nadie. Compartir unas credenciales es compartir una contraseña, y la cuenta es la tuya.

La última vale mucho más allá de esta página, y la tercera es el motivo por el que existe isard build.

Proyecto

Construye la máquina que tu clase va a usar de verdad.

  1. Escribe un perfil de construcción para un servidor Ubuntu LTS con las herramientas que necesita tu curso, por ejemplo git, curl, docker.io y python3.
  2. Añade un paso run: que añada el usuario al grupo docker, y una entrada files: que escriba un /etc/motd con el nombre de la plantilla y la fecha.
  3. Compruébalo con --dry-run hasta que no dé ningún error.
  4. Constrúyelo con --keep-media, para que una segunda construcción no vuelva a descargar la ISO.
  5. Crea un escritorio a partir de la plantilla terminada y demuestra que docker run hello-world funciona sin sudo.
Mostrar la solución
# class.yaml
image:
  distro: ubuntu
  variant: server
  release: lts

template:
  name: class-base
  description: Ubuntu LTS with docker and python
  vcpus: 4
  memory_gb: 8
  disk_gb: 100

user:
  name: isard
  password_env: ISARD_TEMPLATE_PASSWORD
  ssh_key: ~/.ssh/id_ed25519.pub

hostname: class-base
timezone: Europe/Madrid

packages: [git, curl, docker.io, python3]
run:
  - systemctl enable --now docker
  - usermod -aG docker isard
files:
  /etc/motd: |
    class-base — Ubuntu LTS, docker + python
    Built 2026-08-14 with `isard build`.

$ export ISARD_TEMPLATE_PASSWORD='una-contrasenya-llarga'
$ isard build class.yaml --dry-run
$ isard build class.yaml --keep-media

Después:

$ isard create demo --template class-base --yes
$ isard start demo --wait
$ isard ssh demo -- 'docker run --rm hello-world'
Hello from Docker!

docker run sin sudo es lo que demuestra que el usermod se ha ejecutado, y conviene comprobarlo en lugar de darlo por hecho: un cambio de grupo solo tiene efecto en un nuevo inicio de sesión, y este es un nuevo inicio de sesión.