helm

package
v1.40.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrJobTemplateChanged = errors.New("the chart changed the pod template of a live Job, which is immutable")

ErrJobTemplateChanged is returned (wrapped) by Reconcile when the chart changed the pod template of a Job that is live. The template is immutable, so the release cannot converge until the chart stops changing it (a hook with before-hook-creation, or a versioned Job name) or the Job is removed.

View Source
var ErrValuesSchema = errors.New("chart values do not satisfy the chart's values.schema.json")

ErrValuesSchema marks a failure to satisfy a chart's values.schema.json, as opposed to a failure of the operation itself. A consumer classifies with errors.Is and can then answer 4xx rather than 5xx: the input is invalid, and nothing about the server is wrong.

A PLAIN SENTINEL, NOT helm's TYPE, and that is the same decision as Hook above. helm's chartutil.JSONSchemaValidationError would make helm.sh/helm/v3 a DIRECT requirement of every consumer that wants to classify this -- chart-inspector has it as indirect and should keep it that way. Detection needs helm and lives in helm/v3; the sentinel needs nothing and lives here.

WHY A SENTINEL IS NEEDED AT ALL, measured against helm v3.20.2. helm HAS a typed error and discards it before any caller sees it:

chartutil/jsonschema.go:150  return JSONSchemaValidationError{err}   // typed, exported
chartutil/jsonschema.go:80   sb.WriteString(err.Error())             // type -> string
chartutil/jsonschema.go:107  return errors.New(sb.String())          // plain error
chartutil/values.go:168      fmt.Errorf(errFmt, err.Error())         // %s, not %w

The chain is broken twice, and the render path uses the flattening entry point (chartutil/values.go:167). So errors.As on helm's own type cannot work downstream of an install, however correct it looks: the type exists and never arrives. Classifying by message text would mean depending on the format of a strings.Builder with no compatibility promise, which is the thing helm's wording has already changed under this repo once.

Functions

This section is empty.

Types

type ActionConfig

type ActionConfig struct {
	ChartVersion          string
	ChartName             string
	Values                map[string]interface{}
	Description           string
	Timeout               time.Duration
	Wait                  bool
	WaitForJobs           bool
	Atomic                bool
	PostRenderer          PostRenderer // Custom interface defined below
	Labels                map[string]string
	Replace               bool
	Force                 bool
	DryRun                DryRunMode
	TakeOwnership         bool
	SkipSchemaValidation  bool
	SkipCRDs              bool
	Verify                bool
	NoHooks               bool
	DependencyUpdate      bool
	Devel                 bool
	IncludeCRDs           bool
	SubNotes              bool
	HideNotes             bool
	EnableDNS             bool
	InsecureSkipTLSverify bool

	Username           string
	Password           string
	PassCredentialsAll bool
	Verbose            bool
	LogWriter          io.Writer
}

ActionConfig holds all possible configuration values for Install AND Upgrade. It acts as a data transfer object between your app and the specific Helm implementation.

type Client

type Client interface {
	Install(ctx context.Context, releaseName string, chartRef string, config *InstallConfig) (*Release, error)
	Upgrade(ctx context.Context, releaseName string, chartRef string, config *UpgradeConfig) (*Release, error)
	// Reconcile performs a fork-free, self-healing "apply-if-changed" reconcile:
	// it converges the live cluster to the rendered chart (recreating deleted
	// children and patching drifted fields via helm's 3-way merge) and writes a
	// new revision + runs hooks ONLY when the cluster was actually mutated. At
	// steady state it is a no-op (no revision, no hooks). See the v3 impl for the
	// exact change-detection semantics.
	Reconcile(ctx context.Context, releaseName string, chartRef string, config *UpgradeConfig) (*ReconcileResult, error)
	Uninstall(ctx context.Context, releaseName string, config *UninstallConfig) error
	Rollback(ctx context.Context, releaseName string, config *RollbackConfig) (*Release, error)
	GetRelease(ctx context.Context, releaseName string, config *GetConfig) (*Release, error)
	ListReleases(ctx context.Context, config *ListConfig) ([]*Release, error)
	Close() error
}

