masorange_rules_helm

Bazel rules to package, lint, publish and deploy Helm charts, plus a few companions used around a deployment: decrypting sops secrets, creating Kubernetes namespaces (with GKE Workload Identity) and uploading files to Google Cloud Storage.

Every external tool (helm, sops, kubectl, gcloud) is fetched by Bazel as a toolchain, so builds do not depend on what is installed on the host.

• Requirements
• Installation
• Quick start
• Rules
• Toolchains
• Stamping values
• Examples
• Development
• Releases
• License

Check the releases page for the latest version: every release carries a ready-to-paste snippet for both setups.

# MODULE.bazel
bazel_dep(name = "masorange_rules_helm", version = "1.8.2")

The module registers the helm, sops, kubectl and gcloud toolchains for you. See Toolchains to pin different versions.

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

http_archive(
    name = "masorange_rules_helm",
    sha256 = "<sha256 from the release notes>",
    strip_prefix = "masorange_rules_helm-1.8.2",
    urls = ["https://github.com/masmovil/masorange_rules_helm/releases/download/v1.8.2/masorange_rules_helm-v1.8.2.tar.gz"],
)

load("@masorange_rules_helm//:repositories.bzl", "masorange_rules_helm_repositories")

masorange_rules_helm_repositories()

load("@masorange_rules_helm//:config.bzl", "masorange_rules_helm_configure")

masorange_rules_helm_configure()

masorange_rules_helm_repositories() fetches the dependencies (bazel_skylib, rules_pkg, rules_oci, aspect_bazel_lib) and masorange_rules_helm_configure() sets them up and registers the toolchains. WORKSPACE support is legacy: Bazel 8 disables it by default and Bazel 9 removes it, so prefer bzlmod.

Package a chart from its sources, stamp the digest of the image it deploys into values.yaml, lint it, publish it and install it:

load("@masorange_rules_helm//helm:defs.bzl", "helm_chart", "helm_lint_test", "helm_push", "helm_release", "helm_uninstall")
load("@rules_oci//oci:defs.bzl", "oci_image")

oci_image(
    name = "image",
    base = "@distroless_java",
    entrypoint = ["java", "-jar", "/app.jar"],
)

helm_chart(
    name = "chart",
    chart_name = "my-service",
    srcs = glob(["chart/**"]),
    version = "1.4.0",
    app_version = "2.3.1",
    # writes the image digest into .image.tag and appends "@" to .image.repository
    image = ":image",
    values = {
        "replicaCount": "3",
        "ingress.host": "my-service.example.com",
    },
    deps = ["//charts/base:chart"],
)

# bazel test //my-service:lint
helm_lint_test(
    name = "lint",
    chart = ":chart",
)

# bazel run //my-service:push
helm_push(
    name = "push",
    chart = ":chart",
    repository_url = "oci://europe-docker.pkg.dev/my-project/helm-charts",
)

# bazel run //my-service:install
helm_release(
    name = "install",
    chart = ":chart",
    release_name = "my-service",
    namespace = "my-namespace",
    values = ["values-prod.yaml"],
    kubernetes_context = "my-cluster",
)

# bazel run //my-service:uninstall
helm_uninstall(
    name = "uninstall",
    release_name = "my-service",
    namespace = "my-namespace",
    kubernetes_context = "my-cluster",
)

bazel build //my-service:chart produces my-service-1.4.0.tgz. Rules that talk to a registry or a cluster (helm_push, helm_release, helm_uninstall, k8s_namespace, gcs_upload) build an executable: run them with bazel run.

Load from @masorange_rules_helm//helm:defs.bzl.

helm_chart also exposes a ChartInfo provider (chart name, version, sources and archive) for rules that want to consume charts.

Load from @masorange_rules_helm//sops:defs.bzl.

Load from @masorange_rules_helm//k8s:defs.bzl.

Load from @masorange_rules_helm//gcs:defs.bzl.

The binaries are downloaded from their official release channels and pinned by sha256:

With bzlmod the module registers the default versions. To pin another one, declare your own installation with a distinct name and register it; toolchains registered by the root module take precedence:

# MODULE.bazel
tools = use_extension("@masorange_rules_helm//:extensions.bzl", "toolchains")
tools.install(
    helm_name = "helm_pinned",
    helm_version = "v3.13.2",
)
use_repo(tools, "helm_pinned_toolchains")

register_toolchains("@helm_pinned_toolchains//:all")

The same tag accepts sops_name/sops_version, kubectl_name/kubectl_version and gcloud_name/gcloud_version. Versions must be one of the listed ones (each entry carries its checksums in */private/*_toolchain.bzl; adding a version is a small PR).

With WORKSPACE, masorange_rules_helm_configure() registers the defaults; the register_*_toolchains(name, version, register = True) helpers in toolchains.bzl let you register a different version.

values accepts Bazel workspace status variables. Enable stamping on the target and pass --stamp together with a --workspace_status_command:

helm_chart(
    name = "chart",
    chart_name = "my-service",
    srcs = glob(["chart/**"]),
    stamp = -1,  # follow --stamp / --nostamp
    values = {
        "deployment.branch": "${STABLE_GIT_BRANCH}",
        "deployment.buildTime": "${BUILD_TIMESTAMP}",
    },
)

bazel build //my-service:chart --stamp --workspace_status_command=./stamp.sh

Both stable and volatile variables are supported. Stamped charts are rebuilt whenever the status changes, so keep stamp off for charts that must stay cacheable.

The examples/ directory is a standalone Bazel module that consumes these rules the way a user would; it is built by CI and by the BCR presubmit on Bazel 7, 8 and 9.

bazel test //...                      # rules and integration tests (uses stamp.sh in CI: --config=ci)
(cd examples && bazel test //...)     # the examples module, against the local checkout
bazel run //docs:write_docs_md        # regenerate docs/*.md with Stardoc after changing a docstring

Rule implementations live under <area>/private/; the public API is re-exported from <area>/defs.bzl (and helm/helm.bzl for the pre-1.0 load path). Tests for helm_chart are in helm/tests/helm_chart and unpack the produced archive to compare it with the expected files.

Pushing a tag vX.Y.Z runs release.yaml: it runs the tests, builds the source archive, creates the GitHub release with the installation snippet and opens the publication PR against the Bazel Central Registry through publish.yaml.

Apache 2.0