Apple Containerization

The Containerization package allows applications to use Linux containers by executing them inside lightweight virtual machines. It provides Swift APIs for several core container operations:

• OCI Image Management: Manage OCI images and interact with remote registries.
• Filesystem Operations: Create and populate ext4 file systems.
• Networking: Interact with the Netlink socket family.
• Kernel Management: Create optimized Linux kernels for fast boot times.
• Runtime Management: Spawn lightweight virtual machines and manage the runtime environment.
• Process Management: Spawn and interact with containerized processes.
• Architecture Support: Use Rosetta 2 for running linux/amd64 containers on Apple silicon.

On macOS, it uses Virtualization.framework. On Linux, it uses cloud-hypervisor + KVM.

ContainerizationEXT4 is a specialized toolset designed for ext4 filesystem operations within containerized environments. It provides two primary capabilities:

1. Read Superblock: Inspect and read the superblock of an existing ext4 block device.
2. Format Device: Format a new block device with the ext4 filesystem.

Requirements

• Platform: The library compiles on macOS and Linux, but the cloud-hypervisor binary itself only runs on Linux.
• Dependencies: Requires swift-nio and swift-log.

Compatibility

• Target API: /api/v1/ REST namespace.
• Minimum Version: Tested against cloud-hypervisor v40 and later. Earlier versions may have incompatible JSON schemas or missing endpoints.

Before running make dist-x86_64, ensure the following are configured:

1. Pinned Source Checkouts: Manually clone required dependencies into the .local/ directory. The build does not fetch them automatically.

   git clone -b v52.0 https://github.com/cloud-hypervisor/cloud-hypervisor .local/cloud-hypervisor
   git clone https://gitlab.com/virtio-fs/virtiofsd .local/virtiofsd

2. x86_64 Kernel: An x86_64 kernel must exist at kernel/vmlinuz-x86_64 or kernel/vmlinux-x86_64. You can build it using:

   make -C kernel TARGET_ARCH=x86_64

3. Linux Dev Image: The build depends on the linux-image target. The first run will automatically handle the container build cache for the dev image.

To interact with the cloud-hypervisor REST API over a Unix domain socket, instantiate a CloudHypervisor.Client. You must provide a socketPath as a URL pointing to the .sock file.

By default, the client manages its own MultiThreadedEventLoopGroup and shuts it down on deinit. If you want to provide your own eventLoopGroup (e.g., to share resources with other NIO-based libraries), pass it via the eventLoopGroup: parameter. Note that if you provide your own group, the client will not shut it down on deinit.

import CloudHypervisor
import NIOPosix

let group = MultiThreadedEventLoopGroup(numberOfThreads: 2)
defer { try? group.syncShutdownGracefully() }

let client = try CloudHypervisor.Client(
    socketPath: URL(filePath: "/run/ch/vm0.sock"),
    eventLoopGroup: group
)

You can provide your own kernel to Containerization. If using a pre-built kernel, ensure it has VIRTIO drivers compiled directly into the kernel (not as modules).

Recommended Source: The Kata Containers project provides an optimized Linux kernel. Artifacts can be found on their releases page, or the image vmlinux.container can be located at /opt/kata/share/kata-containers/.

Containerization uses grpc-swift and swift-protobuf. Use the following commands for maintenance tasks:

Regenerate RPC interfaces:

make protos

Generate and view local API documentation:

make docs
make serve-docs

After running make serve-docs, preview the documentation at http://localhost:8000/containerization/documentation/.

make protos

make docs
make serve-docs
# Then open http://localhost:8000/containerization/documentation/

When using the Linux backend (CHVirtualMachineManager), the following requirements must be met on the host:

• Binaries: cloud-hypervisor and virtiofsd must be available on PATH. You can provide explicit URLs to CHVirtualMachineManager.init to override default lookups.
• KVM Access: The calling user must have read and write access to /dev/kvm.
• Networking: You are responsible for pre-staging TAP, bridge, or NAT plumbing. The TAPInterface type consumes an existing TAP device by name.
• Storage: Uses virtio-blk for block storage and virtio-fs (via virtiofsd) for shared directories.

To build the Containerization package on macOS, ensure you meet these requirements:

Hardware/Software Requirements:

• Mac with Apple silicon
• macOS 26
• Xcode 26

Setup Steps:

1. Set the active developer directory to your installed Xcode:

sudo xcode-select -s <PATH_TO_XCODE>

2. Install the container CLI (from apple/container) and ensure it is on your PATH. This is used to compile the Linux guest (vminitd/vmexec) inside a Linux container, so you do not need a Swift toolchain or Static Linux SDK on your host.

container --version

sudo xcode-select -s <PATH_TO_XCODE>

# Install per https://github.com/apple/container, then verify it is on PATH:
container --version

Use make dist-x86_64 to produce a self-contained x86_64 Linux deployment tarball located at bin/containerization-x86_64-<sha>.tar.gz. This build runs inside the aarch64 Linux dev container and requires make and container on the host.

The resulting tarball contains:

• cctl host binary (static musl)
• cloud-hypervisor VMM (static musl)
• virtiofsd filesystem daemon (dynamic glibc)
• An x86_64 Linux kernel
• initfs.ext4 guest rootfs (containing vminitd + vmexec)

Deployment Host Requirements: Because virtiofsd is dynamically linked, the target host must provide:

• glibc ≥ 2.35 (e.g., Ubuntu 22.04, Debian 12, RHEL 9)
• libseccomp.so.2
• libcap-ng.so.0

The build target is controlled by the TARGET_ARCH make variable. If unset, the build defaults to the host architecture (normalizing aarch64 to arm64 and amd64 to x86_64).

Available Architectures:

• arm64: Produces vmlinux-arm64 (an uncompressed Image).
• x86_64: Produces vmlinuz-x86_64 (a compressed bzImage). This is cross-compiled inside the arm64 container.

Commands:

• Build for host: make
• Build for arm64: make TARGET_ARCH=arm64
• Build for x86_64: make TARGET_ARCH=x86_64 or the alias make x86_64.

Resulting kernels are placed in the bin/ directory.