Install and upgrade releases

Use HelmSharp.Action when a component owns a deployment, not just its YAML. HelmClient.UpgradeInstallAsync combines chart loading, values, rendering, hooks, Kubernetes apply, optional readiness waiting, and release-history persistence.

dotnet add package HelmSharp.Action --version 1.3.2

Start with a dry run

Give HelmClient an IHelmOptionsProvider owned by your application. It is where you centralize defaults such as namespace, field manager, Kubernetes version, API versions, and timeout rather than letting each caller invent them.

var request = new HelmUpgradeInstallRequest
{
    ReleaseName = "demo",
    Namespace = "default",
    Chart = chartPath,
    ValuesFiles = ["values.production.yaml"],
    CreateNamespace = true,
    Wait = true,
    TimeoutSeconds = 300,
    DryRun = true
};

var result = await client.UpgradeInstallAsync(request, cancellationToken);

if (!result.Succeeded)
{
    logger.LogWarning("Release preview failed: {Error}", result.StandardError);
    return;
}

Console.WriteLine(result.StandardOutput);

A dry run renders and validates the request without applying resources or creating a release revision. This short example is suitable for a one-off preview. When the target release might have history, an approval preview must also derive DryRunIsUpgrade and DryRunRevision from the complete history; use the state-aware review-to-deployment example before recording the approval. ReuseValues is not supported with DryRun; for an approval workflow, resolve and persist the stored effective values before rendering instead.

Apply the approved request

After an explicit approval, rebuild the request from the recorded inputs and apply it through the state-aware review-to-deployment example. Do not silently change values, chart version, target namespace, capability inputs, or the resolved release state between preview and apply. HelmUpgradeInstallRequest is mutable, so do not share the preview request with the apply operation.

Set lifecycle behavior deliberately

Setting	Meaning
Install = false	A missing release is an error; use this for upgrade-only endpoints.
ReuseValues = true	Start from the stored release values, then overlay this request's values. It is incompatible with DryRun; resolve those values yourself before an approval preview.
ResetValues = true	Start from chart defaults. It cannot be combined with ReuseValues.
Wait = true	Wait for supported resource readiness after apply.
WaitForJobs = true	Also wait for Jobs; it requires Wait or Atomic.
TimeoutSeconds	One limit for applying resources, hooks, readiness waiting, and cancellation.
Atomic = true	Wait and recover on failure.
DisableHooks = true	Do not execute chart hooks.
MaxHistory	Retain at most this many stored revisions; 0 means no limit.

HelmSharp stores successful, superseded, failed, and retained-uninstall revisions in Kubernetes Secrets. A default uninstall purges release history; a retained uninstall records an uninstalled revision. Use StatusAsync, HistoryAsync, GetManifestAsync, GetValuesAsync, and the revision-specific inspection methods to read what was actually stored; inspection does not re-render the current chart.

Control uninstall and rollback cleanup

var result = await client.UninstallAsync(new HelmUninstallRequest
{
    ReleaseName = "demo",
    Namespace = "default",
    KeepHistory = true,
    Wait = true,
    TimeoutSeconds = 300,
    DeletionPropagation = HelmDeletionPropagation.Foreground
}, cancellationToken);

Uninstall deletes regular manifest resources in reverse order. DeletionPropagation defaults to Background; Foreground asks Kubernetes to retain each owner until blocking dependents are gone, while Orphan leaves dependents behind. Wait = true additionally polls until every requested resource is absent. An object already absent is successful. A discovery, permission, or other API failure stops cleanup and identifies the affected resource. Resources annotated with helm.sh/resource-policy: keep are not sent a direct delete request, and release history is then either purged or marked uninstalled according to KeepHistory. As with Helm, this annotation cannot prevent Kubernetes from cascading deletion when the resource's namespace or owner is deleted.

Rollback applies the target revision and then deletes resources that exist only in the current revision, also in reverse order with background propagation. It does not directly delete resources annotated with helm.sh/resource-policy: keep, subject to the same namespace and owner-cascade limitation. Post-rollback hooks run only after that cleanup succeeds.

Hooks and readiness are part of the operation

Hooks run in weight and then name order. Job and Pod hooks are observed for completion within the timeout; other hook kinds are applied without a completion observer. The supported cleanup policies are before-hook-creation, hook-succeeded, and hook-failed; when no policy is declared, before-hook-creation is used. Cleanup waits until Kubernetes reports the hook object absent before continuing. hook-succeeded resources remain available to later hooks in the same event batch, then are deleted in reverse execution order after the whole batch succeeds; if a later hook fails or the operation is canceled, previously successful hooks are finalized before the original failure is returned. A failed before-hook-creation delete prevents a conflicting hook create, and a failed hook-succeeded cleanup fails the operation. Failure/cancellation finalization shares one independent bounded window across the whole cleanup batch and continues past individual delete errors; if cleanup fails, HelmSharp preserves the original hook exception and attaches the cleanup exception or aggregate at Exception.Data["HelmSharp.HookCleanupError"]. DisableHooks = true skips hook execution and hook cleanup. Hook cleanup uses background propagation and never deletes the release's regular manifest. For Helm parity and to avoid cascading deletion of custom resources, delete policies never delete CustomResourceDefinition hooks.

The built-in readiness waiter covers common workload resources. A CRD can be applied, but its domain-specific readiness is not inferred. Add a product-specific health check when a deployment is not ready merely because Kubernetes accepted the object.

Permissions and error handling

The Kubernetes identity needs permission for the rendered resource kinds, namespaces, CRDs where used, hooks, and the release Secret records. High-level operations can return CommandResult or throw; inspect Succeeded, ExitCode, StandardOutput, and StandardError when a result is returned, and catch/log exceptions at the service boundary. Troubleshoot failures covers the two failure models and the diagnostic context worth retaining.