rules_helm

Bazel rules for producing helm charts

Setup MODULE.bazel

rules_helm is published to the Bazel Central Registry:

bazel_dep(name = "rules_helm", version = "{version}")

Run as a tool

bazel run @helm//:helm -- ...

Use in a genrule

genrule(
    name = "genrule",
    srcs = [":chart"],
    outs = ["template.yaml"],
    cmd = "$(HELM_BIN) template my-chart $(execpath :chart) > $@",
    toolchains = ["@rules_helm//helm:current_toolchain"],
)

Helm Rules

helm_chart rule.

helm_chart

load("@rules_helm//helm:helm_chart.bzl", "helm_chart")

helm_chart(*, name, chart, chart_json, crds, values, values_json, substitutions, templates, schema,
           files, images, deps, install_name, registry_url, registry_url_file, login_url, push_cmd,
           helm_opts, install_opts, package_opts, push_opts, upgrade_opts, uninstall_opts, data,
           stamp, **kwargs)

Rules for producing a helm package and some convenience targets.

target	rule	condition
`{name}`	helm_package	`None`
`{name}.push_images`	helm_push_images	`None`
`{name}.oci_digest`	helm_oci_digest	`None`
`{name}.push_registry`	helm_push (`include_images = False`)	`registry_url` or `registry_url_file` is defined.
`{name}.push`	helm_push (`include_images = True`)	`registry_url` or `registry_url_file` is defined.
`{name}.install`	helm_install	`None`
`{name}.uninstall`	helm_uninstall	`None`
`{name}.upgrade`	helm_upgrade	`None`

PARAMETERS

Name	Description	Default Value
name	The name of the helm_package target.	none
chart	The path to the chart directory. Defaults to `Chart.yaml`.	`None`
chart_json	The json encoded contents of `Chart.yaml`.	`None`
crds	A list of crd files to include in the package.	`None`
values	The path to the values file. Defaults to `values.yaml`.	`None`
values_json	The json encoded contents of `values.yaml`.	`None`
substitutions	A dictionary of substitutions to apply to `values.yaml`.	`{}`
templates	A list of template files to include in the package.	`None`
schema	A JSON Schema file for values. Defaults to `values.schema.json`.	`None`
files	Files accessed in templates via the `.Files` api.	`[]`
images	A list of oci_push or image_push targets	`[]`
deps	A list of helm package dependencies.	`None`
install_name	The `helm install` name to use. `name` will be used if unset.	`None`
registry_url	The registry url for the helm chart. `{name}.push_registry` is only defined when a value is passed here. Mutually exclusive with `registry_url_file`.	`None`
registry_url_file	A file containing the registry url for the helm chart. `{name}.push_registry` is only defined when a value is passed here. Mutually exclusive with `registry_url`.	`None`
login_url	The registry url to log into for publishing helm charts.	`None`
push_cmd	An alternative command to `push` for publishing helm charts.	`None`
helm_opts	Additional options to pass to helm.	`[]`
install_opts	Additional options to pass to `helm install`.	`[]`
package_opts	Additional options to pass to `helm package`.	`[]`
push_opts	Additional options to pass to `helm push`.	`[]`
upgrade_opts	Additional options to pass to `helm upgrade`.	`[]`
uninstall_opts	Additional options to pass to `helm uninstall`.	`[]`
data	Additional runtime data to pass to the helm install, upgrade, and uninstall targets.	`[]`
stamp	Whether to encode build information into the helm chart.	`None`
kwargs	Additional keyword arguments for `helm_package`.	none

helm_command rules.

helm_command

load("@rules_helm//helm:helm_command.bzl", "helm_command")

helm_command(name, data, command, helm_opts, install_name, opts, package, values)

Produce an executable that invokes helm with an arbitrary subcommand. Useful for wrapping helm plugins (e.g. helm-diff) without requiring a dedicated rule for each plugin.

Example:

load("@rules_helm//helm:defs.bzl", "helm_command")

helm_command(
    name = "my_chart.diff",
    command = ["diff", "upgrade"],
    install_name = "my-chart",
    package = ":my_chart",
)

