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
<PackageReference Include="Aspire.Hosting.Kubernetes" Version="17.0.0" />
<PackageVersion Include="Aspire.Hosting.Kubernetes" Version="17.0.0" />
<PackageReference Include="Aspire.Hosting.Kubernetes" />
paket add Aspire.Hosting.Kubernetes --version 17.0.0
#r "nuget: Aspire.Hosting.Kubernetes, 17.0.0"
#:package Aspire.Hosting.Kubernetes@17.0.0
#addin nuget:?package=Aspire.Hosting.Kubernetes&version=17.0.0
#tool nuget:?package=Aspire.Hosting.Kubernetes&version=17.0.0
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
| Product | Versions 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. |
-
net10.0
- Aspire.Hosting (>= 17.0.0)
- AspNetCore.HealthChecks.Uris (>= 9.0.0)
- Google.Protobuf (>= 3.36.1)
- Grpc.AspNetCore (>= 2.83.0)
- Grpc.Net.ClientFactory (>= 2.83.0)
- Grpc.Tools (>= 2.83.0)
- Hex1b (>= 0.173.0)
- KubernetesClient (>= 19.0.2)
- MessagePack (>= 2.5.307)
- Microsoft.Extensions.Configuration.Abstractions (>= 10.0.15)
- Microsoft.Extensions.Configuration.Binder (>= 10.0.15)
- Microsoft.Extensions.Configuration.EnvironmentVariables (>= 10.0.15)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.15)
- Microsoft.Extensions.Diagnostics.HealthChecks (>= 10.0.15)
- Microsoft.Extensions.FileSystemGlobbing (>= 10.0.15)
- Microsoft.Extensions.Hosting (>= 10.0.15)
- Microsoft.Extensions.Hosting.Abstractions (>= 10.0.15)
- Microsoft.Extensions.Http (>= 10.0.15)
- Microsoft.Extensions.Logging (>= 10.0.15)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.15)
- Microsoft.Extensions.Options (>= 10.0.15)
- Microsoft.Extensions.Primitives (>= 10.0.15)
- ModelContextProtocol (>= 1.4.1)
- Newtonsoft.Json (>= 13.0.4)
- OpenTelemetry.Exporter.OpenTelemetryProtocol (>= 1.18.0)
- OpenTelemetry.Extensions.Hosting (>= 1.18.0)
- Polly.Core (>= 8.7.0)
- Semver (>= 3.0.0)
- StreamJsonRpc (>= 2.25.29)
- System.IO.Hashing (>= 10.0.15)
- YamlDotNet (>= 18.1.0)
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 |