HelmSharp.Release 1.2.0

<h1 align="center"> <img src="https://raw.githubusercontent.com/GaTTGeng/HelmSharp/master/docs/public/wordmark.svg" alt="HelmSharp" width="352"> </h1>

简体中文

HelmSharp is a managed .NET library for rendering Helm-style charts and driving Kubernetes release workflows without invoking the helm executable. It is intended for applications that need Helm-like behavior inside a .NET process: template rendering, values merging, chart packaging, repository operations, and release lifecycle operations against Kubernetes.

The project is under active development. M1 (Helm template parity) and M2 (chart packaging and repository parity) are complete, with the renderer continuously checked against focused fixtures and selected public Helm charts. Later milestones expand release lifecycle and Kubernetes operations.

The latest published version is 1.2.0. The M2 packaging, repository, pull, and dependency capabilities described below and in the linked distribution guide are available in the 1.2.0 NuGet packages.

Documentation site: https://gattgeng.github.io/HelmSharp/

The documentation now includes workflow guides, realistic integration examples, package-by-package guidance, and generated API reference pages for public types and members.

Packages

This repository is organized as several NuGet packages:

For most applications, start with HelmSharp.Action.

Requirements

• .NET 8, .NET 9, and .NET 10 SDKs for building all target frameworks locally.
• A Kubernetes cluster and kubeconfig for release install, upgrade, rollback, uninstall, and status operations.
• No helm binary is required.
• Supported package target frameworks: net8.0, net9.0, and net10.0.
• .NET Framework is not supported unless a future release adds a netstandard target.

Installation

dotnet add package HelmSharp.Action

For lower-level use cases:

dotnet add package HelmSharp.Chart
dotnet add package HelmSharp.Engine

Quick Start

Render a local chart:

using HelmSharp.Action;

var client = new HelmClient(new StaticHelmOptionsProvider());

var result = await client.TemplateAsync(new HelmTemplateRequest
{
    ReleaseName = "demo",
    Namespace = "default",
    Chart = @"C:\charts\my-chart",
    SetValues = new Dictionary<string, string>
    {
        ["image.tag"] = "1.2.3",
        ["replicaCount"] = "2"
    }
});

Console.WriteLine(result.StandardOutput);

sealed class StaticHelmOptionsProvider : IHelmOptionsProvider
{
    public ValueTask<HelmExecutionOptions> GetHelmAsync(CancellationToken cancellationToken = default)
        => ValueTask.FromResult(new HelmExecutionOptions
        {
            DefaultNamespace = "default",
            FieldManager = "helmsharp"
        });
}

More complete examples are available in examples.

Install or upgrade a release:

var result = await client.UpgradeInstallAsync(new HelmUpgradeInstallRequest
{
    ReleaseName = "demo",
    Namespace = "default",
    Chart = @"C:\charts\my-chart",
    CreateNamespace = true,
    Wait = true,
    TimeoutSeconds = 300
});

if (result.ExitCode != 0)
{
    Console.Error.WriteLine(result.StandardError);
}
else
{
    Console.WriteLine(result.StandardOutput);
}

Run a dry run without mutating the cluster:

await foreach (var line in client.UpgradeInstallStreamAsync(new HelmUpgradeInstallRequest
{
    ReleaseName = "demo",
    Namespace = "default",
    Chart = @"C:\charts\my-chart",
    DryRun = true
}))
{
    Console.WriteLine(line);
}

Supported Capabilities

The list below describes the current master branch. See the version note above before using M2 APIs from NuGet.

• Chart loading from directories and .tgz archives.
• values.yaml, inline values, --set, --set-string, --set-json, and --set-file-style value overrides.
• Helm-style template rendering for common control flow and functions.
• Helm-compatible chart packaging with .helmignore, version/appVersion overrides, dependencies, and safe archive layout.
• Traditional HTTP repository config/cache management, index generation/merge, offline search, semantic-version pull, digest verification, and safe extraction.
• Dependency list/update/build with Helm-compatible Chart.lock, repository aliases, chart aliases, and local file:// dependencies.
• Managed Kubernetes apply/delete/wait operations for common Kubernetes resources.
• Release history stored in Kubernetes Secrets.
• Install, upgrade, uninstall, rollback, status, history, manifest, values, hooks, notes, and test-oriented APIs.

