10 files changed, 418 insertions, 0 deletions

diff --git a/conf/distro/include/container-host-containerd.conf b/conf/distro/include/container-host-containerd.conf
new file mode 100644
index 00000000..c4a68845
--- /dev/null
+++ b/conf/distro/include/container-host-containerd.conf
@@ -0,0 +1,14 @@
+# Container host configuration fragment: Containerd
+#
+# Include from local.conf to set up a containerd-based container host.
+# Requires meta-virt-host.conf to be included first:
+#
+#   require conf/distro/include/meta-virt-host.conf
+#   require conf/distro/include/container-host-containerd.conf
+#   MACHINE = "qemux86-64"
+#   bitbake container-image-host
+#
+# Sets CONTAINER_PROFILE and the DISTRO_FEATURES required by
+# container-image-host with the containerd engine stack.
+
+CONTAINER_PROFILE = "containerd"
diff --git a/conf/distro/include/container-host-docker.conf b/conf/distro/include/container-host-docker.conf
new file mode 100644
index 00000000..5bf29359
--- /dev/null
+++ b/conf/distro/include/container-host-docker.conf
@@ -0,0 +1,14 @@
+# Container host configuration fragment: Docker
+#
+# Include from local.conf to set up a Docker-based container host.
+# Requires meta-virt-host.conf to be included first:
+#
+#   require conf/distro/include/meta-virt-host.conf
+#   require conf/distro/include/container-host-docker.conf
+#   MACHINE = "qemux86-64"
+#   bitbake container-image-host
+#
+# Sets CONTAINER_PROFILE and the DISTRO_FEATURES required by
+# container-image-host with the Docker engine stack.
+
+CONTAINER_PROFILE = "docker"
diff --git a/conf/distro/include/container-host-k3s-node.conf b/conf/distro/include/container-host-k3s-node.conf
new file mode 100644
index 00000000..75580d71
--- /dev/null
+++ b/conf/distro/include/container-host-k3s-node.conf
@@ -0,0 +1,18 @@
+# Container host configuration fragment: K3s agent node
+#
+# Include from local.conf to set up a K3s agent (worker) node.
+# Requires meta-virt-host.conf to be included first:
+#
+#   require conf/distro/include/meta-virt-host.conf
+#   require conf/distro/include/container-host-k3s-node.conf
+#   MACHINE = "qemux86-64"
+#   bitbake container-image-host
+#
+# Sets CONTAINER_PROFILE and the DISTRO_FEATURES required by
+# container-image-host with K3s agent-only orchestration. The
+# k3s-node profile bundles the k3s agent, embedded containerd,
+# and CNI plugins. The node joins an existing k3s server cluster.
+
+CONTAINER_PROFILE = "k3s-node"
+
+DISTRO_FEATURES:append = " k3s"
diff --git a/conf/distro/include/container-host-k3s.conf b/conf/distro/include/container-host-k3s.conf
new file mode 100644
index 00000000..6e3733b1
--- /dev/null
+++ b/conf/distro/include/container-host-k3s.conf
@@ -0,0 +1,17 @@
+# Container host configuration fragment: K3s server
+#
+# Include from local.conf to set up a K3s server (control plane + agent).
+# Requires meta-virt-host.conf to be included first:
+#
+#   require conf/distro/include/meta-virt-host.conf
+#   require conf/distro/include/container-host-k3s.conf
+#   MACHINE = "qemux86-64"
+#   bitbake container-image-host
+#
+# Sets CONTAINER_PROFILE and the DISTRO_FEATURES required by
+# container-image-host with K3s orchestration. The k3s-host profile
+# bundles the k3s server, embedded containerd, and CNI plugins.
+
+CONTAINER_PROFILE = "k3s-host"
+
+DISTRO_FEATURES:append = " k3s"
diff --git a/conf/distro/include/container-host-podman.conf b/conf/distro/include/container-host-podman.conf
new file mode 100644
index 00000000..7190e32b
--- /dev/null
+++ b/conf/distro/include/container-host-podman.conf
@@ -0,0 +1,17 @@
+# Container host configuration fragment: Podman
+#
+# Include from local.conf to set up a Podman-based container host.
+# Requires meta-virt-host.conf to be included first:
+#
+#   require conf/distro/include/meta-virt-host.conf
+#   require conf/distro/include/container-host-podman.conf
+#   MACHINE = "qemux86-64"
+#   bitbake container-image-host
+#
+# Sets CONTAINER_PROFILE and the DISTRO_FEATURES required by
+# container-image-host with the Podman engine stack.
+# Includes ipv6 which is required by the podman packagegroup.
+
+CONTAINER_PROFILE = "podman"
+
+DISTRO_FEATURES:append = " ipv6"
diff --git a/conf/distro/include/container-registry.conf b/conf/distro/include/container-registry.conf
new file mode 100644
index 00000000..357e7913
--- /dev/null
+++ b/conf/distro/include/container-registry.conf
@@ -0,0 +1,29 @@
+# Container registry configuration fragment
+#
+# Include from local.conf to enable a local development registry:
+#
+#   require conf/distro/include/container-registry.conf
+#
+# Defaults to an insecure (HTTP) registry at localhost:5000 with
+# namespace "yocto". Override any variable after the require line.
+#
+# This fragment enables the container-registry IMAGE_FEATURES, which
+# installs registry configuration into the target rootfs (daemon.json
+# for Docker, registries.conf.d/ for Podman/containerd).
+#
+# For a secure (TLS + authentication) registry, override these after
+# the require:
+#
+#   CONTAINER_REGISTRY_URL = "registry.example.com:5000"
+#   CONTAINER_REGISTRY_SECURE = "1"
+#   CONTAINER_REGISTRY_USERNAME = "myuser"
+#   # Optional: enable htpasswd authentication
+#   CONTAINER_REGISTRY_AUTH = "1"
+#   # Optional: custom namespace
+#   CONTAINER_REGISTRY_NAMESPACE = "myproject"
+
+CONTAINER_REGISTRY_URL ?= "localhost:5000"
+CONTAINER_REGISTRY_NAMESPACE ?= "yocto"
+CONTAINER_REGISTRY_INSECURE ?= "1"
+
+IMAGE_FEATURES:append = " container-registry"
diff --git a/conf/distro/include/meta-virt-dev.conf b/conf/distro/include/meta-virt-dev.conf
new file mode 100644
index 00000000..06dcbb95
--- /dev/null
+++ b/conf/distro/include/meta-virt-dev.conf
@@ -0,0 +1,28 @@
+# QEMU development and testing settings
+#
+# Include from local.conf when developing and testing with runqemu:
+#
+#   require conf/distro/include/meta-virt-dev.conf
+#
+# This is separate from the build profiles (container-host-*, xen-host-*)
+# and provides settings that only matter for QEMU-based development:
+# image format, memory, debug features, etc.
+#
+# Typical local.conf for QEMU-based k3s development:
+#
+#   require conf/distro/include/meta-virt-host.conf
+#   BUILD_PROFILE ?= "k3s"
+#   require conf/distro/include/container-host-${BUILD_PROFILE}.conf
+#   require conf/distro/include/meta-virt-dev.conf
+#   MACHINE = "qemux86-64"
+
+# Use raw ext4 for runqemu boot/test cycles.
+# Snapshot formats (qcow2) don't work well with repeated boots.
+IMAGE_FSTYPES = "ext4"
+
+# Xen QEMU settings: Dom0 memory cap and total VM memory
+QB_XEN_CMDLINE_EXTRA ?= "dom0_mem=512M"
+QB_MEM ?= "-m 1024"
+
+# Debug-friendly image features
+EXTRA_IMAGE_FEATURES ?= "allow-empty-password empty-root-password allow-root-login post-install-logging"
diff --git a/conf/distro/include/meta-virt-host.conf b/conf/distro/include/meta-virt-host.conf
new file mode 100644
index 00000000..99d5271e
--- /dev/null
+++ b/conf/distro/include/meta-virt-host.conf
@@ -0,0 +1,20 @@
+# Base virtualization host configuration fragment
+#
+# Common DISTRO_FEATURES for any virtualization work: containers, Xen,
+# k3s, or custom/mixed configurations.
+#
+# Use standalone for custom builds:
+#
+#   require conf/distro/include/meta-virt-host.conf
+#   MACHINE = "qemux86-64"
+#
+# Or let a specific profile (container-host-*, xen-host-*) inherit it.
+
+DISTRO_FEATURES:append = " virtualization systemd seccomp vmsep vcontainer"
+
+# Container runtime provider — the unified runc recipe provides both
+# runc-docker and runc-opencontainers via RPROVIDES
+PREFERRED_PROVIDER_virtual/runc ?= "runc"
+
+# Multiconfig for cross-arch vruntime builds (vdkr/vpdmn blobs)
+BBMULTICONFIG ?= "vruntime-aarch64 vruntime-x86-64"
diff --git a/conf/distro/include/xen-host.conf b/conf/distro/include/xen-host.conf
new file mode 100644
index 00000000..0d21cc63
--- /dev/null
+++ b/conf/distro/include/xen-host.conf
@@ -0,0 +1,17 @@
+# Xen host configuration fragment
+#
+# Include from local.conf for Xen Dom0 development and testing.
+# Requires meta-virt-host.conf to be included first:
+#
+#   require conf/distro/include/meta-virt-host.conf
+#   require conf/distro/include/xen-host.conf
+#   MACHINE = "qemux86-64"
+#   bitbake xen-image-minimal
+#
+# Enables Xen hypervisor support, vxn (Docker CLI for Xen), and containerd
+# for the OCI runtime path.
+
+DISTRO_FEATURES:append = " xen vxn"
+
+# Xen Dom0 image packages: vxn, containerd
+IMAGE_INSTALL:append:pn-xen-image-minimal = " vxn containerd-opencontainers"
diff --git a/docs/build-profiles.md b/docs/build-profiles.md
new file mode 100644
index 00000000..602d11b9
--- /dev/null
+++ b/docs/build-profiles.md
@@ -0,0 +1,244 @@
+# Build Profiles — Configuration Fragments for meta-virtualization
+
+## Overview
+
+meta-virtualization provides configuration fragments in `conf/distro/include/`
+that replace the manual DISTRO_FEATURES, CONTAINER_PROFILE, and related
+settings typically scattered across `local.conf`. Each fragment is a small
+`.conf` file that sets the minimum variables needed for a specific build
+profile.
+
+The fragments are organized in layers:
+
+```
+meta-virt-host.conf              <- base (always required first)
+  container-host-docker.conf     <- container profiles (pick one)
+  container-host-podman.conf
+  container-host-containerd.conf
+  container-host-k3s.conf
+  container-host-k3s-node.conf
+  xen-host.conf                  <- Xen support (composable)
+meta-virt-dev.conf               <- QEMU dev settings (opt-in)
+container-registry.conf          <- registry config (opt-in)
+```
+
+## Quick Start
+
+Add to `local.conf`:
+
+```bash
+# Base (always first)
+require conf/distro/include/meta-virt-host.conf
+
+# Container profile — change BUILD_PROFILE to switch
+BUILD_PROFILE ?= "podman"
+require conf/distro/include/container-host-${BUILD_PROFILE}.conf
+
+# Optional: Xen support (composable with any container profile)
+require conf/distro/include/xen-host.conf
+
+# Optional: QEMU development settings
+require conf/distro/include/meta-virt-dev.conf
+
+# Optional: Container registry
+require conf/distro/include/container-registry.conf
+
+MACHINE = "qemux86-64"
+```
+
+Then build:
+
+```bash
+bitbake container-image-host    # container host image
+bitbake xen-image-minimal       # Xen image (if xen-host.conf included)
+```
+
+## Switching Profiles
+
+Change one variable to switch the entire container stack:
+
+```bash
+BUILD_PROFILE ?= "docker"       # Docker + runc + CNI
+BUILD_PROFILE ?= "podman"       # Podman + crun + netavark
+BUILD_PROFILE ?= "containerd"   # Containerd + crun + CNI
+BUILD_PROFILE ?= "k3s"          # K3s server + embedded containerd + CNI
+BUILD_PROFILE ?= "k3s-node"     # K3s agent node
+```
+
+Or override from the command line:
+
+```bash
+BUILD_PROFILE=docker bitbake container-image-host
+```
+
+## Fragment Reference
+
+### meta-virt-host.conf (Base — Required)
+
+The foundation for all virtualization work. Must be included first.
+
+**Sets:**
+- `DISTRO_FEATURES:append = " virtualization systemd seccomp vmsep vcontainer"`
+- `PREFERRED_PROVIDER_virtual/runc ?= "runc"`
+- `BBMULTICONFIG ?= "vruntime-aarch64 vruntime-x86-64"`
+
+**Use standalone** for custom/mixed configurations where you want to set
+CONTAINER_PROFILE and other variables manually.
+
+### container-host-docker.conf
+
+Docker engine stack.
+
+**Sets:**
+- `CONTAINER_PROFILE = "docker"`
+
+**Results in:** docker-moby, runc, CNI networking.
+
+### container-host-podman.conf
+
+Podman engine stack.
+
+**Sets:**
+- `CONTAINER_PROFILE = "podman"`
+- `DISTRO_FEATURES:append = " ipv6"` (required by podman packagegroup)
+
+**Results in:** podman, crun, netavark + aardvark-dns networking.
+
+### container-host-containerd.conf
+
+Standalone containerd stack.
+
+**Sets:**
+- `CONTAINER_PROFILE = "containerd"`
+
+**Results in:** containerd, crun, CNI networking.
+
+### container-host-k3s.conf
+
+K3s server (control plane + agent).
+
+**Sets:**
+- `CONTAINER_PROFILE = "k3s-host"`
+- `DISTRO_FEATURES:append = " k3s"`
+
+**Results in:** k3s-server, embedded containerd, CNI plugins.
+
+### container-host-k3s-node.conf
+
+K3s agent (worker node). Joins an existing k3s server cluster.
+
+**Sets:**
+- `CONTAINER_PROFILE = "k3s-node"`
+- `DISTRO_FEATURES:append = " k3s"`
+
+**Results in:** k3s-agent, embedded containerd, CNI plugins.
+
+### xen-host.conf
+
+Xen hypervisor support. Composable with any container profile.
+
+**Sets:**
+- `DISTRO_FEATURES:append = " xen vxn"`
+- `IMAGE_INSTALL:append:pn-xen-image-minimal = " vxn containerd-opencontainers"`
+
+**Use with:** `bitbake xen-image-minimal`
+
+### meta-virt-dev.conf
+
+QEMU development and testing settings. Only include when developing
+and testing with runqemu.
+
+**Sets:**
+- `IMAGE_FSTYPES = "ext4"` (raw ext4 for persistent boots, no snapshots)
+- `QB_XEN_CMDLINE_EXTRA ?= "dom0_mem=512M"`
+- `QB_MEM ?= "-m 1024"`
+- `EXTRA_IMAGE_FEATURES ?= "allow-empty-password empty-root-password allow-root-login post-install-logging"`
+
+### container-registry.conf
+
+Local development container registry. Defaults to insecure HTTP at
+localhost:5000 with namespace "yocto".
+
+**Sets:**
+- `CONTAINER_REGISTRY_URL ?= "localhost:5000"`
+- `CONTAINER_REGISTRY_NAMESPACE ?= "yocto"`
+- `CONTAINER_REGISTRY_INSECURE ?= "1"`
+- `IMAGE_FEATURES:append = " container-registry"`
+
+**For secure (TLS) registries,** override after the require:
+
+```bash
+require conf/distro/include/container-registry.conf
+CONTAINER_REGISTRY_URL = "registry.example.com:5000"
+CONTAINER_REGISTRY_SECURE = "1"
+CONTAINER_REGISTRY_USERNAME = "myuser"
+```
+
+## Design Notes
+
+**Profiles are pure deltas.** They do not include `meta-virt-host.conf`
+themselves. This avoids BitBake duplicate inclusion warnings when
+combining multiple fragments (e.g., a container profile + xen-host.conf).
+The user must always include `meta-virt-host.conf` first.
+
+**`meta-virt-dev.conf` is separate** from the build profiles. It contains
+settings that only matter for QEMU-based development (image format,
+memory, debug features) and should not be included in production builds.
+
+**Fragments use weak assignments (`?=`)** for most settings so they can
+be overridden in `local.conf`. The exceptions are `CONTAINER_PROFILE`
+and profile-specific `DISTRO_FEATURES:append` which use strong
+assignments since they define the profile's identity.
+
+## Example: Full Development local.conf
+
+```bash
+# After the standard Poky local.conf boilerplate...
+
+CONF_VERSION = "2"
+
+###############################################################################
+# Virtualization Profile & Development Configuration
+###############################################################################
+
+# Base: virtualization systemd seccomp vmsep vcontainer + BBMULTICONFIG
+require conf/distro/include/meta-virt-host.conf
+
+# Container profile (switch BUILD_PROFILE to change)
+BUILD_PROFILE ?= "podman"
+require conf/distro/include/container-host-${BUILD_PROFILE}.conf
+
+# Xen support (composable with any container profile)
+require conf/distro/include/xen-host.conf
+
+# QEMU development settings (IMAGE_FSTYPES, QB_MEM, debug features)
+require conf/distro/include/meta-virt-dev.conf
+
+# Container registry (insecure localhost:5000)
+require conf/distro/include/container-registry.conf
+
+# Additional local settings
+DISTRO_FEATURES:append = " pam"
+INIT_MANAGER = "systemd"
+MACHINE = "qemux86-64"
+
+# Provider overrides
+include bruce-providers.inc
+
+# Xen guest bundles
+IMAGE_INSTALL:append:pn-xen-image-minimal = " example-xen-guest-bundle"
+IMAGE_INSTALL:append:pn-xen-image-minimal = " alpine-xen-guest-bundle"
+```
+
+## Launch Commands
+
+```bash
+# Container host (podman/docker/containerd/k3s)
+runqemu qemux86-64 container-image-host ext4 nographic kvm slirp
+
+# Xen Dom0
+runqemu qemux86-64 xen-image-minimal wic nographic kvm qemuparams="-m 4096"
+
+# K3s with extra memory
+runqemu qemux86-64 container-image-host ext4 nographic kvm slirp qemuparams="-m 4096"
+```