diff --git a/docs/source/Tutorials.rst b/docs/source/Tutorials.rst index af851b10c7..6140e91829 100644 --- a/docs/source/Tutorials.rst +++ b/docs/source/Tutorials.rst @@ -14,3 +14,4 @@ Here are a number of useful tutorials to get you up and running with Podman. If * `How to use Podman's Go RESTful bindings `_: An introduction to using our RESTful Golang bindings in an external application. * `Common network setups `_: A basic guide to common network setups for Podman. * `Socket activation `_: Learn how to run containers that support socket activation. +* `Customizing the Podman Machine OS image `_: Build and apply a custom machine OS image, for example to add package dependencies or enable emulation of additional CPU architectures. diff --git a/docs/tutorials/podman_machine_os_customization.md b/docs/tutorials/podman_machine_os_customization.md new file mode 100644 index 0000000000..d01ca9a639 --- /dev/null +++ b/docs/tutorials/podman_machine_os_customization.md @@ -0,0 +1,102 @@ +![PODMAN logo](https://raw.githubusercontent.com/containers/common/main/logos/podman-logo-full-vert.png) + +# Customizing the Podman Machine OS Image + +The Podman machine runs on a bootc-based OS image hosted at +`quay.io/podman/machine-os`. While the default image covers the most common use +cases, you may need to customize it - for example, to add extra package +dependencies, enable additional kernel modules, or extend the set of emulated +CPU architectures available inside the machine. + +This tutorial walks through building a custom machine OS image and applying it +to a Podman machine, using the addition of extra CPU architecture support beyond +the default `amd64` and `arm64` as a worked example. + +The examples below use `quay.io` as the container registry for storing and +distributing the custom image. This is not a requirement - `podman machine os +apply` supports multiple image sources and transports, so it is possible to +build and apply an image entirely locally without a remote registry. See the +[podman-machine-os-apply(1)](https://github.com/containers/podman/blob/main/docs/source/markdown/podman-machine-os-apply.1.md) +man page for the full list of supported URI forms. + +**NOTE**: `podman machine os apply` is not supported on WSL-based machines. + +## Prerequisites + +- Podman installed and working on your local system +- An account on a container registry (this tutorial uses `quay.io`) +- The version of the machine OS image you want to extend (check the + [machine-os tags](https://quay.io/repository/podman/machine-os?tab=tags) + to find the right tag) + +## Step 1: Create the Containerfile + +Create a `Containerfile` that layers your customizations on top of the base +machine OS image. Replace `` with the tag matching your current Podman +machine OS version. + +The example below installs `qemu-user-static`, which enables emulation of +additional CPU architectures such as `s390x`, `ppc64le`, and `riscv64`: + +```dockerfile +FROM quay.io/podman/machine-os: +RUN dnf -y install qemu-user-static +``` + +Add any other packages or configuration changes your use case requires in the +same Containerfile. + +**NOTE**: The base image is a bootc-compatible OS image, not a regular +application container image. Only changes that are valid for a bootc image +(installed packages, dropped-in config files, etc.) are appropriate here. + +## Step 2: Build the Custom Image + +Build the image and tag it for your registry. Replace `` and +`` with your registry username and the same version tag used in the +Containerfile. + +```console +podman build -f Containerfile -t quay.io//machine-os-custom: +``` + +## Step 3: Push the Image to a Registry + +Push the newly built image to your registry so that `podman machine os apply` +can reach it. + +```console +podman push quay.io//machine-os-custom: +``` + +## Step 4: Initialize a Podman Machine + +If you do not already have a Podman machine running, initialize and start one +now. If an existing machine is already running you can skip this step. + +```console +podman machine init --now +``` + +## Step 5: Apply the Custom OS Image + +Use `podman machine os apply` to rebase the machine onto your custom image. +The `--restart` flag stops and restarts the machine automatically so the new OS +takes effect immediately. + +```console +podman machine os apply --restart docker://quay.io//machine-os-custom: +``` + +## Verification + +Once the machine restarts, verify that the customization is in place. For the +extra-architectures example, try running a container for a non-native +architecture: + +```console +podman run --rm --platform linux/s390x docker.io/library/alpine uname -m +``` + +You should see `s390x` (or whichever architecture you chose) printed to the +console.