Helm API

A simple HTTP API server that provides Helm templating functionality without requiring a Kubernetes cluster connection. This service accepts GET requests with query parameters and returns rendered YAML manifests. Supports local charts, repository charts, and OCI registry charts.

Features

• Client-only templating: Templates Helm charts without connecting to a Kubernetes cluster
• RESTful API: Simple HTTP GET endpoint with query parameters
• Multiple chart sources: Support for local charts, HTTP/HTTPS repositories, and OCI registries
• Configurable: Support for all major Helm template options including values, files, and Kubernetes versions
• Container-ready: Built with GoReleaser and ko for easy container deployment
• Structured Logging: Configurable structured logging with slog and slog-http middleware
• Observability: OpenTelemetry integration with trace and span ID logging
• Flexible Configuration: Environment variables and YAML file configuration support

API Endpoint

GET /template

Renders a Helm chart template and returns the resulting YAML manifests using query parameters.

Query Parameters

Parameter	Type	Required	Description
chart	string	Yes	Path to the Helm chart, chart name, or OCI registry URL
chart_version	string	No	Version of the chart (works with repository charts)
repository	string	No	Chart repository URL (HTTP/HTTPS or OCI registry)
release_name	string	No	Name of the release (default: "release-name")
namespace	string	No	Target namespace (default: "default")
kube_version	string	No	Kubernetes version for capabilities (default: "v1.29.0")
set	array	No	Set values (equivalent to --set, can be used multiple times)
value_files	array	No	Specify values files (can be used multiple times)
file_values	array	No	Set values from files (can be used multiple times)
json_values	array	No	Set JSON values (can be used multiple times)
show_only	array	No	Only show specific template files (can be used multiple times)
api_versions	array	No	Additional API versions for capabilities (can be used multiple times)
include_crds	boolean	No	Include CRDs in output
skip_tests	boolean	No	Skip test manifests
is_upgrade	boolean	No	Set .Release.IsUpgrade instead of .Release.IsInstall
validate	boolean	No	Enable manifest validation

Response

Returns the rendered YAML manifests with Content-Type: application/x-yaml.

Usage Examples

Basic template request

curl "http://localhost:8080/template?chart=nginx&release_name=my-nginx"

With custom values

curl "http://localhost:8080/template?chart=./my-chart&set=replicaCount=3&set=image.tag=v2.0"

Multiple parameters

curl "http://localhost:8080/template?chart=nginx&release_name=test&namespace=production&set=replicas=2&include_crds=true&kube_version=v1.28.0"

Using array parameters

curl "http://localhost:8080/template?chart=./my-chart&set=key1=value1&set=key2=value2&show_only=deployment.yaml&show_only=service.yaml"

With chart repository

curl "http://localhost:8080/template?chart=nginx&repository=https://charts.bitnami.com/bitnami&chart_version=15.0.0&release_name=my-nginx"

With OCI registry

curl "http://localhost:8080/template?chart=oci://registry-1.docker.io/bitnamicharts/nginx&chart_version=15.0.0&release_name=oci-nginx"

Health Check

curl "http://localhost:8080/health"

Installation

Using Go

go install github.com/appkins-org/helm-api@latest

Building from Source

git clone https://github.com/appkins-org/helm-api.git
cd helm-api
go build -o helm-api .

Building and Running

Local Development

# Install dependencies
go mod tidy

# Run the server
go run main.go

# The server will start on port 8080

Using Docker

# Build the container
docker build -t helm-api .

# Run the container
docker run -p 8080:8080 helm-api

Using GoReleaser with ko

# Build and publish container (requires Docker and ko)
goreleaser release --snapshot --clean

# Or just build containers
goreleaser build --snapshot --clean

Configuration

The application supports configuration through environment variables and YAML files, with environment variables taking precedence.

Configuration File

Create a config.yaml file (see config.example.yaml for reference) and set the CONFIG_FILE environment variable:

export CONFIG_FILE=config.yaml
./helm-api

Environment Variables

Variable	Description	Default
CONFIG_FILE	Path to YAML configuration file	""
PORT	Server port	"8080"
HOST	Server host	""
LOG_LEVEL	Log level (debug, info, warn, error)	"info"
LOG_FORMAT	Log format (text, json)	"text"
LOG_OUTPUT	Log output (stdout, stderr, file path)	"stdout"
LOG_HTTP_ENABLED	Enable HTTP request/response logging	true
LOG_HTTP_REQUEST_BODY	Log request bodies	false
LOG_HTTP_RESPONSE_BODY	Log response bodies	false
LOG_HTTP_REQUEST_HEADERS	Log request headers	false
LOG_HTTP_RESPONSE_HEADERS	Log response headers	false
TRACING_ENABLED	Enable tracing features	false
TRACING_WITH_SPAN_ID	Include span IDs in logs	false
TRACING_WITH_TRACE_ID	Include trace IDs in logs	false

Logging

The application uses structured logging with slog and HTTP middleware from slog-http.

Examples

# Debug logging with JSON format
LOG_LEVEL=debug LOG_FORMAT=json ./helm-api

# Enable detailed HTTP logging
LOG_HTTP_REQUEST_BODY=true LOG_HTTP_RESPONSE_BODY=true ./helm-api

# Enable OpenTelemetry integration
TRACING_ENABLED=true TRACING_WITH_SPAN_ID=true TRACING_WITH_TRACE_ID=true ./helm-api

# Log to file
LOG_OUTPUT=/var/log/helm-api.log ./helm-api

Chart Authentication

For private repositories or OCI registries, you may need to configure authentication:

• HTTP/HTTPS repositories: Use helm repo add to configure credentials before running the server
• OCI registries: Use helm registry login or configure Docker credentials
• Local charts: Ensure the chart path is accessible to the server process

Requirements

• Go 1.21 or later
• Helm charts accessible to the server
• For repository charts: Network access to chart repositories
• For OCI charts: Network access to OCI registries and proper authentication if required
• For container builds: Docker and optionally ko

Testing

The project includes comprehensive tests for both the HTTP server and the template processing functionality.

Running Tests

# Run all tests
go test ./...

# Run tests with verbose output
go test -v ./...

# Run tests with coverage
go test ./... -cover

# Run benchmarks
go test ./... -bench=.

Test Coverage

• HTTP Server Tests (main_test.go): Tests all HTTP endpoints including error cases, content-type validation, and mock HTTP server functionality
• Template Package Tests (internal/template/template_test.go): Tests template request validation, Kubernetes version parsing, value merging, and helper functions
• Integration Tests: Includes a full test chart creation and processing test

Manual Testing

You can test the API manually by starting the server and making HTTP requests:

# Start the server
go run main.go

# Test health endpoint
curl "http://localhost:8080/health"

# Test template endpoint
curl "http://localhost:8080/template?chart=nginx&release_name=test"

Development

This project uses:

• Helm SDK: For chart templating functionality
• Go standard library: For HTTP server
• GoReleaser: For building and releasing
• ko: For building OCI containers

License

MIT License