Any helm plugin referenced by command must be registered in the active helm toolchain (see helm_plugin / helm_toolchain).

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
data	Additional data to pass to the helm invocation.	List of labels	optional	`[]`
command	Subcommand tokens placed between `helm_opts` and `opts` (e.g. `["diff", "upgrade"]`).	List of strings	required
helm_opts	Additional arguments to pass to `helm` before the subcommand.	List of strings	optional	`[]`
install_name	Release name appended as a positional after `opts`. Omitted when unset.	String	optional	`""`
opts	Additional arguments to pass after the subcommand.	List of strings	optional	`[]`
package	Optional helm package. When set, its chart path is appended as the final positional argument.	Label	optional	`None`
values	Values files to pass to the subcommand via `--values`.	List of labels	optional	`[]`

helm_import rules.

helm_import

load("@rules_helm//helm:helm_import.bzl", "helm_import")

helm_import(name, chart, version)

A rule that allows pre-packaged Helm charts to be used within Bazel.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
chart	A Helm chart's `.tgz` file.	Label	optional	`None`
version	The version fo the helm chart	String	optional	`""`

helm_import_repository

load("@rules_helm//helm:helm_import.bzl", "helm_import_repository")

helm_import_repository(name, chart_name, repository, sha256, url, version)

A rule for fetching external Helm charts from an arbitrary URL or repository.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this repository.	Name	required
chart_name	Chart name to import. Must be set if `repository` is specified	String	optional	`""`
repository	Chart repository url where to locate the requested chart. Mutually exclusive with `url`.	String	optional	`""`
sha256	The expected SHA-256 hash of the chart imported.	String	optional	`""`
url	The url where a chart can be directly downloaded. Mutually exclusive with `chart_name`, `repository`, and `version`	String	optional	`""`
version	Specify a version constraint for the chart version to use. Must be set if `repository` is specified.	String	optional	`""`

helm_install rules.

helm_install

load("@rules_helm//helm:helm_install.bzl", "helm_install")

helm_install(name, data, helm_opts, install_name, opts, package, values)

Produce an executable for performing a helm install operation.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
data	Additional data to pass to `helm install`.	List of labels	optional	`[]`
helm_opts	Additional arguments to pass to `helm` during install.	List of strings	optional	`[]`
install_name	The name to use for the `helm install` command. The target name will be used if unset.	String	optional	`""`
opts	Additional arguments to pass to `helm install`.	List of strings	optional	`[]`
package	The helm package to install.	Label	required
values	Values files to pass to `helm install --values`.	List of labels	optional	`[]`

helm_uninstall

load("@rules_helm//helm:helm_install.bzl", "helm_uninstall")

helm_uninstall(name, data, helm_opts, install_name, opts)

Produce an executable for performing a helm uninstall operation.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
data	Additional data to pass to `helm uninstall`.	List of labels	optional	`[]`
helm_opts	Additional arguments to pass to `helm` during install.	List of strings	optional	`[]`
install_name	The name to use for the `helm install` command. The target name will be used if unset.	String	optional	`""`
opts	Additional arguments to pass to `helm uninstall`.	List of strings	optional	`[]`

helm_upgrade

load("@rules_helm//helm:helm_install.bzl", "helm_upgrade")

helm_upgrade(name, data, helm_opts, install_name, opts, package, values)

Produce an executable for performing a helm upgrade operation.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
data	Additional data to pass to `helm upgrade`.	List of labels	optional	`[]`
helm_opts	Additional arguments to pass to `helm` during upgrade.	List of strings	optional	`[]`
install_name	The name to use for the `helm upgrade` command. The target name will be used if unset.	String	optional	`""`
opts	Additional arguments to pass to `helm upgrade`.	List of strings	optional	`[]`
package	The helm package to upgrade.	Label	required
values	Values files to pass to `helm upgrade --values`.	List of labels	optional	`[]`

helm_lint rules.

helm_lint_test

load("@rules_helm//helm:helm_lint.bzl", "helm_lint_test")

helm_lint_test(name, chart, opts, substitutions, values)

A rule for performing helm lint on a helm package

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
chart	The helm package to run linting on.	Label	required
opts	Additional arguments to pass to `helm lint`.	List of strings	optional	`[]`
substitutions	A dictionary of substitutions passed to `helm lint --set flag.	Dictionary: String -> String	optional	`{}`
values	A list of files passed to `helm lint --values flag.	List of labels	optional	`[]`

