yesod-mirror/tools/jsonnet_compiler/README.md

Custom Jsonnet Compiler

This directory contains a custom Jsonnet compiler built with Go. It wraps the standard go-jsonnet library and adds a native function helmTemplate to support rendering Helm charts directly within Jsonnet.

helmTemplate Native Function

The helmTemplate function allows you to render a Helm chart located on the filesystem.

Signature

native("helmTemplate")(name, chartPath, opts)

• name: The release name.
• chartPath: The path to the Helm chart directory (containing Chart.yaml). Crucial: This path must be relative to the directory containing the file that calls helmTemplate. When using Bazel external repositories, this often means navigating up to the execution root (e.g., ../../external/repo_name).
• opts: A configuration object.
  • calledFrom: (Required) The path of the file calling the function. Usually std.thisFile. The compiler uses this to resolve relative paths.
  • nameFormat: (Optional) Format string for resource names.
  • values: (Optional) Values to pass to the Helm chart.
  • includeCRDs: (Optional) Boolean, default true.
  • namespace: (Optional) Namespace for the release.

Usage Example

local helm = std.native("helmTemplate");

helm("my-release", "../../external/my_chart_repo", {
  calledFrom: std.thisFile,
  namespace: "default",
  values: {
    replicaCount: 2,
  },
})

Bazel Integration

This compiler is registered as a custom toolchain in //tools/jsonnet_compiler:helm_jsonnet_toolchain and used by rules_jsonnet.

Imports and JPaths

When using rules_jsonnet, the imports attribute adds directories to the Jsonnet search path (-J).

• imports = ["."] adds the package directory.
• deps on jsonnet_library targets adds their roots to the search path.

When importing files from external repositories (like tanka-util), ensure the import path matches the structure within that repository. For example, if tanka-util library is at the root of the @github_com_grafana_jsonnet_libs_tanka_util repo, you can import it as import "tanka-util/main.libsonnet" provided the repo root is in the search path (which deps handles).