From a6b72fdd8daf7a82fd644ddfadb4d70dba0d9dd1 Mon Sep 17 00:00:00 2001 From: "aspire-repo-bot[bot]" <268009190+aspire-repo-bot[bot]@users.noreply.github.com> Date: Mon, 11 May 2026 03:46:35 +0000 Subject: [PATCH] docs: Add external Helm charts documentation for AddHelmChart Documents the new AddHelmChart API introduced in microsoft/aspire#16589. - New page: deployment/kubernetes/helm-charts.mdx - AddHelmChart, WithHelmValue, WithNamespace, WithReleaseName, WithDestroy - Both Kubernetes and AKS environments covered - Sidebar entry and cross-references added Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../config/sidebar/deployment.topics.ts | 4 + .../docs/deployment/kubernetes/aks.mdx | 9 + .../deployment/kubernetes/helm-charts.mdx | 165 ++++++++++++++++++ .../docs/deployment/kubernetes/index.mdx | 5 + .../docs/deployment/kubernetes/kubernetes.mdx | 9 + 5 files changed, 192 insertions(+) create mode 100644 src/frontend/src/content/docs/deployment/kubernetes/helm-charts.mdx diff --git a/src/frontend/config/sidebar/deployment.topics.ts b/src/frontend/config/sidebar/deployment.topics.ts index c2c5a9c0b..3c4f86ac5 100644 --- a/src/frontend/config/sidebar/deployment.topics.ts +++ b/src/frontend/config/sidebar/deployment.topics.ts @@ -124,6 +124,10 @@ export const deploymentTopics: StarlightSidebarTopicsUserConfig = { label: 'Azure Kubernetes Service (AKS)', slug: 'deployment/kubernetes/aks', }, + { + label: 'External Helm charts', + slug: 'deployment/kubernetes/helm-charts', + }, { label: 'Ingress & Gateway API', slug: 'deployment/kubernetes-ingress', diff --git a/src/frontend/src/content/docs/deployment/kubernetes/aks.mdx b/src/frontend/src/content/docs/deployment/kubernetes/aks.mdx index 4249a1223..cb616513f 100644 --- a/src/frontend/src/content/docs/deployment/kubernetes/aks.mdx +++ b/src/frontend/src/content/docs/deployment/kubernetes/aks.mdx @@ -232,10 +232,19 @@ If pods fail with `ImagePullBackOff`, verify that the AKS cluster has the correc az aks check-acr --resource-group --name --acr .azurecr.io ``` +## Install external Helm charts + +Use `AddHelmChart` on the AKS environment to install pre-existing Helm charts — such as cert-manager or NGINX ingress — as post-deploy pipeline steps alongside your application. + + +See [Install external Helm charts](/deployment/kubernetes/helm-charts/) for a full walkthrough of `AddHelmChart`, `WithHelmValue`, `WithNamespace`, `WithReleaseName`, and `WithDestroy`. + + ## See also - [AKS integration](/integrations/cloud/azure/aks/) - [Kubernetes integration](/integrations/compute/kubernetes/) +- [Install external Helm charts](/deployment/kubernetes/helm-charts/) - [Deploy to Kubernetes](/deployment/kubernetes/) - [Deploy to Azure](/deployment/azure/) - [Pipelines and app topology](/deployment/pipelines/) diff --git a/src/frontend/src/content/docs/deployment/kubernetes/helm-charts.mdx b/src/frontend/src/content/docs/deployment/kubernetes/helm-charts.mdx new file mode 100644 index 000000000..961df7442 --- /dev/null +++ b/src/frontend/src/content/docs/deployment/kubernetes/helm-charts.mdx @@ -0,0 +1,165 @@ +--- +title: Install external Helm charts +description: Learn how to install external Helm charts alongside your Aspire application during Kubernetes deployment using AddHelmChart. +--- + +import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components'; +import LearnMore from '@components/LearnMore.astro'; + +Install pre-existing Helm charts — such as cert-manager, NGINX ingress controller, or monitoring tools — as part of your Aspire Kubernetes deployment. Aspire runs `helm upgrade --install` for each configured external chart after deploying your application's own generated Helm chart. + + +For the core Kubernetes deployment setup, see [Deploy to Kubernetes clusters](/deployment/kubernetes/kubernetes/) or [Deploy to AKS](/deployment/kubernetes/aks/). + + +## Overview + +When you use `aspire deploy`, Aspire deploys your application as a Helm chart and then runs any additional install steps you have defined. `AddHelmChart` registers one of these post-deploy pipeline steps. The install order is: + +1. Aspire generates and deploys your application's own Helm chart (`helm-deploy-{environment}`). +2. Each external chart registered with `AddHelmChart` is installed via `helm upgrade --install` (`helm-install-{name}`). + +## Add an external Helm chart + +Call `AddHelmChart` on a Kubernetes or AKS environment resource, passing the chart name (used as both the resource name and the default Helm release name), a chart reference, and a chart version: + + + +```csharp title="AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var k8s = builder.AddKubernetesEnvironment("k8s"); + +k8s.AddHelmChart("cert-manager", "oci://quay.io/jetstack/charts/cert-manager", "1.17.0"); + +var api = builder.AddProject("api"); + +builder.Build().Run(); +``` + + + +The `chartReference` parameter accepts: + +- OCI URLs — `oci://registry.example.com/repo/chart` +- HTTP(S) URLs — `https://charts.example.com/chart-1.0.0.tgz` +- Local paths — `./charts/my-chart` +- Packaged `.tgz` filenames — `my-chart-1.0.0.tgz` +- Repository-qualified names — `stable/nginx-ingress` + +The `chartVersion` must be a valid semantic version (for example, `1.17.0`). + +## Configure Helm values + +Use `WithHelmValue` to pass `--set key=value` arguments to the Helm install command: + + + +```csharp title="AppHost.cs" +k8s.AddHelmChart("cert-manager", "oci://quay.io/jetstack/charts/cert-manager", "1.17.0") + .WithHelmValue("crds.enabled", "true") + .WithHelmValue("config.enableGatewayAPI", "true"); +``` + + + +Value keys support dot-notation (`config.enableGatewayAPI`) and indexed array paths (`args[0]`). Both key and value are validated to prevent shell metacharacters from being passed to Helm. + +## Configure the namespace and release name + +By default, the chart is installed using the environment's namespace and the chart's resource name as the release name. Use `WithNamespace` and `WithReleaseName` to override these: + + + +```csharp title="AppHost.cs" +k8s.AddHelmChart("ingress-nginx", "oci://ghcr.io/nginx/helm/nginx-ingress", "2.0.0") + .WithNamespace("ingress-nginx") + .WithReleaseName("ingress-nginx"); +``` + + + +- `WithNamespace` accepts a string that follows [RFC 1123 DNS label](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-label-names) rules (lowercase alphanumerics and hyphens, max 63 characters). +- `WithReleaseName` follows Helm's release-name rules (DNS label format, max 53 characters). + +## Uninstall on destroy + +By default, external charts are not uninstalled when you run `aspire destroy`. This is intentional: cluster-wide tools such as cert-manager or monitoring agents are often shared by multiple workloads and shouldn't be torn down when a single application is removed. + +To opt in to uninstall-on-destroy, call `WithDestroy()`: + + + +```csharp title="AppHost.cs" +k8s.AddHelmChart("podinfo", "oci://ghcr.io/stefanprodan/charts/podinfo", "6.7.1") + .WithHelmValue("replicaCount", "2") + .WithDestroy(); +``` + + + +When `WithDestroy()` is set, `aspire destroy` runs `helm uninstall` for the chart in addition to removing your application's resources. + +:::tip +Use `WithDestroy()` for charts that are tightly coupled to the specific application — for example, a sidecar chart that has no value without the app — and omit it for shared infrastructure (cert-manager, observability stacks, etc.). +::: + +## Deploy to AKS + +The same `AddHelmChart` API is available on AKS environments through the `Aspire.Hosting.Azure.Kubernetes` package: + + + +```csharp title="AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var aks = builder.AddAzureKubernetesEnvironment("aks"); + +aks.AddHelmChart("podinfo", "oci://ghcr.io/stefanprodan/charts/podinfo", "6.7.1") + .WithHelmValue("replicaCount", "2") + .WithDestroy(); + +var api = builder.AddProject("api"); + +builder.Build().Run(); +``` + + + +The AKS overload delegates to the inner Kubernetes environment, so all the same `WithHelmValue`, `WithNamespace`, `WithReleaseName`, and `WithDestroy` options apply. + +## Complete example + +The following example installs cert-manager and a custom podinfo chart alongside an Aspire application on Kubernetes: + + + +```csharp title="AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +var k8s = builder.AddKubernetesEnvironment("k8s"); + +// cert-manager is a cluster-wide tool — don't uninstall it when the app is destroyed +k8s.AddHelmChart("cert-manager", "oci://quay.io/jetstack/charts/cert-manager", "1.17.0") + .WithHelmValue("crds.enabled", "true"); + +// podinfo is specific to this app — uninstall it on destroy +k8s.AddHelmChart("podinfo", "oci://ghcr.io/stefanprodan/charts/podinfo", "6.7.1") + .WithNamespace("podinfo") + .WithHelmValue("replicaCount", "2") + .WithDestroy(); + +var api = builder.AddProject("api"); + +builder.Build().Run(); +``` + + + +## See also + +- [Deploy to Kubernetes clusters](/deployment/kubernetes/kubernetes/) +- [Deploy to AKS](/deployment/kubernetes/aks/) +- [Kubernetes integration](/integrations/compute/kubernetes/) +- [AKS integration](/integrations/cloud/azure/aks/) +- [Pipelines and app topology](/deployment/pipelines/) diff --git a/src/frontend/src/content/docs/deployment/kubernetes/index.mdx b/src/frontend/src/content/docs/deployment/kubernetes/index.mdx index b1a9bf629..2eec38cf6 100644 --- a/src/frontend/src/content/docs/deployment/kubernetes/index.mdx +++ b/src/frontend/src/content/docs/deployment/kubernetes/index.mdx @@ -85,4 +85,9 @@ For more on the pipeline model and how publish and deploy relate, see [Pipelines description="Hosting integration reference for Aspire.Hosting.Azure.Kubernetes." href="/integrations/cloud/azure/aks/" /> + diff --git a/src/frontend/src/content/docs/deployment/kubernetes/kubernetes.mdx b/src/frontend/src/content/docs/deployment/kubernetes/kubernetes.mdx index 043247f2b..f04d10fb3 100644 --- a/src/frontend/src/content/docs/deployment/kubernetes/kubernetes.mdx +++ b/src/frontend/src/content/docs/deployment/kubernetes/kubernetes.mdx @@ -335,10 +335,19 @@ If your application can't find connection strings at runtime, verify that the ge Kubernetes Secrets store values as base64-encoded strings. Verify that your Secrets are properly encoded and that the generated templates reference them correctly. Use `kubectl get secret -o yaml` to inspect Secret contents. +## Install external Helm charts + +Use `AddHelmChart` on the Kubernetes environment to install pre-existing Helm charts — such as cert-manager, NGINX ingress, or monitoring tools — as post-deploy pipeline steps alongside your application's own chart. + + +See [Install external Helm charts](/deployment/kubernetes/helm-charts/) for a full walkthrough of `AddHelmChart`, `WithHelmValue`, `WithNamespace`, `WithReleaseName`, and `WithDestroy`. + + ## See also - [Kubernetes integration](/integrations/compute/kubernetes/) - [Deploy to AKS](/deployment/kubernetes/aks/) +- [Install external Helm charts](/deployment/kubernetes/helm-charts/) - [Pipelines and app topology](/deployment/pipelines/) - [Publishing and deployment overview](/deployment/overview/) - [Kubernetes documentation](https://kubernetes.io/docs/)