Implementation Roadmap & Future Design

This document outlines the planned improvements, feature priorities, and strategic vision for jhelm.

1. 0.1.0 Prerelease Target

The first published prerelease (0.1.0, on Maven Central, marked pre-release) is defined by two things being true at once: a broad real-world conformance bar and a stable, extraction-ready engine. The release is cut via maven_release.yml (releaseVersion=0.1.0, nextVersion=0.2.0-SNAPSHOT).

1.1. Exit criteria (Definition of Done)

Area Criterion Status

Conformance gate

≥ 300 charts render byte-identical to helm template in CI (the KpsComparisonTest suite, charts.csv), order-independent and with only the documented comparison-ignores (random/timestamp names, generated secrets/certs).

✅ 540 / 540

Engine maturity

The Go template + Sprig engine ships as the standalone gotmpl4j library on Maven Central; jhelm consumes it as a dependency (gotmpl4j 1.2.0). The 540-chart suite is its de-facto conformance test.

✅ Extracted — gotmpl4j on Maven Central; 540-chart suite green

Supported surface

All modules ship as supported: gotemplate/sprig/helm (engine), core (chart lifecycle: install/upgrade/rollback/uninstall/list/status/history), kube (apply/wait), rest, plugin, cli, plus the Spring Boot starter.

—

Repo + deps

HTTP and OCI repositories with digest verification; Helm-faithful SemVer version selection; recursive dependency value coalescing; hooks; JSON-Schema validation.

Mostly done

Quality gates

spring-javaformat, Checkstyle, PMD, and JaCoCo coverage all green on a full ./mvnw clean verify.

Green

Docs

Antora docs current; CHANGELOG.adoc 0.1.0 section; README “Status” reflects the prerelease.

In progress

1.2. gotmpl4j (engine extraction — done)

The Go template engine has been extracted into the standalone gotmpl4j library, published to Maven Central (org.alexmond:gotmpl4j-core, gotmpl4j-sprig, plus a Spring Boot starter; gotmpl4j 1.2.0). jhelm consumes it as an ordinary dependency, keeping only the Helm-specific function layer (jhelm-gotemplate-helm) in this repository. The extraction holds the properties that made it mechanical rather than a redesign:

  • Correctness — no known rendering gaps; the 540-chart parity suite is the conformance bar.

  • Clean boundary — the engine has zero dependencies on Sprig, Helm, or core; Sprig (priority 100) and Helm (priority 200) functions load only via ServiceLoader.

  • Stable API — GoTemplate, Function, FunctionProvider are settled.

  • Coverage — comprehensive unit tests for lexer/parser/executor and every function category, independent of the chart suite.

1.3. API freeze (shipped in 0.4.0 — toward 1.0)

The pre-1.0 API freeze milestone landed in 0.4.0, settling the public surface ahead of a stable 1.0:

  • Unchecked exceptions — the action layer and KubeService throw the JhelmException hierarchy instead of throws Exception.

  • No leaked Kubernetes-client types — ApiException/ApiClient are wrapped behind KubeClient; BouncyCastle PGP types behind SigningKey/VerificationKeyring.

  • Options objects — the action API takes immutable InstallOptions/UpgradeOptions/ UninstallOptions/RollbackOptions instead of long parameter lists.

  • Immutable result models — Release/ReleaseInfo/MapConfig are immutable; release status is a typed ReleaseStatus enum and the lifecycle phase a LifecyclePhase enum.

1.4. Explicit non-goals for 0.1.0

  • Full gitlab parity — blocked on a complete Helm CoalesceValues/ProcessDependencies reimplementation (deep, high-risk); tracked separately.

  • The gotmpl4j extraction itself — 0.1.0 makes the engine ready; the split lands post-0.1.0.

  • Charts that are inherently uncomparable to a separate helm template run (wall-clock timestamps or random suffixes in resource names).

  • Server-Side Apply, WASM plugins, post-renderers, and chart signing (later phases below).

2. Recommended Implementation Roadmap

The roadmap is divided into several phases focusing on compatibility, feature completeness, and architectural modernization.

