DEV Community: Gatt Geng

HelmSharp v1.1.0: making Helm compatibility inspectable

Gatt Geng — Wed, 01 Jul 2026 09:23:17 +0000

In the first post, I introduced HelmSharp as a managed .NET SDK for rendering Helm charts from .NET without calling the helm executable at runtime.

Since then, the project has moved from "the renderer can get through real charts" to something more useful: compatibility work that is easier to inspect, reproduce, and challenge.

HelmSharp v1.1.0 completes the first rendering-parity milestone, but this post is not really about a scorecard. The more important part is the process behind it: using Helm as an oracle, tightening the parts of the renderer where small differences matter, and building a docs site with a Live Compare tool so users can test their own charts instead of trusting a claim in a README.

First post:

HelmSharp: render Helm charts from .NET without shelling out to helm

Docs:

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

What changed since the first post

The first milestone was about proving that HelmSharp could render realistic charts without falling over.

That was useful, but it was also an incomplete definition of compatibility.

A renderer can avoid exceptions and still be wrong. It can produce valid YAML with different whitespace. It can evaluate a function almost like Helm, but not quite. It can serialize YAML in a way Kubernetes accepts, while still producing output that makes a diff-based deployment workflow noisy.

So the work after the first post focused on the boring details that make compatibility real.

Whitespace and trim behavior

Helm templates are Go text/template templates with Helm-specific objects and functions on top.

That means trim markers are not cosmetic. In a chart, the difference between {{ ... }}, {{- ... }}, {{ ... -}}, and {{- ... -}} can change the output in ways that show up directly in manifests.

This became one of the main areas of work in v1.1.0:

block right-trim behavior
define-body trimming
indentation around action lines
newline preservation in places where Helm keeps it
indent / nindent behavior around trimmed actions

These are small rules, but they compound. A renderer that is "mostly right" here produces noisy diffs.

Sprig and Helm function behavior

Helm charts rely heavily on Sprig functions. Not just common helpers like default, quote, toYaml, and nindent, but also functions that show up only when a chart starts doing more dynamic work.

The v1.1.0 work closed remaining gaps around functions such as:

empty
keys
mergeOverwrite
regex helpers
string slicing edge cases
trunc and substr behavior

The point is not that every function is interesting on its own. The point is that Helm charts treat this function set as part of the language. If the SDK exposes Helm-style rendering, the function behavior has to be treated as compatibility surface.

YAML edge cases

Some of the remaining differences were not parser problems at all. They were YAML behavior problems.

Examples included:

YAML tags
octal values
merge keys
block scalars
comment trimming
key ordering in toYaml output

These are exactly the kinds of details that small handcrafted examples miss. Real charts contain years of accumulated Helm idioms, YAML tricks, and formatting assumptions.

That is why I keep using public charts as compatibility input. They are not perfect coverage, but they are much better than only testing charts designed for the test suite.

Helm as oracle, not dependency

One design rule has stayed the same:

Helm CLI is allowed in tests.

Helm CLI is not allowed as an SDK runtime dependency.

The golden tests run Helm and HelmSharp against the same chart input, then compare the rendered output. That gives the project a concrete oracle without making consumer applications install or ship Helm.

This distinction matters.

If HelmSharp simply called helm template internally, the library would be much easier to build, but it would not solve the original problem. The whole reason I started this project was to remove the runtime dependency from .NET services, operators, preview APIs, and deployment tools.

So Helm remains the reference implementation, not the execution engine.

Why I built a documentation site

The README was becoming the wrong shape for the project.

At first, a README was enough: install package, render chart, show compatibility notes.

But once the SDK started covering more than one workflow, the documentation needed routing by intent:

"I want to render my first chart."
"I want to build a preview API."
"I need to understand values precedence."
"I want to compare Helm and HelmSharp output."
"I want generated API reference pages."

A flat README cannot serve all of those well.

So the docs moved into a VitePress site:

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

