From fbfb34768846726e4f1508914c62be207204e2aa Mon Sep 17 00:00:00 2001 From: Jonathan Lebon Date: Mon, 8 Jun 2026 10:30:13 -0400 Subject: [PATCH] Cargo.toml: bump version to v0.6.0 --- Cargo.lock | 2 +- Cargo.toml | 2 +- README-dev.md | 2 +- README.md | 66 ++++++++++++++++++++++++++---------------- packaging/chunkah.spec | 2 +- 5 files changed, 45 insertions(+), 29 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 8b307a9..dba3b9b 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -187,7 +187,7 @@ dependencies = [ [[package]] name = "chunkah" -version = "0.5.0" +version = "0.6.0" dependencies = [ "anyhow", "camino", diff --git a/Cargo.toml b/Cargo.toml index dccaf0f..eeebc1f 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "chunkah" -version = "0.5.0" +version = "0.6.0" description = "An OCI building tool for content-based layers" authors = ["Jonathan Lebon "] repository = "https://github.com/coreos/chunkah" diff --git a/README-dev.md b/README-dev.md index b785bd7..3a7df6c 100644 --- a/README-dev.md +++ b/README-dev.md @@ -112,7 +112,7 @@ use the `Containerfile.splitter`, passing the target image as the `--from`: IMG=quay.io/fedora/fedora-minimal:latest buildah build --skip-unused-stages=false --from $IMG \ --build-arg CHUNKAH_CONFIG_STR="$(podman inspect $IMG)" \ - https://github.com/coreos/chunkah/releases/download/v0.5.0/Containerfile.splitter + https://github.com/coreos/chunkah/releases/download/v0.6.0/Containerfile.splitter ``` Additional arguments can be passed to chunkah using the CHUNKAH_ARGS build diff --git a/README.md b/README.md index 68a5e6e..e617cea 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,7 @@ with content-based layers. - [Understanding components](#understanding-components) - [Customizing the layers](#customizing-the-layers) - [Limiting the number of layers](#limiting-the-number-of-layers) + - [Output options](#output-options) - [Building from a raw rootfs](#building-from-a-raw-rootfs) - [Customizing the OCI image config and annotations](#customizing-the-oci-image-config-and-annotations) - [Pruning and filtering](#pruning-and-filtering) @@ -102,7 +103,7 @@ use the `Containerfile.splitter`, passing the target image as the `--from`: IMG=quay.io/fedora/fedora-minimal:latest buildah build --skip-unused-stages=false --from $IMG \ --build-arg CHUNKAH_CONFIG_STR="$(podman inspect $IMG)" \ - https://github.com/coreos/chunkah/releases/download/v0.5.0/Containerfile.splitter + https://github.com/coreos/chunkah/releases/download/v0.6.0/Containerfile.splitter ``` Additional arguments can be passed to chunkah using the CHUNKAH_ARGS build @@ -113,7 +114,8 @@ argument. > RFE][buildah-rfe]). > > For Buildah versions before v1.44, this also requires `-v $(pwd):/run/src -> --security-opt=label=disable`. +> --security-opt=label=disable`. Note that this will leave behind an `out/` +> directory in the current directory. Another option is using the chunkah image directly and image mounts: @@ -130,6 +132,11 @@ The `-t`/`--tag` option sets the image name in the OCI archive so that `podman load` automatically tags the loaded image. Without it, the image is loaded as an unnamed image identified only by its digest. +For large images, this approach is less efficient than using +`Containerfile.splitter`, which avoids the overhead of tarring and untarring +the OCI archive (though the same efficiency can be gained by using +[`--output oci:PATH`](#output-options) and importing it using `skopeo copy`.) + #### Using Docker/Moby You can use the chunkah image directly using image mounts (requires v28+): @@ -157,9 +164,9 @@ docker load -i out.dockerarchive ### Splitting an image at build time (buildah/podman only) -This uses a method called the "`FROM oci-archive:` trick", for lack of a better -term. It has the massive advantage of being compatible with a regular `buildah -build` flow and also makes it more natural to apply configs to the image, but is +This uses a method called the "`FROM oci:` trick", for lack of a better term. +It has the massive advantage of being compatible with a regular `buildah build` +flow and also makes it more natural to apply configs to the image, but is specific to the Podman ecosystem. This *will not* work with Docker. ```Dockerfile @@ -173,11 +180,11 @@ RUN dnf install -y git-core && dnf clean all FROM quay.io/coreos/chunkah AS chunkah ARG CHUNKAH_CONFIG_STR -RUN --mount=from=builder,src=/,target=/chunkah,ro \ - --mount=type=bind,target=/run/src,rw \ - chunkah build > /run/src/out.ociarchive +RUN --mount=type=bind,target=/run/src,rw \ + --mount=from=builder,target=/chunkah,ro \ + chunkah build --output oci:/run/src/out -FROM oci-archive:out.ociarchive +FROM oci:out ENTRYPOINT ["git"] ``` @@ -187,7 +194,8 @@ ENTRYPOINT ["git"] > `--jobs` option. > > For Buildah versions before v1.44, this also requires `-v $(pwd):/run/src -> --security-opt=label=disable`. +> --security-opt=label=disable`. Note that this will leave behind an `out/` +> directory in the current directory. > [!NOTE] @@ -251,6 +259,25 @@ content-based layers. Too many layers may mean excessive processing and overhead when pushing/pulling the image. Note that containers-storage has a hard limit of 500 layers. +### Output options + +By default, chunkah writes an OCI archive to stdout. The `-o`/`--output` flag +controls where and in what format the image is written. It supports an optional +transport prefix: + +- `--output PATH` or `--output oci-archive:PATH` — write an OCI archive to a + file instead of stdout. +- `--output oci:PATH` — write the OCI directory layout directly to disk. This + avoids the overhead of tarring and untarring the archive, which is + particularly useful in the buildah `FROM oci:` flow (see [Splitting an image + at build time](#splitting-an-image-at-build-time-buildahpodman-only)). + +By default, layers are uncompressed (since in the common case the OCI +archive/directory is immediately imported into a container storage backend, +which would immediately uncompress it). Use `--compressed` to enable gzip +compression for layers (and the OCI archive itself, if applicable). The +compression level can be tuned with `--compression-level` (0-9, default 6). + ### Building from a raw rootfs For completeness, note it's of course also possible to split any arbitrary @@ -267,13 +294,8 @@ podman run --rm -v /path/to/rootfs:/chunkah:z \ > be expensive for a large rootfs. You can use `--security-opt=label=disable` to > avoid this, but it disables SELinux separation with the chunkah container. -When running chunkah directly in this way, the OCI archive is written to stdout -by default. Use `-o`/`--output` to write to a file instead (whose directory -would then have to be mounted in). - -By default, layers and the OCI archive are uncompressed. Use `--compressed` -to enable gzip compression for both. The compression level can be tuned with -`--compression-level` (0-9, default 6). +See [Output options](#output-options) for controlling the output format and +compression. ### Customizing the OCI image config and annotations @@ -354,17 +376,11 @@ RUN --mount=from=builder,src=/,target=/chunkah,ro \ --mount=type=bind,target=/run/src,rw \ chunkah build --prune /sysroot/ --max-layers 128 \ --label ostree.commit- --label ostree.final-diffid- \ - > /run/src/out.ociarchive + --output oci:/run/src/out -FROM oci-archive:out.ociarchive +FROM oci:out ``` -> [!NOTE] -> A minimum version of `bootc` is required for using chunkah -> chunked images. Those are [v1.1.3](https://github.com/bootc-dev/bootc/commit/c49ccec5050a2905f8967852b8ca48502a6d4c13) -> for chunkah with <= 128 layers and [v1.9.0](https://github.com/bootc-dev/bootc/commit/207b7f0abfc2cc683dd69a054e625d03abfaf8fd) -> for chunkah with > 128 layers. - ### Debugging Use `-v` for verbose output or the `RUST_LOG` environment variable for diff --git a/packaging/chunkah.spec b/packaging/chunkah.spec index 3f10d61..0b0efb1 100644 --- a/packaging/chunkah.spec +++ b/packaging/chunkah.spec @@ -1,7 +1,7 @@ %global crate chunkah Name: chunkah -Version: 0.5.0 +Version: 0.6.0 Release: %autorelease Summary: OCI building tool for content-based container image layers