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

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.

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",
    kubernetes,
    "../fallback-pages");

api.WithKubernetesIngress(ingress => ingress
    .AtHost("api.example.test")
    .UsingIngressClass("traefik")
    .InKubernetesEnvironment(kubernetes)
    .WithTraefikErrorPageFallback(fallbackPages, "apps", fallback => fallback
        .WithMiddlewareName("api-fallback-errors")
        .HandlingStatus("502", "503", "504")
        .Serving("/{status}.html")
        .ForwardingNoRequestHeaders()));

The fallback Service and static file container are owned by the library helper. The consumer provides the page source paths to mount into the container. Use the builder overload when you need to change the image, endpoint, port, or mounted destination path. The integrated overload adds the Traefik Middleware custom resource to that fallback service's Kubernetes AdditionalResources. Use TraefikErrorsMiddleware.Create(...) directly when you need to add the custom resource yourself inside PublishAsKubernetesService(...). 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.WithKubernetesIngress("api", ingress => ingress
    .WithConfigurationFrom(builder.Configuration)
    .InKubernetesEnvironment(kubernetes));

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 Deployment metadata receives reloader.stakater.com/auto: "true" so Stakater Reloader can roll the workload after the referenced Secret changes.

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.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.