Getting Started

This guide is for the first integration decision: do you only need rendered manifests, or do you want Helm-like release workflows as well?

If your application just needs Kubernetes YAML, start with the rendering path. It is the smallest surface area and the clearest way to verify that HelmSharp fits your chart.

Install

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

Add HelmSharp.Action later if you want command-like release operations.

Render a chart without Helm CLI

using HelmSharp.Chart;
using HelmSharp.Engine;

var chart = await HelmChartLoader.LoadAsync("/charts/my-chart", ct);

var values = await HelmValues.BuildAsync(
    chart: chart,
    valuesFiles: ["values.production.yaml"],
    valuesContent: null,
    setValues: new Dictionary<string, string>
    {
        ["image.tag"] = "1.25",
        ["replicaCount"] = "2"
    },
    setFileValues: null,
    setStringValues: null,
    setJsonValues: null,
    cancellationToken: ct);

var renderer = new HelmTemplateRenderer(chart, "demo", "default", values);
var manifests = renderer.Render();
var notes = renderer.RenderNotes();

Use this path when you are building preview pages, policy checks, drift reports, generated pull requests, or a controller that needs to inspect manifests before applying them.

Keep values close to your product model

HelmSharp accepts the same common override shapes users expect from Helm:

Input	Use it when
valuesFiles	Operators already maintain environment-specific values files.
valuesContent	Values are generated by your application or stored outside the filesystem.
setValues	You need ordinary --set-style overrides.
setStringValues	Strings must stay strings even when they look like numbers or booleans.
setJsonValues	A product setting maps naturally to a JSON object or array.
setFileValues	A value should come from file content.

Later inputs override earlier ones. Keep that order visible in application code; it makes deployment previews easier to explain.

Move up to release workflows

Install HelmSharp.Action when you want one client for template, dry-run, install, upgrade, rollback, uninstall, status, history, package, and repository operations.

dotnet add package HelmSharp.Action

using HelmSharp.Action;

var client = new HelmClient(optionsProvider);

var result = await client.UpgradeInstallAsync(new HelmUpgradeInstallRequest
{
    ReleaseName = "demo",
    Namespace = "default",
    Chart = "/charts/my-chart",
    ValuesFiles = ["values.production.yaml"],
    CreateNamespace = true,
    Wait = true,
    TimeoutSeconds = 300,
    DryRun = true
});

Console.WriteLine(result.StandardOutput);

Keep DryRun = true until your application has an explicit moment where it is allowed to mutate the cluster.

Minimal static options provider

For production applications, implement IHelmOptionsProvider from configuration or dependency injection. For a small console app, this is enough:

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

Run the repository examples

dotnet run --project examples/RenderChart -- examples/sample-chart
dotnet run --project examples/InstallRelease -- examples/sample-chart demo
dotnet run --project examples/InstallRelease -- examples/sample-chart demo --apply

The install example defaults to dry-run mode. Passing --apply submits resources to the current Kubernetes context.

Next step

Read the API overview to choose the smallest package surface for your application, then check Helm compatibility for the chart behavior you rely on.