helm_lint_aspect

load("@rules_helm//helm:helm_lint.bzl", "helm_lint_aspect")

helm_lint_aspect()

An aspect for running helm lint on helm package targets

ASPECT ATTRIBUTES

ATTRIBUTES

helm_oci_digest rules.

helm_oci_digest

load("@rules_helm//helm:helm_oci_digest.bzl", "helm_oci_digest")

helm_oci_digest(name, chart)

Compute the OCI manifest digest for a Helm chart at build time.

This rule constructs the OCI manifest that helm push (Helm v4) would create and computes its sha256 digest. The .tgz file's mtime is used for the creation annotation, formatted in UTC to match the push side.

The digest file contains a single line: sha256:<hex>.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
chart	A helm_chart target providing HelmPackageInfo.	Label	required

HelmOCIDigestInfo

load("@rules_helm//helm:helm_oci_digest.bzl", "HelmOCIDigestInfo")

HelmOCIDigestInfo(digest)

OCI manifest digest for a Helm chart, computed at build time.

FIELDS

Name	Description
digest	File: Text file containing the OCI manifest digest (sha256:...)

helm_package rule.

Rules

helm_package

helm_package

load("@rules_helm//helm:helm_package.bzl", "helm_package")

helm_package(name, deps, chart, chart_json, crds, files, images, opts, schema, stamp, substitutions,
             templates, values, values_json)

Rules for creating Helm chart packages.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	Other helm packages this package depends on.	List of labels	optional	`[]`
chart	The `Chart.yaml` file of the helm chart	Label	optional	`None`
chart_json	The `Chart.yaml` file of the helm chart as a json object	String	optional	`""`
crds	All Custom Resource Definitions associated with the current helm chart. E.g., the `./crds` directory	List of labels	optional	`[]`
files	Files accessed in templates via the `.Files` api	List of labels	optional	`[]`
images	A list of oci_push or image_push targets.	List of labels	optional	`[]`
opts	Additional arguments to pass to `helm package` commands.	List of strings	optional	`[]`
schema	The `values.schema.json` file for the current package.	Label	optional	`None`
stamp	Whether to encode build information into the helm actions. Possible values: - `stamp = 1`: Always stamp the build information into the helm actions, even in --nostamp builds. This setting should be avoided, since it potentially kills remote caching for the target and any downstream actions that depend on it. - `stamp = 0`: Always replace build information by constant values. This gives good build result caching. - `stamp = -1`: Embedding of build information is controlled by the --[no]stamp flag. Stamped targets are not rebuilt unless their dependencies change.	Integer	optional	`-1`
substitutions	A dictionary of substitutions to apply to the `values.yaml` file.	Dictionary: String -> String	optional	`{}`
templates	All templates associated with the current helm chart. E.g., the `./templates` directory	List of labels	optional	`[]`
values	The `values.yaml` file for the current package.	Label	optional	`None`
values_json	The `values.yaml` file for the current package as a json object.	String	optional	`""`

HelmPackageInfo provider

Providers

HelmPackageInfo

HelmPackageInfo

load("@rules_helm//helm:helm_package_info.bzl", "HelmPackageInfo")

HelmPackageInfo(chart, images, metadata)

A provider for helm packages

FIELDS

Name	Description
chart	File: The result of `helm package`
images	list[Target]: A list of @rules_oci//oci:defs.bzl%oci_push or @rules_img//img:push.bzl%image_push targets
metadata	File: A json encoded file containing metadata about the helm chart

helm_plugin rule.

Rules

helm_plugin

helm_plugin

load("@rules_helm//helm:helm_plugin.bzl", "helm_plugin")

helm_plugin(name, data, plugin_name, yaml)

Define a helm plugin.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
data	Additional files associated with the plugin.	List of labels	optional	`[]`
plugin_name	An explicit name for the plugin. If unset, `name` will be used.	String	optional	`""`
yaml	The yaml file representing the plugin	Label	required

helm_push rules.

Rules

helm_push

load("@rules_helm//helm:helm_push.bzl", "helm_push")

