Skip to content

README.adoc

Latest commit

 

History

History
221 lines (178 loc) · 9.27 KB

README.adoc

File metadata and controls

221 lines (178 loc) · 9.27 KB
Raw

jhelm

Table of Contents

Maven Central License Build Status codecov UniTrack coverage UniTrack tests Java 21 Documentation

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.

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 (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

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 gotmpl4j project (on Maven Central) and is consumed as a dependency.

Tech Stack

Java

21

Spring Boot

4.0.7

Kubernetes Client

26.0.0

Template engine

gotmpl4j 1.4.0

CLI framework

Picocli 4.7.7

Quick Start

As a library

Add jhelm-core to your pom.xml:

    org.alexmond
    jhelm-core
    1.5.0

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

    org.alexmond
    jhelm-kube
    1.5.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.5.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.5.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.5.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.