Architecture

jhelm is a multi-module Maven project.

1. Module Structure

jhelm (parent)
├── jhelm-gotemplate-helm/  — Helm-specific template functions (depends on: gotmpl4j)
├── jhelm-core/             — Helm logic, charts, actions (depends on: jhelm-gotemplate-helm, gotmpl4j)
├── jhelm-kube/             — Kubernetes client integration (depends on: jhelm-core)
├── jhelm-rest/             — REST API over jhelm operations (depends on: jhelm-core, jhelm-kube)
├── jhelm-plugin/           — Maven plugin for packaging charts
└── jhelm-cli/              — CLI entry point, Spring Boot + Picocli (depends on: jhelm-core, jhelm-kube)

The Go template language and Sprig function library are not part of this repository. They live in the standalone gotmpl4j project (published to Maven Central) and are consumed as a dependency. jhelm contributes only the Helm-specific layer on top.

2. Modules

2.1. gotmpl4j (external dependency)

The Go template engine, on Maven Central as org.alexmond:gotmpl4j-core and org.alexmond:gotmpl4j-sprig.

  • Lexer → Parser → AST → Executor pipeline implementing Go’s text/template language

  • The Sprig function set (strings, collections, math, encoding, crypto, date, semver, …)

  • missingkey=zero mode so an absent/nil value renders as the empty string, matching Helm

2.2. jhelm-gotemplate-helm

The Helm-specific template functions layered on top of gotmpl4j, registered via the engine’s FunctionProvider SPI.

  • Template inclusion and evaluation: include, tpl, required

  • Conversion helpers: toYaml, fromYaml, toJson, fromJson, toToml

  • Kubernetes/chart helpers: lookup, .Capabilities, .Files

2.3. jhelm-core

Core Helm logic and models. Ships with Spring Boot auto-configuration (JhelmCoreAutoConfiguration).

  • Engine — orchestrates template rendering with subchart recursion, value merging, and JSON Schema validation

  • ChartLoader — loads charts from the filesystem (templates, subcharts, CRDs, README, schema)

  • RepoManager — manages chart repositories (HTTP and OCI), content-based caching, digest verification

  • Action classes — encapsulate Helm operations: InstallAction, UpgradeAction, RollbackAction, UninstallAction, TemplateAction, ShowAction, ListAction, StatusAction, HistoryAction, GetAction, CreateAction

  • TemplateCache — LRU cache for parsed template ASTs (thread-safe, configurable size)

  • SchemaValidator — validates chart values against values.schema.json (JSON Schema Draft-07)

2.4. jhelm-kube

Kubernetes client integration. Ships with Spring Boot auto-configuration (JhelmKubeAutoConfiguration).

  • HelmKubeService — Kubernetes operations using the official Java client: resource apply/delete via server-side PATCH, ConfigMap-based release storage (Helm-compatible format), resource status checking (Deployments, StatefulSets, Jobs, Pods)

  • AsyncHelmKubeService — extends HelmKubeService with CompletableFuture-based async methods using Java 21 virtual threads (Executors.newVirtualThreadPerTaskExecutor())

2.5. jhelm-cli

CLI entry point built with Picocli and Spring Boot. Provides 22 top-level commands covering the full Helm workflow. See the CLI Reference for details.

2.6. jhelm-rest

A Spring MVC REST API exposing chart and template operations over HTTP. Ships OpenAPI/Swagger documentation (springdoc). See the REST API reference for endpoints.

2.7. jhelm-plugin

A Maven plugin that packages charts as part of a project build, so chart artifacts can be produced and attached from CI without the Helm CLI.

3. Key Design Decisions

3.1. Template Rendering

  • A new GoTemplate instance is created per render to prevent template accumulation across calls.

  • Named templates (define blocks) are collected from the chart and all subcharts before rendering begins.

  • Subchart rendering is recursive with a maximum depth of 3 to prevent infinite loops.

  • Parsed template ASTs can be cached in a configurable LRU cache (TemplateCache) for performance.

3.2. Spring Boot Integration

  • JhelmKubeAutoConfiguration runs before JhelmCoreAutoConfiguration so that the KubeService bean is available for conditional registration of Kubernetes-dependent action beans.

  • All auto-configured beans use @ConditionalOnMissingBean, allowing applications to override any bean.

  • Optional dependencies (e.g., TemplateCache) are injected via ObjectProvider to avoid hard failures.

3.3. Kubernetes Release Storage

Releases are stored as Kubernetes ConfigMaps, matching Helm’s native format:

  • ConfigMap name: sh.helm.release.v1.<release-name>.v<version>

  • Labels: owner=helm, name=<release-name>, status=<status>, version=<version>

  • Data: JSON-encoded release object, Base64-encoded in the ConfigMap

3.4. Async Operations

The AsyncKubeService interface extends KubeService with CompletableFuture-based async variants of every method. The default implementation (AsyncHelmKubeService) dispatches work to a virtual-thread executor, keeping platform threads free for other work.