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. 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.
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. 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, is refused the same way. Only the root is inspected. Reference a chart pushed as a single manifest instead.
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.
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 still pulls chartURL:version, then compares the digest of the manifest it received with digest and returns an error naming both when they differ, before rendering anything. 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.
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: