diff --git a/README.md b/README.md index e4b8b3c..8ee68d9 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # unbase_oci: Streamline OCI Container Images The **unbase OCI tool** is designed to streamline container images by eliminating unnecessary components inherited from the base container, thereby reducing bloat and enhancing security. -It essentially produces a so called *"distroless"* container image. +It produces [bare container images](https://github.com/gardenlinux/gardenlinux/blob/main/docs/01_developers/bare_container.md). Operating on OCI archives, the tool performs a thorough comparison between a base image and a target image. It identifies additions made to the target image in relation to the base image, as well as the dependencies of these additions. The tool then strips away extraneous elements, resulting in a minimized target image. @@ -57,10 +57,10 @@ Options: ## Example Usage -For instance, consider building a container on top of a Debian base. Let's assume `debian.oci` represents an exported OCI archive of the Debian base image, while `container.oci` is an exported OCI archive of the target image. To create a *"distroless"* variant of the target container, containing only the dependencies of explicitly installed components on top of Debian (e.g.: libc), execute: +For instance, consider building a container on top of a Debian base. Let's assume `debian.oci` represents an exported OCI archive of the Debian base image, while `container.oci` is an exported OCI archive of the target image. To create a *bare* variant of the target container, containing only the dependencies of explicitly installed components on top of Debian (e.g.: libc), execute: ```shell -./unbase_oci --ldd-dependencies debian.oci container.oci container_distroless.oci +./unbase_oci --ldd-dependencies debian.oci container.oci container_bare.oci ``` For a more comprehensive example, please refer to the detailed guide in [example/htop](example/htop/README.md). This will further illustrate the tool's functionality in practice. diff --git a/example/htop/README.md b/example/htop/README.md index e02bf75..e33d6d1 100644 --- a/example/htop/README.md +++ b/example/htop/README.md @@ -1,6 +1,6 @@ # unbase_oci: Guided Example (htop) -This guide demonstrates the utilization of the `unbase_oci` tool to construct a *"distroless"* container image for the `htop` utility program. +This guide demonstrates the utilization of the `unbase_oci` tool to construct a *bare* container image for the `htop` utility program. Creating a container image to run htop is a straightforward process, achieved with the following `Containerfile`: @@ -28,16 +28,16 @@ podman save --format oci-archive htop > htop.oci Subsequently, we can initiate the `unbase_oci` tool: ```shell -./unbase_oci --dpkg-dependencies debian.oci htop.oci htop_distroless.oci +./unbase_oci --dpkg-dependencies debian.oci htop.oci htop_bare.oci ``` -This operation generates a fresh oci archive, named htop_distroless.oci, encompassing only the requisite components from htop.oci. The debian base layer is minimized as much as possible. To validate the container image, load it into podman: +This operation generates a fresh oci archive, named htop_bare.oci, encompassing only the requisite components from htop.oci. The debian base layer is minimized as much as possible. To validate the container image, load it into podman: ```shell -podman load < htop_distroless.oci +podman load < htop_bare.oci ``` -This step provides the sha256 hash sum of the imported image, enabling its tagging with `podman tag IMAGE_HASH htop:distroless`. However, executing the image using `podman run --rm -it --pid host htop:distroless` results in an error: +This step provides the sha256 hash sum of the imported image, enabling its tagging with `podman tag IMAGE_HASH htop:bare`. However, executing the image using `podman run --rm -it --pid host htop:bare` results in an error: ``` Error opening terminal: xterm. @@ -54,25 +54,25 @@ ncurses-base Subsequently, re-run `unbase_oci`, this time incorporating the `--dpkg-include` flag: ```shell -./unbase_oci --dpkg-dependencies --dpkg-include dpkg_include debian.oci htop.oci htop_distroless.oci +./unbase_oci --dpkg-dependencies --dpkg-include dpkg_include debian.oci htop.oci htop_bare.oci ``` Now, proceed to reload and tag the image: ```shell -podman load < htop_distroless.oci -podman tag IMAGE_HASH htop:distroless +podman load < htop_bare.oci +podman tag IMAGE_HASH htop:bare ``` (Ensure the new hash output from `podman load` is employed, replacing the previous one.) -Upon executing `podman run --rm -it --pid host htop:distroless`, `htop` functions seamlessly. +Upon executing `podman run --rm -it --pid host htop:bare`, `htop` functions seamlessly. To gauge the impact of the container slimming process, refer to `podman image list htop`. The output will resemble the following: ``` REPOSITORY TAG IMAGE ID SIZE -localhost/htop distroless 1fa393aa45c2 45.4 MB +localhost/htop bare 1fa393aa45c2 45.4 MB localhost/htop latest 5c62748f7b15 165 MB ``` @@ -104,14 +104,14 @@ The file specifies regex patterns; paths matching any of these patterns will be Proceed with the following command: ```shell -./unbase_oci --include include --ldd-dependencies debian.oci htop.oci htop_distroless.oci +./unbase_oci --include include --ldd-dependencies debian.oci htop.oci htop_bare.oci ``` Once more, load and tag the image: ```shell -podman load < htop_distroless.oci -podman tag IMAGE_HASH htop:distroless +podman load < htop_bare.oci +podman tag IMAGE_HASH htop:bare ``` This action similarly yields a functional htop container image. @@ -120,7 +120,7 @@ A review of `podman image list htop` shows an even more substantial image size r ``` REPOSITORY TAG IMAGE ID SIZE -localhost/htop distroless 9efb3ca1d364 23.2 MB +localhost/htop bare 9efb3ca1d364 23.2 MB localhost/htop latest 5c62748f7b15 165 MB ``` @@ -140,7 +140,7 @@ var/log Subsequently, execute `unbase_oci` once more: ```shell -./unbase_oci --include include --exclude exclude --ldd-dependencies debian.oci htop.oci htop_distroless.oci +./unbase_oci --include include --exclude exclude --ldd-dependencies debian.oci htop.oci htop_bare.oci ``` This ultimate optimization step culminates in an impressive image size reduction of 97%. diff --git a/example/htop/run_example b/example/htop/run_example index 097c66b..93d24e2 100755 --- a/example/htop/run_example +++ b/example/htop/run_example @@ -29,14 +29,14 @@ podman save --format oci-archive debian > debian.oci podman build --arch "$arch" --tag htop . podman save --format oci-archive htop > htop.oci -../../unbase_oci --container-image "$container_image" --exclude exclude --dpkg-dependencies --dpkg-include dpkg_include --print-tree debian.oci htop.oci htop_distroless_dpkg.oci -image="$(podman load < htop_distroless_dpkg.oci | awk '{ print $NF }')" -podman tag "$image" htop:distroless_dpkg -podman run --rm htop:distroless_dpkg htop --version - -../../unbase_oci --container-image "$container_image" --include include --exclude exclude --ldd-dependencies --print-tree debian.oci htop.oci htop_distroless.oci -image="$(podman load < htop_distroless.oci | awk '{ print $NF }')" -podman tag "$image" htop:distroless -podman run --rm htop:distroless htop --version +../../unbase_oci --container-image "$container_image" --exclude exclude --dpkg-dependencies --dpkg-include dpkg_include --print-tree debian.oci htop.oci htop_bare_dpkg.oci +image="$(podman load < htop_bare_dpkg.oci | awk '{ print $NF }')" +podman tag "$image" htop:bare_dpkg +podman run --rm htop:bare_dpkg htop --version + +../../unbase_oci --container-image "$container_image" --include include --exclude exclude --ldd-dependencies --print-tree debian.oci htop.oci htop_bare.oci +image="$(podman load < htop_bare.oci | awk '{ print $NF }')" +podman tag "$image" htop:bare +podman run --rm htop:bare htop --version podman image list --sort size localhost/htop diff --git a/example/sapmachine/run_example b/example/sapmachine/run_example index 8bb4921..e3c21cd 100755 --- a/example/sapmachine/run_example +++ b/example/sapmachine/run_example @@ -29,10 +29,10 @@ podman save --format oci-archive debian > debian.oci podman build --arch "$arch" --tag sapmachine . podman save --format oci-archive sapmachine > sapmachine.oci -../../unbase_oci --container-image "$container_image" --exclude exclude --ldd-dependencies --print-tree debian.oci sapmachine.oci sapmachine_distroless.oci -image="$(podman load < sapmachine_distroless.oci | awk '{ print $NF }')" -podman tag "$image" sapmachine:distroless -podman run --rm sapmachine:distroless /opt/sapmachine-jre-20.0.2/bin/java --version +../../unbase_oci --container-image "$container_image" --exclude exclude --ldd-dependencies --print-tree debian.oci sapmachine.oci sapmachine_bare.oci +image="$(podman load < sapmachine_bare.oci | awk '{ print $NF }')" +podman tag "$image" sapmachine:bare +podman run --rm sapmachine:bare /opt/sapmachine-jre-20.0.2/bin/java --version if [ ! -e hello.jar ]; then native_arch="$(podman system info --format json | jq -r '.host.arch')" @@ -41,6 +41,6 @@ if [ ! -e hello.jar ]; then podman run --rm -v "$PWD:/mnt" java bash -c 'cd /mnt && javac HelloWorld.java && jar -c -e HelloWorld -f hello.jar HelloWorld.class' fi -podman run --rm -v "$PWD/hello.jar:/hello.jar" sapmachine:distroless /opt/sapmachine-jre-20.0.2/bin/java -jar /hello.jar +podman run --rm -v "$PWD/hello.jar:/hello.jar" sapmachine:bare /opt/sapmachine-jre-20.0.2/bin/java -jar /hello.jar podman image list --sort size localhost/sapmachine