Aspire.Hosting.Kubernetes 17.0.0

Prefix Reserved
dotnet add package Aspire.Hosting.Kubernetes --version 17.0.0
                    
NuGet\Install-Package Aspire.Hosting.Kubernetes -Version 17.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Aspire.Hosting.Kubernetes" Version="17.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Aspire.Hosting.Kubernetes" Version="17.0.0" />
                    
Directory.Packages.props
<PackageReference Include="Aspire.Hosting.Kubernetes" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Aspire.Hosting.Kubernetes --version 17.0.0
                    
#r "nuget: Aspire.Hosting.Kubernetes, 17.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Aspire.Hosting.Kubernetes@17.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Aspire.Hosting.Kubernetes&version=17.0.0
                    
Install as a Cake Addin
#tool nuget:?package=Aspire.Hosting.Kubernetes&version=17.0.0
                    
Install as a Cake Tool

Kubernetes hosting integration

Use this integration to model, configure, and deploy Aspire compute resources to Kubernetes.

Getting started

Prerequisites

  • Helm v4.0.0 or later on your PATH.

Aspire shells out to helm upgrade --install to deploy the generated chart and validates the Helm version up front, so missing or older installs produce a clear actionable error instead of cryptic flag failures.

Add the integration

From your AppHost directory, add the Aspire.Hosting.Kubernetes integration with the Aspire CLI:

aspire add Aspire.Hosting.Kubernetes
aspire add Aspire.Hosting.Dotnet

Usage example

In the AppHost, add the environment:

C#

builder.AddKubernetesEnvironment("k8s");

TypeScript

await builder.addKubernetesEnvironment("k8s");

The dashboard container included in the published Helm chart opts out of dashboard usage and error telemetry by default (ASPIRE_DASHBOARD_TELEMETRY_OPTOUT=true). This does not affect the application's OpenTelemetry data sent to the dashboard.

Browser-origin endpoint properties use deployment inputs rather than internal Kubernetes service addresses. The referenced endpoint must be external HTTP(S); internal and non-HTTP(S) endpoint references are rejected. For example, frontend.GetEndpoint("http").BrowserOrigins reads Parameters:frontend-http-BrowserOrigins, which aspire deploy supplies through its Helm values override file. The input accepts a comma-separated origin list; published charts retain a placeholder for it. frontend.GetEndpoint("http").PrimaryBrowserOrigin uses a separate Parameters:frontend-http-PrimaryBrowserOrigin input containing a single origin. Its default is the first origin from the same matching routes used for BrowserOrigins. Explicit literal hostnames on matching Ingress paths or Gateway routes provide overridable defaults. Route-specific hostnames override inherited hostnames, and matching TLS configuration selects HTTPS. Concrete route hostnames also match wildcard HTTPS listener scopes. Ingress wildcards match one label; Gateway wildcards can match multiple labels. This uses configured routing hostnames, not certificate contents. Hostless routes, wildcard hosts, and deferred hostname expressions still require an explicit origin input; internal service DNS and controller-assigned addresses are not assumed to be browser origins. Different endpoint identities retain separate inputs even when their readable names collide.

Custom manifests in polyglot AppHosts

Use addManifest inside a Kubernetes service customization to add custom resources to the generated Helm chart. withField accepts JSON-compatible primitives, objects, and arrays, including arrays of objects:

await api.publishAsKubernetesService(async (service) => {
    const policy = await service.addManifest("cilium.io/v2", "CiliumNetworkPolicy", "api-netpol");
    await policy.withField("spec.endpointSelector.matchLabels", {
        "app.kubernetes.io/component": "api"
    });
    await policy.withField("spec.ingress", [{
        fromEndpoints: [{
            matchLabels: { "app.kubernetes.io/component": "frontend" }
        }]
    }]);
});

Paths are dot-separated, so pass keys containing dots or slashes inside an object at the parent path, as shown above. Each call replaces the value at that path; it does not merge an existing subtree. Non-JSON objects such as resource handles are not supported as field values, including inside objects and arrays. Use the dedicated namespace, label, and annotation methods for manifest metadata. In C# AppHosts, use AdditionalResources with a BaseKubernetesResource subclass for typed custom resources.

Container registries

Assign a registry to a project or Dockerfile-backed resource to include its registry-qualified image name in the published Helm chart:

C#

var registry = builder.AddContainerRegistry("registry", "registry.example.com", "apps");

builder.AddDotnetProject("api", "../Api/Api.csproj")
    .WithContainerRegistry(registry);

TypeScript

