Arkanis.Aspire.Hosting.Extensions.Kubernetes 1.0.0-dev.22

This is a prerelease version of Arkanis.Aspire.Hosting.Extensions.Kubernetes.
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
                    
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="Arkanis.Aspire.Hosting.Extensions.Kubernetes" Version="1.0.0-dev.22" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Arkanis.Aspire.Hosting.Extensions.Kubernetes" Version="1.0.0-dev.22" />
                    
Directory.Packages.props
<PackageReference Include="Arkanis.Aspire.Hosting.Extensions.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 Arkanis.Aspire.Hosting.Extensions.Kubernetes --version 1.0.0-dev.22
                    
#r "nuget: Arkanis.Aspire.Hosting.Extensions.Kubernetes, 1.0.0-dev.22"
                    
#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 Arkanis.Aspire.Hosting.Extensions.Kubernetes@1.0.0-dev.22
                    
#: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=Arkanis.Aspire.Hosting.Extensions.Kubernetes&version=1.0.0-dev.22&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=Arkanis.Aspire.Hosting.Extensions.Kubernetes&version=1.0.0-dev.22&prerelease
                    
Install as a Cake Tool

Arkanis.Aspire.Hosting.Extensions.Kubernetes

NuGet License

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.

  • Arkanis.Aspire.Hosting.Extensions.Kubernetes.ExternalSecrets adds External Secrets Operator helpers.
  • Arkanis.Aspire.Hosting.Extensions.Kubernetes.Tailscale adds Tailscale Kubernetes Operator helpers.
  • Arkanis.Aspire.Hosting.Extensions.Kubernetes.CloudNativePostgres adds CloudNativePG helpers.

Repository

Source, issues, and release workflow details are available at https://github.com/ArkanisCorporation/Aspire.Hosting.Extensions.Kubernetes.

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 (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
Loading failed