jhelm

Table of Contents

• Why jhelm
• Features
• Modules
• Tech Stack
• Spring Boot compatibility
• Quick Start
  • As a library
  • As a CLI
  • As a REST API
  • As an MCP server
• Documentation
• Building
• License

A native Java implementation of the Helm package manager for Kubernetes. Render templates, manage charts, and deploy releases from the JVM — as an embeddable library, a Spring Boot starter, a REST API, or a standalone CLI — without shelling out to the Go-based Helm binary.

📖 Documentation: https://www.alexmond.org/jhelm/current/

Why jhelm

• Helm-faithful rendering, in pure Java — jhelm renders chart templates identically to helm template (same charts, default values, pinned --kube-version v1.35.0) across a continuously-run suite of 540+ real-world charts (Bitnami, Grafana, GitLab, Kubernetes-monitoring, and more), with no Go or helm binary. The comparison is byte-for-byte apart from a small set of documented, non-semantic differences (generated secrets/certs and toYaml key-ordering in checksum/* annotations). This is template-rendering parity; install/upgrade reuse the same renderer but talk to the cluster through the Kubernetes Java client. Parity is enforced in CI on every change.

• Pure JVM, no native binary — no helm executable, no exec, no platform-specific distribution. Just a Maven dependency.

• MCP-native — the same operations are exposed as Model Context Protocol tools, so an AI agent can render charts and manage releases directly. See the MCP guide.

• Designed to be embedded — a clean programmatic API (TemplateAction, InstallAction, …), Spring Boot auto-configuration, and a REST module, in addition to the CLI.

• Go template engine on Maven Central — the template/Sprig engine is the standalone gotmpl4j library, reusable on its own.

Features

• Go template engine — the full Go text/template language with Helm’s Sprig function set and Helm-specific functions (include, tpl, required, lookup, toYaml, …), matched against Helm’s own conformance tests.

• Chart lifecycle — install, upgrade, rollback, uninstall, list, status, history, test.

• Repository & registry management — add/remove repos, search, pull, push over both classic HTTP repositories and OCI registries.

• Dependency management — list, update, and build chart dependencies (Chart.yaml dependencies, charts/ vendoring, conditions/tags).

• Packaging & provenance — package charts to .tgz, sign and verify with PGP provenance files.

• Spring Boot integration — auto-configured beans, @ConfigurationProperties, and a programmatic action API.

• REST API — a Spring MVC library exposing chart and template operations over HTTP, with OpenAPI/Swagger documentation. Split into a pure jhelm-rest library and a jhelm-rest-starter that carries the auto-configuration, with a READ_ONLY/FULL access mode gating the cluster-mutating endpoints.

• MCP server — jhelm-mcp / jhelm-mcp-starter expose jhelm operations as Model Context Protocol tools for AI agents (built on Spring AI), mirroring the REST operation set with the same READ_ONLY/FULL access mode.

• JSON Schema validation — validates chart values against values.schema.json with a full JSON Schema validator (draft 2020-12 by default; a schema’s own $schema, such as Draft-07, is honoured).

• Async Kubernetes operations — Java 21 virtual threads via AsyncKubeService.

• Value management beyond Helm — Spring-Boot-style value profiles (per-environment overlays via -P/--profile), values sourced from a central Spring Cloud Config Server, and {cipher}-encrypted secret values decrypted at render time (with jhelm encrypt / jhelm decrypt). All opt-in; charts that don’t use them render byte-for-byte as Go Helm.

Modules

Module	Description
jhelm-core	Chart model, loader, repository manager, rendering engine, and action API. The main entry point for library users.
jhelm-gotemplate-helm	Helm-specific template functions (include, tpl, required, toYaml, lookup, …) layered on top of gotmpl4j.
jhelm-kube	Kubernetes client integration — apply/delete resources, Helm-compatible Secret-based release storage, async operations.
jhelm-rest	Spring MVC REST API over jhelm operations, with OpenAPI documentation (pure library — bring your own auto-configuration).
jhelm-rest-starter	Spring Boot starter that auto-configures the jhelm-rest API, with a READ_ONLY/FULL access mode gating cluster-mutating endpoints.
jhelm-mcp	Model Context Protocol server exposing jhelm operations as AI-agent tools (built on Spring AI), mirroring the REST operation set.
jhelm-mcp-starter	Spring Boot starter that auto-configures the jhelm-mcp server, with a READ_ONLY/FULL access mode.
jhelm-plugin	WebAssembly plugin runtime — loads and runs jhelm’s sandboxed .jhp plugins.
jhelm-plugin-api	Java plugin API — extension points for post-renderers, chart downloaders, lifecycle listeners, and template functions.
jhelm-cli	Standalone CLI (Spring Boot + Picocli) — 22 Helm-compatible commands plus encrypt/decrypt for secret values.

The Go template + Sprig engine lives in the separate gotmpl4j project (on Maven Central) and is consumed as a dependency.

Tech Stack

Java	21
Spring Boot	4.1.1
Kubernetes Client	26.0.0
Template engine	gotmpl4j 1.4.0
CLI framework	Picocli 4.7.7

Spring Boot compatibility

jhelm has its own MAJOR.MINOR.PATCH version. Each jhelm minor line is built on one Spring Boot line, so pick the jhelm line that matches the Spring Boot version of your application.

jhelm	Spring Boot	Branch	Status
1.6.x	4.1.x	main	Current — new features land here
1.5.x	4.0.x	4.0	Maintenance — bug fixes and Spring Boot patch updates only

Moving to a new Spring Boot minor always starts a new jhelm minor line. The previous line then moves to a branch named after its Spring Boot line (for example 4.0) and receives bug fixes and Spring Boot patch updates only — new features go to the newest line.

Quick Start

As a library

Add jhelm-core to your pom.xml:

    org.alexmond
    jhelm-core
    1.6.0

For Kubernetes operations (install/upgrade/rollback against a cluster), also add:

    org.alexmond
    jhelm-kube
    1.6.0

Render a chart programmatically (Spring Boot auto-configures the action beans):

@Autowired
TemplateAction templateAction;

// Render with default values
String manifest = templateAction.render(
        "/path/to/chart", "my-release", "default");

// Render with value overrides
String manifest = templateAction.render(
        "/path/to/chart", "my-release", "default",
        Map.of("replicaCount", 3, "image", Map.of("tag", "1.2.3")));

See the Spring Boot Starter guide for the full action API and configuration properties.

As a CLI

./mvnw clean install -DskipTests
java -jar jhelm-cli/target/jhelm-1.6.0.jar template my-release ./my-chart

The CLI mirrors the Helm command surface:

jhelm template my-release ./my-chart        # render manifests locally
jhelm install my-release ./my-chart -n prod # install into a cluster
jhelm upgrade my-release ./my-chart         # upgrade an existing release
jhelm repo add bitnami https://charts.bitnami.com/bitnami
jhelm pull bitnami/nginx --untar

As a REST API

Add the jhelm-rest-starter to a Spring Boot web application:

    org.alexmond
    jhelm-rest-starter
    1.6.0

The API is read-only by default; cluster-mutating endpoints are deny-by-default behind an API key (jhelm.security.mode=FULL + jhelm.security.api-key). See the REST API guide.

As an MCP server

Add the jhelm-mcp-starter to expose jhelm operations as MCP tools for AI agents:

    org.alexmond
    jhelm-mcp-starter
    1.6.0

Run it locally (see jhelm-mcp-sample) and point an agent at the STREAMABLE HTTP transport. See the MCP guide.

Documentation

Full documentation — getting started, architecture, CLI reference, configuration, the REST API, the MCP server, the security model, and the Helm function catalogue — is published at https://www.alexmond.org/jhelm/current/.

Building

./mvnw clean install          # build + run tests
./mvnw test -pl jhelm-core    # test a single module

Helm-parity tests (rendering jhelm against helm template over the chart suite) require a local helm binary on the PATH.

License

Apache License 2.0