const registry = await builder.addContainerRegistry("registry", "registry.example.com", "apps");
const api = await builder.addNodeApp("api", "../api", "server.js");
await api.withContainerRegistry(registry);

For this example, aspire publish writes registry.example.com/apps/api:latest to the image parameter in values.yaml. Image push options that customize the remote image name or tag are also respected. Existing container images, such as redis:7, are unchanged.

Literal registry values and non-secret parameter defaults can be resolved during publishing. Registry values that require provisioning, secrets, or parameters without defaults remain deferred, with <resource>:latest as the published placeholder. aspire deploy resolves the image names again after provisioning and supplies them through a Helm values override file. If deploying the published chart yourself, supply the deferred image values to Helm.

Volumes

Use a target-neutral volume when the Kubernetes environment's default storage policy is sufficient:

C#

builder.AddDotnetProject("api", "../Api/Api.csproj")
    .WithVolume("data", "/data", env: "DATA_PATH");

TypeScript

const api = await builder.addNodeApp("api", "../api", "server.js");
await api.withVolume("/data", "data", "DATA_PATH");

Projects and executables receive a workload-scoped Aspire store directory in run mode. The directory is reused across AppHost runs regardless of whether the process has a session or persistent lifetime. When published, the volume uses the Kubernetes environment's DefaultStorageType, which is emptyDir — storage lives for the lifetime of the pod and is lost when the pod restarts or is rescheduled. DATA_PATH contains /data. For storage that outlives the pod, use a persistent volume instead.

Persistent volumes

Add a persistent volume and expose its effective path through an environment variable:

C#

var k8s = builder.AddKubernetesEnvironment("k8s");
var data = k8s.AddPersistentVolume("data")
    .WithCapacity("20Gi");

builder.AddDotnetProject("api", "../Api/Api.csproj")
    .WithPersistentVolume(data, "/data", env: "DATA_PATH");

TypeScript

const k8s = await builder.addKubernetesEnvironment("k8s");
const data = await k8s.addPersistentVolume("data");
await data.withCapacity("20Gi");

const api = await builder.addNodeApp("api", "../api", "server.js");
await api.withKubernetesPersistentVolumeMount(data, "/data", { env: "DATA_PATH" });

When a project or executable runs locally, DATA_PATH points to a persistent directory in the AppHost's Aspire store. That store is normally under the AppHost intermediate-output directory, so cleaning build outputs can remove the local data. Local containers use a worktree-scoped container volume instead, provided the mount names an environment variable. Mounts that do not name one keep the persistent volume's own name for the local container volume, so data written by an earlier version of the AppHost stays attached. A single persistent-volume resource cannot be shared between local containers and local projects or executables because those execution types cannot use one backing store reliably.

When published or deployed, DATA_PATH contains /data. Applications can therefore use the same environment variable in both environments. The isReadOnly mount option is enforced after deployment, but Aspire cannot make a directory read-only for a process running directly on the host.

aspire publish -o k8s-artifacts

Persistent volume claim customization

Use WithConfiguration / withConfiguration to customize the generated claim after the environment defaults and fluent volume settings have been applied. Multiple callbacks run in registration order and see changes made by earlier callbacks.

C#

var data = k8s.AddPersistentVolume("data")
    .WithConfiguration(claim =>
    {
        claim.Metadata.Labels["example.com/retention"] = "retain";
        claim.Spec.VolumeMode = "Filesystem";
        claim.Spec.StorageClassName = "";
    });

TypeScript

const data = await k8s.addPersistentVolume("data");
await data.withConfiguration(async (claim) => {
    const metadata = await claim.metadata.get();
    await metadata.labels.set("example.com/retention", "retain");

    const spec = await claim.spec.get();
    await spec.volumeMode.set("Filesystem");
    await spec.storageClassName.set("");
});

TypeScript callbacks receive live remote objects: await property and collection operations rather than assigning JavaScript properties. The supported claim surface includes labels, annotations, storage class, volume name, volume mode, access modes, and resource requests. For example, use await metadata.annotations(), await spec.accessModes(), and await (await spec.resources.get()).requests() to access the corresponding mutable collections.

Setting storageClassName to "" requests a classless volume; setting it to null omits the field so Kubernetes can assign its default StorageClass. The fluent equivalents are withStorageClass("") and withoutStorageClass(). Use the existing parameterized fluent methods when storage class, capacity, or annotations should be resolved through Helm parameters; callbacks see the generated values.

Other claim fields, including selectors, data sources, volume attributes classes, resource limits, and claim name/namespace customization, remain C#-only. Setting volumeMode to "Block" does not create the workload's required volumeDevices bindings; the persistent-volume mount APIs generate filesystem mounts.

