[rdark]

Closes #276.

multi_deploy pushes many images from one bazel run (concurrently in later versions), but each chart still needs its own bazel run of helm_push. helm_push cannot provide DeployInfo, because DeployInfo describes an image push or load, not a command to run. This PR describes the chart as the OCI artifact helm push creates, and lets rules_img push that.

Digest
The pushed manifest is byte-identical to the one helm push creates, so its digest is the one helm_oci_digest gives. For tests/helm_oci_manifest:simple, helm_oci_manifest, helm_oci_digest and helm push (Helm 3.16.3 and 4.3.1) all give sha256:b6137ff1…. rules_img writes a top-level mediaType that helm push does not, so helm_oci_manifest sets omit_media_type (rules_img#805, released in 0.3.24) to leave it out.

Usage

load("@rules_helm//helm:defs.bzl", "helm_chart")
load("@rules_helm//helm:rules_img.bzl", "helm_oci_manifest")
load("@rules_img//img:multi_deploy.bzl", "multi_deploy")

helm_chart(name = "chart")

# Describes the push; it is not runnable on its own.
helm_oci_manifest(name = "chart_oci_manifest", chart = ":chart", registry_url = "oci://registry.example.com/charts")

# `bazel run :deploy` pushes the chart. Image push targets can go in the same list.
multi_deploy(name = "deploy", operations = [":chart_oci_manifest"])

The target is an image_manifest with the Helm config media type, the chart .tgz as its only layer, the annotations helm push writes, and an image_push_spec for <registry_url>/<chart name>:<chart version> (+ in the version becomes _, as Helm does). It is built from rules_img's public rules only. helm_chart does not create it; it is opt-in through the new helm/rules_img.bzl.

Not supported, and documented in the macro: push_cmd and plugins such as cm-push, HELM_REGISTRY_USERNAME/HELM_REGISTRY_PASSWORD login (credentials come from rules_img's Docker config and credential helpers), include_images, and charts from helm_import (their metadata has no created value).

Two issues a user might otherwise hit: rules_img expands Go templates in annotation values, so {{ in chart metadata is escaped; and the manifest sets soci = "disabled", since a SOCI index would add an annotation helm push does not write.

Dependency change

rules_img is now a non-dev dependency at 0.3.24, the first release with omit_media_type. 0.3.14 is the first version that reads annotations_file as a JSON object with values verbatim; earlier versions split KEY=VALUE lines and trim them. 0.3.18 adds multi_deploy --sink, which the offline test uses. omit_platform (0.3.21) is not needed: it changes only the manifest descriptor, and the pushed bytes on 0.3.24 are identical with and without it.

This has a cost for consumers who never load helm/rules_img.bzl. In a throwaway consumer module with one helm_chart, built from an empty repository cache, the change added rules_img+ (about 1.3 MB of source), hermetic_launcher+ (164 KB) and the img_toolchain hub repo (20 KB) to the fetched repositories, because both modules register toolchains. No img tool binaries were fetched. Module resolution also raises rules_img to at least 0.3.24, bazel_features to 1.47.0 and package_metadata to 0.0.10, and adds hermetic_launcher 0.0.17.

Moving to 0.3.17 or later broke tests/with_image_deps_img on Linux, because img_pull started making :image an alias. #304 fixed that before this PR.

Implementation

The chart-reading and annotation code moves out of oci_digest.go into helm/private/oci_digest/ociartifact, unchanged. oci_digest keeps its output (the simple and created digest goldens pass unchanged), and a new oci_parts tool writes the config blob, annotations, tag and destination for rules_img.

Testing

• tests/helm_oci_manifest runs each multi_deploy with --sink oci:<dir>, offline, and checks the Helm config and layer media types, that the layer is the chart .tgz, that the config blob and manifest equal goldens from a real helm push, that each manifest's digest equals helm_oci_digest's, the reference for a trailing-slash registry_url and for registry_url_file, a {{ description and a + version. It also passes with SOCI forced on, and fails on every chart's digest with omit_media_type = False.
• Go unit tests for ociartifact and oci_parts.
• bazel test //... on macOS with Bazel 9.3.1 (with and without --config=strict) and with Bazel 7.7.2 and --config=strict, as ci-min-bazel runs it: 68 pass, 3 skipped (the Linux-only with_image_deps_img tests).
• By hand: pushed the three test charts to a local registry with bazel run //tests/helm_oci_manifest:deploy, and pushed the same .tgz files with helm push from Helm 3.16.3 and 4.3.1. Each chart got the same digest from all three pushes, equal to its helm_oci_digest output. helm pull, helm show chart and helm template accept the pushed charts with both Helm versions, and the pulled .tgz is byte-identical to the built one.
• Not run locally: Linux and Windows (CI runs them), Helm 3.17.3, Flux pulling a chart, and registries that need credentials.

[rdark]

CI failures are 429's from ECR

[rdark]

@abrisco I moved back into draft status - I think it would be better to wait on a rules_img release with rules_img#805 in, then we have byte-identical manifests from day 1. Will move back out of draft when that happens

[rdark]

@abrisco rules_img made a release with our needed changes in to make the manifest byte-identical so moved back out of draft

[abrisco]

Sorry for the delay here, I'll take a look this weekend!

[abrisco]

Is there a way to avoid this being a mandatory dependency?

[rdark]

Not with the existing macro in this module. Bazel doesn't have any concept of optional deps.

Few options that I can think of:

1. Separate rules_helm_img module in this repo (e.g in module/rules_helm_img). Needs a second BCR module and release workflow change. Looks like rules_img published img_tool like this.
2. Have the caller pass the rules in. Should work but a bit clunky and a weird API
3. Ship just helm_oci_parts and then document 30 or so lines or rules_img wiring to copy. Also clunky.

If we really want to avoid this dep in the root module, I think 1. is probably the least worst option.

LMK what you think!

[rdark]

@abrisco I've opened a speculative PR demonstrating 1 here: rdark#2