Client is the interface that the rest of your app uses. It returns your custom *Release, not the Helm SDK struct.

type DryRunMode

type DryRunMode int
const (
	DryRunNone DryRunMode = iota
	DryRunClient
	DryRunServer
)

type GetConfig

type GetConfig struct {
	Version int
	// Namespace overrides the client's namespace for this lookup. Empty means the client's own.
	//
	// A release is identified by name AND namespace, so without this a caller could only ask
	// about releases in the namespace the client was built for — and callers that install into
	// several namespaces (operators, test harnesses standing up prerequisites) had no way to ask
	// "does this release already exist?" at all. Mirrors InstallConfig.Namespace and
	// UpgradeConfig's handling, so the same override means the same thing on every verb.
	Namespace string
}

type Hook

type Hook struct {
	// Name is the hook object's name, and Kind its Kubernetes kind.
	Name string
	Kind string
	// Path is the chart-relative template path, which is what makes a hook diagnosable: an
	// operator told "this hook has no RBAC" needs to know which file to look at.
	Path string
	// Manifest is the rendered document. It carries the apiVersion and namespace that Kind alone
	// does not, so a consumer resolving a GVK must parse this rather than infer from Kind.
	Manifest string
	// Events are the hook's phases ("pre-delete", "post-install", ...) as plain strings.
	//
	// A consumer deciding RBAC must NOT filter on these: an object needs its permissions
	// regardless of which phase fires it, and helm deletes a previous hook object under
	// before-hook-creation whatever its phase. Carried because a diagnostic should be able to say
	// WHICH hook, not so the set can be narrowed.
	Events []string
}

Hook is one lifecycle hook of a release, projected from helm's release.Hook.

PROJECTED RATHER THAN RE-EXPORTED, deliberately. Release exists so a consumer does not take a direct dependency on helm's types — chart-inspector has helm.sh/helm/v3 as an INDIRECT requirement and should keep it that way. Re-exporting []*release.Hook, or helm's HookEvent, would make helm direct for every consumer that touches a hook. Only the fields a consumer needs are carried; everything else about a hook (weight, delete policies, last run) stays helm's business.

type InstallConfig

type InstallConfig struct {
	*ActionConfig
	Namespace  string
	RestConfig *rest.Config
	// Install-Only Fields
	GenerateName    bool
	CreateNamespace bool
}

type ListConfig

type ListConfig struct {
	// All ignores the limit/offset
	All bool
	// AllNamespaces searches across namespaces
	AllNamespaces bool
	// Sort indicates the sort to use
	Sort Sorter
	// Overrides the default lexicographic sorting
	ByDate      bool
	SortReverse bool
	// StateMask accepts a bitmask of states for items to show.
	//
	// LEAVE IT AT ZERO TO GET HELM'S OWN DEFAULT, which is ListDeployed|ListFailed — the same set
	// the `helm list` CLI shows. A zero value means "not specified" and is NOT applied
	// (plumbing#74); before that fix it was assigned through, and helm skips every release when
	// the mask is 0, so an unset field returned an empty slice with a nil error.
	//
	// The previous text here said "The default is ListDeployed", copied from helm's own comment at
	// pkg/action/list.go:119 — which is wrong about its own code at :142. The CLI's `list --help`
	// is the accurate statement: "By default, it lists only releases that are deployed or failed."
	// So a FAILED release is not hidden by default; what --all adds is superseded, uninstalled,
	// uninstalling and the pending-* family, and `pending-install` is the one that hides an install
	// that never completed.
	StateMask ListStates
	// Limit is the number of items to return per Run()
	Limit int
	// Offset is the starting index for the Run() call
	Offset int
	// Filter is a filter that is applied to the results
	Filter       string
	Short        bool
	NoHeaders    bool
	TimeFormat   string
	Uninstalled  bool
	Superseded   bool
	Uninstalling bool
	Deployed     bool
	Failed       bool
	Pending      bool
	Selector     string
}

