Helm Plugins

Helm Plugins extend the functionality of Helm, the package manager for Kubernetes, by allowing users and developers to add custom commands and behaviors beyond the core Helm features. They enable the automation of Helm workflows, integration with other tools, and customization of Helm’s command-line interface (CLI). Helm Plugins are separate executables that Helm discovers and invokes, making it possible to tailor Helm’s functionality to specific organizational or project needs without modifying Helm’s core codebase.

Plugin Metadata and Configuration

Each Helm Plugin is defined by metadata stored in a plugin.yaml file located within the plugin’s directory structure. This metadata file specifies essential information about the plugin such as its name, version, description, the command it implements, usage instructions, and the executable to run.

Key fields in plugin.yaml include:

• name: The unique name of the plugin.
• version: The version of the plugin.
• usage: A brief description of what the plugin does or how it should be used.
• command: The CLI command string that Helm recognizes to invoke the plugin.
• description: A detailed explanation of the plugin’s purpose.
• hooks (optional): Defines lifecycle hooks that allow the plugin to run at specific points during Helm operations.
• bin (optional): The path to the binary or script that implements the plugin logic.
• homepage and sources (optional): URLs for documentation or source code repositories.

The plugin’s executable can be a compiled binary, a shell script, or any executable file compatible with the user’s environment. Helm invokes this executable when the plugin’s command is triggered.

CLI Plugins

CLI Plugins are the most common type of Helm Plugins. They add new Helm subcommands or augment existing commands with additional functionality.

Command Invocation

When a user runs helm <plugin-command>, Helm intercepts the command and checks if a plugin matching that command exists. If found, Helm executes the plugin’s binary, passing along any arguments and flags.

For example, a plugin named helm-diff can be invoked as:

helm diff upgrade my-release my-chart

where diff is the plugin command.

Argument and Flag Handling

Plugins receive the command-line arguments and flags as-is, enabling them to parse and process them independently of Helm. Plugins can implement their own flag parsing or leverage Helm’s conventions for consistency.

Output and Error Handling

Plugins output results directly to stdout and stderr. Helm forwards this output to the user’s terminal. Plugins should use standard exit codes to indicate success or failure, allowing Helm and scripts to handle errors appropriately.

Getter Plugins

Getter Plugins extend Helm’s ability to fetch chart dependencies and resources from custom or non-standard sources. Helm’s built-in getters can retrieve data from HTTP(S), Git, OCI registries, and local files. Getter Plugins allow the addition of new protocols or authentication mechanisms.

Use Cases

• Fetching charts or dependencies from private repositories with specialized authentication.
• Accessing charts stored in unconventional locations or formats.
• Integrating with internal artifact stores or proprietary systems.

Implementation

Getter Plugins are executables that implement a standard interface Helm calls when attempting to retrieve a resource over a given protocol. The plugin reads the requested URL and writes the fetched content to stdout.

URL Scheme Registration

A Getter Plugin registers itself for one or more URL schemes (e.g., custom://) by implementing the getter interface and declaring supported schemes in its metadata. When Helm encounters a URL with a registered scheme, it delegates fetching to the appropriate Getter Plugin.

Post-Renderer Plugins

Post-Renderer Plugins allow users to process Helm’s rendered Kubernetes manifest output before it is sent to the cluster for deployment. This enables advanced customization and integration with other tools.

Workflow Integration

After Helm renders templates into manifests, it pipes the output through the post-renderer plugin executable. The plugin can modify, transform, validate, or augment the manifests as needed.

Use Cases

• Injecting additional labels or annotations.
• Enforcing security policies or resource quotas.
• Applying custom patches or transformations.
• Integrating with tools like kustomize or yq.

Execution Model

The post-renderer plugin is a command-line executable that accepts the rendered manifests on stdin and outputs the modified manifests on stdout. Helm invokes it automatically if configured via the --post-renderer flag.

Plugin Runtime Model

Helm Plugins operate as external processes launched by the Helm CLI. This process-based model ensures strong separation between Helm core and plugin implementations, allowing plugins to be written in any language or environment.

Plugin Discovery

Helm discovers plugins by scanning the user’s Helm plugin directory, usually located at ~/.config/helm/plugins. Each plugin resides in its own subdirectory containing the plugin.yaml and executable files.

Execution Context

When a plugin command is invoked, Helm sets environment variables and command-line arguments for the plugin process. Environment variables provide context such as Helm version, plugin root directory, and configuration paths.

Lifecycle Hooks

Plugins can define hooks triggered during Helm operations, like pre-install or post-upgrade events. These hooks enable plugins to execute code at specific points in a release lifecycle and integrate tightly with Helm workflows.

Security Considerations

Since plugins execute arbitrary code, users should ensure they trust the source of plugins they install. Helm plugins run with the user’s permissions, so malicious plugins can potentially affect system or cluster state.

Plugin Development

Developing Helm Plugins involves creating an executable that meets Helm’s plugin interface requirements and packaging it with appropriate metadata.

Language and Tools

Plugins can be developed in any programming language capable of creating executables or scripts. Common languages include Go, Python, Bash, and others.

Development Steps

1. Create the executable implementing the desired functionality.
2. Create the plugin.yaml metadata file with the plugin’s configuration.
3. Organize the files in a directory structure under the Helm plugins directory or package them for distribution.
4. Test the plugin by invoking it through Helm.

Best Practices

• Follow Helm’s CLI conventions for consistency.
• Implement clear and helpful usage messages.
• Handle errors gracefully and provide meaningful exit codes.
• Document the plugin’s purpose, usage, and installation instructions.

Plugin Packaging and Distribution

To share Helm Plugins with others, they must be packaged and distributed in a manner that simplifies installation and updates.

Packaging Format

Plugins are packaged as compressed archives (e.g., .tgz) containing the plugin directory, metadata, and binaries. This archive structure allows Helm to install the plugin atomically.

Installation

Users install plugins using the Helm CLI command:

helm plugin install <plugin-archive-url>

Helm downloads, extracts, and registers the plugin automatically.

Updating and Removing Plugins

• Plugins can be updated using:

helm plugin update <plugin-name>

• Plugins can be removed via:

helm plugin uninstall <plugin-name>

Distribution Channels

Plugins can be distributed via GitHub releases, artifact repositories, or private registries. Good distribution practices include versioning, digital signatures, and documentation to ensure trust and usability.

Helm Plugins provide a powerful extensibility mechanism that enhances Helm’s capabilities and allows users to tailor Helm’s behavior to their specific Kubernetes deployment workflows. Through metadata configuration, versatile plugin types, a well-defined runtime model, and robust packaging options, Helm Plugins foster a vibrant ecosystem of tools and integrations around Helm.