Adopting usrmerge filesystem layout

TL;DR: Chainguard is adopting “usrmerge” filesystem layout.

To enhance standardization and compatibility with modern Linux applications and other major distributions, Chainguard is adopting the "usrmerge" filesystem layout. This layout consolidates binaries and libraries into the /usr directory structure. 

This announcement provides our customers with information about the change and what to do in case you have modified images from Chainguard.

What is usrmerge?

Usrmerge refers to the adoption of a filesystem layout where legacy directories, such as /bin, /sbin, /lib are replaced with symlinks to their new locations under /usr, such as /usr/bin and /usr/lib.

Every other enterprise distro, including RHEL, CentOS, SUSE, Ubuntu, and Debian all have utilized usrmerge for nearly a decade. Alpine does not, but has plans to adopt in the future.  

What are we doing?

We are moving the contents of /sbin, /usr/sbin and /bin into /usr/bin, and libraries from /lib into /usr/lib; and corresponding symlinks.

This will be done in 4 different stages, starting with /sbin, followed by /bin, /usr/sbin and finishing with /lib.

Why are we doing this?

For standardization, compatibility and because many modern Linux applications expect usrmerged filesystem locations. 

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 & images shipping files (binaries or libraries) in legacy directories, while others under usr directories often 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 a more sustainable future.

When are we doing this?

We are aiming to start the transition on 2025-03-03 (March 3rd 2025). It is expected to take 3 weeks.

How will this affect me?

Other than underlying image changes, we expect little to no impact to you:

• Images created before the start of the transition will not be impacted at all.
• Images created after the transition will have binaries or libraries shipped in usrmerged locations with appropriate symlinks back.

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.

• 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!

When can I expect additional updates?

We take our responsibility as your trusted software supply chain partner seriously and appreciate your patience as we work to complete this transition. We will provide updates as they become available at support.chainguard.dev.

If you have any questions, please do not hesitate to contact our Support team via support.chainguard.dev.