CLI

Introducció

Tot el que hi ha a Escriptori funciona.

També són onze clics, i els faràs cada dia.

isard és una ordre que fa el mateix des del terminal:

$ isard create dev --template ubuntu
$ isard start dev --wait
$ isard ssh dev

Tres línies, i la tercera et deixa en un intèrpret d'ordres d'una màquina que no existia quan vas començar a escriure.

És un programa en Python que parla amb la mateixa API amb què parla el web de la Generalitat.

No hi ha una segona plataforma ni cap accés privilegiat: tot el que pot fer isard ho podries fer amb clics, i tot el que no pot fer encara l'has de fer amb clics.

Entorn de treball

isard està publicat a PyPI, així que instal·la'l com a eina global amb Tool:

$ uv tool install isard
Resolved 24 packages in 412ms
Installed 24 packages in 63ms
Installed 1 executable: isard

Comprova que hi és:

$ isard version
isard 0.3.0

Necessita Python 3.11 o més nou.

No cal que l'aconsegueixis tu: si el del sistema és més antic, uv baixa un Python adequat per a l'eina, i aquest és bona part del motiu per instal·lar-la així.

Per actualitzar-la més endavant:

$ uv tool upgrade isard

Iniciar la sessió

Totes les ordres necessiten el teu compte de la Generalitat, el mateix que vas escriure al navegador a la pàgina anterior.

Executa'n una i mira:

$ isard list
Gencat username (@edu.gencat.cat is added for you): 12345678a
Password:

Funciona, i dimecres ja n'estaràs tip.

Posa les credencials a l'entorn:

$ export GENCAT_USERNAME="12345678a"
$ export GENCAT_PASSWORD="la-teva-contrasenya"

El sufix @edu.gencat.cat s'afegeix sol, així que el nom d'usuari és la forma curta: el teu DNI, lletra inclosa.

Les variables d'entorn moren amb el terminal, així que el que de debò vols és un fitxer .env al directori on treballes:

GENCAT_USERNAME=12345678a
GENCAT_PASSWORD=la-teva-contrasenya

isard el llegeix del directori actual cada vegada que s'executa.

On viu la sessió

Iniciar la sessió com cal és lent: és un ball SAML a través del proveïdor d'identitat de la Generalitat, amb unes quantes redireccions, i triga un parell de segons.

Fer-ho a cada ordre seria insuportable, així que isard ho fa una vegada i desa el resultat a la memòria cau:

Tots dos s'escriuen amb chmod 600: els pots llegir tu i ningú més.

A Windows són a %APPDATA%\isard\.

La sessió es comprova a si mateixa abans de cada crida i es renova quan ha caducat, així que no t'has de preocupar mai d'això.

isard login força un inici de sessió nou i mostra què ha obtingut:

$ isard login
Authenticating with Gencat...
Gencat session cached at /Users/david/.config/isard/session.json
Authenticating with IsardVDI...
IsardVDI session cached at /Users/david/.config/isard/isardvdi.json

-- Gencat Session --
Username       : 12345678a@edu.gencat.cat
Display name   : David de Mingo
Email          : david@optersoft.com
Organization   : Institut
Session ID     : 8f2a1c4e-...
Expires at     : 2026-08-14 19:42:11 UTC
Expires in     : 07:58:22
Gencat valid   : Yes
IsardVDI valid : Yes

I isard logout les llença totes dues:

$ isard logout
Logged out successfully

Aquesta és l'ordre que has de fer servir en una màquina compartida, i la que has de provar quan alguna cosa es comporta com si fossis una altra persona.

Què tinc

isard list és la vista d'Escriptoris, en text:

$ isard list
NAME   STATE    IP               OS
box-1  Started  10.2.76.37       Ubuntu 24.04
box-2  Stopped  -                Ubuntu 24.04
dev    Started  192.168.122.214  Fedora 44

Quatre columnes, ordenades per nom.

Un - a la columna IP vol dir que la màquina està aturada, o que està en marxa i no ha informat de cap adreça: el cas de la pàgina anterior.

Afegeix --hardware i anirà a preguntar de què està feta cadascuna:

$ isard list --hardware
NAME   STATE    IP               OS            CPU     MEMORY
box-1  Started  10.2.76.37       Ubuntu 24.04  2 vCPU  4096 MB
box-2  Stopped  -                Ubuntu 24.04  2 vCPU  4096 MB
dev    Started  192.168.122.214  Fedora 44     4 vCPU  8192 MB

Són dues columnes més i una crida a l'API per plantilla, així que és una mica més lent.

També és l'ordre que respon per què m'he quedat sense quota.

Quines plantilles hi ha

