container-bundle: add package-based container bundling support

This class creates installable packages that bundle pre-processed
container images. When installed via IMAGE_INSTALL, containers are
automatically merged into the target image's container storage.

Component relationships for bundling a local container:

  1. Application Recipe (builds the software)
     recipes-demo/myapp/myapp_1.0.bb
     - Compiles application binaries
     - Creates installable package (myapp)

  2. Container Image Recipe (creates OCI image containing the app)
     recipes-demo/images/myapp-container.bb
     - inherit image image-oci
     - IMAGE_INSTALL = "myapp"
     - Produces: ${DEPLOY_DIR_IMAGE}/myapp-container-latest-oci/

  3. Bundle Recipe (packages container images for deployment)
     recipes-demo/bundles/my-bundle_1.0.bb
     - inherit container-bundle
     - CONTAINER_BUNDLES = "myapp-container:autostart"
     - Creates installable package with OCI data

Flow: application recipe -> container image recipe -> bundle recipe
      -> IMAGE_INSTALL in host image -> container deployed on target

Usage:
    inherit container-bundle
    CONTAINER_BUNDLES = "myapp-container:autostart redis-container"

CONTAINER_BUNDLES format: source[:autostart-policy]
  - source: Container IMAGE recipe name or remote registry URL
  - autostart-policy: Optional (autostart, always, unless-stopped, on-failure)

Features:
- Auto-generates dependencies on container image recipes (do_image_complete)
- Supports remote containers via skopeo (requires CONTAINER_DIGESTS)
- Runtime auto-detected from CONTAINER_PROFILE (docker/podman)
- Produces OCI directories and metadata for container-cross-install

Signed-off-by: Bruce Ashfield <bruce.ashfield@gmail.com>

2 files changed, 118 insertions, 0 deletions

diff --git a/recipes-extended/container-bundles/example-container-bundle_1.0.bb b/recipes-extended/container-bundles/example-container-bundle_1.0.bb
new file mode 100644
index 00000000..a91e4609
--- /dev/null
+++ b/recipes-extended/container-bundles/example-container-bundle_1.0.bb
@@ -0,0 +1,68 @@
+# example-container-bundle_1.0.bb
+# ===========================================================================
+# Example container bundle recipe demonstrating container-bundle.bbclass
+# ===========================================================================
+#
+# This recipe shows how to create a package that bundles containers.
+# When installed via IMAGE_INSTALL, the containers are automatically
+# merged into the target image's container storage.
+#
+# Usage in image recipe (e.g., container-image-host.bb):
+#   IMAGE_INSTALL += "example-container-bundle"
+#
+# Or in local.conf (use pn- override for specific images):
+#   IMAGE_INSTALL:append:pn-container-image-host = " example-container-bundle"
+#
+# IMPORTANT: Do NOT use global IMAGE_INSTALL:append without pn- override!
+# This causes circular dependencies when container images try to include
+# the bundle that depends on them.
+#
+# ===========================================================================
+
+SUMMARY = "Example container bundle"
+DESCRIPTION = "Demonstrates container-bundle.bbclass by bundling the \
+               container-base image. Use this as a template for your \
+               own container bundles."
+HOMEPAGE = "https://github.com/anthropics/meta-virtualization"
+LICENSE = "MIT"
+LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
+
+inherit container-bundle
+
+# Define containers to bundle
+# Format: source[:autostart-policy]
+#
+# source: Either a local recipe name or registry URL
+#   - Local: "container-base" (simple recipe name)
+#   - Remote: "docker.io/library/alpine:3.19" (registry URL)
+#
+# autostart: (optional) autostart | always | unless-stopped | on-failure
+#
+# Runtime is determined automatically from CONTAINER_PROFILE (or CONTAINER_BUNDLE_RUNTIME)
+
+# Bundle the test containers we've been using:
+# - container-base: minimal busybox container
+# - container-app-base: busybox with app structure
+# - autostart-test-container: container that logs startup for autostart testing
+CONTAINER_BUNDLES = "\
+    container-base \
+    container-app-base \
+    autostart-test-container:autostart \
+"
+
+# Override runtime if needed (uncomment to force a specific runtime):
+# CONTAINER_BUNDLE_RUNTIME = "podman"
+
+# For remote containers (not used in this example), you MUST provide digests:
+# CONTAINER_DIGESTS[docker.io/library/redis:7] = "sha256:e422889e156e..."
+#
+# Get the digest with:
+#   skopeo inspect docker://docker.io/library/redis:7 | jq -r '.Digest'
+
+# Example with multiple containers and autostart:
+# CONTAINER_BUNDLES = "\
+#     myapp:autostart \
+#     mydb \
+#     docker.io/library/redis:7 \
+# "
+# CONTAINER_DIGESTS[docker.io/library/redis:7] = "sha256:e422889..."
diff --git a/recipes-extended/container-bundles/remote-container-bundle_1.0.bb b/recipes-extended/container-bundles/remote-container-bundle_1.0.bb
new file mode 100644
index 00000000..7da267e5
--- /dev/null
+++ b/recipes-extended/container-bundles/remote-container-bundle_1.0.bb
@@ -0,0 +1,50 @@
+# SPDX-FileCopyrightText: Copyright (C) 2025 Bruce Ashfield
+#
+# SPDX-License-Identifier: MIT
+#
+# remote-container-bundle_1.0.bb
+# ===========================================================================
+# Test recipe for remote container fetching via container-bundle.bbclass
+# ===========================================================================
+#
+# This recipe demonstrates and tests fetching containers from a remote
+# registry during the Yocto build. The container is pulled via skopeo
+# and bundled into a package that can be installed into target images.
+#
+# Usage in image recipe:
+#   IMAGE_INSTALL += "remote-container-bundle"
+#
+# Or in local.conf:
+#   IMAGE_INSTALL:append:pn-container-image-host = " remote-container-bundle"
+#
+# The container will be available as "busybox:1.36" in the target's
+# Docker/Podman storage after boot.
+#
+# ===========================================================================
+
+SUMMARY = "Remote container bundle test"
+DESCRIPTION = "Tests container-bundle.bbclass remote container fetching. \
+               Pulls busybox from docker.io and bundles it for installation."
+HOMEPAGE = "https://github.com/anthropics/meta-virtualization"
+LICENSE = "MIT"
+LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
+
+inherit container-bundle
+
+# Remote container from Docker Hub
+# Using busybox as it's small (~2MB) and available for multiple architectures
+CONTAINER_BUNDLES = "\
+    docker.io/library/busybox:1.36 \
+"
+
+# REQUIRED: Pinned digest for reproducible builds
+# Get with: skopeo inspect docker://docker.io/library/busybox:1.36 | jq -r '.Digest'
+# Note: This is the multi-arch manifest digest, skopeo will select the correct arch
+# Key format: Replace / and : with _ for BitBake variable flag compatibility
+CONTAINER_DIGESTS[docker.io_library_busybox_1.36] = "sha256:768e5c6f5cb6db0794eec98dc7a967f40631746c32232b78a3105fb946f3ab83"
+
+# Note: busybox is GPL-licensed, so no LICENSE_FLAGS needed.
+# For containers with commercial licenses, you would add:
+#   LICENSE_FLAGS:append = " commercial"
+# And accept in local.conf:
+#   LICENSE_FLAGS_ACCEPTED:append = " commercial"