Test-Workflows

Diese Anleitung fasst die plattformspezifischen Test-Workflows zusammen, die früher in der Haupt-README.md standen. Nutzen Sie die plattformübergreifende Matrix im Root-README für einen schnellen Überblick über die unterstützten Plattformen. Die konkreten Befehle finden Sie in den folgenden Abschnitten.

Einheitlicher VM-Workflow

Die meisten VM-gestützten Testabläufe folgen vom Repository-Root aus demselben Lebenszyklus:

sailwright build <osname> [--type <type>] [--arch <arch>]
sailwright create <osname> [--type <type>] [--arch <arch>]
sailwright start <osname> [--type <type>] [--arch <arch>]
sailwright provision <osname> [--type <type>] [--arch <arch>] --check
sailwright provision <osname> [--type <type>] [--arch <arch>]
sailwright stop <osname> [--type <type>] [--arch <arch>]
sailwright destroy <osname> [--type <type>] [--arch <arch>]

• build erstellt oder aktualisiert das wiederverwendbare VM-Artefakt.
• create erstellt das verwaltete VM-Ziel aus diesem Artefakt.
• start startet eine bereits erstellte VM, wenn sie gestoppt ist.
• provision führt den Ansible-Workflow gegen das laufende Ziel aus.
• stop fährt die VM herunter, ohne sie zu löschen.
• destroy entfernt das verwaltete VM-Ziel.

Je nach Backend startet die VM bereits während create zum ersten Mal, oder es ist noch ein kleiner hostspezifischer Schritt nötig. Sobald eine VM erstellt wurde, verwenden Sie start, um sie erneut zu booten.

Verwenden Sie die list-Subcommands, um zu sehen, was Ihr aktueller Host unterstützt:

sailwright build list
sailwright create list
sailwright start list
sailwright provision list
sailwright stop list
sailwright destroy list

Verwenden Sie --help beim Root-Befehl oder einem beliebigen Subcommand, um unterstützte Flags und Nutzungsdetails einzusehen:

sailwright --help
sailwright create --help
sailwright start --help
sailwright provision --help

OCI-Build-Artefakt-Registry-Workflow

Fertige Build-Artefakte können in eine OCI-Registry gepusht und aus ihr gepullt werden. Die Befehle verwenden dasselbe Zielvokabular wie der VM-Workflow sowie ein Docker-ähnliches Referenz-Argument:

sailwright push list
sailwright pull list

sailwright push localhost:5000/sailwright/ubuntu-server-amd64:qemu \
  --plain-http \
  --os ubuntu \
  --type server \
  --arch amd64 \
  --host-os linux

sailwright pull localhost:5000/sailwright/ubuntu-server-amd64:qemu \
  --plain-http \
  --os ubuntu \
  --type server \
  --arch amd64 \
  --host-os linux

Der OCI-Client liest standardmäßig Docker-Anmeldedaten, sodass docker login bei authentifizierten Registries funktioniert. Verwenden Sie --username, --password-stdin oder --access-token, wenn Sie befehlsspezifische Anmeldedaten benötigen.

Der Linux-GitHub-Actions-Build-Workflow veröffentlicht fertige Ubuntu-Artefakte bei Pushes auf main sowie bei manuell von main gestarteten workflow_dispatch-Läufen in der GitHub Container Registry. Artefakte werden unter ghcr.io/<owner>/ubuntu-24 mit Tags nach dem Schema <type>-<arch>-<hostos>-build abgelegt, zum Beispiel:

ghcr.io/csautter/ubuntu-24:server-amd64-linux-build
ghcr.io/csautter/ubuntu-24:desktop-arm64-linux-build

Windows-VM-Build-Artefakte werden absichtlich nicht veröffentlicht.

Fügen Sie bei HTTPS-Registries mit einem internen oder selbstsignierten Zertifikat bevorzugt die Registry-CA mit --ca-file /path/to/ca.pem hinzu. Für kurzlebige Tests gegen eine Registry, der Sie bereits vertrauen, deaktiviert --insecure-skip-tls-verify die TLS-Zertifikatsprüfung.

Verwenden Sie --plain-http für eine lokale zot-Registry. Um den Opt-in-Integrationstest gegen diese Registry auszuführen:

