linux/meta-virtualization.git/docs, branch master-next

container-bundle: add CONTAINER_FLAGS_ACCEPTED to acknowledge container licenses

2026-06-13T03:51:50+00:00

container-bundle.bbclass emits a bb.warn on every parse of a recipe that fetches a remote container. The warning's intent is sound: the integrator is shipping content they did not build from source, and the license/redistribution implications deserve a deliberate review. After that review has happened, though, the warning has nowhere to go. It keeps firing on every build, and there is no way for an image recipe that intentionally bundles e.g. an alpine or busybox base container to have a clean parse log. Users who want to add deliberate third-party base images (the app-container-alpine demo Tim is working on is the immediate motivation) end up either editing the bbclass to suppress the warning entirely or living with the noise — both bad. Add CONTAINER_FLAGS_ACCEPTED, mirroring oe-core's LICENSE_FLAGS / LICENSE_FLAGS_ACCEPTED pattern. The recipe never declares its own container licenses as accepted; instead the integrator opts in via local.conf or distro config after reviewing each container: CONTAINER_FLAGS_ACCEPTED += "docker.io/library/alpine" URLs in CONTAINER_FLAGS_ACCEPTED are matched against both the full URL (with :tag or @digest) and the bare URL with tag/digest stripped, so accepting "docker.io/library/alpine" covers every tag of that container. A "*" wildcard accepts every third-party container — for distros that have a standing review process. When a URL matches, the bb.warn is demoted to a bb.note instead of being silenced entirely. The note remains in the build log and the recipe's task log, so SBOM tools, audit pipelines, and distro release reviews can still see that an acknowledged third-party container was pulled. The point of the change is to remove the visible "WARNING" line from clean builds, not to hide that the fetch happened. The unacknowledged-URL warning is also reworded to print a copy-pasteable CONTAINER_FLAGS_ACCEPTED line for the specific URL, so the user reading the warning doesn't have to grep the docs to find the variable name. Documentation lives in both the bbclass header block and docs/container-bundling.md (under a new "Acknowledging Third-Party Container Licenses" section), with the exact warning text and the exact note text quoted so they're greppable from either entry point. Signed-off-by: Bruce Ashfield

docs/container-bundling: refresh multi-layer mode section

2026-06-12T17:13:19+00:00

Three related updates to the multi-layer documentation, all driven by patterns that came up reviewing recent OCI image recipes: - Drop the "IMAGE_INSTALL must include all packages to trigger builds" guidance from the example. As of the matching bbclass change, image-oci.bbclass folds OCI_LAYERS packages: entries into IMAGE_INSTALL automatically, so recipes only set the package list once. The example used to demonstrate the dual-source-of-truth workaround for the original limitation; with the limitation gone the example was actively misleading. - Add a "Conditional Packages per Layer" subsection documenting the bb.utils.contains() pattern for adding/omitting packages from a packages: layer based on PACKAGECONFIG (or any other variable), without duplicating the whole OCI_LAYERS declaration in two branches. This is a real, useful idiom that recipes have started using; previously undocumented. - Fill in the "host" layer type row in the layer-type table. The type was already supported and explained in image-oci.bbclass inline docs, but the user-facing reference table only listed packages / directories / files. Signed-off-by: Bruce Ashfield

conf: add kvm-host.conf configuration fragment

2026-05-12T12:52:59+00:00

Building kvm-image-minimal fails without the 'kvm' DISTRO_FEATURE, requiring users to manually add it to local.conf. Every other virtualization platform (Xen, Docker, Podman, k3s, containerd) already has a composable configuration fragment in conf/distro/include/ that can be included with a single require line. Add kvm-host.conf following the same pattern as xen-host.conf: a pure delta fragment that appends the kvm DISTRO_FEATURE. Composable with any container profile and the base meta-virt-host.conf. Signed-off-by: Bruce Ashfield

vcontainer: add BBMASK for parse savings and suppress layer warnings

2026-05-10T20:15:50+00:00

The initial vcontainer distro had no BBMASK at all, making it effectively poky with fewer DISTRO_FEATURES. Every multiconfig parsed the entire recipe universe even though container image builds only need a small subset. With 4+ multiconfigs, the parse overhead is significant. Add vcontainer-bbmask.inc as a lighter alternative to vruntime's aggressive BBMASK. It masks the same categories irrelevant to any container/VM build (graphics, multimedia, desktop, virtualization platforms, orchestration tools, meta-python, meta-filesystems, meta-webserver) but keeps the OCI tooling that vruntime blocks: umoci, container-registry, image recipes, sloci, oci-image-tools. Masking entire layers (meta-python, meta-filesystems, meta-webserver) produces BBFILE_PATTERN warnings because the layers are registered in bblayers.conf (shared with the main build) but have zero recipes after masking. BitBake provides BBFILE_PATTERN_IGNORE_EMPTY_ to suppress this, but checks it on self.data (the base datastore), not per-multiconfig datastores. Setting it in the distro config has no effect. Move the suppression to meta-virt-host.conf which is included by the main build's local.conf and therefore visible to the base datastore. Signed-off-by: Bruce Ashfield

container-registry: add multi-arch OCI push support and tests

2026-05-10T13:58:45+00:00

