[UPDATE] Adopting usrmerge for /usr/sbin and /lib has been postponed

[Update] We wanted to inform you that our planned migration to the “usrmerge” filesystem layout, which affects /sbin and /usr/bin, has been postponed. The new migration date is now set for March 31, 2025.

As communicated on February 24th, 2025 (article: https://support.chainguard.dev/hc/en-us/articles/34341831779611-Adopting-usrmerge-filesystem-layout), Chainguard is adopting a usrmerge filesystem layout (matching every other enterprise Linux operating system). This 4 stage transition (/sbin, /bin, /usr/sbin, /lib) was scheduled to be completed by March 24th, 2025. Thus far, only /sbin and /usr/bin have been completed.

In an effort to reduce the impact to our customers, we have decided to postpone the completion of the transition of /usr/sbin and /lib. Before we initiate the process, we will send another update to keep you informed. Additionally, once the package building is completed, we will send a follow-up communication to all customers.

What should I do if I believe I will be impacted?

Our Customer Success team will provide detailed guidance to reduce the risk of being impacted in a follow-up communication. If you need immediate help, reach out through our support portal at support.chainguard.dev.

What are the changes?

On the day of the transition you should expect the following changes:

• All affected packages will be updated to install binaries in /usr/bin instead of /usr/sbin.
  • /usr/sbin will become a symlink to /usr/bin.

• All affected packages will be updated to install libraries in /usr/lib instead of /lib.
  • /lib will become a symlink to /usr/lib.

• Images will be updated (rebuilt) to include the changes above.

How long will this take?

We expect this transition to take up to 48hrs, from the moment the packages are updated to the moment that all images have been updated (rebuilt and published).

How will this affect me?

As communicated on February 24th, 2025 (article: https://support.chainguard.dev/hc/en-us/articles/34341831779611-Adopting-usrmerge-filesystem-layout), we expect minimal impact.

If you use “apk add” in your Dockerfiles, in normal circumstances:

• 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).

However, you will be impacted if you use  “apk add” in unexpected circumstances:

• If you are using a pre-usrmerge image (e.g. such as a pre-usrmerge epoch/unique tag) and are attempting to install/upgrade post-usrmerge package(s) (e.g by forcing or pinning a version/epoch)
  • “apk add <package>=<post-usrmerged-version>” and/or 
  • “apk upgrade” or 
  • “apk upgrade && apk add <package>”
• Or If you use a post-usrmerge image and are attempting to force install a pre-usrmerge package (e.g. by pinning an older version)”
  •  “apk add package>=<pre-usrmerged-version>”.
• Or if you are installing packages into a new root folder, and copying the root folder into the root directory of your runtime image.
  • apk add --no-cache --initdb --root /newroot $PACKAGES 

If you use Chainguard Custom Assembly you will not be affected by these changes as it's a supported mechanism for adding packages to images.

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

-Your Chainguard Team