Abans de crear res has de saber a partir de què ho crees:

$ isard template

-- Available Templates --
NAME                     DESCRIPTION                     OS
fedora-server-44         Fedora Server, netinst          Fedora
ubuntu-24-04-desktop     Ubuntu 24.04 Desktop            Ubuntu
ubuntu-24-04-server      Ubuntu 24.04 Server             Ubuntu
windows-11-t3            Windows 11                      Windows

La llista del teu centre és més llarga i la major part no és el que busques, així que filtra-la:

$ isard template --filter ubuntu

-- Available Templates (filtered by 'ubuntu') --
NAME                  DESCRIPTION           OS
ubuntu-24-04-desktop  Ubuntu 24.04 Desktop  Ubuntu
ubuntu-24-04-server   Ubuntu 24.04 Server   Ubuntu

--filter és una simple cerca de subcadena al nom, sense distingir majúscules i minúscules.

--hardware també funciona aquí, i val la pena mirar-ho: et diu com de gran és la màquina que fa cada plantilla abans que en facis cap.

$ isard template --filter ubuntu --hardware

-- Available Templates (filtered by 'ubuntu') --
NAME                  DESCRIPTION           OS      CPU     MEMORY   DISK
ubuntu-24-04-desktop  Ubuntu 24.04 Desktop  Ubuntu  2 vCPU  4096 MB  40 GB
ubuntu-24-04-server   Ubuntu 24.04 Server   Ubuntu  2 vCPU  4096 MB  40 GB

Les plantilles que el teu centre ha desactivat no hi apareixen.

Si en falta una que t'han dit que hi hauria de ser, aquest és el motiu, i és una incidència per a l'Àtom, no un error de l'eina.

Crear un escriptori

$ isard create dev --template ubuntu-24-04-server
Matched template: 'ubuntu-24-04-server'
✓ Desktop 'dev' created successfully!

Dues vCPU, 4 GB de RAM, i les interfícies Default i Wireguard: la mateixa forma que els valors per defecte del formulari, excepte que la de Wireguard sempre hi és.

Això últim és deliberat, i és el motiu pel qual l'eina és agradable de fer servir: la interfície que t'oblides de marcar és la interfície que necessites quaranta minuts després, i afegir-la més tard costa un reinici.

Si no poses --template, et dona la llista perquè triïs:

$ isard create dev
Select a template:
  1. fedora-server-44 [Fedora]
  2. ubuntu-24-04-desktop [Ubuntu]
  3. ubuntu-24-04-server [Ubuntu]
  4. windows-11-t3 [Windows]
Select (1-4): 3

Això va bé a mà i no serveix de res en un script, així que --filter filtra aquesta llista de la mateixa manera que filtra template.

No cal que escriguis bé el nom

Torna a mirar això:

$ isard create dev --template ubuntu-24-04-server

Ningú no escriu això dues vegades.

Per això isard no t'ho demana. Prova:

$ isard create dev --template ubuntu

Hi ha dues plantilles amb ubuntu al nom, així que pregunta:

$ isard create dev --template ubuntu
Select a template:
  1. ubuntu-24-04-desktop [Ubuntu]
  2. ubuntu-24-04-server [Ubuntu]
Select (1-2): 2

Ara prova un nom que no sigui ambigu:

$ isard create dev --template fedora
Matched template: 'fedora-server-44'
✓ Desktop 'dev' created successfully!

Un sol candidat, així que diu quin ha triat i continua.

I ara escriu-lo malament a posta:

$ isard start bx-1
Matched: 'box-1'

La regla de sota té tres passos, en ordre:

1. una coincidència exacta, sense distingir majúscules i minúscules: s'agafa en silenci, perquè és el que volies dir;
2. si no n'hi ha, tots els noms que són prou semblants (Jaro-Winkler ≥ 0.5) o que contenen el que has escrit;
3. aquesta llista, ordenada per proximitat.

Si en queda un, es fa servir, amb una línia Matched: perquè vegis què ha passat. Si en queden dos o més, s'obre el selector. Si no en queda cap, és un error que llista tots els escriptoris que tens, i normalment n'hi ha prou per veure l'errada tu mateix.

Un tros curt és un nom vàlid. isard start box troba box-1 si és l'únic.

Arrencar i aturar

$ isard start dev
✓ Desktop 'dev' starting

L'ordre torna immediatament, perquè arrencar una màquina triga una estona i no hi ha cap motiu per segrestar-te el terminal.

Que és just el contrari del que vols quan el següent que fas és connectar-t'hi:

$ isard start dev
$ isard ssh dev
Error: connection refused

La màquina encara no estava en marxa.