type ListStates

type ListStates uint
const (
	// ListDeployed filters on status "deployed"
	ListDeployed ListStates = 1 << iota
	// ListUninstalled filters on status "uninstalled"
	ListUninstalled
	// ListUninstalling filters on status "uninstalling" (uninstall in progress)
	ListUninstalling
	// ListPendingInstall filters on status "pending" (deployment in progress)
	ListPendingInstall
	// ListPendingUpgrade filters on status "pending_upgrade" (upgrade in progress)
	ListPendingUpgrade
	// ListPendingRollback filters on status "pending_rollback" (rollback in progress)
	ListPendingRollback
	// ListSuperseded filters on status "superseded" (historical release version that is no longer deployed)
	ListSuperseded
	// ListFailed filters on status "failed" (release version not deployed because of error)
	ListFailed
	// ListUnknown filters on an unknown status
	ListUnknown
)

type PostRenderer

type PostRenderer interface {
	// Run expects the rendered manifests and returns modified manifests
	Run(renderedManifests *bytes.Buffer) (*bytes.Buffer, error)
}

--- Custom Interfaces --- We duplicate the PostRenderer interface here so users can implement it without importing the Helm SDK directly.

type ReconcileResult

type ReconcileResult struct {
	Changed        bool
	Created        int
	Deleted        int
	PatchedUpdated int
	Release        *Release
	// ChangedObjects identifies the children this reconcile created, deleted or patched, as
	// "group/version/Kind/namespace/name". The counts above say THAT something drifted;
	// core-provider#175's open half is that nothing said WHICH child — so an operator seeing
	// "patched=1" a hundred times an hour had no way to reach the cause. Diagnosing one such case
	// took a cluster-wide differential across five compositions; this line would have named the
	// child outright.
	//
	// Free to collect: the loop that decides `patched` already computes this identity per child
	// (infoKey) and already holds both the live and target objects. No extra read, no extra decode,
	// no new comparison.
	//
	// CAPPED, and the cap is part of the design rather than tidiness. The composition that prompted
	// this writes two revisions a minute, so an uncapped list would turn a diagnostic into the same
	// log-volume problem #175 is about.
	ChangedObjects []string
	// ChangedObjectsOmitted is how many identities exceeded the cap and were not listed, so a
	// reader can tell a genuinely short list from a truncated one.
	ChangedObjectsOmitted int
	// ChangedPaths names, for each child in ChangedObjects that the merge PATCHED (keyed by the same
	// identity), the JSON paths whose persisted content differed, e.g. "metadata.annotations[checksum/config]"
	// or "spec.replicas" (plumbing#112). changedObjects says WHICH child drifted; this says which field,
	// which is what a drift investigation needs and what a managedFields snapshot taken after the heal
	// cannot give (the heal takes ownership). PATHS ONLY, never values: a value may be Secret data or a
	// token. Capped at a few paths per child (ChangedPathsOmitted counts the rest). Created and deleted
	// children have no entry: the whole object is the change.
	ChangedPaths map[string][]string
	// ChangedPathsOmitted is, per child, how many changed paths exceeded the cap.
	ChangedPathsOmitted map[string]int
	// AppliedPartially reports that the self-heal apply converged SOME children and failed on
	// others (core-provider#276). When it is true, Reconcile returns BOTH this result and a
	// non-nil error, and the error names the children that failed.
	//
	// WHY THE RESULT IS RETURNED AT ALL ON ERROR. helm's own update collects per-object errors and
	// CONTINUES — pkg/kube/client.go appends to updateErrors, appends to res.Updated "regardless",
	// and returns a populated Result alongside the joined error. So the other children really did
	// converge. Reconcile used to answer that with `return nil, err`, throwing the populated result
	// away: the change detection below never ran, the stored digest never advanced, and a
	// composition reported total failure while most of it was healthy. Observed on a0, where six
	// orphaned Jobs from an earlier release wedged a Keystone composition permanently.
	//
	// A caller that follows the Go idiom and checks err before touching the result will see only a
	// failure, which is the OLD behaviour and remains safe. A caller that wants to distinguish
	// "nothing converged" from "most of it converged" must check this field — hence a named bool
	// rather than relying on result != nil, which is easy to read past.
	//
	// No revision is persisted on a partial apply: the real Upgrade that would write one patches the
	// same objects and would fail the same way, so Reconcile returns before it.
	AppliedPartially bool
	// IntendedDeletions identifies the children the merge was ASKED to delete — those present in
	// the stored manifest and absent from the render — as "group/version/Kind/namespace/name".
	//
	// WHY INTENT AND NOT JUST THE OUTCOME (core-provider#304). `Deleted` reports what helm says it
	// removed. On its own it cannot distinguish three states that matter:
	//
	//	intended 0, deleted 0   nothing was removed from the render. Correct, and the common case.
	//	intended 1, deleted 1   the removal converged.
	//	intended 1, deleted 0   THE DEFECT. Either helm's deletion loop never ran — it sits AFTER
	//	                        the error switch in pkg/kube/client.go, so one unpatchable object
	//	                        skips every deletion — or the delete was issued and did not stick.
	//
	// A caller seeing only `deleted: 0` cannot tell the first from the third, which is exactly how
	// #304 went unnoticed: a node removed from a spec left its child alive for sixteen minutes
	// while the log said deleted:0, and that same line is printed by every healthy steady-state
	// reconcile.
	//
	// Computed with helm's OWN ResourceList.Difference against the same two lists the merge
	// receives, so it matches helm's matching exactly (group+kind+name+namespace, version-
	// independent via isMatchingInfo) rather than replicating it. Taken after filterLiveJobs and
	// the adoption pass, so it reflects the lists as actually handed over.
	IntendedDeletions []string
	// IntendedDeletionsOmitted is how many identities exceeded the cap and were not listed, so a
	// reader can tell a genuinely short list from a truncated one.
	IntendedDeletionsOmitted int

	// KeptDeletions names the intended deletions helm did NOT perform because the live object carries
	// helm.sh/resource-policy: keep (core-provider, 2026-11-08). helm is right to leave them alive;
	// what must still happen is that the release RECORDS the change. Each one therefore counts toward
	// Changed, so the real Upgrade writes a revision with the new values and manifest, and the release
	// stops claiming the object. A deletion that was intended, not kept and not performed (its delete
	// failed) is deliberately NOT here: counting it would write a revision without the object, helm
	// would forget it, and the delete would never be retried.
	KeptDeletions []string
	// KeptDeletionsOmitted is how many kept identities exceeded the cap and were not listed.
	KeptDeletionsOmitted int
	// ChangedJobTemplates names the live Jobs (namespace/name) whose pod template the CHART changed
	// between the stored release and this render (core-provider#403). A Job's spec.template is
	// immutable, so such a release cannot be applied; Reconcile returns ErrJobTemplateChanged
	// alongside this list. Empty when no such Job exists.
	ChangedJobTemplates []string
	// RetriedFailedRelease is true when the stored latest revision was "failed" and this reconcile
	// therefore ran the real upgrade again rather than treating that revision's manifest as
	// converged (core-provider#403).
	RetriedFailedRelease bool
}