2.1. Phase 1: Helm 4 Core Compatibility (2-3 weeks)

  1. Add missing template functions (mustToYaml, mustToJson, etc.) - ✅ COMPLETED

  2. Category-based function refactoring - ✅ COMPLETED

  3. Remove duplicate legacy functions - ✅ COMPLETED

  4. Implement Server-Side Apply in HelmKubeService

  5. Enhanced OCI registry support with digest verification

  6. Content-based chart caching

  7. Multi-document values file support

2.2. Phase 2: Feature Completeness (3-4 weeks)

  1. Dependency management system

  2. Hooks support (pre/post install/upgrade)

  3. Missing commands (get, show, dependency)

  4. JSON Schema validation - ✅ COMPLETED

  5. Improved resource status watching

2.3. Phase 3: Architecture & Quality (2-3 weeks)

  1. Remove Spring Boot from core modules (making them library-first)

  2. Async/reactive support - ✅ COMPLETED (virtual-thread AsyncKubeService)

  3. Metrics and observability

  4. Enhanced error recovery

  5. Better contextual error messages

2.4. Phase 4: Advanced Features (4-6 weeks)

  1. Plugin system architecture

  2. WebAssembly plugin support

  3. Post-renderers

  4. Chart signing/verification

  5. Chart testing framework

2.5. Phase 5: Polish & Performance (2-3 weeks)

  1. Template compilation cache - ✅ COMPLETED (LRU TemplateCache)

  2. CLI color output

  3. CPU/memory profiling

  4. Enhanced test coverage

  5. Documentation improvements

3. Compatibility Matrix

Feature Helm 3 Helm 4 jhelm Current Priority Status

Template Rendering

✅

✅

✅

-

Complete

Sprig Functions

✅

✅

✅

P1

✅ Complete (minor gaps tracked in Function Coverage)

Helm 4 must Functions*

❌

✅

✅

P1

✅ Complete

Server-Side Apply

❌

✅

❌

P1

Pending

Three-Way Merge

✅

❌

✅

P1

Complete

Plugin System

✅

✅ (new)

❌

P2

Pending

OCI Registries

✅

✅ (enhanced)

⚠️

P1

Partial

Chart Dependencies

✅

✅

✅

P2

✅ Complete

Hooks

✅

✅

✅

P2

✅ Complete

JSON Schema

❌

✅

✅

P2

✅ Complete

Content Caching

❌

✅

✅

P1

✅ Complete

Structured Logging

❌

✅

⚠️

P1

Partial

4. Spring Boot Integration Roadmap ⭐

4.1. Strategic Vision

Transform jhelm into an enterprise-grade Helm management platform powered by Spring Boot, offering:

  • Centralized Configuration: Spring Config Server integration for values management across environments.

  • REST API: Full-featured API for programmatic Helm operations.

  • Web UI: Modern web interface for chart management and deployments.

  • Multi-tenancy: Support for multiple teams, clusters, and environments.

  • Real-time Operations: WebSocket-based deployment status and logs.

  • Enterprise Features: Security, audit logging, RBAC, SSO integration.

4.2. Architecture Design

4.2.1. New Modules

Module Description

jhelm-server

Purpose: REST API and Web UI server.
Technology: Spring Boot 4, Spring Web/WebFlux, Spring Security.
Components: REST Controllers, WebSocket endpoints, Web UI integration, OpenAPI docs, Actuator metrics.

jhelm-config

Purpose: Configuration management and Spring Config integration.
Technology: Spring Cloud Config, Spring Profiles.
Components: ConfigurationProperties for Helm values, Profile-based config, Config Server client, Encryption support.

jhelm-security

Purpose: Authentication, authorization, and audit (Future).
Technology: Spring Security, OAuth2, JWT.
Components: RBAC for Helm operations, SSO/LDAP integration, API key management, Audit logging.

4.2.2. Enhanced Existing Modules

  • jhelm-core: Add @ConfigurationProperties, Spring Environment integration, Spring Events for deployment lifecycle, Spring Cache for template caching.

  • jhelm-kube: Reactive operations with Spring WebFlux, Spring Retry for resilience, Spring Cloud Kubernetes for discovery, Async deployment support.

  • jhelm-cli: Read from Spring Config Server, support environment variables via Spring Boot.

  • jhelm-gotemplate-helm: Remains lightweight, no Spring dependency (pure Java), tracking the external gotmpl4j engine.