Helm — API Surface#

API types#

Helm exposes three distinct API surfaces: a CLI (primary user-facing), an embeddable Go library (pkg/action), and a plugin/extension system. There is no HTTP server or gRPC service — Helm is a client-side tool that drives Kubernetes via client-go.

CLI#

Framework#

Cobra (github.com/spf13/cobra). One file per subcommand in pkg/cmd/. The root command is constructed by NewRootCmd(out, args, logSetup) → newRootCmdWithConfig(actionConfig, ...).

Command structure#

Commands are divided into two groups registered in pkg/cmd/root.go:

Chart management commands (operate on chart artifacts, no cluster needed):

Release management commands (require cluster access):

System / meta commands:

Flag patterns#

Global persistent flags (registered via settings.AddFlags(flags) on the root command’s PersistentFlags()):

--namespace / -n        Target Kubernetes namespace
--kubeconfig            Path to kubeconfig file
--kube-context          Kubeconfig context name
--kube-token            Bearer token for authentication
--kube-apiserver        Kubernetes API server endpoint
--kube-as-user          Impersonate user
--kube-as-group         Impersonate groups
--kube-ca-file          CA certificate file
--kube-insecure-skip-tls-verify
--kube-tls-server-name
--debug                 Enable verbose output
--burst-limit           Client-side throttling limit (default 100)
--qps                   Queries per second
--registry-config       Path to registry config
--repository-config     Path to repositories.yaml
--repository-cache      Path to repo cache directory
--color / --colour      Color mode: never, auto, always

Environment variable binding (HELM_* → EnvSettings struct):

HELM_NAMESPACE, HELM_KUBECONTEXT, HELM_KUBETOKEN, HELM_KUBEASUSER,
HELM_KUBEASGROUPS, HELM_KUBEAPISERVER, HELM_KUBECAFILE,
HELM_KUBETLS_SERVER_NAME, HELM_KUBEINSECURE_SKIP_TLS_VERIFY,
HELM_PLUGINS, HELM_REGISTRY_CONFIG, HELM_REPOSITORY_CONFIG,
HELM_REPOSITORY_CACHE, HELM_CONTENT_CACHE, HELM_MAX_HISTORY,
HELM_BURST_LIMIT, HELM_QPS, HELM_DEBUG, HELM_DRIVER

CLI flags shadow env vars. HELM_DRIVER selects the storage backend (secrets, configmaps, memory, sql).

Shell completion: Cobra’s built-in ValidArgsFunction and RegisterFlagCompletionFunc are used extensively. The --namespace and --kube-context flags dynamically query the live cluster for completions.

Library API (pkg/action)#

This is Helm’s most architecturally significant API surface. The package doc states: “This is a library for calling top-level Helm actions.” It is the stable embeddable API consumed by projects like Flux CD and Argo CD.

Entry point: Configuration#

// NewConfiguration creates a configuration with optional options.
func NewConfiguration(options ...ConfigurationOption) *Configuration

// ConfigurationSetLogger sets the slog handler on the Configuration.
func ConfigurationSetLogger(h slog.Handler) ConfigurationOption

// Init wires up storage driver + Kubernetes client.
func (cfg *Configuration) Init(getter genericclioptions.RESTClientGetter, namespace, helmDriver string, ...) error

*Configuration is injected into every action constructor. It holds all shared dependencies (Kubernetes client, storage, registry client).

Action types and their Run() methods#

API style#

• Constructor injection: New<Action>(cfg *Configuration) returns a concrete action struct.
• Field configuration: Callers set fields directly on the struct (no builder methods):

  client := action.NewInstall(cfg)
  client.ReleaseName = "myapp"
  client.Namespace = "production"
  client.DryRun = true
  client.Wait = true
  client.Timeout = 5 * time.Minute
  rel, err := client.Run(chart, values)

• Functional options for Pull, Push, RegistryLogin (uses With* option funcs alongside the struct approach).
• ConfigurationOption functional options for customizing Configuration at construction.

Backward compatibility#

pkg/action carries an implicit stability contract since Flux, Argo CD, and other major projects import it directly. The v4 module path (helm.sh/helm/v4) marks the current breaking-change boundary. Interfaces like Releaser and Charter (from pkg/release and pkg/chart respectively) are the stable contracts callers program against.

Plugin / Extension system#

Helm has a first-class, typed plugin system used to extend four different extension points.

Plugin types (registered in internal/plugin/plugin_type_registry.go)#

Plugin runtimes#

1. Subprocess (runtime: subprocess) — the original plugin mechanism:

• Plugin is a standalone executable (any language)
• Helm invokes it as a child process, communicating via stdin/stdout JSON
• Platform-specific commands supported via platformCommand in plugin.yaml
• Hooks invoked on lifecycle events: install, upgrade, delete, update

2. WASM / Extism (runtime: extism/v1) — new in v4:

• Plugin is a .wasm binary loaded via the Extism runtime (WebAssembly)
• Sandboxed execution with configurable memory limits and filesystem access
• Memory and filesystem permissions configured in plugin.yaml under runtimeConfig
• All four plugin types can use either runtime

Key plugin interfaces#

// Plugin — client-facing plugin abstraction (internal/plugin/plugin.go)
type Plugin interface {
    Dir() string
    Metadata() Metadata
    Invoke(ctx context.Context, input *Input) (*Output, error)
}

// PluginHook — lifecycle event callbacks
type PluginHook interface {
    InvokeHook(event string) error
}

// PostRenderer — extension point for YAML transformation (pkg/postrenderer/postrenderer.go)
type PostRenderer interface {
    Run(renderedManifests *bytes.Buffer) (modifiedManifests *bytes.Buffer, err error)
}

// Getter — extension point for chart sources (pkg/getter/getter.go)
type Getter interface {
    Get(href string, options ...Option) (*bytes.Buffer, error)
}

Extension point: PostRenderer#

PostRenderer is the cleanest extension point for library consumers. Passed directly into action.Install or action.Upgrade:

client := action.NewInstall(cfg)
client.PostRenderer = myKustomizeRenderer  // any PostRenderer impl

The built-in factory NewPostRendererPlugin(settings, pluginName, args...) creates a PostRenderer backed by a postrenderer/v1 plugin. Library consumers can also implement PostRenderer directly without writing a plugin.

Extension point: Getter#

Custom chart retrieval protocols are registered in pkg/getter.Providers. The built-in providers handle http://, https://, and oci://. Getter plugins bridge to a getter/v1 plugin that receives the URL and returns chart bytes.

Plugin installation#

helm plugin install supports three installation sources:

• Local directory
• HTTP/HTTPS tarball URL (with optional provenance verification)
• OCI registry artifact (artifact type: application/vnd.helm.plugin.v1+json)

API surface summary#