helm_push(name, env, include_images, login_url, opts, package, push_cmd, registry_url,
          registry_url_file)

Produce an executable for performing a helm push to a registry.

Before performing helm push the executable produced will conditionally perform helm registry login if the following environment variables are defined:

HELM_REGISTRY_USERNAME: The value of --username.
HELM_REGISTRY_PASSWORD/HELM_REGISTRY_PASSWORD_FILE: The value of --password or a file containing the --password value.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
env	Environment variables to set when running this target.	Dictionary: String -> String	optional	`{}`
include_images	If True, images depended on by `package` will be pushed as well.	Boolean	optional	`False`
login_url	The URL of the registry to use for `helm login`. E.g. `my.registry.io`	String	optional	`""`
opts	Additional arguments to pass to `helm` commands.	List of strings	optional	`[]`
package	The helm package to push to the registry.	Label	required
push_cmd	An alternative command to `push` for publishing the helm chart. E.g. `cm-push`	String	optional	`""`
registry_url	The registry URL at which to push the helm chart to. E.g. `oci://my.registry.io/chart-name`. Mutually exclusive with `registry_url_file`.	String	optional	`""`
registry_url_file	A file containing the registry URL at which to push the helm chart to. Mutually exclusive with `registry_url`.	Label	optional	`None`

helm_push_images

load("@rules_helm//helm:helm_push.bzl", "helm_push_images")

helm_push_images(name, env, package)

Produce an executable for pushing all oci images used by a helm chart.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
env	Environment variables to set when running this target.	Dictionary: String -> String	optional	`{}`
package	The helm package to upload images from.	Label	required

helm_push_registry

load("@rules_helm//helm:helm_push.bzl", "helm_push_registry")

helm_push_registry(name, env, include_images, login_url, opts, package, push_cmd, registry_url,
                   registry_url_file)

Produce an executable for performing a helm push to a registry.

Before performing helm push the executable produced will conditionally perform helm registry login if the following environment variables are defined:

HELM_REGISTRY_USERNAME: The value of --username.
HELM_REGISTRY_PASSWORD/HELM_REGISTRY_PASSWORD_FILE: The value of --password or a file containing the --password value.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
env	Environment variables to set when running this target.	Dictionary: String -> String	optional	`{}`
include_images	If True, images depended on by `package` will be pushed as well.	Boolean	optional	`False`
login_url	The URL of the registry to use for `helm login`. E.g. `my.registry.io`	String	optional	`""`
opts	Additional arguments to pass to `helm` commands.	List of strings	optional	`[]`
package	The helm package to push to the registry.	Label	required
push_cmd	An alternative command to `push` for publishing the helm chart. E.g. `cm-push`	String	optional	`""`
registry_url	The registry URL at which to push the helm chart to. E.g. `oci://my.registry.io/chart-name`. Mutually exclusive with `registry_url_file`.	String	optional	`""`
registry_url_file	A file containing the registry URL at which to push the helm chart to. Mutually exclusive with `registry_url`.	Label	optional	`None`

helm_template rules.

Rules

helm_template

load("@rules_helm//helm:helm_template.bzl", "helm_template")

helm_template(name, out, chart, opts, values)

A rule for rendering helm chart templates to a file.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
out	The output file to write the output from `helm template`.	Label; nonconfigurable	optional	`None`
chart	The helm package to resolve charts for.	Label	required
opts	Additional arguments to pass to `helm template`.	List of strings	optional	`[]`
values	Values files to pass to `helm template --values`.	List of labels	optional	`[]`

helm_template_test

load("@rules_helm//helm:helm_template.bzl", "helm_template_test")

helm_template_test(name, chart, installer, opts, template_patterns, values)

A test rule for rendering helm chart templates.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
chart	The helm package to resolve templates for. Mutually exclusive with `installer`.	Label	required
installer	The `helm_install`/`helm_upgrade` target to resolve templates for. Mutually exclusive with `chart`.	Label	optional	`None`
opts	Additional arguments to pass to `helm template`.	List of strings	optional	`[]`
template_patterns	A mapping of template paths to regex patterns required to match.	Dictionary: String -> List of strings	optional	`{}`
values	Values files to pass to `helm template --values`.	List of labels	optional	`[]`