ACME certificates with cert-manager

Install cert-manager and configure an issuer with the provider's ACME directory URL:

var k8s = builder.AddKubernetesEnvironment("k8s");
var certManager = k8s.AddCertManager("cert-manager");

var letsEncrypt = certManager.AddIssuer("letsencrypt")
    .WithAcmeServer("https://acme-v02.api.letsencrypt.org/directory", "ops@contoso.com")
    .WithHttp01Solver();

// api must expose an external HTTP endpoint; the Gateway must be publicly reachable on port 80.
k8s.AddGateway("public")
    .WithGatewayClass("my-gateway-class")
    .WithRoute("/", api.GetEndpoint("http"))
    .WithTls(letsEncrypt);

The former WithLetsEncryptProduction and WithLetsEncryptStaging helpers have been removed. Use WithAcmeServer with the corresponding URL instead; for TypeScript, use withAcmeServer with either strings or parameters. Use staging for development and CI to avoid production rate limits; staging certificates are not publicly trusted.

The directory URL can also be a non-secret parameter, so one AppHost can select an endpoint per environment without changing source:

var serverUrl = builder.AddParameter("acmeserver");
var email = builder.AddParameter("acmeemail");
var issuer = certManager.AddIssuer("acme")
    .WithAcmeServer(serverUrl, email)
    .WithHttp01Solver();

Set Parameters__acmeserver and Parameters__acmeemail before deployment. The URL and email must either both be literal strings or both be parameters. TypeScript uses the same withAcmeServer(serverUrl, email) method for both forms.

Provider ACME directory External Account Binding
Let's Encrypt production https://acme-v02.api.letsencrypt.org/directory Not required
Let's Encrypt staging https://acme-staging-v02.api.letsencrypt.org/directory Not required
ZeroSSL https://acme.zerossl.com/v2/DV90 Required
Google Trust Services production https://dv.acme-v02.api.pki.goog/directory Required
Google Trust Services staging https://dv.acme-v02.test-api.pki.goog/directory Required

Other ACME providers, including SSL.com, Sectigo, and DigiCert, use the same APIs with their account/product-specific directory URLs and EAB credentials. Provider-specific authentication and credential acquisition remain outside Aspire. Private ACME servers also require the appropriate TLS trust configuration; EAB does not establish that trust.

External Account Binding

EAB is defined by RFC 8555, section 7.3.4. It binds a newly registered ACME account to an existing provider account using a key identifier and an HMAC key. It does not replace the domain-ownership challenge.

For ZeroSSL, obtain EAB credentials from the provider and pass the HMAC key as a secret parameter:

var keyId = builder.AddParameter("acmeeabkeyid");
var hmacKey = builder.AddParameter("acmeeabhmackey", secret: true);

var zeroSsl = certManager.AddIssuer("zerossl")
    .WithAcmeServer(serverUrl, email)
    .WithExternalAccountBinding(keyId, hmacKey)
    .WithHttp01Solver();

Both EAB arguments must be parameters; the HMAC parameter must be secret. Set Parameters__acmeserver to https://acme.zerossl.com/v2/DV90 for ZeroSSL. In TypeScript:

const keyId = await builder.addParameter("acmeeabkeyid");
const hmacKey = await builder.addParameter("acmeeabhmackey", { secret: true });
const serverUrl = await builder.addParameter("acmeserver");
const email = await builder.addParameter("acmeemail");
const issuer = await certManager.addIssuer("zerossl");
await issuer.withAcmeServer(serverUrl, email);
await issuer.withExternalAccountBinding(keyId, hmacKey);
await issuer.withHttp01Solver();

Supply parameters using your pipeline's secure environment-variable mechanism, with Parameters__acmeeabkeyid and Parameters__acmeeabhmackey set before aspire deploy. Never print the HMAC key or enable shell tracing around credential acquisition. Pass the provider's unpadded base64url HMAC text unchanged; do not base64-decode it yourself.

Aspire applies an issuer-specific <issuer>-eab Secret before applying the ClusterIssuer. The value is sent to kubectl through stdin, not command-line arguments or published artifacts. Kubernetes' Secret.data base64 encoding is a separate layer, not encryption: restrict Secret access with RBAC and configure encryption at rest as appropriate. Existing Secrets not marked as Aspire cert-manager-managed are not adopted or deleted. Destroy removes the managed EAB Secret before uninstalling cert-manager, even if EAB was removed from the issuer configuration before redeployment; it does not explicitly delete cert-manager's separate <issuer>-account-key Secret. If EAB Secret cleanup fails, destroy logs a warning and continues with Helm uninstall and infrastructure teardown. Remove any retained EAB Secret manually. Changing issuer names or namespaces after deployment requires manual cleanup of resources at their previous locations.

