Getting Started

1. Prerequisites

  • Java 21 or later

  • Maven 3.9+ (or use the included mvnw wrapper)

  • A Kubernetes cluster (for deploy operations; not needed for template rendering)

2. Building from Source

git clone https://github.com/alexmond/jhelm.git
cd jhelm
./mvnw clean install

3. Using the CLI

After building, run the CLI via the application JAR:

java -jar jhelm-cli/target/jhelm-{jhelm-version}.jar --help

3.1. Examples

Render chart templates locally:

jhelm template my-release ./my-chart
jhelm template my-release ./my-chart -f custom-values.yaml
jhelm template my-release ./my-chart --set image.tag=v2.0

Add a chart repository and install a chart:

jhelm repo add bitnami https://charts.bitnami.com/bitnami
jhelm pull bitnami/nginx --version 15.0.0
jhelm install my-nginx ./nginx -n production

Check release status and history:

jhelm list -n production
jhelm status my-nginx -n production --show-resources
jhelm history my-nginx -n production

See the CLI Reference for all available commands.

4. Using as a Library

Add jhelm-core to your Maven project for offline operations (template rendering, chart loading, repo management):

<dependency>
    <groupId>org.alexmond</groupId>
    <artifactId>jhelm-core</artifactId>
    <version>{jhelm-version}</version>
</dependency>

Add jhelm-kube when you also need Kubernetes operations (install, upgrade, rollback, etc.):

<dependency>
    <groupId>org.alexmond</groupId>
    <artifactId>jhelm-kube</artifactId>
    <version>{jhelm-version}</version>
</dependency>

Both modules ship with Spring Boot auto-configuration. In a Spring Boot application the relevant beans are created automatically.

4.1. Minimal Code Example

import org.alexmond.jhelm.core.service.Engine;
import org.alexmond.jhelm.core.service.ChartLoader;
import org.alexmond.jhelm.core.model.Chart;
import java.io.File;
import java.util.Map;

// Load a chart from disk
ChartLoader loader = new ChartLoader();
Chart chart = loader.load(new File("/path/to/my-chart"));

// Render templates
Engine engine = new Engine();
String manifest = engine.render(chart, Map.of(), Map.of(
    "Name", "my-release",
    "Namespace", "default",
    "IsInstall", true
));

System.out.println(manifest);

For Spring Boot integration with auto-configured beans and configuration properties, see the Spring Boot Starter guide.

5. Using the REST API

Add jhelm-rest-starter to a Spring Boot web application to expose Helm operations over HTTP:


    org.alexmond
    jhelm-rest-starter
    0.6.0

Run a minimal Spring Boot application — the endpoints are auto-configured:

@SpringBootApplication
public class MyHelmApp {
    public static void main(String[] args) {
        SpringApplication.run(MyHelmApp.class, args);
    }
}

Out of the box the API is read-only (the default jhelm.security.mode=READ_ONLY), so template and read endpoints work immediately and safely:

curl -X POST http://localhost:8080/api/v1/charts/template \
  -H 'Content-Type: application/json' \
  -d '{"chartRef": "bitnami/nginx", "releaseName": "demo", "namespace": "default"}'

Cluster-mutating endpoints (install/upgrade/uninstall/rollback/test) are deny-by-default: they are enabled only when you set mode=FULL and configure an API key. Without a key they return 403; with the gate open, a request missing or presenting a bad key returns 401.

jhelm:
  security:
    mode: FULL
    api-key: changeme
curl -X POST http://localhost:8080/api/v1/releases \
  -H 'X-API-Key: changeme' \
  -H 'Content-Type: application/json' \
  -d '{"chartRef": "bitnami/nginx", "releaseName": "demo", "namespace": "default"}'

See the REST API reference for all endpoints and the Security model for the full gating rules.

6. Using the MCP Server

Add jhelm-mcp-starter to a Spring Boot application to expose jhelm operations as Model Context Protocol tools for AI agents:


    org.alexmond
    jhelm-mcp-starter
    0.6.0

The server is auto-configured and serves the STREAMABLE HTTP MCP transport. Run it locally and point your agent at it; the read-only tools are available immediately. The jhelm-mcp-sample module is a runnable demo:

cd jhelm-mcp-sample
../mvnw spring-boot:run

See the MCP Server guide for the tool catalogue and the local/desktop security model.