From 93f14ce7954c8acefc7100127247fac7688e7509 Mon Sep 17 00:00:00 2001
From: Lukas Frank <lukas.frank@sap.com>
Date: Wed, 26 Aug 2026 15:45:32 +0200
Subject: [PATCH] Move `libvirt-provider` docs to central docs

Signed-off-by: Lukas Frank <lukas.frank@sap.com>
---
 docs/.vitepress/config.mts                    | 10 ++-
 .../providers/libvirt-provider/console.md     | 22 +++++++
 .../providers/libvirt-provider/ignition.md    | 65 +++++++++++++++++++
 3 files changed, 96 insertions(+), 1 deletion(-)
 create mode 100644 docs/iaas/architecture/providers/libvirt-provider/console.md
 create mode 100644 docs/iaas/architecture/providers/libvirt-provider/ignition.md

diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index 803afd0..5c8b24c 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -111,7 +111,15 @@ export default withMermaid({
           items: [
             { text: 'Overview', link: '/iaas/architecture/providers/' },
             { text: 'Brokers', link: '/iaas/architecture/providers/brokers' },
-            { text: 'libvirt-provider', link: '/iaas/architecture/providers/libvirt-provider' },
+            {
+              text: 'libvirt-provider',
+              collapsed: true,
+              items: [
+                { text: 'Overview', link: '/iaas/architecture/providers/libvirt-provider' },
+                { text: 'Console', link: '/iaas/architecture/providers/libvirt-provider/console' },
+                { text: 'Ignition', link: '/iaas/architecture/providers/libvirt-provider/ignition' },
+              ],
+            },
             { text: 'ceph-provider', link: '/iaas/architecture/providers/ceph-provider' },
           ],
         },
diff --git a/docs/iaas/architecture/providers/libvirt-provider/console.md b/docs/iaas/architecture/providers/libvirt-provider/console.md
new file mode 100644
index 0000000..8e4d164
--- /dev/null
+++ b/docs/iaas/architecture/providers/libvirt-provider/console.md
@@ -0,0 +1,22 @@
+# Console
+
+Every machine is equipped with a serial console which allows interactive access to the guest, e.g. via the
+`Exec` endpoint of the IRI `MachineRuntime` service.
+
+## Console log
+
+The console output of a machine is additionally mirrored to a log file on the hypervisor. This is an always-on
+feature and uses the libvirt [`<log>`](https://libvirt.org/formatdomain.html#element-log) sub-element of the
+serial chardev, so the interactive console stays usable while all traffic is persisted.
+
+The log file is stored per machine at:
+
+```text
+<libvirt-provider-dir>/machines/<machine-uid>/logs/console.log
+```
+
+It is written with `append="on"`, i.e. the content is preserved across domain restarts. This allows operators
+to inspect early boot logs (firmware, bootloader, kernel) of a machine, which is especially useful when a
+machine fails to boot.
+
+The console log is removed together with the machine directory when the machine is deleted.
diff --git a/docs/iaas/architecture/providers/libvirt-provider/ignition.md b/docs/iaas/architecture/providers/libvirt-provider/ignition.md
new file mode 100644
index 0000000..ca337bf
--- /dev/null
+++ b/docs/iaas/architecture/providers/libvirt-provider/ignition.md
@@ -0,0 +1,65 @@
+# Ignition
+
+The following is a minimal Ignition configuration that contains everything libvirt-provider-specific to get the service up and running.
+
+```yaml
+variant: fcos
+version: 1.3.0
+systemd:
+  units:
+  - name: postinstall.service
+    enabled: true
+    contents: |
+      [Unit]
+      Description=Post configuration service
+      ConditionFirstBoot=yes
+      After=systemd-networkd-wait-online.service inventory.service
+      Wants=inventory.service
+
+      [Service]
+      Type=oneshot
+      ExecStart=/opt/postinstall.sh
+
+      [Install]
+      WantedBy=multi-user.target
+storage:
+  directories:
+  - path: /var/lib/libvirt-provider
+    user:
+      name: libvirt-provider
+    group:
+      name: libvirt-provider
+    mode: 0755
+  files:
+  - path: /opt/postinstall.sh
+    mode: 0755
+    overwrite: yes
+    contents:
+      inline: |
+        #!/usr/bin/env bash
+        set -Eeuo pipefail
+        export DEBIAN_FRONTEND=noninteractive
+  
+        apt-get update
+        apt-get install -y libvirt-daemon-system libvirt-clients ovmf ceph-common
+  
+        # libvirt-qemu user runs the VM processes,
+        # so it also needs access to the libvirt-provider group to read/write the disk images
+        usermod -aG libvirt-provider libvirt-qemu
+  
+        # libvirt-provider user needs to be in the libvirt group to interact with the
+        # libvirt daemon socket
+        usermod -aG libvirt libvirt-provider
+passwd:
+  groups:
+    - name: libvirt-provider
+      gid: 65532 # specific GID used in the IronCore context
+  users:
+    - name: libvirt-provider
+      uid: 65532 # specific UID used in the IronCore context
+      primary_group: libvirt-provider
+      home_dir: "/nonexistent" # Ubuntu/Debian standard for system users without home directories
+      no_create_home: true
+      no_user_group: true
+      shell: "/sbin/nologin"
+```