Guide for building custom node images#97
Open
HarshwardhanPatil07 wants to merge 1 commit into
Open
Conversation
HarshwardhanPatil07
force-pushed
the
docs-custom-node-images
branch
from
July 11, 2026 10:32
9cac3ed to
8ed631d
Compare
Document how to build a disk image with a custom or patched package and test it with bink. Covers two approaches: - Runtime update via bootc switch (no disk rebuild) - Full disk image rebuild for boot-critical changes Includes concrete examples for COPR repos, local RPMs, binary replacement, and building bootc from source using the bootc repo's Dockerfile with the bink node image as base. Closes: bootc-dev#91 Signed-off-by: HarshwardhanPatil07 <harshpat@redhat.com>
HarshwardhanPatil07
force-pushed
the
docs-custom-node-images
branch
from
July 11, 2026 10:47
8ed631d to
f6363ce
Compare
alicefr
reviewed
Jul 16, 2026
Comment on lines
+36
to
+43
| # Check the ostree deployment | ||
| ostree admin status | ||
|
|
||
| # Show ostree commit details | ||
| ostree show --repo=/sysroot/ostree/repo <checksum> | ||
|
|
||
| # Check the origin file (which container image the node tracks) | ||
| sudo cat /sysroot/ostree/deploy/default/deploy/*.origin |
Collaborator
There was a problem hiding this comment.
This is true for ostree but not for composefs. Can you please also add the other variant
| ```bash | ||
| bink node ssh node1 --cluster-name <name> | ||
|
|
||
| ostree admin status |
Collaborator
There was a problem hiding this comment.
can we also provide the composefs version for completness.
| - **Stage 1** (`Containerfile`): Builds a bootc OCI image from `quay.io/fedora/fedora-bootc:44`. Uses `bootc-base-imagectl build-rootfs` with `--install` flags for packages (kubernetes, CRI-O, etc.). Validated with `bootc container lint`. | ||
| - **Stage 2** (`Containerfile.disk`): Converts the bootc OCI image to a qcow2 disk using `bcvk to-disk`. The final container image contains only `/disk.qcow2` and `/images.txt`. | ||
|
|
||
| > **Important:** Do not run `podman build` directly on `node-images/fedora/Containerfile`. The `build-rootfs` command requires elevated privileges. Always use the Makefile targets (`make build-bootc-image`, `make build-disk-image`) which pass the correct flags (`--cap-add=all --security-opt=label=disable --device /dev/fuse`). |
Collaborator
There was a problem hiding this comment.
You can add this as N:B with the required flags and an example of the full podman command
| --cluster-name custom-test | ||
| ``` | ||
|
|
||
| > **Note:** COPR repos should be used as an opt-in customization for debugging and testing, not as a permanent change to the default image. Upstream COPR updates can introduce unexpected changes that break CI. |
Collaborator
There was a problem hiding this comment.
We decided to use it in order to get the latest bootc. So this sentence it somehow contradicts what we are doing :D
| NODE_IMAGE=localhost/custom-node:disk-composefs | ||
| ``` | ||
|
|
||
| ## Testing with Multiple Nodes |
Collaborator
There was a problem hiding this comment.
This is superfluous it depends on the type of bug you are investigating. I would simply drop it
Comment on lines
+315
to
+337
| ## Troubleshooting | ||
|
|
||
| ### KVM Permission Errors | ||
|
|
||
| ``` | ||
| qemu-system-x86_64: Could not access KVM kernel module: Permission denied | ||
| ``` | ||
|
|
||
| Add your user to the `kvm` group or set permissions: `sudo chmod 666 /dev/kvm`. | ||
|
|
||
| ### `bootc container lint` Failures | ||
|
|
||
| The Containerfile runs `bootc container lint` at the end. Custom modifications must preserve: | ||
| - `/sbin/init` as the entrypoint (`CMD ["/sbin/init"]`) | ||
| - Labels: `containers.bootc 1` and `ostree.bootable 1` | ||
|
|
||
| ### Disk Space | ||
|
|
||
| The qcow2 build via bcvk needs approximately 15 GB of temporary space. Free disk space or reduce the disk size with `DISK_SIZE=8G`. | ||
|
|
||
| ### COPR Repo Not Found | ||
|
|
||
| Verify the Fedora version and architecture string matches the base image. For `quay.io/fedora/fedora-bootc:44`, use `fedora-44-x86_64`. |
Collaborator
There was a problem hiding this comment.
I don't think these are really necessary. I would drop them
|
|
||
| Add your user to the `kvm` group or set permissions: `sudo chmod 666 /dev/kvm`. | ||
|
|
||
| ### `bootc container lint` Failures |
Collaborator
There was a problem hiding this comment.
Doesn't the lint already tell you what it is going wrong?
Collaborator
|
Very nice guide, thanks for writing this! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
how to build a disk image with a custom or patched package and test it with bink. Covers two approaches:
Closes: #91