Arkanis.Aspire.Hosting.Extensions.Kubernetes
1.0.0-dev.22
dotnet add package Arkanis.Aspire.Hosting.Extensions.Kubernetes --version 1.0.0-dev.22
NuGet\Install-Package Arkanis.Aspire.Hosting.Extensions.Kubernetes -Version 1.0.0-dev.22
<PackageReference Include="Arkanis.Aspire.Hosting.Extensions.Kubernetes" Version="1.0.0-dev.22" />
<PackageVersion Include="Arkanis.Aspire.Hosting.Extensions.Kubernetes" Version="1.0.0-dev.22" />
<PackageReference Include="Arkanis.Aspire.Hosting.Extensions.Kubernetes" />
paket add Arkanis.Aspire.Hosting.Extensions.Kubernetes --version 1.0.0-dev.22
#r "nuget: Arkanis.Aspire.Hosting.Extensions.Kubernetes, 1.0.0-dev.22"
#:package Arkanis.Aspire.Hosting.Extensions.Kubernetes@1.0.0-dev.22
#addin nuget:?package=Arkanis.Aspire.Hosting.Extensions.Kubernetes&version=1.0.0-dev.22&prerelease
#tool nuget:?package=Arkanis.Aspire.Hosting.Extensions.Kubernetes&version=1.0.0-dev.22&prerelease
Arkanis.Aspire.Hosting.Extensions.Kubernetes
Shared .NET Aspire hosting extensions for Kubernetes publishing. This package contains manifest and YAML infrastructure, ingress helpers, PersistentVolumeClaim helpers, environment variables, Kubernetes connection-string secret references, and deployment-target selection.
Installation
dotnet add package Arkanis.Aspire.Hosting.Extensions.Kubernetes
Quick Start
using Aspire.Hosting;
using Aspire.Hosting.Extensions.Kubernetes;
using Aspire.Hosting.Extensions.Kubernetes.KubernetesConnections;
using Aspire.Hosting.Extensions.Kubernetes.KubernetesIngresses;
using Aspire.Hosting.Extensions.Kubernetes.PersistentVolumeClaims;
var builder = DistributedApplication.CreateBuilder(args);
var api = builder.AddProject<Projects.Api>("api");
var kubernetes = builder.AddKubernetesEnvironment("kubernetes");
api.WithKubernetesEnvironmentVariables(env =>
env.WithConfigurationFrom(builder.Configuration));
api.WithKubernetesIngress(ingress =>
ingress
.AtHost("api.example.test")
.AtPath("/", "Prefix")
.UsingIngressClass("nginx")
.InKubernetesEnvironment(kubernetes));
api.WithNewKubernetesPersistentVolumeClaim(
"data",
"api-data",
"/var/lib/api",
claim => claim
.WithStorageRequest("10Gi")
.WithReadWriteOnce()
.WithStorageClass("fast"));
api.WithExistingKubernetesPersistentVolumeClaim(
"shared-cache",
"existing-cache",
"/mnt/cache",
readOnly: true);
builder.Build().Run();
WithKubernetesIngress(...) emits the Ingress manifest during Kubernetes publish.
UseNewClaim(...) and WithNewKubernetesPersistentVolumeClaim(...) emit standalone PersistentVolumeClaim manifests during Kubernetes publish.
Existing-claim APIs only add workload mounts and require the claim to exist or be declared elsewhere.
Use AddKubernetesIngressesFromResourceAnnotations() and WithPersistentVolumeClaims(...) only for legacy AppHosts or environment-wide manifests.
Use WithKubernetesPersistentVolumeClaim(...) when a PVC mount needs configuration binding or an explicit Kubernetes environment.
Deployment Environment Settings
Call AddDeploymentEnvironmentConfiguration() near the start of an AppHost to load conventional settings files in override order.
var builder = DistributedApplication.CreateBuilder(args);
builder.AddDeploymentEnvironmentConfiguration();
if (builder.Environment.IsKubernetesDeployment())
{
// Configure Kubernetes publishing resources.
}
var deployment = builder.Environment.GetDeploymentEnvironment();
// Kubernetes-Staging resolves to DeploymentEnvironment("Kubernetes", "Staging").
For Kubernetes-Staging, the extension loads optional files in this order:
flowchart LR
A[appsettings.json] --> B[appsettings.Kubernetes.json]
B --> C[appsettings.Kubernetes.Staging.json]
C --> D[appsettings.Kubernetes-Staging.json]
D --> E[appsettings.local.json]
E --> F[Environment variables]
Later sources override earlier values.
The files do not reload on change.
Pass includeLocalSettings: false to omit the local file, or use configureBeforeEnvironmentVariables to add a custom configuration provider between JSON files and environment variables.
The method returns the AppHost builder for fluent chaining.
Environment variables are deliberately added last, so they can override command-line configuration providers that Aspire added before this call.
IsKubernetesDeployment() recognizes Kubernetes and well-formed Kubernetes-* environment names without matching unrelated names such as KubernetesPreview.
GetDeploymentEnvironment() requires a nonempty environment type and retains its casing for case-sensitive settings-file lookup.
The recognized Kubernetes prefix is canonicalized in file names, so kubernetes-Staging still loads appsettings.Kubernetes.Staging.json.
Environment names used as file names may contain letters, digits, dots, underscores, and hyphens, but cannot contain traversal sequences.
When adopting these extensions, remove matching AppHost-local GetDeploymentEnvironment() and IsKubernetesDeployment() methods to avoid ambiguous extension calls.
Reference-aware Environment Values
Use the callback overload of WithVariable(...) to build a Kubernetes value from literals, existing environment variables, and a referenced resource's published Service.
The Service host and port are taken from the generated Service model, including later Service customizations.
Declare the source resource before the consumer in the AppHost model.
var redis = builder.AddContainer("redis", "redis")
.WithEndpoint(targetPort: 6379, name: "tcp")
.WithComputeEnvironment(kubernetes);
var web = builder.AddProject<Projects.Web>("web")
.WithComputeEnvironment(kubernetes);
// Project REDIS_PASSWORD from a Kubernetes Secret before configuring REDIS_URL.
web.WithKubernetesEnvironmentVariables(env => env
.WithVariable("REDIS_URL", value => value
.AsUri("redis")
.WithRawPasswordEnvironment("REDIS_PASSWORD")
.WithServiceEndpoint(redis, "tcp")));
The example emits a value shaped like redis://:$(REDIS_PASSWORD)@redis:6379 for a Service named redis on port 6379.
Kubernetes expands $(REDIS_PASSWORD) at Pod startup only if REDIS_PASSWORD appears earlier in the container's env list.
The raw expansion does not percent-encode a password, so use it only for URI-safe passwords.
When encoding is needed, inject the complete prepared URI from a Secret, such as an External Secrets Operator template.
Composed values containing Kubernetes expansion expressions are omitted from local Aspire runs.
Service DNS is the preferred discovery method because it follows Service changes and does not depend on Service creation before the consumer Pod.
For applications that need kubelet-injected variables, ServiceLinkHost, ServiceLinkPort, ServiceLinkTcpAddress, ServiceLinkTcpPort, and ServiceLinkPortUri derive their names from the final published Service.
ServiceLinkVariable(source, service => ...) accepts the published Aspire Kubernetes Service model for additional kubelet variable patterns.
Service link references require both resources to share a Kubernetes environment and namespace, the Service to exist before the Pod starts, and enableServiceLinks to remain enabled.
STAKATER_*_SECRET variables injected by Reloader are rollout hashes, not Secret values.
Use Secret projection APIs to supply credentials.
Traefik Error Page Fallbacks
Use WithTraefikErrorPageFallback(...) on a resource-local Ingress when Traefik should serve a static fallback page for selected upstream errors.
This emits a Traefik Middleware CRD and attaches it to the generated Kubernetes Ingress with traefik.ingress.kubernetes.io/router.middlewares.
var fallbackPages = builder
.AddTraefikErrorPageFallbackPages("fallback-pages", "../fallback-pages")
.WithComputeEnvironment(kubernetes);
api
.WithComputeEnvironment(kubernetes)
.WithKubernetesIngress(ingress => ingress
.AtHost("api.example.test")
.UsingIngressClass("traefik")
.WithTraefikErrorPageFallback(fallback => fallback
.UsingService(fallbackPages)
.WithMiddlewareName("api-fallback-errors")
.HandlingStatusCodes(502, 503, 504)
.Serving("/{status}.html")
.ForwardingNoRequestHeaders()));
The fallback pages helper uses the supplied directory as a Docker build context and copies it into an image.
It does not emit a developer-machine bind mount or a Kubernetes hostPath volume.
Use its callback to change the base image, endpoint, port, or content destination path.
You can instead pass any existing Aspire compute resource with an HTTP endpoint to UsingService(...).
The Ingress owns the generated Middleware and its Traefik router reference.
The fallback service is not mutated with additional Kubernetes resources.
The target Kubernetes environment is inferred from the Ingress resource's WithComputeEnvironment(...) association.
When an Aspire fallback service is supplied, both resources must target the same compute environment.
The generated Middleware uses the Helm release namespace by default.
Use InNamespace(...) only for an explicit Middleware namespace and UsingServiceNamespace(...) only when the fallback Service is in another namespace.
HandlingStatuses(...) and HandlingStatusCodes(...) replace the default handled statuses.
Use AddHandledStatusCode(...) or AddHandledStatusRange(...) for additive changes.
Status expressions are validated as HTTP status codes, inclusive ranges, or comma-separated combinations.
Traefik must have its CRDs installed, and its Kubernetes Ingress provider must allow empty services when this is used for no-ready-endpoint outages.
For Traefik Helm values, that means providers.kubernetesIngress.allowEmptyServices=true.
Configuration Examples
Resource-local builders can read deployment details from AppHost configuration.
Ingress binding reads Kubernetes:Ingress:Resources:{ResourceName}:{IngressName} plus shared ingress defaults.
api
.WithComputeEnvironment(kubernetes)
.WithKubernetesIngress("api", ingress => ingress
.WithConfigurationFrom(builder.Configuration)
.WithTraefikErrorPageFallback(fallback => fallback
.UsingService(fallbackPages)));
KubernetesIngressConfiguration is the shared typed shape used by resource-local builders and legacy environment-wide options.
It includes the host, path, TLS, ingress class, cluster issuer, metadata, and optional ErrorPageFallback policy.
WithConfigurationFrom(...) binds that shape and delegates to WithConfiguration(...), so later fluent calls override configured values by normal call order.
Fallback configuration controls middleware policy while UsingService(...) remains code-first because it references an Aspire resource or Kubernetes Service identity.
PVC mount binding reads Kubernetes:Volumes:Resources:{ResourceName}:{VolumeName}.
It binds the claim name, mount path, and read-only flag for an existing claim.
api.WithKubernetesPersistentVolumeClaim("data", volume => volume
.WithConfigurationFrom(builder.Configuration)
.InKubernetesEnvironment(kubernetes));
When application resources are selected by deployment target, use ConfigureAny(...) to apply shared resource extensions to the active project-backed or container-backed resource.
using Aspire.Hosting.Extensions.Kubernetes.Targeting;
var targetedResources = new TargetedResourceFactory(useContainerResource: true);
var api = targetedResources.AddTargetedApplicationResource(
() => builder.AddProject<Projects.Api>("api"),
() => builder.AddContainer("api", "ghcr.io/example/api:latest"));
api.ConfigureAny(resource => resource
.WithKubernetesEnvironmentVariables(env => env.WithConfigurationFrom(builder.Configuration)));
Secret Reload Restarts
WithKubernetesConnectionString(...) rewrites generated connection-string environment variables to use Kubernetes secretKeyRef values.
When it does that, the generated workload metadata receives reloader.stakater.com/auto: "true" so Stakater Reloader can roll the workload after the referenced Secret changes.
The typed Aspire Kubernetes publisher currently emits Deployment and StatefulSet workloads.
Connection-string Secret references and PersistentVolumeClaim mounts work with either workload type.
Other publishing targets are unchanged because Kubernetes Secret selectors, workload annotations, and PersistentVolumeClaims are Kubernetes-only concepts.
web.WithKubernetesConnectionString(postgres, "ApplicationDatabase");
web.WithoutSecretReloadRestart();
Use WithoutSecretReloadRestart() only for workloads that must not restart automatically after a referenced Kubernetes Secret rotates.
Scope
This package records Kubernetes publishing intent in the Aspire AppHost model. It does not install a Kubernetes cluster, ingress controller, storage class, operator, CRD, or live-cluster resource.
Related Packages
Arkanis.Aspire.Hosting.Extensions.Kubernetes.ExternalSecretsadds External Secrets Operator helpers.Arkanis.Aspire.Hosting.Extensions.Kubernetes.Tailscaleadds Tailscale Kubernetes Operator helpers.Arkanis.Aspire.Hosting.Extensions.Kubernetes.CloudNativePostgresadds CloudNativePG helpers.
Repository
Source, issues, and release workflow details are available at https://github.com/ArkanisCorporation/Aspire.Hosting.Extensions.Kubernetes.
| 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
- Arkanis.Common.Aspire.ServiceDefaults (>= 1.0.0-dev.1)
- Aspire.Hosting (>= 13.5.4)
- Aspire.Hosting.Kubernetes (>= 13.5.3-preview.1.26425.3)
- JetBrains.Annotations (>= 2026.2.0)
- Microsoft.Extensions.Configuration (>= 10.0.12)
- Microsoft.Extensions.Configuration.Binder (>= 10.0.12)
- Microsoft.Extensions.DependencyInjection (>= 10.0.12)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.12)
- Microsoft.Extensions.Logging (>= 10.0.12)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.12)
- YamlDotNet (>= 18.1.0)
NuGet packages (3)
Showing the top 3 NuGet packages that depend on Arkanis.Aspire.Hosting.Extensions.Kubernetes:
| Package | Downloads |
|---|---|
|
Arkanis.Aspire.Hosting.Extensions.Kubernetes.ExternalSecrets
Reusable Aspire hosting extensions for publishing External Secrets Operator manifests from Kubernetes and Aspire Secret configuration. |
|
|
Arkanis.Aspire.Hosting.Extensions.Kubernetes.CloudNativePostgres
Reusable Aspire hosting extensions for publishing CloudNativePG database resources and credentials ExternalSecrets. |
|
|
Arkanis.Aspire.Hosting.Extensions.Kubernetes.Tailscale
Reusable Aspire hosting extensions for publishing Tailscale Kubernetes Operator services, ingresses, proxy classes, proxy groups, and policies. |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 1.0.0-dev.22 | 469 | 9/27/2026 |
| 1.0.0-dev.21 | 83 | 9/27/2026 |
| 1.0.0-dev.20 | 143 | 9/18/2026 |
| 1.0.0-dev.19 | 153 | 9/17/2026 |
| 1.0.0-dev.18 | 179 | 9/11/2026 |
| 1.0.0-dev.17 | 318 | 8/8/2026 |
| 1.0.0-dev.16 | 113 | 8/7/2026 |
| 1.0.0-dev.15 | 98 | 8/7/2026 |
| 1.0.0-dev.14 | 117 | 8/6/2026 |
| 1.0.0-dev.13 | 115 | 8/6/2026 |
| 1.0.0-dev.12 | 110 | 8/6/2026 |
| 1.0.0-dev.11 | 106 | 8/6/2026 |
| 1.0.0-dev.10 | 99 | 8/5/2026 |
| 1.0.0-dev.9 | 140 | 8/1/2026 |
| 1.0.0-dev.8 | 103 | 8/1/2026 |
| 1.0.0-dev.7 | 253 | 7/5/2026 |
| 1.0.0-dev.6 | 109 | 7/5/2026 |
| 1.0.0-dev.5 | 145 | 7/4/2026 |
| 1.0.0-dev.4 | 139 | 7/3/2026 |
| 1.0.0-dev.3 | 125 | 7/2/2026 |