--wait ho arregla: l'ordre no torna fins que l'escriptori està en marxa:

$ isard start dev --wait
⠹ Waiting for 'dev' to start...
✓ Desktop 'dev' is running

--wait és el que fa que l'eina es pugui fer servir en scripts. Sense ell, cada línia després de start és una cursa.

La paciència per defecte és de 120 segons. Una màquina gran, o una tarda atrafegada, en demana més:

$ isard start dev --wait --timeout 300

Aturar té la mateixa forma:

$ isard stop dev --wait
⠹ Waiting for 'dev' to stop...
✓ Desktop 'dev' is stopped

$ time isard start box-1
✓ Desktop 'box-1' starting

real	0m1.9s

$ isard stop box-1 --wait
$ time isard start box-1 --wait
✓ Desktop 'box-1' is running

real	0m24.3s

Reservar

Alguns escriptoris no es poden arrencar quan vulguis: el cas habitual és un amb GPU.

$ isard start gpu-box
Error: this desktop needs a booking before it can start.

No és una fallada, és una cua. --book reserva la franja i després arrenca:

$ isard start gpu-box --book --wait
✓ Booked 60 minutes
✓ Desktop 'gpu-box' is running

--book-minutes canvia l'hora. Això és GPU.

Esborrar

$ isard delete dev
Delete desktop 'dev'? [y/N]:

La resposta per defecte és no, que és la correcta per a qualsevol cosa que porti un delete.

Respon y i l'escriptori va a la paperera, d'on encara es pot recuperar.

Dues opcions ho canvien, i van juntes:

$ isard delete dev --permanent --yes
✓ Desktop 'dev' deleted permanently

--permanent se salta la paperera. --yes se salta la pregunta.

Totes dues són bones en un script i dolentes a mà. Un script que s'atura a preguntar és un script que es penja; una persona a qui no es pregunta és una persona que esborra la feina de la setmana passada.

Obrir-lo

isard view obre la pantalla de l'escriptori:

$ isard view dev
Matched: 'dev'
✓ Desktop is running
Launching remote-viewer...

Fa per tu tot el ball del .vv de la pàgina anterior (baixa el fitxer SPICE, descodifica el certificat, obre remote-viewer) i, si l'escriptori estava aturat, primer l'arrenca i espera.

Si remote-viewer no està instal·lat, l'instal·la:

--no-install ho desactiva, que és el que vols si t'estimes més fer-ho tu.

Arribar-hi

isard ssh et posa en un shell a la màquina:

$ isard ssh dev
isard@dev:~$

Darrere d'aquesta sola línia passen moltes coses (una clau que s'ha de registrar, un bastió al port 443, un escriptori que s'arrenca si estava aturat) i és tot el contingut de Bastió.

El que importa aquí és l'altra forma.

Amb una ordre després de --, isard ssh no és interactiu:

$ isard ssh dev -- uname -a
Linux dev 6.8.0-51-generic #52-Ubuntu SMP x86_64 GNU/Linux

Aquesta és la línia que fa que tota l'eina valgui la pena.

La sortida de l'ordre és la sortida de l'ordre, el seu codi de sortida és el seu codi de sortida, i tot el que escriu isard mateix va a stderr, així que una canonada no ha de filtrar mai línies d'indicador d'activitat de les teves dades:

$ isard ssh dev -- 'cat /etc/os-release' | grep VERSION_ID
VERSION_ID="24.04"

Hi pots fer passar un directori sencer:

$ tar czf - src | isard ssh dev -- 'tar xzf - -C /home/isard'

Tota una classe en un bucle

Ajunta les peces i el sentit d'una ordre davant d'un formulari es fa evident:

$ for n in 1 2 3; do
>   isard create box-$n --template ubuntu-24-04-server
>   isard start box-$n --wait
> done
✓ Desktop 'box-1' created successfully!
✓ Desktop 'box-1' is running
✓ Desktop 'box-2' created successfully!
✓ Desktop 'box-2' is running
✓ Desktop 'box-3' created successfully!
✓ Desktop 'box-3' is running

Tres màquines, una línia, cap clic.

Desmuntar-les és el mateix bucle al revés:

$ for n in 1 2 3; do isard delete box-$n --yes; done

I executar la mateixa ordre a totes és un altre:

$ for n in 1 2 3; do
>   echo "== box-$n"
>   isard ssh box-$n -- 'uptime'
> done
== box-1
 11:42:03 up 2 min,  0 users,  load average: 0.08, 0.03, 0.01
== box-2
 11:42:09 up 2 min,  0 users,  load average: 0.11, 0.04, 0.01
== box-3
 11:42:14 up 1 min,  0 users,  load average: 0.15, 0.05, 0.01

