README.md

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}")

Rules

• helm_chart
• helm_import_repository
• helm_import
• helm_install
• helm_lint_aspect
• helm_lint_test
• helm_package
• helm_push
• helm_push_images
• helm_register_toolchains
• helm_toolchain
• helm_uninstall
• helm_upgrade
• rules_helm_dependencies
• chart_content

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

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, 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 crds associated with the current helm chart. E.g., the ./crds directory	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)

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

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, 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
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 templates.	[]
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)

Register helm toolchains.

PARAMETERS

Name	Description	Default Value
version	The version of Helm to use	"3.16.3"
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(name)

An aspect for running helm lint on helm package targets

ASPECT ATTRIBUTES

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required

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	""