chart

Overview ¶

Package chart provides utilities for reading and modifying Chainguard Helm charts stored as OCI artifacts or on the filesystem.

Chainguard Helm charts embed metadata that describes how container image references map to values.yaml paths. This package uses that metadata to read, inspect, and patch charts without requiring knowledge of the underlying template format.

Inspecting a Chart Package ¶

To read chart metadata and image mappings from a chart filesystem (typically an expanded Chainguard chart APK), use Read:

chartData, err := chart.Read(expandedAPK.TarFS)
if err != nil {
	return err
}

// chartData.Meta has Chart.yaml fields (name, version, dependencies, etc.)
// chartData.Mapping has the parsed image mapping template
// chartData.Subcharts has recursive subchart data, keyed by dependency alias

Extracting values.yaml from an OCI Artifact ¶

img, err := remote.Image(ref)
if err != nil {
	return err
}

values, err := chart.ReadValues(img)
if err != nil {
	return err
}
// values is nil if the chart has no values.yaml

Reading and Modifying Chart.yaml Metadata ¶

To read and parse Chart.yaml metadata from an OCI artifact:

meta, err := chart.ReadChartMeta(img)
if err != nil {
	return err
}
// meta contains APIVersion, Name, Version, AppVersion, Description, Dependencies

To modify Chart.yaml metadata and create a new chart artifact:

meta.Version = "2.0.0"
meta.AppVersion = "1.5.0"

patched, err := chart.ReplaceChartMeta(img, meta)
if err != nil {
	return err
}
// patched is a new OCI artifact with updated Chart.yaml

Patching Image References into a Chart ¶

To replace image references in a chart's values.yaml using a mapping template and a set of concrete refs, use ReplaceValues. It returns a new OCI artifact with the updated values.yaml — all other files, annotations, and metadata are preserved:

refs := map[string]string{
	"nginx": "cgr.dev/chainguard/nginx:latest@sha256:abc123...",
}
patched, err := chart.ReplaceValues(img, mapping, refs)
if err != nil {
	return err
}
if err := remote.Write(dstRef, patched); err != nil {
	return err
}

Detecting Helm Charts ¶

Use the MediaType constant to identify Helm chart content layers when inspecting OCI manifests:

mt, _ := layers[0].MediaType()
if mt == chart.MediaType {
	// this is a Helm chart
}

package main

import (
	"fmt"

	"chainguard.dev/sdk/helm/chart"
)

func main() {
	// The MediaType constant identifies Helm chart content layers in OCI images
	fmt.Println(chart.MediaType)
}

Output:
application/vnd.cncf.helm.chart.content.v1.tar+gzip