ReconcileResult reports what a Reconcile did to converge the cluster to the rendered chart. Changed is true iff the live cluster was actually mutated (a child was created, deleted, or patched with a non-empty diff). When Changed is false the cluster already matched the desired manifest and NO new helm revision was written and NO hooks ran.

type Release

type Release struct {
	Name         string
	Namespace    string
	Revision     int
	ChartVersion string
	Status       Status
	Values       map[string]interface{}
	Manifest     string
	// Updated is helm's Info.LastDeployed for this revision — when the (possibly still
	// pending) revision record was written. For a pending-install/upgrade/rollback status,
	// time.Since(Updated) is how long the operation has been in flight, which callers use to
	// tell a legitimately in-progress operation from a genuinely stuck one.
	Updated time.Time

	// Hooks are the release's lifecycle hooks. helm keeps them OUT of Manifest by construction —
	// releaseutil.SortManifests splits them into their own slice — so a consumer that reads only
	// Manifest cannot see them at all.
	//
	// WHY THIS IS EXPOSED (core-provider#311). chart-inspector derives a composition's RBAC from a
	// dry-run install: the tracer records the API calls, and the result is narrowed against
	// Manifest. A dry run executes no hooks and Manifest excludes them, so NO grant was ever
	// generated for a hook object. A `pre-delete` hook therefore turned teardown into an uninstall
	// that could never succeed — measured on a real cluster, with the controlled comparison being
	// one template rendering four objects of which only the hook-annotated one went ungranted.
	//
	// The hooks are available on a DRY RUN: helm populates rel.Hooks at action/install.go:317 and
	// returns early for a dry run at :364 — after. And collection is PHASE-AGNOSTIC: SortManifests
	// gathers every hook and merely records its Events, so a pre-delete hook is present in the
	// result of an install probe.
	Hooks []Hook
}

