Adopting usrmerge filesystem layout for /lib.

Hello, 

TL;DR: Chainguard is finalizing the adoption of the “usrmerge” filesystem layout, focusing on libraries. We started this process in March to enhance standardization and compatibility with modern Linux applications and other major distributions. This email provides more details on the final actions you'll need to take.

Take action if:

• You use apko, melange, or the bazel apko rules, you’ll need to update those tools.

• You ran into issues with the previous usrmerge changes, review mitigation strategies.

Be aware of:

• New version of apk-tools

• Anything trying to bootstrap a /lib directory outside of Chainguard supported tools.

To enhance standardization and compatibility with modern Linux applications and major Linux distributions, Chainguard has been adopting the "usrmerge" filesystem layout in Chainguard OS and Wolfi. This layout consolidates binaries and libraries into the /usr directory structure. The final stage of this transition is focused on consolidating libraries into /usr/lib.

This announcement provides you with information about the change and what to do if you have modified Chainguard container images. Background information about usrmerge is available on our Support Page, “Adopting usrmerge filesystem layout,” and at the end of this post.
 

How will this affect me?

If you use Chainguard tools, please update to the versions listed below (or greater) before this transition to avoid issues. Existing and new tools will continue to work for existing workflows.

• apko >= v0.27.6

• melange >= v0.23.15

• rules_apko for bazel >= v1.5.3
   

Other than underlying image changes, we expect little to no impact to you when using Chainguard container images:

• Images created before the start of the transition will not be impacted.

• Images created after the transition will have binaries or libraries shipped in usrmerged locations with appropriate symlinks back.

• Images that include “apk-tools” will ship with a patched version that includes support for usrmerged lib locations.
   

If you use “apk add” in your Dockerfiles:

• APK should resolve to a package revision previous to its usrmerge transition, while the transition is incomplete (and you have a non-usrmerged image).

• APK should resolve to a package revision of a usrmerged package after the transition is complete (and you have a usrmerged image).

What should I do or be aware of?

• Avoid using “apk add <package>=<version>” and “apk upgrade” to force the installation of any packages being transitioned, including wolfi-baselayout.

  • As of today, “apk add” cannot assure package interdependence with those available within the image, even before this transition.

  • We discourage the usage of “apk upgrade”.

  • If you attempt to add/upgrade new usrmerged packages during or after this transition, this may result in:

    • Packages being unable to install, or

    • Packages being installed with errors, at which point we cannot assure they will work as expected.

• A patched version of apk-tools v2.14.10-3 is provided to handle the transition when using “apk –initdb”

  • This version is compatible with both new and old filesystem layouts.
     

• Ensure you are not moving binaries, libraries or creating symlinks to usrmerged locations in your Dockerfiles. These practices can sometimes lead to unexpected issues and lead to unsupported scenarios. If you have any questions, feel free to ask!

Why is Chainguard making this change?

At Chainguard, we haven’t adopted a specific filesystem layout until now. As a result, we hadn’t enforced usrmerge guidelines. This has translated into some packages and images shipping files (binaries or libraries) in legacy directories, while others under usr directories require the creation of symlinks for compatibility with usrmerge.

As we continue to expand our catalog, we believe that standardization and compatibility is key for our customers to ease migration to Chainguard products.

Need help or have questions?

Please contact your Technical Success Manager should you require more information. If you need immediate help, reach out through our support portal at support.chainguard.dev or via support@chainguard.dev.

-Your Chainguard Team