See the chart packaging and repository workflow guide for complete examples. OCI/provenance parity remains planned separately.

Compatibility Validation

HelmSharp's template engine is continuously validated with golden tests. The suite includes focused fixture charts and selected public Helm charts. Each public chart below is rendered by both helm template (reference) and HelmSharp's managed renderer; outputs are compared document-by-document after normalization.

These results are a compatibility signal for the pinned chart versions in the table, not a blanket certification for every chart in the Helm ecosystem. Validate your own chart when it relies on uncommon Helm behavior.

Last updated: 2026-07-16 · HelmSharp version: 1.2.0 · Helm version: v4.2.2 · Test framework: net10.0

Summary

Per-Chart Breakdown

podinfo          █████████████████████  100%  (21/21 templates)
metrics-server   █████████████████████  100%  (18/18 templates)
external-dns     █████████████████████  100%  ( 7/ 7 templates)
ingress-nginx    █████████████████████  100%  (42/42 templates)
cert-manager     █████████████████████  100%  (41/41 templates)
                 ─────────────────────
                 █████████████████████  100%  (129/129 templates overall)

Error Analysis

For the pinned public charts listed above, all 129 templates render without parser exceptions and match helm template after normalization. This is the current compatibility signal for the covered charts, not a guarantee that every Helm chart uses only covered behavior.

Key parity milestones closed since the 1.0.3 release:

• #109 / #111 / #113 — Block right-trim now preserves action-line indent matching Go text/template behavior; cert-manager golden test restored from 45/52 to 52/52 exact match.
• #112 — ParseDefine now applies right-trim to define body, matching ParseBlock behavior.
• #97 — Completed Sprig function parity for remaining gaps (empty, keys, mergeOverwrite, mustRegexMatch, mustRegexReplaceAll, etc.).
• #102 — Resolved cert-manager remaining content diffs (YAML tag, octal values, merge keys, block scalars, comment trimming).
• #96 / #99 / #108 — Resolved selected public-chart golden test content diffs to achieve Pass verdicts across all five charts.

Verdict Legend

Known Scope

HelmSharp is not a full Helm CLI clone. Some advanced Helm behaviors, edge-case template functions, plugins, provenance verification flows, OCI authentication flows, and uncommon Kubernetes resource types may need additional implementation. Contributions that add compatibility with focused tests are welcome.

Documentation

• Documentation site
• Getting started
• Guide: installation and rendering
• Examples: render preview API
• Package guide: HelmSharp.Action
• Generated API reference
• API overview
• Helm compatibility and validation
• Roadmap
• Support
• GitHub releases

Build

dotnet restore HelmSharp.sln
dotnet build HelmSharp.sln --configuration Release --no-restore
dotnet test HelmSharp.sln --configuration Release --no-build --no-restore

Pack

dotnet pack HelmSharp.sln --configuration Release --no-build --output artifacts/packages

The NuGet package metadata is defined in src/Directory.Build.props. The package README is packed from this file.

Continuous Integration and Release

This repository includes GitHub Actions workflows:

• .github/workflows/ci.yml restores, builds, tests, packs, and uploads package artifacts on pushes and pull requests.
• .github/workflows/deploy-docs.yml builds the VitePress documentation site and deploys it to GitHub Pages on pushes to master.
• .github/workflows/release-nuget.yml packs release packages and can publish them to NuGet.org.

NuGet.org publishing is handled by maintainers through the release workflow.

Contributing

See CONTRIBUTING.md.

Security

Please report security issues privately. See SECURITY.md.

License

HelmSharp is licensed under the MIT License.