To allow our customers and users to control our hardened image “overflow,” we have created two approval gateways that can be placed between your pipeline and ours. Digestabot, a free GitHub Action, automates upgrading your Chainguard Images to the latest version, and our Diff API feature helps engineers understand what changes are being merged when a Chainguard Image is updated.
Digestabot takes the burden of keeping Images up to date off of engineers, and works across Dockerfiles and Kubernetes manifests.
If rollouts are expensive or time consuming, it’s important to understand what benefit you may get by upgrading a Chainguard Image before deciding to do so. And that’s what we are announcing today: Diff API is more than an approval gateway, it is the perfect way to see what a new Chainguard Image contains compared to the Image already in use. It will provide all the necessary information customers need to make the right decision to upgrade the container image stack.
The Diff API allows you to understand the following differences between two Chainguard Images:
- If any APK package versions have been added, removed, or updated
- If any vulnerabilities have been added or fixed
- If the image config has changed
With this information, Chainguard Images customers can make informed decisions on when they should upgrade their Images.
So how does Diff API work?
Diff API compares two versions of an image, and returns any differences in the package versions, vulnerabilities, or image configs of the images. It’s able to do this by retrieving the SBOM for each image version and generating up-to-date vulnerability scans with Grype.
The Diff API offers insights into package changes and CVE fixes, making it much easier to make informed decisions about image updates. Learn more in the Diff API documentation on Chainguard Academy.
Follow these three steps to use the Diff API to compare the contents of two image versions:
- Authenticate with Chainguard
- Get the repo UIDs
- Get the Image digests
- Call the Diff API
You’ll need the following tools installed for this tutorial:
Step 1: Authenticate with Chainguard
Step 2: Get the Repo UIDP
First, set the repository you want to diff against:
Next, you’ll need to get the Repo UIDP for this repository to call the Diff API:
Step 3: Get the digests of Chainguard Images
Next, you’ll need the digests of the two images you want to diff. You can use the tag history api to get all of the digests previously associated with a specific tag.
In this example, we’ll diff the latest and latest-dev tags of the image specified by REPO_URL, but you can replace with any two digests you want to diff:
Step 4: Call the Diff API
Finally, call the Diff API with curl:
Why Diff API
“Speed is safety,” says Charity Majors: “... software physics are different. It's more like ice skating, or riding a bicycle: the slower you go the more dangerously you wobble.” And we agree. Chainguard Images are all about enabling teams to run secure and nimble containers.
We created the Diff API to empower our customers to make informed decisions around when they want to upgrade to the latest version of a Chainguard Image. With Diff API, customers get the best of both worlds: the ability to update an image every day if they choose to, and an understanding of when upgrading will have the most impact.