Deployment pipelines and account lifecycle

Credential lifetime and reuse are provider-specific. ZeroSSL documents reusable EAB credentials. Google Public CA credentials must be used within seven days and can register one account. For a new Google account, authenticate to Google in a separate pipeline step and acquire a fresh pair with gcloud publicca external-account-keys create; capture keyId and b64MacKey securely and supply them as the Aspire parameters. Aspire does not authenticate to providers, refresh EAB credentials, or track their expiry.

Once registered, cert-manager renews using the ACME account private-key Secret, not by creating a fresh EAB account each time. Preserve that Secret across redeployments. Deleting/recreating the cluster or losing the account key may require fresh EAB credentials; do not delete account keys as an automatic recovery shortcut. The managed EAB apply path still requires configured parameter values on subsequent deployments.

aspire deploy applies the issuer but does not wait for ACME account registration. Check issuer readiness before treating a deployment as ready for certificate issuance:

kubectl wait clusterissuer/zerossl --for=condition=Ready --timeout=300s

Readiness verifies account setup, not that a Gateway certificate has been issued. Wait for the relevant Certificate separately.

See cert-manager's ACME configuration for account reuse and EAB details.

Additional documentation

https://aspire.dev/integrations/gallery/ https://aspire.dev/integrations/compute/kubernetes/

Feedback & contributing

https://github.com/microsoft/aspire

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (11)

Showing the top 5 NuGet packages that depend on Aspire.Hosting.Kubernetes:

Package Downloads
KubeOps.Aspire.Hosting

.NET Aspire hosting integration for KubeOps operators. Adds an AddKubeOps extension to the distributed application builder so a KubeOps operator project can be orchestrated as a resource in a .NET Aspire AppHost, wired up with references, environment variables and telemetry.

Coworkee.Aspire

AddCoworkeeApp() for the Aspire app host: migrations, auth server, APIs, workers and web wired with Postgres (or SQL Server, SQLite), Redis, Mailpit, Elasticsearch and Keycloak.

Aspire.Hosting.Azure.Kubernetes

Azure Kubernetes Service (AKS) resource types for Aspire.

CommunityToolkit.Aspire.Hosting.Kind

An Aspire hosting integration for Kind that manages local Kind clusters for development with Docker or Podman.

Arkanis.Aspire.Hosting.Extensions.Kubernetes

Reusable Aspire hosting extensions for Kubernetes publishing, manifests, ingress, persistent volumes, environment variables, and deployment-target selection.

GitHub repositories (2)

Showing the top 2 popular GitHub repositories that depend on Aspire.Hosting.Kubernetes:

Repository Stars
mehdihadeli/food-delivery-microservices
🍔 A practical and cloud-native food delivery microservices, built with .Net Aspire, .Net 10, Wolverine, Domain-Driven Design, CQRS, Vertical Slice Architecture, Event-Driven Architecture, and the latest technologies.
petabridge/DrawTogether.NET
Multi-player MS Paint application. Built with Akka.NET, Blazor, and .NET Aspire.
Version Downloads Last Updated
17.0.0 1,904 11/18/2026
13.6.5-preview.1.26559.7 13,207 11/10/2026
13.6.4-preview.1.26523.11 11,951 10/24/2026
13.6.3-preview.1.26521.2 2,052 10/21/2026
13.6.2-preview.1.26519.11 1,862 10/20/2026
13.6.1-preview.1.26506.6 23,829 10/7/2026
13.6.0-preview.1.26479.8 17,071 9/29/2026
13.5.4-preview.1.26464.4 24,471 9/15/2026
13.5.3-preview.1.26425.3 22,734 8/25/2026
13.5.2-preview.1.26421.6 7,341 8/21/2026
13.5.1-preview.1.26420.4 409 8/20/2026
13.5.0-preview.1.26417.10 7,402 8/18/2026
13.4.6-preview.1.26319.6 64,804 6/19/2026
13.4.5-preview.1.26316.12 3,585 6/17/2026
13.4.4-preview.1.26314.3 5,843 6/15/2026
13.4.3-preview.1.26305.13 8,352 6/8/2026
13.4.2-preview.1.26303.6 2,776 6/3/2026
13.4.1-preview.1.26303.3 116 6/3/2026
13.4.0-preview.1.26281.18 20,194 6/1/2026
13.3.5-preview.1.26270.6 11,866 5/21/2026
Loading failed