build-xoa-hl
Packer-Pipeline, die die XOA-hl-VM-Appliance auf XCP-ng erstellt und das von XO Lite CE bereitgestellte XVA-Image erzeugt.
Repository: Vagrantin/build-xoa-hl · Sprache: Bash / Packer JSON / Kickstart · Lizenz: AGPL-3.0
Zweck
Dieses Repository erstellt die XOA HomeLab Edition VM-Appliance: eine AlmaLinux-9-VM, die Packer auf einem echten XCP-ng-Host installiert und mit dem xoa-hl-RPM ausstattet. Das Ergebnis ist ein komprimiertes XVA-Image, das die Bereitstellungsschaltfläche von XO Lite CE importiert.
Beim Build ist die Appliance generisch: Sie enthält zwei einmalige Dienste für den ersten Start. Diese lesen Bereitstellungsdaten (Netzwerk, Administratorzugangsdaten) aus XenStore, wenn XO Lite sie bereitstellt. So funktioniert ein einziges Image für alle Benutzer.
Repository-Struktur
build-xoa-hl/
├── build.config.sample ← infrastructure config template (copy → build.config)
├── scripts/
│ ├── setup-xoa-builder.sh ← build entry point: generates Kickstart + Packer JSON, runs build
│ ├── xoa-first-boot.sh ← in-VM phase 1: XenStore → network + env file
│ └── xoa-credentials.sh ← in-VM phase 2: sets XO admin credentials via xo-cli
├── systemd/
│ ├── xoa-first-boot.service
│ └── xoa-credentials.service
├── bin/ ← vendored VMware VDDK tarball (V2V support)
└── artefact/ ← build/debug artefacts: logs, installed-RPM list, memoVoraussetzungen
- Ein Linux-Buildrechner mit
aptund sudo (entwickelt unter Linux Mint). Das Einrichtungsskript installiert seine Abhängigkeiten selbst: Packer (HashiCorp-apt-Repository), das Packer-Pluginddelnano/xenserver,wget,curl,jq,ufw. - Ein erreichbarer XCP-ng-Host mit root-Zugangsdaten, einem SR namens
Local storageund einem benannten VM-Netzwerk. - Eine veröffentlichte
xoa-hl-Version auf GitHub (das RPM der neuesten Veröffentlichung wird automatisch ermittelt). - Eine ausgefüllte
build.config, kopiert ausbuild.config.sample: IP/Zugangsdaten des XCP-ng-Hosts, Netzwerkname, VM-Name und root-Passwort, AlmaLinux-ISO-URL und RPM-URLs fürxe-guest-utilities.
build.config enthält Zugangsdaten im Klartext (XCP-ng-root-Passwort, VM-root-Passwort). Committen Sie sie niemals; nur build.config.sample gehört in git.Build-Einstiegspunkt scripts/setup-xoa-builder.sh
Läuft auf dem Buildrechner und erzeugt alles, was Packer benötigt:
build.configladen (ohne Datei werden integrierte Standardwerte verwendet).- Voraussetzungen installieren: apt-Pakete, HashiCorp Packer und das Packer-Plugin
ddelnano/xenserver. - Ports 8000–9000/tcp öffnen (ufw). Packer stellt die Kickstart-Datei über seinen integrierten HTTP-Server auf einem Port dieses Bereichs für die VM bereit.
- AlmaLinux-ISO-Prüfsumme ermitteln: Liest die
CHECKSUM-Datei des Mirrors im BSD-Format, mit Fallback aufSHA256SUMSim GNU-Format; bricht den Build ab, wenn keine gültige SHA256-Prüfsumme gefunden wird (außer sie ist inbuild.configfestgelegt). - Neueste xoa-hl-RPM-URL ermitteln: Durchsucht
api.github.com/repos/Vagrantin/xoa-hl/releasesnach der neuesten Veröffentlichung mit.rpm-Artefakt. Verwendet nichtreleases/latest: Dies kann noch auf einerxoa-image-*-Veröffentlichung von vor #22 landen, die nur ein XVA enthält. inst.kserzeugen, die Kickstart-Antwortdatei: DHCP aufeth0, EXT4-Partitionierung (kein LVM), SELinux und Firewall deaktiviert, minimaler Paketsatz;%postaktiviert sshd/chrony, installiertepel-release,wget,nc,vimund erstellt den Benutzerxo(inwheel).almalinux-build.jsonerzeugen, die Packer-Vorlage (siehe unten).- Build ausführen:
packer validate, danachPACKER_LOG=1 packer build almalinux-build.json.
Packer-Vorlage almalinux-build.json
Ein einzelner Builder vom Typ xenserver-iso: Packer lädt das AlmaLinux-ISO auf den XCP-ng-Host, startet eine VM (2 GB RAM, 10-GB-Datenträger) mit inst.ks=http://{{ .HTTPIP }}:{{ .HTTPPort }}/inst.ks in der Kernel-Befehlszeile, wartet auf SSH und führt anschließend die Provisioner aus:
dnf update -y.- xe-guest-utilities und xe-guest-utilities-xenstore installieren (RPM-URLs aus
build.config), erforderlich für XenStore-Zugriff beim ersten Start. - Node.js 24 installieren (NodeSource).
- Das xoa-hl-RPM installieren; es bringt den gesamten XOA-hl-Stack mit (siehe
xoa-hl: Das RPM enthält das fertig gebaute Xen Orchestra unter/opt/xo; sein%postaktiviertredisundxo-server). xoa-first-boot.sh/xoa-credentials.shnach/root/und die beiden systemd-Units nach/etc/systemd/system/hochladen, anschließend beide Units aktivieren.- Image verkleinern: WLAN-Firmware, firewalld, sssd, NetworkManager-Zusätze, rsyslog, docs/man/info-Seiten und nicht englische Gebietsschemata entfernen;
dnf autoremoveundclean all. - Identität entfernen:
/etc/machine-idleeren, damit jede bereitgestellte VM eine eigene ID erzeugt.
Wichtige Builder-Einstellungen: format: xva_compressed (XVA-Ausgabe), keep_vm: never (die gebaute VM wird vom XCP-ng-Host gelöscht) und vm_name (XOA-hl), das Packer als name-label der VM im XVA hinterlegt. Dieses Label zeigt XO Lite nach der Bereitstellung an; es bestimmt auch den Namen der Ausgabedatei <vm_name>.xva.
Automatische Konfiguration beim ersten Start
Zwei einmalige Dienste sind im Image enthalten. XO Lite schreibt die Bereitstellungsdaten beim Bereitstellen der Appliance in XenStore (/local/domain/<domid>/vm-data/*).
Phase 1: xoa-first-boot.service
Läuft vor dem Netzwerkstart (Before=network.target, gesteuert durch ConditionPathExists=!/var/lib/xoa-first-boot.done). Das Skript:
- liest die
vm-data-Schlüssel mitxenstore-read:ip,netmask,gateway,dns,ntp-servers,system-account-xoa-passwordund den JSON-Blockadmin-account(E-Mail und Passwort); - speichert sie in
/etc/xoa-first-boot.env(Modus 600); - schreibt eine NetworkManager-Schlüsseldatei (
/etc/NetworkManager/system-connections/xoa-provisioned.nmconnection), mit statischer IP, falls angegeben, andernfalls DHCP; - protokolliert ausführlich nach
/var/log/xoa-first-boot.logfür die Diagnose vor Ort.
Phase 2: xoa-credentials.service
Läuft einmal nach network-online.target und xo-server.service, gesteuert durch !/var/lib/xoa-credentials.done. Das Skript:
- wartet bis zu 3 Minuten auf xo-server an Port 443;
- setzt das SSH-Passwort des Systembenutzers
xoauf den vorgegebenen Wert; - registriert
xo-climit den initialen Zugangsdaten anwss://127.0.0.1, ruft dannuser.changePasswordunduser.setauf, um die vorgegebenen Administrator-E-Mail und das Passwort anzuwenden; - entfernt sich selbst beim Beenden (trap): schreibt die Abschlussmarkierung, deaktiviert und entfernt beide Units und Skripte und löscht die Umgebungsdatei mit den Geheimnissen.
admin@admin.net / admin. Ändern Sie diese nach der Bereitstellung über die XO-Weboberfläche.Ausgaben
- Das komprimierte XVA-Image in
output-xva/im Buildverzeichnis auf dem Buildrechner. - Die gebaute VM selbst, auf dem XCP-ng-Host behalten (
keep_vm: always). - In der automatisierten Pipeline eine GitHub-Veröffentlichung in diesem Repository (
Vagrantin/build-xoa-hl) mit Tagxoa-image-<date>-<sha7>und ArtefaktXOA-hl.xva, das die Bereitstellungsschaltfläche von XO Lite ermittelt.
Automatisierte Builds: der Orchestrator
In der täglichen Pipeline wird setup-xoa-builder.sh durch die Crate xoa-vm-agent aus buildorchestration ersetzt. Sie führt dieselben Schritte programmatisch aus und zusätzlich:
- Überspringt den Build, wenn HEAD des Repositorys bereits dem zuletzt gebauten SHA entspricht.
- Startet zuerst den Workflow
build-xoa.ymlinVagrantin/xoa-hlüberworkflow_dispatchund wartet auf die RPM-Veröffentlichung. - Führt
packer validateundpacker buildmit erzeugten Dateieninst.ks/almalinux-build.jsonaus. - Veröffentlicht das XVA als GitHub-Release mit Tag
xoa-image-<date>-<sha7>aufVagrantin/build-xoa-hl, also diesem Repository (<sha7>ist derxoa-hl-Commit, aus dem das Image gebaut wurde. Dieser Commit liegt im anderen Repository, deshalb wird das Tag aufmainerstellt und der Quellcommit im Release-Text erfasst). Image-Veröffentlichungen werden in der Versionsmatrix dokumentiert.
Vagrantin/xoa-hl veröffentlicht. Diese Veröffentlichungen bleiben dort, damit bereits ausgelieferte ISOs sie weiter auflösen können. Deshalb müssen Werkzeuge, die xoa-hl nach RPMs durchsuchen, weiterhin Tags mit xoa-image-* überspringen.Mitarbeit
Um ein Problem zu melden oder eine Änderung vorzuschlagen, erstellen Sie ein Issue unter Vagrantin/xcp-hl.