helm_toolchain rule.

Rules

helm_toolchain

helm_toolchain

load("@rules_helm//helm:helm_toolchain.bzl", "helm_toolchain")

helm_toolchain(name, helm, plugins)

A helm toolchain.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
helm	A helm binary	Label	required
plugins	Additional plugins to make available to helm.	List of labels	optional	`[]`

Bzlmod extensions

Module Extensions

helm

helm

helm = use_extension("@rules_helm//helm:extensions.bzl", "helm")
helm.host_tools(name, version)
helm.plugin(name, integrity, strip_prefix, url_templates, version, yaml)
helm.toolchain(name, plugins)

TAG CLASSES

host_tools

An extension for creating a host alias repository that provides a shorter name for the host platform's helm binary.

An example of defining and using host tools:

helm = use_extension("@rules_helm//helm:extensions.bzl", "helm")
helm.host_tools(name = "helm")
use_repo(helm, "helm")

# Then you can use @helm//:helm in your BUILD files

Attributes

Name	Description	Type	Mandatory	Default
name	The name of the host alias repository.	Name	optional	`"helm"`
version	The version of helm to use for host tools.	String	optional	`"4.2.0"`

plugin

An extension tag for declaring Helm plugins.

Plugins are downloaded per-platform and made available to helm.toolchain() tags that reference them by name. Only platforms listed in integrity (and url_templates) will receive the plugin.

An example of declaring the helm-diff plugin and wiring it into a named toolchain:

helm = use_extension("@rules_helm//helm:extensions.bzl", "helm")
helm.host_tools()
helm.plugin(
    name = "diff",
    version = "3.15.5",
    strip_prefix = "diff",
    url_templates = {
        "darwin-arm64": ["https://github.com/databus23/helm-diff/releases/download/v{version}/helm-diff-macos-arm64.tgz"],
        "linux-amd64": ["https://github.com/databus23/helm-diff/releases/download/v{version}/helm-diff-linux-amd64.tgz"],
    },
    integrity = {
        "darwin-arm64": "sha256-KJmZ7wY3gAcWFzK5R9+TfQlaRfEXzJ7hDNRC8NgIDog=",
        "linux-amd64": "sha256-ToJjCrKyMxfAOeezsWYF95qKwPPSKHPg1G6pzZgN2o4=",
    },
)
helm.toolchain(
    name = "with_diff",
    plugins = ["diff"],
)
use_repo(helm, "helm", "helm_toolchains", "with_diff_toolchains")
register_toolchains("@helm_toolchains//:all")

Attributes

Name	Description	Type	Mandatory	Default
name	The name of the plugin.	Name	required
integrity	A mapping of helm platform name to integrity hash. Only platforms listed here will receive the plugin.	Dictionary: String -> String	required
strip_prefix	A directory prefix to strip from the extracted plugin archive.	String	optional	`""`
url_templates	Mapping of helm platform name to a list of URL templates for downloading the plugin on that platform. Only `{version}` is substituted; spell the platform name into the URL string directly. Every key in `integrity` must have a matching entry here.	Dictionary: String -> List of strings	required
version	The version of the plugin to download.	String	required
yaml	Relative path to plugin.yaml within the extracted archive (after strip_prefix).	String	optional	`"plugin.yaml"`

toolchain

Define a named set of helm toolchains with specific plugins.

Creates an independent hub repository @{name}_toolchains containing toolchains for the default helm version with the specified plugins baked in. Only platforms where all referenced plugins are available will have toolchains generated.

The hub is not registered automatically — call register_toolchains explicitly, or use a Starlark transition to override toolchain resolution.

helm = use_extension("@rules_helm//helm:extensions.bzl", "helm")
helm.plugin(name = "diff", ...)
helm.toolchain(
    name = "with_diff",
    plugins = ["diff"],
)
use_repo(helm, "with_diff_toolchains")
register_toolchains("@with_diff_toolchains//:all")

Attributes

Name	Description	Type	Mandatory	Default
name	Name prefix for the hub repository. Produces `@{name}_toolchains`.	Name	required
plugins	Plugin names (from `helm.plugin()` tags) to include in these toolchains.	List of strings	optional	`[]`