La llista completa d'ordres

--help la mostra, i val la pena llegir-la una vegada:

$ isard --help

 Usage: isard [OPTIONS] COMMAND [ARGS]...

 Manage IsardVDI virtual desktops on the Gencat educational platform.

╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ login     Log in to Gencat (SAML) and IsardVDI, then show the session        │
│           summary.                                                           │
│ logout    Clear cached authentication sessions and per-desktop SSH           │
│           confirmations.                                                     │
│ version   Show the version of the isard CLI tool.                            │
│ list      List IsardVDI desktops for the authenticated user.                 │
│ build     Build a template from a YAML profile: install, configure, promote. │
│ create    Create a new desktop from an existing template.                    │
│ start     Start a stopped desktop.                                           │
│ stop      Stop a running desktop.                                            │
│ hardware  Show a desktop's vCPU and memory, or change them on a stopped      │
│           desktop.                                                           │
│ delete    Delete a desktop — move it to the recycle bin, or erase it         │
│           permanently.                                                       │
│ view      Open a desktop in remote-viewer over SPICE.                        │
│ ssh       Open an SSH session to a desktop via the IsardVDI bastion.         │
│ template  List available templates, or create one from media.                │
│ media     List, add, or delete media (the ISO library).                      │
│ seed      Build a local cloud-init / kickstart seed ISO.                     │
│ vpn       Join the desktop network over IsardVDI's WireGuard VPN.            │
╰──────────────────────────────────────────────────────────────────────────────╯

Cada subordre també accepta --help, i aquesta és la resposta a quines opcions tenia start.

hardware és nova: llegeix la vCPU i la memòria d'un escriptori i, en un d'aturat, pot canviar la mida de totes dues.

Quatre d'aquestes tenen una pàgina pròpia:

• vpn → Xarxa
• ssh → Bastió
• template, build, media, seed → Plantilles

També és una biblioteca

isard és un paquet de Python, i tot el que fa l'ordre es pot importar:

from isard import get_desktops, login_to_isardvdi

session = login_to_isardvdi("12345678a@edu.gencat.cat", "la-teva-contrasenya")

for desktop in get_desktops(session):
    print(desktop.name, desktop.state)

box-1 Started
box-2 Stopped
dev Started

No ho necessitaràs gaire sovint: un bucle de shell cobreix la major part del que vol un script.

Val la pena saber que existeix per al dia que vulguis revisar trenta màquines i informar de quines encara estan en marxa, perquè això és un programa, no un bucle.

Exercicis

$ isard template --filter fedora

-- Available Templates (filtered by 'fedora') --
NAME              DESCRIPTION             OS
fedora-server-44  Fedora Server, netinst  Fedora

$ isard create lab --template fedora
Matched template: 'fedora-server-44'
✓ Desktop 'lab' created successfully!

$ isard start lab --wait
✓ Desktop 'lab' is running

$ isard ssh lab
[isard@lab ~]$

$ isard list | awk '$2 == "Started" { print $1 }'
box-1
dev

$ isard stop box
Select a desktop:
  1. box-1 (Started)
  2. box-2 (Started)
  3. box-3 (Started)
Select (1-3):

$ isard list | awk 'NR > 1 && $2 == "Started" { print $1 }' | while read n; do
>   isard stop "$n" --wait
> done
✓ Desktop 'box-1' is stopped
✓ Desktop 'dev' is stopped

$ ls -l ~/.config/isard/
total 24
-rw-------  1 david  staff  1204 14 Aug 11:31 isardvdi.json
-rw-------  1 david  staff  2841 14 Aug 11:31 session.json

$ isard logout
Logged out successfully

$ ls -l ~/.config/isard/
total 0

Projecte

Prepara un directori de treball on puguis tornar durant la resta del curs.

1. Crea un directori, isard/, amb un .env que contingui les teves credencials i un .gitignore que contingui .env.
2. Escriu un script de shell up.sh que creï i arrenqui tres màquines Ubuntu Server, de box-1 a box-3, esperant cadascuna.
3. Escriu down.sh, que les aturi i esborri totes tres sense preguntar.
4. Fes-los executables tots dos i executa'ls.

# up.sh
#!/bin/sh
set -e

for n in 1 2 3; do
    isard create "box-$n" --template ubuntu-24-04-server
    isard start "box-$n" --wait --timeout 300
done

isard list

# down.sh
#!/bin/sh

for n in 1 2 3; do
    isard delete "box-$n" --yes
done

$ chmod +x up.sh down.sh
$ ./up.sh
✓ Desktop 'box-1' created successfully!
✓ Desktop 'box-1' is running
...