DEV_ALCHEMY_OCI_INTEGRATION_REF=localhost:5000/sailwright/integration:oci \
DEV_ALCHEMY_OCI_INTEGRATION_PLAIN_HTTP=true \
go test ./pkg/oci -run TestOCIRegistryPushPullIntegration -count=1

Das gepushte Artefakt ist ein gewöhnliches OCI-Artefakt und kann daher auch mit ORAS untersucht werden:

oras manifest fetch --plain-http localhost:5000/sailwright/ubuntu-server-amd64:qemu

Systemunabhängiger Docker-Workflow

Lokales Host-Provisioning

Verwenden Sie den gemeinsamen lokalen Wrapper, wenn Sie das Playbook auf die aktuelle Maschine anwenden möchten, statt auf eine verwaltete VM:

sailwright provision local --check
sailwright provision local --proto ssh --check
sailwright provision local --playbook ./playbooks/setup.yml --check
sailwright provision local

Plattform-Standardwerte, die konfigurierte Playbook-Auflösung, erweiterte Flags und das Windows-Cleanup-Verhalten finden Sie unter Lokales Provisioning.

Ubuntu-Rollentests unter Linux, WSL, Windows oder macOS

Verwenden Sie das mitgelieferte Docker-Compose-Setup, um das Ubuntu-fokussierte Ansible-Playbook in einem Container auszuführen:

docker compose -f deployments/docker-compose/ansible/docker-compose.yml up

Räumen Sie anschließend wie folgt auf:

docker compose -f deployments/docker-compose/ansible/docker-compose.yml down

Linux-Host-Workflows

Ubuntu unter Linux mit QEMU/KVM und virt-manager

Installieren Sie zunächst die Host-Abhängigkeiten:

sailwright install

sailwright install installiert die libvirt- und QEMU-Host-Pakete, aber bei einigen Distributionen ist vor dem Start der verwalteten VM noch ein manueller Host-Schritt erforderlich: Aktivieren Sie das default-Netzwerk von libvirt, oder gewähren Sie ACL-/Gruppenzugriff auf das System-libvirt-Image-Verzeichnis, falls der Daemon Gäste als anderer Benutzer ausführt.

Bauen und erstellen Sie die Ubuntu-VM:

arch=amd64 # or arm64
type=desktop # or server
sailwright build ubuntu --arch "$arch" --type "$type"
sailwright create ubuntu --arch "$arch" --type "$type"

