rules_helm

Bazel rules for producing helm charts

Setup WORKSPACE

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

# See releases for urls and checksums
http_archive(
    name = "rules_helm",
    sha256 = "{sha256}",
    urls = ["https://github.com/abrisco/rules_helm/releases/download/{version}/rules_helm-v{version}.tar.gz"],
)

load("@rules_helm//helm:repositories.bzl", "helm_register_toolchains", "rules_helm_dependencies")

rules_helm_dependencies()

helm_register_toolchains()

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

rules_helm_transitive_dependencies()

Setup MODULE

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"],
)

Bazel rules for Helm.

Rules

Providers

HelmPackageInfo

Functions

Aspects

helm_lint_aspect

Repository Rules

helm_import_repository

chart_file

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

chart_file(name, api_version, app_version, chart_name, description, type, version)

Create a Helm chart file.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
api_version	The Helm API version	String	optional	`"v2"`
app_version	The version number of the application being deployed.	String	optional	`"1.16.0"`
chart_name	The name of the chart	String	optional	`""`
description	A descritpion of the chart.	String	optional	`"A Helm chart for Kubernetes by Bazel."`
type	The chart type.	String	optional	`"application"`
version	The chart version.	String	optional	`"0.1.0"`

helm_import

load("@rules_helm//helm:defs.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_install

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

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

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

helm_lint_test

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

helm_lint_test(name, chart)

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

helm_package

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

helm_package(name, deps, chart, chart_json, crds, files, images, 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 targets.	List of labels	optional	`[]`
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	`""`

helm_plugin

load("@rules_helm//helm:defs.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

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

helm_push(name, env, include_images, login_url, package, registry_url)

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	`""`
package	The helm package to push to the registry.	Label	required
registry_url	The registry URL at which to push the helm chart to. E.g. `oci://my.registry.io/chart-name`	String	required

helm_push_images

load("@rules_helm//helm:defs.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:defs.bzl", "helm_push_registry")

helm_push_registry(name, env, include_images, login_url, package, registry_url)

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	`""`
package	The helm package to push to the registry.	Label	required
registry_url	The registry URL at which to push the helm chart to. E.g. `oci://my.registry.io/chart-name`	String	required

helm_template_test

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

helm_template_test(name, chart, installer, template_patterns)

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`
template_patterns	A mapping of template paths to regex patterns required to match.	Dictionary: String -> List of strings	optional	`{}`

helm_toolchain

load("@rules_helm//helm:defs.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	`[]`

helm_uninstall

load("@rules_helm//helm:defs.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:defs.bzl", "helm_upgrade")

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

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

HelmPackageInfo

load("@rules_helm//helm:defs.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 targets
metadata	File: A json encoded file containing metadata about the helm chart

chart_content

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

chart_content(name, api_version, description, type, version, app_version)

A convenience wrapper for defining Chart.yaml files with helm_package.chart_json.

PARAMETERS

Name	Description	Default Value
name	The name of the chart	none
api_version	The Helm API version	`"v2"`
description	A descritpion of the chart.	`"A Helm chart for Kubernetes by Bazel."`
type	The chart type.	`"application"`
version	The chart version.	`"0.1.0"`
app_version	The version number of the application being deployed.	`"1.16.0"`

RETURNS

str: A json encoded string which represents Chart.yaml contents.

helm_chart

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

helm_chart(*, name, chart, chart_json, crds, values, values_json, substitutions, templates, files,
           images, deps, install_name, registry_url, login_url, helm_opts, install_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}.push_registry`	helm_push (`include_images = False`)	`registry_url` is defined.
`{name}.push`	helm_push (`include_images = True`)	`registry_url` 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`
files	Files accessed in templates via the `.Files` api.	`[]`
images	A list of oci_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.	`None`
login_url	The registry url to log into for publishing helm charts.	`None`
helm_opts	Additional options to pass to helm.	`[]`
install_opts	Additional options to pass to `helm install`.	`[]`
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_register_toolchains

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

helm_register_toolchains(version, helm_url_templates, plugins)

PARAMETERS

Name	Description	Default Value
version	The version of Helm to use	`"3.17.0"`
helm_url_templates	A list of url templates where helm can be downloaded.	`["https://get.helm.sh/helm-v{version}-{platform}.{compression}"]`
plugins	Labels to `helm_plugin` targets to add to generated toolchains.	`[]`

rules_helm_dependencies

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

rules_helm_dependencies()

Defines helm dependencies

helm_lint_aspect

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

helm_lint_aspect()

An aspect for running helm lint on helm package targets

ASPECT ATTRIBUTES

ATTRIBUTES

helm_import_repository

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

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

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

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this repository.	Name	required
chart_name	Chart name to import.	String	optional	`""`
repo_mapping	In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository. For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`). This attribute is not supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function).	Dictionary: String -> String	optional
repository	Chart repository url where to locate the requested chart.	String	required
sha256	The expected SHA-256 hash of the chart imported.	String	optional	`""`
url	The url where the chart can be directly downloaded.	String	optional	`""`
version	Specify a version constraint for the chart version to use.	String	optional	`""`