From 9a88f5431d05422976a012a7e4c53c9a3af2a849 Mon Sep 17 00:00:00 2001 From: Mark Drake Date: Mon, 20 Jul 2026 10:44:29 -0700 Subject: [PATCH 1/3] https://linear.app/chainguard/issue/DOCS-72/clarify-how-helm-chart-updates-track-image-updates Signed-off-by: Mark Drake --- .../how-to-use/use-chainguard-helm-charts/index.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/content/chainguard/chainguard-images/how-to-use/use-chainguard-helm-charts/index.md b/content/chainguard/chainguard-images/how-to-use/use-chainguard-helm-charts/index.md index e61ec11fba..1d2d88bdeb 100644 --- a/content/chainguard/chainguard-images/how-to-use/use-chainguard-helm-charts/index.md +++ b/content/chainguard/chainguard-images/how-to-use/use-chainguard-helm-charts/index.md @@ -36,6 +36,15 @@ The following is an instructional guide for Chainguard users that are looking fo You can use these Helm charts with Chainguard FIPS container images, but you will need to adjust the charts as they use the non-FIPS images by default. We build a single chart per application and validate that both FIPS and non-FIPS Chainguard Images work with it. +## How chart updates deliver image updates + +Chainguard rebuilds container images regularly to pick up the latest package versions and CVE fixes. When an image updates, the associated chart updates too so that it pins the new image digests. How you receive those image updates depends on whether you reference the chart by tag or by digest: + +- **If you reference the chart by tag** (for example, `--version 10.5.13`), the tag continues to point to the latest image digests as those images update. You stay on the same chart version and pull in the latest image versions each time you install or upgrade. +- **If you pin the chart by digest**, your deployment stays fixed to the exact images that the chart referenced when you recorded that digest. To pick up newer images, update your pinned digest to the current one. + +In short, referencing a chart by tag keeps you current with the latest images automatically, while pinning by digest gives you a fixed, reproducible set of images that you update on your own schedule. The [Pin to digest](#pin-to-digest) section covers how to choose between these approaches. + ## Authentication You will need to authenticate to pull charts. These instructions explain how to use charts and images with the `cgr.dev` repository. If you have mirrored or copied the charts and images to an organization-specific registry, you will need to adapt these instructions to authenticate to your registry, as appropriate. From 1f71d76eb963aa6112226d5a7dc1f856596a6f5b Mon Sep 17 00:00:00 2001 From: Mark Drake Date: Mon, 20 Jul 2026 13:00:35 -0700 Subject: [PATCH 2/3] Clarify Helm update behavior: tags roll images forward on redeploy, digests pin Signed-off-by: Mark Drake --- .../how-to-use/use-chainguard-helm-charts/index.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/content/chainguard/chainguard-images/how-to-use/use-chainguard-helm-charts/index.md b/content/chainguard/chainguard-images/how-to-use/use-chainguard-helm-charts/index.md index 1d2d88bdeb..bbc6048d89 100644 --- a/content/chainguard/chainguard-images/how-to-use/use-chainguard-helm-charts/index.md +++ b/content/chainguard/chainguard-images/how-to-use/use-chainguard-helm-charts/index.md @@ -38,12 +38,13 @@ You can use these Helm charts with Chainguard FIPS container images, but you wil ## How chart updates deliver image updates -Chainguard rebuilds container images regularly to pick up the latest package versions and CVE fixes. When an image updates, the associated chart updates too so that it pins the new image digests. How you receive those image updates depends on whether you reference the chart by tag or by digest: +Chainguard rebuilds container images regularly to pick up the latest package versions and CVE fixes. When an image updates, the associated chart updates too so that it pins the new image digests. -- **If you reference the chart by tag** (for example, `--version 10.5.13`), the tag continues to point to the latest image digests as those images update. You stay on the same chart version and pull in the latest image versions each time you install or upgrade. -- **If you pin the chart by digest**, your deployment stays fixed to the exact images that the chart referenced when you recorded that digest. To pick up newer images, update your pinned digest to the current one. +A chart tag always refers to the chart version, not to a fixed set of images. Chainguard rolls the underlying image digests forward within a tag, so even a specific tag like `10.5.13-r1` keeps pointing at the latest images for that chart version. As with image tags, you can pick a tag fidelity that matches your upgrade appetite — `latest`, a version stream, or a specific `x.y` version — but every chart tag rolls its dependent image digests forward. -In short, referencing a chart by tag keeps you current with the latest images automatically, while pinning by digest gives you a fixed, reproducible set of images that you update on your own schedule. The [Pin to digest](#pin-to-digest) section covers how to choose between these approaches. +Helm does not apply these updates on its own. A release picks up newer images only when something triggers a redeploy: a `helm upgrade`, or a controller such as Argo CD or Flux reconciling the release. A chart referenced by tag then pulls the current chart digest along with its newer image digests. + +To pin both the chart and its images to a fixed, reproducible set, reference the chart by digest instead of by tag. Your deployment then stays fixed to the exact images the chart referenced when you recorded that digest. To pick up newer images, update your pinned digest to the current one. The [Pin to digest](#pin-to-digest) section covers how to do this. ## Authentication From a16aa65d7d6930abcef1c64b408e4fb5b7eec38b Mon Sep 17 00:00:00 2001 From: Mark Drake Date: Mon, 20 Jul 2026 13:42:35 -0700 Subject: [PATCH 3/3] JW suggestions Signed-off-by: Mark Drake --- .../how-to-use/use-chainguard-helm-charts/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/chainguard/chainguard-images/how-to-use/use-chainguard-helm-charts/index.md b/content/chainguard/chainguard-images/how-to-use/use-chainguard-helm-charts/index.md index bbc6048d89..e83528b2f5 100644 --- a/content/chainguard/chainguard-images/how-to-use/use-chainguard-helm-charts/index.md +++ b/content/chainguard/chainguard-images/how-to-use/use-chainguard-helm-charts/index.md @@ -38,11 +38,11 @@ You can use these Helm charts with Chainguard FIPS container images, but you wil ## How chart updates deliver image updates -Chainguard rebuilds container images regularly to pick up the latest package versions and CVE fixes. When an image updates, the associated chart updates too so that it pins the new image digests. +Chainguard rebuilds container images regularly to pick up the latest package versions and CVE fixes. Just like images, charts are also rebuilt regularly to pick up the latest chart updates and the chart's new dependent image digests. -A chart tag always refers to the chart version, not to a fixed set of images. Chainguard rolls the underlying image digests forward within a tag, so even a specific tag like `10.5.13-r1` keeps pointing at the latest images for that chart version. As with image tags, you can pick a tag fidelity that matches your upgrade appetite — `latest`, a version stream, or a specific `x.y` version — but every chart tag rolls its dependent image digests forward. +A chart tag always refers to the chart version, not to a fixed set of images. Chainguard rolls the underlying image digests forward within a tag, so even a specific tag like `10.5.13-r1` keeps pointing at the latest images for that chart version. As with image tags, you can pick a tag fidelity that matches your upgrade appetite — `latest`, a version stream, or a specific `x.y.y-r#` version — but every chart tag rolls its dependent image digests forward. -Helm does not apply these updates on its own. A release picks up newer images only when something triggers a redeploy: a `helm upgrade`, or a controller such as Argo CD or Flux reconciling the release. A chart referenced by tag then pulls the current chart digest along with its newer image digests. +Helm will not apply these updates on its own. A release picks up newer images only when something triggers a redeploy: a `helm upgrade`, or a controller such as Argo CD or Flux reconciling the release. A chart referenced by tag then pulls the current chart digest along with its newer image digests. Running a `helm upgrade` on the same tag will resolve to its newest digest the tag pins to. To pin both the chart and its images to a fixed, reproducible set, reference the chart by digest instead of by tag. Your deployment then stays fixed to the exact images the chart referenced when you recorded that digest. To pick up newer images, update your pinned digest to the current one. The [Pin to digest](#pin-to-digest) section covers how to do this.