Name: jhelm
Author: alexmond

= jhelm
:jhelm-version: 1.5.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 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
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/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
https://modelcontextprotocol.io[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 (Draft-07).
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

[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 | Maven plugin for packaging charts as part of a build.
| 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

== Quick Start

=== As a library

Add jhelm-core to your pom.xml:

[source,xml,subs="attributes"]

org.alexmond jhelm-core {jhelm-version} ----

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

[source,xml,subs="attributes"]

org.alexmond jhelm-kube {jhelm-version} ----

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

org.alexmond jhelm-rest-starter {jhelm-version} ----

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

org.alexmond jhelm-mcp-starter {jhelm-version} ----

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]

[source,xml,subs="attributes"]

[source,xml,subs="attributes"]

[source,java]

[source,bash,subs="attributes"]

./mvnw clean install -DskipTestsjava -jar jhelm-cli/target/jhelm-{jhelm-version}.jar template my-release ./my-chart

[source,bash]

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

[source,xml,subs="attributes"]

[source,xml,subs="attributes"]

[source,bash]

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

Reviews (0)

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

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

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