A guide on how to use Chainguard Images for public catalog tier users
Chainguard Images, container images with zero-known vulnerabilities powered with packages from the Wolfi (un)distro, were designed to make a crucial link in the software supply chain secure by default. A previously announced policy change, which will take place on August 16, 2023, will affect all Chainguard Images public catalog users, that is, open source or “free” tier users.
Starting on August 16, pulling tags other than :latest and :latest-dev will be available only to Standard and Custom catalog tier users. All users across all tiers will continue to have access to pulling by digest. Public tier users using a tag other than :latest or :latest-dev will need to choose a migration path off of other tags.
Users will need to upgrade to a Standard or Custom catalog tier subscription to access non-latest tags (please reach out to our team to upgrade). This blog post further explains the change and actions required for users of the Chainguard Images public catalog. The blog also describes several technical approaches to using Chainguard Images and the underlying tech stack without version tags. If you have questions or run into any issues, please submit an issue on the public Chainguard Images GitHub page.
What exactly is changing?
Users of public tier Chainguard Images currently have access to all image tags for images in the public catalog. (These tags, while available, are no longer listed on the GitHub page in order to discourage new users from using non-:latest tags.) For instance, as of today, June 23, 2023 public catalog users can successfully pull cgr.dev/chainguard/python:3.10. On August 16, 2023 all tags for images in the public catalog will become unavailable except for :latest and :latest-dev tags. Users will still be able to use a digest; for instance, users will be able to successfully pull a Chainguard Python Image such as:
cgr.dev/chainguard/python@sha256:12c0aeacf184fc70e2719147885f46ced54d781ec3deeddaa80f7f9a42dc61ec.This means that projects that currently depend on tags other than :latest or :latest-dev and are public catalog users will have a broken build process without taking additional steps. If users are not yet logged into the Chainguard registry and use a tag other than :latest or :latest-dev, users will receive a 401 message. Public users that are logged in to the registry will receive a 403 error message. All customers using the Standard and Custom catalog subscriptions will be unaffected by this change.
After August 16, 2023 all users of the Chainguard Images public catalog will be unable to discover the digests associated with tags other than :latest or :latest-dev without paying for access to the Standard or Custom catalog. This means that public tier users, including open source projects, will either need to pin to the digest they currently use prior to this policy change—or migrate to the software version associated with :latest.
For instance, current users of cgr.dev/chainguard/python:3.10 will either need to pin to a digest associated with Chainguard Images Python 3.10 or will need to migrate to Python 3.11, the version currently associated with cgr.dev/chainguard/python:latest (as of June 16, 2023). We do not recommend pinning to a version for too long since it poses a long-term security risk, preventing software from incorporating security fixes that remove known vulnerabilities.
To help Chainguard Images public catalog users become aware of version changes and breaking changes, we recommend that all public catalog users authenticate to Chainguard’s container image Registry to opt-in to our notification service. In addition to notifications for major version changes, we plan to provide warnings to users when pulling images with known vulnerabilities or pulling images that have not been updated recently. Authenticating is a simple two-step process of installing our command-line tool and configuring docker with a credential helper. Follow these guidelines to get started.
How to migrate from tags other than :latest
Some users will be unable to use the latest tag, especially in production workflows, since the tag will automatically “jump” across minor and major versions without warning. For these users, we recommended using the image digest instead. The digest is a content-based hash of the image contents and is guaranteed to be immutable, always pointing to the same image. To find the digest for an image, users can run:
docker images --digests cgr.dev/chainguard/wolfi-base
REPOSITORY TAG DIGEST IMAGE ID CREATED SIZE
cgr.dev/chainguard/wolfi-base latest sha256:490977f0fd3d8596d173839dbb314153797312553b43f6a24b0e341cf2e8d473 2606ed78c658 9 days ago 10.9MBOR:
docker inspect --format='{{index .RepoDigests 0}}' cgr.dev/chainguard/wolfi-base
cgr.dev/chainguard/wolfi-base@sha256:490977f0fd3d8596d173839dbb314153797312553b43f6a24b0e341cf2e8d473The digest for remote images can be looked up with the crane tool:
crane digest cgr.dev/chainguard/redis:latest
sha256:09cb89c668875973d5251953bc00447950b1cff1ff1395f9b9ae564c4b105ff5Note that these commands are retrieving the digest of the platform independent image "index." In order to get a platform specific digest you can use docker manifest or pass the platform required to crane:
$ crane digest --platform linux/arm64 cgr.dev/chainguard/redis:latest
sha256:48c1a19670e4bfd4e3087cd45dc741adfe4498856b3907ea6db1aa338cde0f26
$ docker manifest | jq -r '.manifests[] | select(.platform.architecture=="arm64") | .digest'
sha256:48c1a19670e4bfd4e3087cd45dc741adfe4498856b3907ea6db1aa338cde0f26Users can either use the digest associated with :latest or, if necessary, a digest associated with the version tag before the August 16, 2023, policy change.
Public catalog users who are not sure if the software package versions associated with latest are compatible with their technical needs might wish to examine the software versions associated with a package image. In this case, it is recommended to examine the software bill of materials (or SBOM) using a tool like cosign. For instance, by combining cosign output with the JSON parsing tool jq a user can identify the versions of packages inside a particular image digest. For example:
$ cosign download attestation --platform=linux/amd64 --predicate-type=https://spdx.dev/Document cgr.dev/chainguard/python | jq -r .payload | base64 -d | jq -r '.predicate.packages[] | "\(.name) \(.versionInfo)"'
sha256:f77454dab622927ff95d8f993a18781301d8d1173269ac4e9ce880bf329db389 20230201
ca-certificates-bundle 20230506-r0
glibc-locale-posix 2.37-r7
wolfi-baselayout 20230201-r3
ld-linux 2.37-r7
glibc 2.37-r6
bzip2 1.0.8-r4
expat 2.5.0-r3
gdbm 1.23-r3
openssl-config 3.1.1-r1
libcrypto3 3.1.1-r1
libffi 3.4.4-r2
libgcc 13.1.0-r1
libssl3 3.1.1-r1
libstdc++ 13.1.0-r1
mpdecimal 2.5.1-r3
ncurses-terminfo-base 6.4-r2
ncurses 6.4-r2
xz 5.4.3-r0
readline 8.2-r2
sqlite-libs 3.42.0-r0
zlib 1.2.13-r3
python-3.11 3.11.4-r0Note that the above is dependent on using the –platform flag that at the time of writing isn't in a released version of cosign (but can be obtained by installing from source). Otherwise, you will need to obtain the digest of the image for your particular platform and pass it to the above (docker manifest inspect or crane digest can help here).
To find the versions of packages in an existing image, you can use the above command with the digest of the image, but the SBOM information is also contained in the image itself. For example:
$ docker run -it cgr.dev/chainguard/wolfi-base ls /var/lib/db/sbom
apk-tools-2.14.0_rc1-r0.spdx.json ld-linux-2.37-r7.spdx.json wolfi-baselayout-20230201-r3.spdx.json
busybox-1.36.1-r0.spdx.json libcrypto3-3.1.1-r1.spdx.json wolfi-keys-1-r5.spdx.json
ca-certificates-bundle-20230506-r0.spdx.json libssl3-3.1.1-r1.spdx.json zlib-1.2.13-r3.spdx.json
glibc-2.37-r6.spdx.json openssl-config-3.1.1-r1.spdx.json
glibc-locale-posix-2.37-r7.spdx.json wolfi-base-1-r3.spdx.jsonHow to build custom Images with package versions prior to `:latest`
Some projects will not be able to transition to the latest tag due to version issues, for example the differences between Python 3.10 and 3.11 or Go 1.19 and 1.20 may prevent updating immediately. In these cases we recommend users create their own Dockerfiles with the version of Wolfi packages pinned appropriately.
For example, here's a Dockerfile that creates a Go build image with Go pinned to version 1.19.10, then uses that image to build a Go project and copies the resulting binary into the Chainguard static image:
FROM cgr.dev/chainguard/wolfi-base as local_go
RUN apk update && apk add ca-certificates-bundle build-base openssh go-1.19~=1.19.10
ENTRYPOINT /usr/bin/go
FROM local_go AS build
WORKDIR /work
COPY . /work
RUN CGO_ENABLED=0 go build -o /bin/server ./
FROM cgr.dev/chainguard/static
COPY --from=build /bin/server /bin/
ENTRYPOINT [ "/bin/server" ]Note that Wolfi is a community project and there is no guarantee on how long old versions of packages will be available.
To understand which Wolfi packages are required, you can look at the Apko source for images (e.g. this file for nginx). It is also possible to build using Apko and pin package versions.
How to use Chainguard Images publica catalog without access to version tags
First, we recommend adopting a development pattern where digests are used to identify Chainguard Images and are regularly updated by a bot, ensuring that the project and its downstream users benefit from reduced vulnerability counts, bug fixes, and new features. We do this ourselves with our internal digesta-bot tool. This approach combines the stability and reproducibility of using a digest with the good security hygiene of keeping images regularly updated.
Second, Chainguard is here to assist. We will be contacting publicly available free and open source software projects on GitHub that currently use tags other than :latest and :latest-dev to inform the projects of these coming changes and to suggest a migration plan. Additionally, Chainguard will be holding Chainguard Images office hours sessions in July and August where users can discuss migration off of non-:latest versions.
Chainguard Images: Enabling open source users to ship it fast, safe, and right
Chainguard is fully committed to its mission to make the software supply chain secure by default for all users. That being said, we have to balance the cost of building and maintaining images with providing a usable and secure solution for users on the public tier.
We know these changes will disappoint some users. If you find that this change will impact how you are using our public Images, please reach out to our team and we will work with you to ensure a smooth transition. If you are an open source project and are interested in using Chainguard Images, we would love to discuss how we can support you and your project needs. If you are interested in upgrading your catalog access to our Standard or Custom catalog, please reach out to our team for support.
Ready to Lock Down Your Supply Chain?
Talk to our customer obsessed, community-driven team.