It includes guide pages, examples, package pages, generated API references, compatibility notes, and Simplified Chinese localization.

The README still exists, but it is now an entry point instead of the whole manual.

The part I care about most: Live Compare

The Live Compare page is the most important new documentation feature.

Instead of asking users to believe that HelmSharp behaves like Helm, it lets them check.

Open:

https://gattgeng.github.io/HelmSharp/compare

You can upload a packaged Helm chart (.tgz), optionally provide custom values, and run a comparison against the real Helm CLI.

There is also a Quick Examples modal with public charts, so users can try the tool without preparing anything locally.

The result page shows Helm CLI output and HelmSharp output side by side.

This is the trust model I want for HelmSharp.

A compatibility table is useful, but it is still a claim from the maintainer. A live diff is better. It gives users a way to bring their own chart, their own values, and their own expectations.

If the output matches, great.

If it does not, the diff is already the beginning of a bug report.

What this changes for users

For render-only scenarios, HelmSharp is now much easier to evaluate.

You do not have to read through the implementation to decide whether it is worth trying. You can:

Open Live Compare.
Upload your chart.
Add values if needed.
Inspect the Helm CLI and HelmSharp output side by side.

That is a much better starting point than "please trust this compatibility paragraph."

The documentation site also changes how the project explains itself. The README remains the entry point, but deeper topics now have their own pages: first render, values precedence, template behavior, release workflows, Kubernetes operations, compatibility notes, and API reference.

What is next

M1 focused on Helm template parity.

The next work is about expanding the surrounding SDK surface:

chart packaging and repository behavior
dependency and subchart workflows
release lifecycle behavior
Kubernetes apply and wait semantics
OCI and provenance work
continued API and documentation hardening

No hard dates. I am keeping the project driven by reproducible cases and real usage rather than trying to declare broad compatibility too early.

What I am looking for

If you use Helm from .NET tooling today, try the Live Compare page with one of your own charts:

https://gattgeng.github.io/HelmSharp/compare

If it matches, that is useful signal.

If it does not match, that is more useful. Open an issue with the chart, values input, Helm command, HelmSharp output, and the observed difference.

Small reproducible charts are the most helpful. They turn compatibility from a vague report into an engineering task.

If you were replacing helm template inside a .NET service, what would you need to verify before trusting a managed SDK?

GitHub: https://github.com/GaTTGeng/HelmSharp

Docs: https://gattgeng.github.io/HelmSharp/

Live Compare: https://gattgeng.github.io/HelmSharp/compare

NuGet: https://www.nuget.org/packages/HelmSharp.Action

License: MIT

HelmSharp: render Helm charts from .NET without shelling out to helm

Gatt Geng — Mon, 22 Jun 2026 03:47:32 +0000

TL;DR: I built a .NET library that renders Helm charts and drives Kubernetes releases without shelling out to the helm CLI. 129/129 templates across ingress-nginx, cert-manager, external-dns, podinfo, and metrics-server now render successfully. The main entry point is HelmSharp.Action, with lower-level packages available for chart loading, rendering, Kubernetes operations, and release storage. MIT licensed, looking for feedback and early adopters.

Why I Built This

At work, our .NET services deploy to Kubernetes through Helm. Every Docker image had to bundle the helm binary — another dependency to manage, another layer in the image, another surface for CVEs. I wanted to cut that out entirely and do Helm-style rendering directly in-process.

The .NET ecosystem doesn't really have this. There are YAML libraries. There are Kubernetes client libraries. There are template engines. But nothing ties them together the way helm template does — values merging, named templates, include, range, toYaml, the whole Sprig function set, all wired into a single render pipeline. So I started building one. (This is also my first real open source project — I'd spent years consuming OSS without contributing back, and HelmSharp is what came out of deciding to change that.)

What HelmSharp Does

HelmSharp is a multi-package .NET SDK (net8.0 / net9.0 / net10.0) that covers:

