Documentation
¶
Overview ¶
Package helm provides client-side Helm chart rendering from OCI registries and HTTP Helm repositories.
RenderChart pulls a chart and renders its templates using the Helm template engine — equivalent to `helm template` — returning multi-document YAML. No Kubernetes cluster connection is required. RenderOption (WithReleaseName, WithNamespace) overrides the default release identity ("release" in "default"). WithDigest pins an OCI chart to a manifest digest: the render is refused when the pulled manifest has another one, unless it is an image index listing an image manifest with that digest, which is then pulled on its own and rendered. WithDigestVersion renders an OCI chart at the version Flux's helm-controller installs it as, the chart version with the pulled manifest digest as build metadata.
SplitByHookWeight groups rendered objects into HookGroup values by their helm.sh/hook phase and helm.sh/hook-weight, in deployment order, and drops the phases that have no Flux lifecycle equivalent. A missing or non-integer weight counts as 0. Kure does not turn a HookGroup into a Flux Kustomization; the caller does.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RenderChart ¶
func RenderChart(chartURL, version string, values map[string]any, opts ...RenderOption) ([]byte, error)
RenderChart pulls a Helm chart and renders it client-side (equivalent to `helm template`), returning multi-doc YAML.
OCI registries: chartURL must start with "oci://". Authentication uses the local Docker credential store (~/.docker/config.json).
HTTP repositories: chartURL must start with "http://" or "https://", with the chart name as the last path segment (e.g. "https://charts.example.com/myapp"). Only public unauthenticated repositories are supported; basic auth, client TLS, and other credential mechanisms are not.
version is the chart version tag (e.g. "1.16.5"). values are merged on top of the chart's default values. opts customizes the release identity (name, namespace); see WithReleaseName and WithNamespace. Without opts, rendering uses release "release" in namespace "default". WithDigest pins an OCI chart to a manifest digest; WithDigestVersion renders it at its digest-qualified version.
An OCI reference that resolves to an image index is rendered only when the index names exactly one image manifest, whether or not the index carries its optional mediaType field, or when WithDigest names one of the image manifests it lists, which is then pulled and rendered on its own. Any other index is refused with an error naming the reference, before any chart is loaded, with or without WithDigest or WithDigestVersion: one naming several manifests, one holding a nested index, and one holding a chart manifest beside a manifest that is no chart. A root manifest naming a subject, index or not, a root naming a manifest as its config or a layer, a root holding both an image manifest's config, layers or media type and an index's manifests list, and an index listing its single image manifest without a digest, are refused the same way. The single child of an index naming one image manifest is pulled on its own, by the digest the index lists, and rendered from that pull, after the checks a child WithDigest selects passes: one more pull of a child the tag's pull has already fetched. Reference a chart pushed as a single manifest instead, or pin the child to render with WithDigest.
Example ¶
package main
import (
"fmt"
"github.com/go-kure/kure/pkg/stack/helm"
)
func main() {
manifests, err := helm.RenderChart(
"oci://registry.example.com/charts/cilium", // OCI chart URL
"1.16.5", // chart version
map[string]any{ // value overrides (merged on top of chart defaults)
"kubeProxyReplacement": true,
"ipam": map[string]any{
"mode": "kubernetes",
},
},
)
if err != nil {
panic(err)
}
// manifests is multi-doc YAML suitable for kubectl apply -f -
fmt.Print(string(manifests))
}
Output:
Example (Http) ¶
package main
import (
"fmt"
"github.com/go-kure/kure/pkg/stack/helm"
)
func main() {
manifests, err := helm.RenderChart(
"https://charts.bitnami.com/bitnami/redis", // repo base URL + chart name
"19.0.0",
map[string]any{"replicaCount": 3},
)
if err != nil {
panic(err)
}
fmt.Print(string(manifests))
}
Output:
Types ¶
type HookGroup ¶
HookGroup is a set of Helm manifests sharing the same hook phase and weight. Resources with no helm.sh/hook annotation have Phase="" and Weight=0 (main group).
func SplitByHookWeight ¶
SplitByHookWeight groups rendered Helm manifests by hook phase and weight, so a caller can generate one FluxCD Kustomization per group; kure itself does not convert a HookGroup. Groups are returned in execution order: pre-install, pre-upgrade, main (non-hook), post-install, post-upgrade, then any remaining unknown hook phases alphabetically.
Objects whose helm.sh/hook phase has no FluxCD lifecycle equivalent (pre-delete, post-delete, pre-rollback, post-rollback, test) are excluded. Comma-separated hook annotations (e.g. "pre-install,post-install") are treated as a single opaque phase string and placed in the unknown group.
It calls GetAnnotations on each object it is given and does not recover a panic of that method: an object whose method panics panics the call.
Example ¶
package main
import (
"fmt"
"github.com/go-kure/kure/pkg/io"
"github.com/go-kure/kure/pkg/stack/helm"
)
func main() {
// Multi-doc YAML as RenderChart returns it
rendered := []byte(`apiVersion: batch/v1
kind: Job
metadata:
name: db-migrate
annotations:
helm.sh/hook: pre-install
helm.sh/hook-weight: "-5"
---
apiVersion: v1
kind: ConfigMap
metadata:
name: app-config
---
apiVersion: v1
kind: Pod
metadata:
name: app-test
annotations:
helm.sh/hook: test
`)
parsed, err := io.ParseYAML(rendered) // []client.Object
if err != nil {
panic(err)
}
groups := helm.SplitByHookWeight(parsed)
for _, g := range groups {
// groups come in deployment order; turning each into its own FluxCD
// Kustomization is the caller's job: kure does not convert a HookGroup
fmt.Printf("phase=%q weight=%d resources=%d\n", g.Phase, g.Weight, len(g.Resources))
}
}
Output: phase="pre-install" weight=-5 resources=1 phase="" weight=0 resources=1
type RenderOption ¶
type RenderOption func(*renderOptions)
RenderOption customizes how a chart is rendered: the release identity, the digest an OCI chart must match, or the version an OCI chart renders at. Without options, rendering uses release "release" in namespace "default" — the defaults renderChart always used prior to this option's introduction.
func WithDigest ¶
func WithDigest(digest string) RenderOption
WithDigest pins an OCI chart to a manifest digest: "sha256:" followed by 64 lowercase hex characters. RenderChart renders the manifest with that digest and nothing else. It still pulls chartURL:version. When the manifest it received has another digest and is an OCI image index listing an image manifest with digest, RenderChart pulls that child on its own, by digest, and renders it: this selects one chart out of a multi-chart index. The tag then only finds the index; the content is fixed by digest. Any other difference is an error naming both digests, returned before rendering anything, as is a digest the index lists as anything but an image manifest and a selected child that is itself an index, names a subject or names a manifest as its config or a layer. A malformed digest, the empty string included, is refused before any pull. HTTP repositories have no manifest digest, so RenderChart refuses this option for them.
Example ¶
package main
import (
"fmt"
"github.com/go-kure/kure/pkg/stack/helm"
)
func main() {
manifests, err := helm.RenderChart(
"oci://registry.example.com/charts/cilium",
"1.16.5",
nil,
// the manifest digest 1.16.5 is pinned to; any other is an error
helm.WithDigest("sha256:3f1c5a9e0b7d2468ace13579bdf02468ace13579bdf02468ace13579bdf02468"),
)
if err != nil {
panic(err)
}
fmt.Print(string(manifests))
}
Output:
func WithDigestVersion ¶
func WithDigestVersion() RenderOption
WithDigestVersion renders an OCI chart at the version Flux's helm-controller installs it as from an OCIRepository source: the chart's semver version with its build metadata replaced by the first 12 hex characters of the pulled manifest's digest, so "0.33.0" renders as "0.33.0+3f1c5a9e0b7d". Templates that print .Chart.Version, such as the conventional helm.sh/chart label, then match the release helm-controller makes. The digest is the one the pull received, checked against WithDigest first when both are given. A chart version that is not semver, a semver tag ("_" read as "+") naming another version than the chart's, or a chart that is not a Helm v2 API chart (apiVersion v1 or v2), is refused, as helm-controller refuses to install them. HTTP repositories have no manifest digest, so RenderChart refuses this option for them. A root that reaches more than one manifest is refused before any chart is loaded (see RenderChart), so the version is not computed for a chart picked among several. A child WithDigest selects from an image index is versioned from its own digest, and a semver tag must name that child's chart version. The single child of an index naming one image manifest, rendered without WithDigest selecting it, is versioned from the index digest the tag resolved to.
Example ¶
package main
import (
"fmt"
"github.com/go-kure/kure/pkg/stack/helm"
)
func main() {
manifests, err := helm.RenderChart(
"oci://registry.example.com/charts/cilium",
"1.16.5",
nil,
// .Chart.Version renders as 1.16.5+<first 12 hex of the pulled digest>,
// the version Flux's helm-controller installs the chart at
helm.WithDigestVersion(),
)
if err != nil {
panic(err)
}
fmt.Print(string(manifests))
}
Output:
func WithNamespace ¶
func WithNamespace(namespace string) RenderOption
WithNamespace sets the release namespace used during rendering (e.g. for {{ .Release.Namespace }}).
func WithReleaseName ¶
func WithReleaseName(name string) RenderOption
WithReleaseName sets the release name used during rendering (e.g. for {{ .Release.Name }} and the generated resource name helpers).
Example ¶
package main
import (
"fmt"
"github.com/go-kure/kure/pkg/stack/helm"
)
func main() {
values := map[string]any{"kubeProxyReplacement": true}
manifests, err := helm.RenderChart(
"oci://registry.example.com/charts/cilium",
"1.16.5",
values,
helm.WithReleaseName("my-cilium"),
helm.WithNamespace("kube-system"),
)
if err != nil {
panic(err)
}
fmt.Print(string(manifests))
}
Output: