A guide on how to use Chainguard Images for public catalog 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 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:

-- CODE language-bash -- 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.

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:

-- CODE language-bash -- 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.9MB

-- CODE language-bash -- docker inspect --format='{{index .RepoDigests 0}}' cgr.dev/chainguard/wolfi-base cgr.dev/chainguard/wolfi-base@sha256:490977f0fd3d8596d173839dbb314153797312553b43f6a24b0e341cf2e8d473

The digest for remote images can be looked up with the crane tool:

-- CODE language-bash -- crane digest cgr.dev/chainguard/redis:latest sha256:09cb89c668875973d5251953bc00447950b1cff1ff1395f9b9ae564c4b105ff5

Note 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:

-- CODE language-bash -- $ crane digest --platform linux/arm64 cgr.dev/chainguard/redis:latest sha256:48c1a19670e4bfd4e3087cd45dc741adfe4498856b3907ea6db1aa338cde0f26 $ docker manifest | jq -r '.manifests[] | select(.platform.architecture=="arm64") | .digest' sha256:48c1a19670e4bfd4e3087cd45dc741adfe4498856b3907ea6db1aa338cde0f26

Users 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:

-- CODE language-bash -- $ 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-r0

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

-- CODE language-bash -- $ 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.json

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.

-- CODE language-bash -- 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" ]

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.