Package	What it does
`HelmSharp.Action`	High-level Helm client — `TemplateAsync`, `UpgradeInstallAsync`, `RollbackAsync`
`HelmSharp.Chart`	Chart loading from directories and `.tgz`, values merging, `--set` / `--set-json` style overrides
`HelmSharp.Engine`	Helm-style template rendering — 100+ Sprig/Helm functions
`HelmSharp.Kube`	Kubernetes apply, delete, and wait (no `kubectl` needed)
`HelmSharp.Release`	Release history stored in Kubernetes Secrets (Helm-compatible)
`HelmSharp.Repo`	Chart repository index, pull, and search
Plus `Registry`, `Storage`, `PostRenderer` extension points

Here's the lower-level rendering API — no result objects, no stdout strings, just in-process template evaluation:

var chart = await HelmChartLoader.LoadAsync("/charts/my-chart", ct);
var values = await HelmValues.BuildAsync(chart, null, null, new Dictionary<string, object?>
{
    ["image"] = new Dictionary<string, object?> { ["tag"] = "1.2.3" },
    ["replicaCount"] = 3
}, null, null, null, ct);

var renderer = new HelmTemplateRenderer(chart, "my-app", "production", values);
var manifests = renderer.Render();
// manifests is a string of valid YAML — feed it to kubectl apply, store it,
// diff it, whatever you'd do with `helm template` output.

No helm binary. No Process.Start. Values are native .NET objects, not --set strings. The output is just a string — you decide what to do with it.

There's also a higher-level HelmClient API (TemplateAsync, UpgradeInstallAsync, RollbackAsync) that mirrors the Helm CLI workflow if you prefer that shape.

Where We Are Now (v1.0.3)

This week I hit a milestone I'm genuinely proud of: 129 out of 129 templates across 5 real-world public charts now render without a single parser exception.

Chart	Version	Templates
ingress-nginx	4.12.1	42/42 ✅
cert-manager	1.17.1	41/41 ✅
external-dns	1.21.1	7/7 ✅
podinfo	6.14.0	21/21 ✅
metrics-server	3.13.1	18/18 ✅

This was blocked by two parser bugs that took a while to track down — one in pipeline splitting where | inside parenthesized expressions like (empty .x) was incorrectly treated as a pipeline separator, and one in else-if chain reconstruction where C# string interpolation was silently producing single braces instead of double braces. The kind of bug where you stare at it for hours, then the fix is four characters.

The test suite is at 214 tests across three target frameworks, with a golden-test harness that runs helm template as the oracle and diffs the output document-by-document against HelmSharp's renderer.

What's Next

The project follows numbered milestones:

M1 (in progress): Helm template parity — functions, whitespace, built-in objects, control flow
M2: Subchart and dependency resolution
M3: Release lifecycle (install/upgrade/rollback/uninstall with hook execution)
M4: Kubernetes resource lifecycle hardening
M5: OCI registry and provenance
M6: API polish, XML docs, stable surface

No hard dates — I'm pushing forward steadily (you can see the cadence in the commit history). That said, if someone needs a specific feature, I'm happy to re-prioritize. Open source moves faster when real use cases drive it.

What I'm Looking For

If you're writing a .NET Kubernetes operator, a CD pipeline, or any tooling that currently shells out to helm — this is for you. dotnet add package HelmSharp.Action and render one of your charts. If it works, great. If it breaks, I want to know exactly how — open an issue with the chart and template that failed, and I'll fix it.

If you find it useful, a star is appreciated — but stars are earned, not asked for. What I really want is feedback, bug reports, and feature requests from people who actually deploy things to Kubernetes.

Contributions are welcome too. The golden-test harness makes it easy to verify template fixes — add a chart fixture, run the test, see the diff.

If you use Helm in .NET-based tooling today, what would you expect from a managed SDK like this?

GitHub: github.com/GaTTGeng/HelmSharp
NuGet: nuget.org/packages/HelmSharp.Action
License: MIT