Release is a version-agnostic representation of a Helm release. We do not import helm.sh/helm/... here.

func (*Release) GetHooks

func (r *Release) GetHooks() []Hook

GetHooks returns the release's lifecycle hooks. Mirrors GetManifest.

func (*Release) GetManifest

func (r *Release) GetManifest() string

func (*Release) String

func (r *Release) String() string

type RollbackConfig

type RollbackConfig struct {
	ReleaseVersion int
	Timeout        time.Duration
	Wait           bool
	WaitForJobs    bool
	DisableHooks   bool
	DryRun         bool
	Recreate       bool // will (if true) recreate pods after a rollback.
	Force          bool // will (if true) force resource upgrade through uninstall/recreate if needed
	CleanupOnFail  bool
	MaxHistory     int // MaxHistory limits the maximum number of revisions saved per release
}

type Sorter

type Sorter uint
const (
	// ByNameDesc sorts by descending lexicographic order
	ByNameDesc Sorter = iota + 1
	// ByDateAsc sorts by ascending dates (oldest updated release first)
	ByDateAsc
	// ByDateDesc sorts by descending dates (latest updated release first)
	ByDateDesc
)

type Status

type Status string

Status is the status of a release

const (
	// StatusUnknown indicates that a release is in an uncertain state.
	StatusUnknown Status = "unknown"
	// StatusDeployed indicates that the release has been pushed to Kubernetes.
	StatusDeployed Status = "deployed"
	// StatusUninstalled indicates that a release has been uninstalled from Kubernetes.
	StatusUninstalled Status = "uninstalled"
	// StatusSuperseded indicates that this release object is outdated and a newer one exists.
	StatusSuperseded Status = "superseded"
	// StatusFailed indicates that the release was not successfully deployed.
	StatusFailed Status = "failed"
	// StatusUninstalling indicates that an uninstall operation is underway.
	StatusUninstalling Status = "uninstalling"
	// StatusPendingInstall indicates that an install operation is underway.
	StatusPendingInstall Status = "pending-install"
	// StatusPendingUpgrade indicates that an upgrade operation is underway.
	StatusPendingUpgrade Status = "pending-upgrade"
	// StatusPendingRollback indicates that a rollback operation is underway.
	StatusPendingRollback Status = "pending-rollback"
)

Describe the status of a release NOTE: Make sure to update cmd/helm/status.go when adding or modifying any of these statuses.

type UninstallConfig

type UninstallConfig struct {
	DisableHooks        bool
	DryRun              bool
	IgnoreNotFound      bool
	KeepHistory         bool
	Wait                bool
	DeletionPropagation string
	Timeout             time.Duration
	Description         string
}

type UpgradeConfig

type UpgradeConfig struct {
	*ActionConfig
	// Upgrade-Only Fields
	Install    bool
	MaxHistory int
}

Directories

Path Synopsis
v3

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL