= jhelm :jhelm-version: 1.6.0 :url-docs: https://www.alexmond.org/jhelm/current/ :url-docs-mcp: https://www.alexmond.org/jhelm/current/mcp/ :url-docs-rest: https://www.alexmond.org/jhelm/current/rest-api/ :toc:
image:https://img.shields.io/maven-central/v/org.alexmond/jhelm-core.svg?label=Maven%20Central[Maven Central,link=https://search.maven.org/artifact/org.alexmond/jhelm-core] image:https://img.shields.io/badge/License-Apache%202.0-blue.svg[License,link=LICENSE] image:https://img.shields.io/github/actions/workflow/status/alexmond/jhelm/build.yml[Build Status,link=https://github.com/alexmond/jhelm/actions] image:https://codecov.io/gh/alexmond/jhelm/graph/badge.svg[codecov,link=https://codecov.io/gh/alexmond/jhelm] image:https://unitrack.alexmond.org/badge/5/coverage.svg[UniTrack coverage,link=https://unitrack.alexmond.org/projects/5] image:https://unitrack.alexmond.org/badge/5/pass.svg[UniTrack tests,link=https://unitrack.alexmond.org/projects/5] image:https://img.shields.io/badge/Java-21-orange.svg[Java 21] image:https://img.shields.io/badge/docs-alexmond.org-blue[Documentation,link={url-docs}]
A native Java implementation of the https://helm.sh[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 orhelmbinary. The comparison is byte-for-byte apart from a small set of documented, non-semantic differences (generated secrets/certs andtoYamlkey-ordering inchecksum/*annotations). This is template-rendering parity;install/upgradereuse 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
helmexecutable, noexec, no platform-specific distribution. Just a Maven dependency. - MCP-native -- the same operations are exposed as https://modelcontextprotocol.io[Model Context Protocol] tools, so an AI agent can render charts and manage releases directly. See {url-docs-mcp}[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 https://github.com/alexmond/gotmpl4j[gotmpl4j] library, reusable on its own.
== Features
- Go template engine -- the full Go
text/templatelanguage 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.yamldependencies,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-restlibrary and ajhelm-rest-starterthat carries the auto-configuration, with aREAD_ONLY/FULLaccess mode gating the cluster-mutating endpoints. - MCP server --
jhelm-mcp/jhelm-mcp-starterexpose jhelm operations as https://modelcontextprotocol.io[Model Context Protocol] tools for AI agents (built on Spring AI), mirroring the REST operation set with the sameREAD_ONLY/FULLaccess mode. - JSON Schema validation -- validates chart values against
values.schema.jsonwith 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 (withjhelm encrypt/jhelm decrypt). All opt-in; charts that don't use them render byte-for-byte as Go Helm.
== Modules
[cols="1,3"] |=== | 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 https://github.com/alexmond/gotmpl4j[gotmpl4j] project (on Maven Central) and is consumed as a dependency.
== Tech Stack
[cols="1,1"] |=== | 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.
[cols="1,1,1,2"] |=== | 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:
[source,xml,subs="attributes"]
For Kubernetes operations (install/upgrade/rollback against a cluster), also add:
[source,xml,subs="attributes"]
Render a chart programmatically (Spring Boot auto-configures the action beans):
[source,java]
@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 {url-docs}spring-boot-starter/[Spring Boot Starter] guide for the full action API and configuration properties.
=== As a CLI
[source,bash,subs="attributes"]
./mvnw clean install -DskipTests java -jar jhelm-cli/target/jhelm-{jhelm-version}.jar template my-release ./my-chart
The CLI mirrors the Helm command surface:
[source,bash]
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:
[source,xml,subs="attributes"]
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 {url-docs-rest}[the REST
API guide].
=== As an MCP server
Add the jhelm-mcp-starter to expose jhelm operations as MCP tools for AI agents:
[source,xml,subs="attributes"]
Run it locally (see jhelm-mcp-sample) and point an agent at the STREAMABLE HTTP transport.
See {url-docs-mcp}[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 {url-docs}.
== Building
[source,bash]
./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
https://www.apache.org/licenses/LICENSE-2.0[Apache License 2.0]