KubernetesHelmChartExtensions Methods

ClassMethods6 members

Provides extension methods for adding and configuring external Helm charts in a Kubernetes environment.

AddHelmChart(IResourceBuilder<KubernetesEnvironmentResource>, string, string, string)extensionIResourceBuilder<KubernetesHelmChartResource>

Adds an external Helm chart to be installed in the Kubernetes environment. The chart is installed via helm upgrade --install as a pipeline step after the main application Helm chart is deployed.

public static class KubernetesHelmChartExtensions
{
    public static IResourceBuilder<KubernetesHelmChartResource> AddHelmChart(
        this IResourceBuilder<KubernetesEnvironmentResource> builder,
        string name,
        string chartReference,
        string chartVersion)
    {
        // ...
    }
}

KubernetesHelmChartExtensions.cs#L65-L129

Parameters

builderIResourceBuilder<KubernetesEnvironmentResource>The Kubernetes environment resource builder.

namestringThe name of the Helm chart resource (used as release name and namespace if not overridden).

chartReferencestring The Helm chart reference. Can be an OCI registry URL (e.g., oci://quay.io/jetstack/charts/cert-manager) or a chart name from an added repository.

chartVersionstringThe chart version to install.

Returns

IResourceBuilder<KubernetesHelmChartResource>A resource builder for the Helm chart resource.

Remarks

The chart is installed in a dedicated namespace (defaulting to the chart resource name). Use KubernetesHelmChartExtensions.WithNamespace to override the namespace, and KubernetesHelmChartExtensions.WithHelmValue to set chart values.

By default, aspire destroy does not uninstall the external chart, because it may be shared with workloads outside the Aspire app. Opt in to destroy-time uninstall by chaining KubernetesHelmChartExtensions.WithDestroy.

Examples

var k8s = builder.AddKubernetesEnvironment("k8s");

// Install cert-manager from OCI registry
k8s.AddHelmChart("cert-manager", "oci://quay.io/jetstack/charts/cert-manager", "1.17.0")
    .WithHelmValue("crds.enabled", "true");

WithDestroy(IResourceBuilder<KubernetesHelmChartResource>)extensionIResourceBuilder<KubernetesHelmChartResource>

Opts the Helm chart in to destroy-time uninstall. When set, aspire destroy will run helm uninstall for this release as part of the destroy pipeline.

public static class KubernetesHelmChartExtensions
{
    public static IResourceBuilder<KubernetesHelmChartResource> WithDestroy(
        this IResourceBuilder<KubernetesHelmChartResource> builder)
    {
        // ...
    }
}

KubernetesHelmChartExtensions.cs#L223-L226

Parameters

builderIResourceBuilder<KubernetesHelmChartResource>The Helm chart resource builder.

Returns

IResourceBuilder<KubernetesHelmChartResource>The resource builder for chaining.

Remarks

External Helm charts are not uninstalled by default because they may be shared with workloads outside the Aspire app (for example, cert-manager or an ingress controller installed once for many apps). Opt in only when the chart's lifecycle is owned by this app.

Examples

k8s.AddHelmChart("podinfo", "oci://ghcr.io/stefanprodan/charts/podinfo", "6.7.1")
    .WithDestroy();

WithForceConflicts(IResourceBuilder<KubernetesHelmChartResource>)extensionIResourceBuilder<KubernetesHelmChartResource>

Opts the Helm chart in to helm upgrade --install --force-conflicts. When set, Helm's server-side apply forcibly takes over any fields owned by another field manager instead of failing with a conflict.

public static class KubernetesHelmChartExtensions
{
    public static IResourceBuilder<KubernetesHelmChartResource> WithForceConflicts(
        this IResourceBuilder<KubernetesHelmChartResource> builder)
    {
        // ...
    }
}

KubernetesHelmChartExtensions.cs#L279-L282

Parameters

builderIResourceBuilder<KubernetesHelmChartResource>The Helm chart resource builder.

Returns

IResourceBuilder<KubernetesHelmChartResource>The resource builder for chaining.

Remarks

This is most commonly needed for charts whose templates ship admission webhooks (cert-manager, kyverno, gatekeeper, opa-gatekeeper, etc.) on clusters where another admission controller — such as the AKS admissionsenforcer field manager installed by the Azure Policy add-on or Deployment Safeguards — mutates the webhook configuration after install. Helm's Server-Side Apply (used by default for charts that opt in, including cert-manager) refuses to overwrite fields owned by another field manager. Without --force-conflicts, the next helm upgrade fails with a "conflict with admissionsenforcer" error on the webhook's namespaceSelector (or similar). See Deployment Safeguards in AKS and Server-Side Apply conflicts for background.

Unlike the deprecated --force / --force-replace (which delete and recreate the resource and are incompatible with Server-Side Apply), --force-conflicts is non-destructive — it only changes which field manager owns the conflicting field. No resources are deleted or recreated. This flag is also distinct from Helm's --take-ownership, which transfers ownership of an entire resource between Helm releases and does not address field-level conflicts.

Requires Helm v3.18 or later (the version that introduced --force-conflicts for helm upgrade --install). Older Helm versions fail with Error: unknown flag: --force-conflicts.

Examples

// cert-manager on AKS clusters with Azure Policy / Deployment Safeguards enabled.
k8s.AddHelmChart("cert-manager", "oci://quay.io/jetstack/charts/cert-manager", "v1.18.2")
    .WithHelmValue("crds.enabled", "true")
    .WithForceConflicts();

WithHelmValue(IResourceBuilder<KubernetesHelmChartResource>, string, string)extensionIResourceBuilder<KubernetesHelmChartResource>

Sets a Helm value for the chart installation. Values are passed to helm upgrade --install via --set flags.

public static class KubernetesHelmChartExtensions
{
    public static IResourceBuilder<KubernetesHelmChartResource> WithHelmValue(
        this IResourceBuilder<KubernetesHelmChartResource> builder,
        string key,
        string value)
    {
        // ...
    }
}

KubernetesHelmChartExtensions.cs#L146-L154

Parameters

builderIResourceBuilder<KubernetesHelmChartResource>The Helm chart resource builder.

keystringThe value key using dot notation (e.g., config.enableGatewayAPI).

valuestringThe value to set.

Returns

IResourceBuilder<KubernetesHelmChartResource>The resource builder for chaining.

WithNamespace(IResourceBuilder<KubernetesHelmChartResource>, string)extensionIResourceBuilder<KubernetesHelmChartResource>

Sets the Kubernetes namespace for the Helm chart installation. If not set, the namespace defaults to the chart resource name.

public static class KubernetesHelmChartExtensions
{
    public static IResourceBuilder<KubernetesHelmChartResource> WithNamespace(
        this IResourceBuilder<KubernetesHelmChartResource> builder,
        string @namespace)
    {
        // ...
    }
}

KubernetesHelmChartExtensions.cs#L169-L175

Parameters

builderIResourceBuilder<KubernetesHelmChartResource>The Helm chart resource builder.

namespacestringThe namespace to install the chart into.

Returns

IResourceBuilder<KubernetesHelmChartResource>The resource builder for chaining.

WithReleaseName(IResourceBuilder<KubernetesHelmChartResource>, string)extensionIResourceBuilder<KubernetesHelmChartResource>

Sets the Helm release name for the chart installation. If not set, the release name defaults to the resource name.

public static class KubernetesHelmChartExtensions
{
    public static IResourceBuilder<KubernetesHelmChartResource> WithReleaseName(
        this IResourceBuilder<KubernetesHelmChartResource> builder,
        string releaseName)
    {
        // ...
    }
}

KubernetesHelmChartExtensions.cs#L190-L196

Parameters

builderIResourceBuilder<KubernetesHelmChartResource>The Helm chart resource builder.

releaseNamestringThe Helm release name.

Returns

IResourceBuilder<KubernetesHelmChartResource>The resource builder for chaining.