Helm / Advanced: compatibility, trust and delivery evidence / Lesson 14

OCI artifact identity and provenance

Evaluate chart distribution using exact artifact identity, verified origin and reviewed content without confusing a digest or signature with application safety.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Distinguish repository paths, chart versions and immutable content identity.
Explain Helm OCI reference conventions and provenance files.
Define trust decisions separately from integrity checks.

Separate location and identity

A repository location tells a client where to request an artifact; a chart version identifies a package release; a digest identifies exact content within the relevant artifact representation. These fields answer different questions. A familiar registry hostname does not prove that a particular publisher or dependency is trusted. Preserve the reviewed chart archive, its exact identity and the evidence used to approve it. The image referenced by the chart is another artifact with its own identity. Pinning chart contents while leaving image selection mutable still leaves application behavior dependent on a changing external input.

Read OCI conventions

In the Helm 3 OCI model used here, an OCI chart reference uses the oci scheme, and chart name and semantic version constrain naming and tags. A push destination omits the chart basename and tag because Helm derives them from package metadata; retrieval references include the chart name. The first example is a written reference comparison with a reserved example domain. It is not a push or pull command and cannot contact a registry. Distinguish these conventions from older experimental Helm OCI examples, whose commands and behavior differ from supported Helm 3 documentation.

text Illustrative OCI identities

package: catalog-0.4.0.tgz
package metadata: name=catalog, version=0.4.0
OCI push destination concept: oci://registry.example.test/learning
OCI retrieval reference concept: oci://registry.example.test/learning/catalog
requested version concept: 0.4.0

All references are non-runnable text and use a reserved domain. No registry authentication, network transfer or artifact publication occurs.

Understand integrity evidence

A checksum comparison can show that bytes match an expected value, but the expected value must itself come from a trusted channel. The second example hashes two tiny public strings and compares the digests without displaying a pretend chart digest. A mismatch detects changed bytes; a match does not establish who approved the content or whether it contains excessive permissions. Artifact integrity is a useful input to a broader review. Do not weaken transport verification or accept a new digest merely to make a failed check pass; investigate the identity and trust discrepancy first.

python Synthetic byte identity comparison

import hashlib
approved = hashlib.sha256(b"catalog package A").digest()
received = hashlib.sha256(b"catalog package B").digest()
print(approved == received)
print(hashlib.sha256(b"catalog package A").digest() == approved)

Expected output

False
True

False detects the changed public text; True confirms the repeated public text. These are not package, OCI manifest or image digests.

Separate provenance and trust

Helm provenance associates a packaged chart with signed metadata in a companion .prov file. Verification involves the package, signature and a trusted public-key policy. A mathematically valid signature from an unapproved identity is not an organizational approval. Likewise, a trusted signer can publish a package with a mistake. Keep signer authorization, key lifecycle and content review explicit. This lesson performs no signing, key export or verification command and accesses no keyring. It explains what evidence a provenance workflow would need, avoiding any claim that a displayed signature line represents a real verification result.

Review the whole chain

A release may combine a parent chart, subcharts, container images, embedded files and runtime external dependencies. List each source of executable or configuration behavior and how it is pinned and approved. A chart signature does not automatically validate every future image tag resolution or remote script invoked by a container. Avoid relying on a single green badge. For an offline review, retain a synthetic bill of inputs and name the checks not performed. Promotion should use the same reviewed artifact bytes rather than rebuilding from a loosely constrained source and assuming the result is equivalent.

Common errors and fixes

A digest mismatch is fixed by replacing the expected digest

Why it happens: The check was treated as an obstacle rather than evidence.
How to fix it: Investigate artifact identity, source and approval before accepting new bytes.
Prevent it next time: Protect the approved inventory through a trusted review process.

A signed chart is assumed to make every image safe

Why it happens: Package provenance was extended to unrelated runtime artifacts.
How to fix it: Review image identities and their trust evidence separately.
Prevent it next time: Inventory all executable inputs in the release chain.

An OCI push reference redundantly includes name and tag

Why it happens: Retrieval syntax was copied into the push destination concept.
How to fix it: Use the selected Helm version’s documented destination convention.
Prevent it next time: Keep distribution examples version-scoped and distinguish push from retrieval.

Check your understanding

1. A chart archive is approved but its image tag is mutable. What remains nonreproducible?

Show worked solution

The image bytes selected later can change even when the chart archive does not. Record an approved image identity, use the chart’s documented digest interface when appropriate and keep image policy evidence separate. Reproducibility includes all behavior-producing inputs, not only the package that generates the image reference.

2. Verification succeeds with an unknown public key. Is the package approved?