projectbluefin/fsdk-containers/slim-an-image

Slim an Image

Use when an image is too large, or when extending the shared SLIM recipe.

When to Use

Use when carving a smaller OCI image from FSDK, removing runtime bloat, or adding a regression assertion for removed content.

When NOT to Use

Do not use for the shell-enabled nspawn machine-image lane; its retained development environment is deliberate. Do not replace a component-based image with a package-manager overlay.

Core Process

1. Measure the artifact and identify the largest removable runtime content.
2. Reuse include/slim.yml; apply only the documented exception when required.
3. Build the affected image and run its just verify contract.
4. Add an assertion or executable smoke test for behavior that a removal or

stripping step could regress.

Rule: include include/slim.yml in every new OCI script and choose the appropriate shared command variable; do not copy/paste the recipe.

rm -rf _sizecheck
just bst artifact checkout <name>/<name>-runtime.bst --directory _sizecheck
du -sh _sizecheck && du -ah _sizecheck/usr | sort -rh | head -20
rm -rf _sizecheck

_sizecheck must be a project-relative path — the bst container only sees /src (the repo). An absolute /tmp/... path is written inside the container and lost.

Reference files

Lock it in

Add a regression assertion to just verify (the slim gates) for anything you cut that must stay gone, so it fails the build if it creeps back.

For per-image removals in slim.extra that the shared SLIM recipe does not cover, declare the path in the record's gates.forbid_paths (or gates.forbid_binaries for the basename-only shorthand) so the merge gate proves the file is absent (issue #421). The shared recipe's no-shell / no-sanitizers / no-locale-archive / no-debug-symbols regex gates are unconditional for distroless images; forbid_paths is the per-image equivalent for CLIs the binary's closure pulls in but the binary never executes.

Common Rationalizations

• “The binary ran once locally.” A one-time check does not protect the next

version bump; put the check in just verify.

• “Excluding shells removes bash.” Bash is in FSDK's runtime domain and must

be explicitly removed for distroless images.

• “Excluding debug removes the debug symbols.” It did not — ~905 KB of separated

DWARF survived it until #316 stripped it in include/slim.yml and gated it. Verify the rootfs, not the element.

• “The compose exclude: list says it is gone, so it is gone.” Two domains have now

been caught leaking. Confirm with podman export | tar -tvf.

• “The build dependency is harmless.” Confirm it is build-only and absent from

the composed runtime image.

Red Flags

• Copying a SLIM command block instead of including include/slim.yml.
• Removing CA certificates, tzdata, or required charset modules to hit a size

target.

• Stripping a prebuilt binary without a local-only execution test.

Verification

• [ ] The element uses the component minimum, never platform.bst.
• [ ] just validate, the affected image build, and just verify pass.
• [ ] The image retains CA certificates, tzdata, and the required charset set.
• [ ] New stripping or removal behavior has a durable just verify regression

check.

Reference result

base: ~73 MB rootfs → ~45 MB image after slim (measured with podman image inspect .Size), all gates green.