The registry push script (container-registry-index.bb) treated all OCI directories as single-arch, calling 'skopeo copy oci:' which fails with "more than one image in oci, choose an image" when the directory contains a multi-arch image index. The original push implementation predated multi-arch OCI support and only handled the single-manifest case. Detect multi-arch OCI Image Index directories (both flat and nested layouts) in the direct-path push mode and use 'skopeo copy --all' to push the entire manifest list to the registry in one operation. This preserves the multi-platform structure so that clients pulling from the registry automatically get the correct architecture. Also strip the '-multiarch' suffix from directory names when deriving the registry image name, so container-base-multiarch-multiarch-oci pushes as 'container-base' rather than 'container-base-multiarch'. Add build-profiles.md documentation for the vcontainer distro, container multiconfigs, and multi-arch container build workflow. Add test_vcontainer_distro.py with 54 tests across three tiers: - Tier 1: Static file assertions (vruntime-base.inc, vcontainer.conf, multiconfigs, bbclass defaults, recipe structure) - Tier 2: Cross-file consistency (shared base, distro-MC alignment, bbclass-to-multiconfig file matching) - Tier 3: Build output verification (OCI index structure, platform entries, blob integrity, manifest validation) Signed-off-by: Bruce Ashfield

conf/distro: add build profile configuration fragments

2026-04-05T02:09:58+00:00

Add includable configuration fragments that replace manual DISTRO_FEATURES, CONTAINER_PROFILE, and related settings in local.conf. Fragments are organized as a base + composable deltas: - meta-virt-host.conf: base for all virtualization work (virtualization, systemd, seccomp, vmsep, vcontainer, BBMULTICONFIG) - container-host-{docker,podman,containerd,k3s,k3s-node}.conf: container engine profiles setting CONTAINER_PROFILE and profile-specific DISTRO_FEATURES - xen-host.conf: Xen hypervisor support (xen, vxn distro features, xen-image-minimal packages) - meta-virt-dev.conf: QEMU development settings (IMAGE_FSTYPES, QB_MEM, debug image features) - container-registry.conf: local dev registry defaults (insecure localhost:5000) Profiles are pure deltas and do not auto-include the base to avoid BitBake duplicate inclusion warnings. Users include meta-virt-host.conf first, then add profile fragments. The BUILD_PROFILE variable enables single-line profile switching. Usage in local.conf: require conf/distro/include/meta-virt-host.conf BUILD_PROFILE ?= "podman" require conf/distro/include/container-host-${BUILD_PROFILE}.conf Tested with podman, docker, and xen builds. Signed-off-by: Bruce Ashfield

container-cross-install: add tests and documentation for custom service files

2026-02-09T03:34:12+00:00

Add pytest tests to verify CONTAINER_SERVICE_FILE varflag support: TestCustomServiceFileSupport (unit tests, no build required): - test_bbclass_has_service_file_support - test_bundle_class_has_service_file_support - test_service_file_map_syntax - test_install_custom_service_function TestCustomServiceFileBoot (boot tests, require built image): - test_systemd_services_directory_exists - test_container_services_present - test_container_service_enabled - test_custom_service_content - test_podman_quadlet_directory Documentation updates: - docs/container-bundling.md: Add "Custom Service Files" section with variable format, usage examples for both BUNDLED_CONTAINERS and container-bundle packages, and example .service/.container files - tests/README.md: Add test class entries to structure diagram and "What the Tests Check" table Signed-off-by: Bruce Ashfield

image-oci: add layer caching for multi-layer OCI builds

2026-02-09T03:32:52+00:00

Add layer caching to speed up multi-layer OCI image rebuilds. When enabled, pre-installed package layers are cached to disk and restored on subsequent builds, avoiding repeated package installation. New variables: - OCI_LAYER_CACHE: Enable/disable caching (default "1") - OCI_LAYER_CACHE_DIR: Cache location (default ${TOPDIR}/oci-layer-cache/${MACHINE}) Cache key is computed from: - Layer name and type - Sorted package list - Package versions from PKGDATA_DIR - MACHINE and TUNE_PKGARCH Cache automatically invalidates when: - Package versions change - Layer definition changes - Architecture changes Benefits: - First build: ~10-30s per layer (cache miss, packages installed) - Subsequent builds: ~1s per layer (cache hit, files copied) - Shared across recipes with identical layer definitions Build log shows cache status: NOTE: OCI Cache HIT: Layer 'base' (be88c180f651416b) NOTE: OCI: Pre-installed packages for 3 layers (cache: 3 hits, 0 misses) Also adds comprehensive pytest suite for multi-layer OCI functionality including tests for 1/2/3 layer modes and cache behavior. Signed-off-by: Bruce Ashfield

image-oci: add multi-layer OCI image support with OCI_LAYERS

2026-02-09T03:32:52+00:00

Add support for creating multi-layer OCI images with explicit layer definitions via OCI_LAYERS variable. This enables fine-grained control over container layer composition. New variables: - OCI_LAYER_MODE: Set to "multi" for explicit layer definitions - OCI_LAYERS: Define layers as "name:type:content" entries - packages: Install specific packages in a layer - directories: Copy directories from IMAGE_ROOTFS - files: Copy specific files from IMAGE_ROOTFS Package installation uses Yocto's package manager classes (RpmPM, OpkgPM) for consistency with do_rootfs, rather than calling dnf/opkg directly. Example usage: OCI_LAYER_MODE = "multi" OCI_LAYERS = "\ base:packages:base-files+base-passwd+netbase \ shell:packages:busybox \ app:packages:curl \ " This creates a 3-layer OCI image with discrete base, shell, and app layers that can be shared and cached independently. Signed-off-by: Bruce Ashfield

docs: add OCI multi-layer and vshell documentation

2026-02-09T03:32:52+00:00

Update container-bundling.md with: - New "OCI Multi-Layer Images" section explaining: - Single vs multi-layer image differences - OCI_BASE_IMAGE usage (recipe name or path) - OCI_IMAGE_CMD vs OCI_IMAGE_ENTRYPOINT behavior - When to use CMD (base images) vs ENTRYPOINT (wrapper tools) Signed-off-by: Bruce Ashfield