Standardmäßig verwendet der Linux-Workflow für create/start/stop/destroy die libvirt-Systemverbindung (qemu:///system), sodass die VM an libvirts Standard-NAT-Netzwerk angebunden wird und im üblichen Fall ausgehenden Internetzugang erhält. Verwaltete QCOW2-Disks liegen standardmäßig unter /var/tmp/dev-alchemy/libvirt/images, wodurch kein vorab angelegtes, root-eigenes Image-Verzeichnis nötig ist. Sailwright erstellt verwaltete Image-Verzeichnisse mit dem Modus 0750; falls Ihr System-libvirt-Daemon Gäste als anderer Benutzer ausführt, gewähren Sie den Zugriff explizit über einen libvirt-Storage-Pool, Gruppenbesitz/ACLs für DEV_ALCHEMY_LIBVIRT_IMAGE_DIR, oder verwenden Sie die Session-Verbindung weiter unten.

Wenn eine VM ein benanntes libvirt-Netzwerk verwendet, prüft Sailwright dieses vorab, bevor die Domain definiert oder gestartet wird. Mit der Standard-System-URI wird dabei Folgendes geprüft:

virsh --connect qemu:///system net-info default

Falls das default-Netzwerk existiert, aber inaktiv ist, aktivieren Sie es mit:

sudo virsh --connect qemu:///system net-start default
sudo virsh --connect qemu:///system net-autostart default

Wenn Sie stattdessen die rootlose libvirt-Benutzer-Session bevorzugen, setzen Sie:

export DEV_ALCHEMY_LIBVIRT_URI=qemu:///session
# Optional when you want a custom storage location for the session connection:
export DEV_ALCHEMY_LIBVIRT_IMAGE_DIR="$HOME/.local/share/dev-alchemy/libvirt/images"

Der eingebaute Session-Pfad verwendet libvirts User-Mode-Networking und benötigt daher nicht das default-NAT-Netzwerk. Wird später ein benanntes Netzwerk für eine Session-URI konfiguriert, wird dieselbe Vorabprüfung gegen qemu:///session ausgeführt.

Wenn Sie stattdessen den traditionellen System-libvirt-Image-Speicherort bevorzugen, setzen Sie:

export DEV_ALCHEMY_LIBVIRT_URI=qemu:///system
export DEV_ALCHEMY_LIBVIRT_IMAGE_DIR=/var/lib/libvirt/images/dev-alchemy

Anschließend können Sie die erstellte VM entweder über virt-manager oder über die CLI booten:

sailwright start ubuntu --arch "$arch" --type "$type"
sailwright provision ubuntu --arch "$arch" --type "$type" --check
sailwright provision ubuntu --arch "$arch" --type "$type"
sailwright stop ubuntu --arch "$arch" --type "$type"
sailwright destroy ubuntu --arch "$arch" --type "$type"

Der Provision-Wrapper ermittelt die libvirt-Gast-IP mit virsh domifaddr und führt ansible-playbook mit einem inline definierten SSH-Inventory-Ziel aus. Optionale Ubuntu-Provisioning-Overrides können in .env oder der Prozessumgebung über LIBVIRT_UBUNTU_ANSIBLE_* gesetzt werden:

LIBVIRT_UBUNTU_ANSIBLE_USER=packer
LIBVIRT_UBUNTU_ANSIBLE_PASSWORD=P@ssw0rd!
LIBVIRT_UBUNTU_ANSIBLE_BECOME_PASSWORD=P@ssw0rd!
# Optional (defaults shown):
LIBVIRT_UBUNTU_ANSIBLE_CONNECTION=ssh
LIBVIRT_UBUNTU_ANSIBLE_SSH_COMMON_ARGS=-o StrictHostKeyChecking=no -o ServerAliveInterval=10 -o ServerAliveCountMax=3 -o ControlMaster=no -o ControlPersist=no
LIBVIRT_UBUNTU_ANSIBLE_SSH_TIMEOUT=120
LIBVIRT_UBUNTU_ANSIBLE_SSH_RETRIES=3

Zugehörige Anleitung:

• Ubuntu Packer README

Windows unter Linux mit QEMU/KVM und virt-manager

Installieren Sie zunächst die Host-Abhängigkeiten:

sailwright install

Bauen und erstellen Sie die Windows-11-VM:

arch=amd64 # or arm64
sailwright build windows11 --arch "$arch" --headless
sailwright create windows11 --arch "$arch"

Anschließend können Sie die erstellte VM entweder über virt-manager oder über die CLI booten:

sailwright start windows11 --arch "$arch"

Der Lebenszyklus verwendet dieselben libvirt-Standardwerte wie Ubuntu unter Linux: qemu:///system sowie verwaltete Disks unter /var/tmp/dev-alchemy/libvirt/images, sofern nicht DEV_ALCHEMY_LIBVIRT_URI oder DEV_ALCHEMY_LIBVIRT_IMAGE_DIR gesetzt ist.

Falls /dev/kvm nicht verfügbar oder unzuverlässig ist, setzen Sie DEV_ALCHEMY_QEMU_FORCE_SOFTWARE_EMULATION=1, um die KVM-Erkennung zu umgehen und die QEMU-TCG-Softwareemulation zu erzwingen.

Setzen Sie die WinRM-Anmeldedaten in der .env im Projekt-Root oder in der Prozessumgebung:

LIBVIRT_WINDOWS_ANSIBLE_USER=Administrator
LIBVIRT_WINDOWS_ANSIBLE_PASSWORD=your-secure-password
# Optional (defaults shown):
LIBVIRT_WINDOWS_ANSIBLE_CONNECTION=winrm
LIBVIRT_WINDOWS_ANSIBLE_WINRM_TRANSPORT=basic
LIBVIRT_WINDOWS_ANSIBLE_PORT=5985

Führen Sie das Provisioning vom Repository-Root aus durch:

sailwright provision windows11 --arch "$arch" --check
sailwright provision windows11 --arch "$arch"
sailwright stop windows11 --arch "$arch"
sailwright destroy windows11 --arch "$arch"

Der Provision-Wrapper ermittelt die libvirt-Gast-IP mit virsh domifaddr und führt ansible-playbook mit einem inline definierten WinRM-Inventory-Ziel aus.

Zugehörige Anleitung:

• Windows Packer README

Windows-Host-Workflows

Ubuntu unter Windows mit Hyper-V

Installieren Sie zunächst die Host-Abhängigkeiten:

sailwright.exe install

Bauen Sie das Ubuntu-Artefakt:

# server
sailwright.exe build ubuntu --type server --arch amd64
# desktop
sailwright.exe build ubuntu --type desktop --arch amd64

Erstellen Sie die VM:

$env:VAGRANT_HYPERV_SWITCH = "Default Switch"
sailwright.exe create ubuntu --type server --arch amd64
# or desktop
sailwright.exe create ubuntu --type desktop --arch amd64

Führen Sie das Provisioning durch:

sailwright.exe provision ubuntu --type server --arch amd64 --check
sailwright.exe provision ubuntu --type server --arch amd64

Der Befehl ermittelt die VM-IP automatisch und führt Ansible über den Windows/Cygwin-Wrapper aus. Optionale Ubuntu-Provisioning-Overrides können in .env über HYPERV_UBUNTU_ANSIBLE_* gesetzt werden.

Zugehörige Anleitungen:

• Ubuntu Packer README
• Ubuntu Hyper-V deployment README

Windows unter Windows mit Docker Desktop

Verwenden Sie Docker Desktop mit aktivierten Windows-Containern:

docker compose -f deployments/docker-compose/ansible-windows/docker-compose.yml up

Räumen Sie anschließend wie folgt auf:

docker compose -f deployments/docker-compose/ansible-windows/docker-compose.yml down

Weitere Details:

• Docker Windows Ansible README

Windows unter Windows mit Hyper-V

Installieren Sie zunächst die Host-Abhängigkeiten:

sailwright.exe install

Für den Build benötigen Sie ein Windows-ISO. Sie können eines manuell von Microsoft herunterladen oder Folgendes verwenden:

• download_win_11.ps1

Build-Details finden Sie hier:

• Windows Packer README
• Windows Hyper-V deployment README

Sobald die VM läuft, führen Sie das Provisioning vom Repository-Root aus durch:

sailwright.exe provision windows11 --arch amd64 --check
sailwright.exe provision windows11 --arch amd64

Setzen Sie die WinRM-Anmeldedaten in der .env im Projekt-Root oder in der Prozessumgebung:

HYPERV_WINDOWS_ANSIBLE_USER=Administrator
HYPERV_WINDOWS_ANSIBLE_PASSWORD=your-secure-password
# Optional (defaults shown):
HYPERV_WINDOWS_ANSIBLE_CONNECTION=winrm
HYPERV_WINDOWS_ANSIBLE_WINRM_TRANSPORT=basic
HYPERV_WINDOWS_ANSIBLE_PORT=5985

Optionale Shell-Pfad-Overrides für den Windows/Cygwin-Wrapper:

$env:CYGWIN_BASH_PATH = "C:\tools\cygwin\bin\bash.exe"
# or, if you prefer setting the Cygwin terminal path:
$env:CYGWIN_TERMINAL_PATH = "C:\tools\cygwin\bin\mintty.exe"

Reihenfolge der Pfadauflösung für das Provisioning:

1. CYGWIN_BASH_PATH
2. CYGWIN_TERMINAL_PATH, wenn CYGWIN_BASH_PATH nicht gesetzt ist
3. Automatische Erkennung von C:\tools\cygwin\bin\bash.exe
4. Automatische Erkennung von C:\cygwin64\bin\bash.exe

Wenn CYGWIN_TERMINAL_PATH auf mintty.exe verweist, löst das Provisioning es zur benachbarten bash.exe auf.

macOS-Host-Workflows

macOS unter macOS mit Tart

Verwenden Sie das mitgelieferte Skript:

./scripts/macos/test-ansible-macos.sh

Das Skript führt das Ansible-Playbook gegen eine temporäre Tart-VM aus. Tart-Projekt:

• https://github.com/cirruslabs/tart

Standardmäßig verwendet Sailwright die Entwicklungs-Anmeldedaten des Tart-Images für den Ansible-Zugriff (admin / admin). Überschreiben Sie diese bei Bedarf in .env:

TART_MACOS_ANSIBLE_USER=admin
TART_MACOS_ANSIBLE_PASSWORD=admin

TART_MACOS_ANSIBLE_BECOME_PASSWORD verwendet standardmäßig den Wert von TART_MACOS_ANSIBLE_PASSWORD, wenn nicht gesetzt.

Räumen Sie anschließend wie folgt auf:

tart delete sequoia-base

Windows unter macOS mit UTM

Installieren Sie zunächst die Host-Abhängigkeiten:

sailwright install

Bauen und erstellen Sie die Windows-11-VM:

# arm64 requires sudo to create a custom .iso file for automated installation.
# sudo rights are evaluated at runtime, so you can run the build command without sudo and it will ask for sudo rights only if needed.
arch=arm64 # or amd64
# sudo sailwright build windows11 --arch $arch --headless
sailwright build windows11 --arch $arch --headless
# `--headless` applies to `build`, not `create`.
sailwright create windows11 --arch $arch

Öffnen Sie UTM und starten Sie die erstellte VM.

Setzen Sie die WinRM-Anmeldedaten in der .env im Projekt-Root oder in der Prozessumgebung:

UTM_WINDOWS_ANSIBLE_USER=Administrator
UTM_WINDOWS_ANSIBLE_PASSWORD=your-secure-password
# Optional (defaults shown):
UTM_WINDOWS_ANSIBLE_CONNECTION=winrm
UTM_WINDOWS_ANSIBLE_WINRM_TRANSPORT=basic
UTM_WINDOWS_ANSIBLE_PORT=5985

Führen Sie das Provisioning vom Repository-Root aus durch:

sailwright provision windows11 --arch $arch --check
sailwright provision windows11 --arch $arch

Der Wrapper ermittelt die VM-IP automatisch aus der generierten UTM-Konfiguration und arp -a und führt anschließend ansible-playbook mit einem inline definierten Inventory-Ziel aus. Unter macOS setzt er außerdem automatisch OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES für den Ansible-Prozess.

Wenn Sie die ermittelte IP manuell prüfen möchten:

bash ./deployments/utm/determine-vm-ip-address.sh --arch $arch --os windows11

Zugehörige Anleitung:

• Windows Packer README

Neu gebaute Windows-Images installieren eine dedizierte WinRM-Firewallregel für TCP 5985 auf allen Netzwerkprofilen, sodass spätere Änderungen an NIC oder Netzwerkprofil die Erreichbarkeit nicht beeinträchtigen sollten. Bei älteren Images muss das Netzwerk unter Umständen noch manuell auf Private umgestellt oder eine entsprechende Firewallregel hinzugefügt werden.

Ubuntu unter macOS mit UTM

Installieren Sie zunächst die Host-Abhängigkeiten:

sailwright install

Bauen und erstellen Sie die Ubuntu-VM:

arch=arm64 # or amd64
type=desktop # or server
sailwright build ubuntu --arch $arch --type $type
sailwright create ubuntu --arch $arch --type $type

Öffnen Sie UTM und starten Sie die erstellte VM.

Setzen Sie die Ubuntu-SSH-Anmeldedaten in der .env im Projekt-Root oder in der Prozessumgebung:

UTM_UBUNTU_ANSIBLE_USER=packer
UTM_UBUNTU_ANSIBLE_PASSWORD=P@ssw0rd!
UTM_UBUNTU_ANSIBLE_BECOME_PASSWORD=P@ssw0rd!
# Optional (defaults shown):
UTM_UBUNTU_ANSIBLE_CONNECTION=ssh
UTM_UBUNTU_ANSIBLE_SSH_COMMON_ARGS=-o StrictHostKeyChecking=no -o ServerAliveInterval=10 -o ServerAliveCountMax=3 -o ControlMaster=no -o ControlPersist=no
UTM_UBUNTU_ANSIBLE_SSH_TIMEOUT=120
UTM_UBUNTU_ANSIBLE_SSH_RETRIES=3

Führen Sie das Provisioning vom Repository-Root aus durch:

sailwright provision ubuntu --type $type --arch $arch --check
sailwright provision ubuntu --type $type --arch $arch

Der Wrapper ermittelt die VM-IP automatisch aus der generierten UTM-Konfiguration und arp -a und führt anschließend ansible-playbook mit einem inline definierten Inventory-Ziel aus. Unter macOS setzt er außerdem automatisch OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES für den Ansible-Prozess.

Wenn Sie die ermittelte IP manuell prüfen möchten:

bash ./deployments/utm/determine-vm-ip-address.sh --arch $arch --os "ubuntu-$type"