feat: CommunityToolkit.Aspire.Hosting.K3s — k3s Kubernetes cluster hosting integration

.gitignore

@@ -23,6 +23,8 @@ examples/perl/**/local/*
 **cpanfile.snapshot
 **/.aspire/modules/
 **/*.AppHost.TypeScript/nuget.config
+
+**/.k3s/
 tsconfig.apphost.json
 .ngrok
 bun.lock
@@ -34,4 +36,7 @@ apphost.js
 affected-tests
 examples/**/.modules/*
 examples/**/.aspire/modules/*
-examples/**/.aspire/integrations/*
+examples/**/.aspire/integrations/*
+playground/**/.modules/*
+playground/**/.aspire/modules/*
+playground/**/.aspire/integrations/*

CommunityToolkit.Aspire.slnx

@@ -67,6 +67,9 @@
     <Project Path="examples/java/CommunityToolkit.Aspire.Hosting.Java.ServiceDefaults/CommunityToolkit.Aspire.Hosting.Java.ServiceDefaults.csproj" />
     <Project Path="examples/java/CommunityToolkit.Aspire.Hosting.Java.WebApp/CommunityToolkit.Aspire.Hosting.Java.WebApp.csproj" />
   </Folder>
+  <Folder Name="/examples/k3s/">
+    <Project Path="examples/k3s/CommunityToolkit.Aspire.Hosting.K3s.AppHost/CommunityToolkit.Aspire.Hosting.K3s.AppHost.csproj" />
+  </Folder>
   <Folder Name="/examples/k6/">
     <Project Path="examples/k6/CommunityToolkit.Aspire.Hosting.k6.ApiService/CommunityToolkit.Aspire.Hosting.k6.ApiService.csproj" />
     <Project Path="examples/k6/CommunityToolkit.Aspire.Hosting.k6.AppHost/CommunityToolkit.Aspire.Hosting.k6.AppHost.csproj" />
@@ -241,6 +244,7 @@
     <Project Path="src/CommunityToolkit.Aspire.Hosting.Golang/CommunityToolkit.Aspire.Hosting.Golang.csproj" />
     <Project Path="src/CommunityToolkit.Aspire.Hosting.Java/CommunityToolkit.Aspire.Hosting.Java.csproj" />
     <Project Path="src/CommunityToolkit.Aspire.Hosting.JavaScript.Extensions/CommunityToolkit.Aspire.Hosting.JavaScript.Extensions.csproj" />
+    <Project Path="src/CommunityToolkit.Aspire.Hosting.K3s/CommunityToolkit.Aspire.Hosting.K3s.csproj" />
     <Project Path="src/CommunityToolkit.Aspire.Hosting.k6/CommunityToolkit.Aspire.Hosting.k6.csproj" />
     <Project Path="src/CommunityToolkit.Aspire.Hosting.KurrentDB/CommunityToolkit.Aspire.Hosting.KurrentDB.csproj" />
     <Project Path="src/CommunityToolkit.Aspire.Hosting.LavinMQ/CommunityToolkit.Aspire.Hosting.LavinMQ.csproj" />
@@ -312,6 +316,7 @@
     <Project Path="tests/CommunityToolkit.Aspire.Hosting.GoFeatureFlag.Tests/CommunityToolkit.Aspire.Hosting.GoFeatureFlag.Tests.csproj" />
     <Project Path="tests/CommunityToolkit.Aspire.Hosting.Java.Tests/CommunityToolkit.Aspire.Hosting.Java.Tests.csproj" />
     <Project Path="tests/CommunityToolkit.Aspire.Hosting.JavaScript.Extensions.Tests/CommunityToolkit.Aspire.Hosting.JavaScript.Extensions.Tests.csproj" />
+    <Project Path="tests/CommunityToolkit.Aspire.Hosting.K3s.Tests/CommunityToolkit.Aspire.Hosting.K3s.Tests.csproj" />
     <Project Path="tests/CommunityToolkit.Aspire.Hosting.k6.Tests/CommunityToolkit.Aspire.Hosting.k6.Tests.csproj" />
     <Project Path="tests/CommunityToolkit.Aspire.Hosting.Keycloak.Extensions.Tests/CommunityToolkit.Aspire.Hosting.Keycloak.Extensions.Tests.csproj" />
     <Project Path="tests/CommunityToolkit.Aspire.Hosting.KurrentDB.Tests/CommunityToolkit.Aspire.Hosting.KurrentDB.Tests.csproj" />

Directory.Packages.props

@@ -103,6 +103,7 @@
     <PackageVersion Include="Microsoft.PowerShell.SDK" Version="7.4.10" />
     <PackageVersion Include="ModelContextProtocol" Version="0.4.0-preview.3" />
     <PackageVersion Include="ModelContextProtocol.AspNetCore" Version="0.4.0-preview.3" />
+    <PackageVersion Include="KubernetesClient" Version="19.0.2" />
     <PackageVersion Include="KurrentDB.Client" Version="1.2.0" />
     <PackageVersion Include="SSH.NET" Version="2025.1.0" />
   </ItemGroup>

README.md

@@ -16,6 +16,7 @@ This repository contains the source code for the Aspire Community Toolkit, a col
 | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | - **Learn More**: [`Hosting.Golang`][golang-integration-docs] <br /> - Stable 📦: [![CommunityToolkit.Aspire.Hosting.Golang][golang-shields]][golang-nuget] <br /> - Preview 📦: [![CommunityToolkit.Aspire.Hosting.Golang][golang-shields-preview]][golang-nuget-preview]                                                                                                                   | A hosting integration Golang apps.                                                                                                                                          |
 | - **Learn More**: [`Hosting.Java`][java-integration-docs] <br /> - Stable 📦: [![CommunityToolkit.Aspire.Hosting.Java][java-shields]][java-nuget] <br /> - Preview 📦: [![CommunityToolkit.Aspire.Hosting.Java][java-shields-preview]][java-nuget-preview]                                                                                                                                   | An integration for running Java code in Aspire either using the local JDK or using a container.                                                                        |
+| - **Learn More**: [`Hosting.K3s`][k3s-integration-docs] <br /> - Stable 📦: [![CommunityToolkit.Aspire.Hosting.K3s][k3s-shields]][k3s-nuget] <br /> - Preview 📦: [![CommunityToolkit.Aspire.Hosting.K3s][k3s-shields-preview]][k3s-nuget-preview]                                                                                                                                           | An Aspire hosting integration for [k3s](https://k3s.io/), a lightweight Kubernetes distribution by Rancher.                                                                 |
 | - **Learn More**: [`Hosting.NodeJS.Extensions`][nodejs-ext-integration-docs] <br /> - Stable 📦: [![CommunityToolkit.Aspire.NodeJS.Extensions][nodejs-ext-shields]][nodejs-ext-nuget] <br /> - Preview 📦: [![CommunityToolkit.Aspire.Hosting.JavaScript.Extensions][nodejs-ext-shields-preview]][nodejs-ext-nuget-preview]                                                                  | An integration that contains some additional extensions for running Node.js applications                                                                                    |
 | - **Learn More**: [`Hosting.Ollama`][ollama-integration-docs] <br /> - Stable 📦: [![CommunityToolkit.Aspire.Hosting.Ollama][ollama-shields]][ollama-nuget] <br /> - Preview 📦: [![CommunityToolkit.Aspire.Hosting.Ollama][ollama-shields-preview]][ollama-nuget-preview]                                                                                                                   | An Aspire hosting integration leveraging the [Ollama](https://ollama.com) container with support for downloading a model on startup.                                        |
 | - **Learn More**: [`OllamaSharp`][ollama-integration-docs] <br /> - Stable 📦: [![CommunityToolkit.Aspire.OllamaSharp][ollamasharp-shields]][ollamasharp-nuget] <br /> - Preview 📦: [![CommunityToolkit.Aspire.OllamaSharp][ollamasharp-shields-preview]][ollamasharp-nuget-preview]                                                                                                        | An Aspire client integration for the [OllamaSharp](https://github.com/awaescher/OllamaSharp) package.                                                                       |
@@ -109,6 +110,11 @@ This project is supported by the [.NET Foundation](https://dotnetfoundation.org)
 [java-nuget]: https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Java/
 [java-shields-preview]: https://img.shields.io/nuget/vpre/CommunityToolkit.Aspire.Hosting.Java?label=nuget%20(preview)
 [java-nuget-preview]: https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Java/absoluteLatest
+[k3s-integration-docs]: https://learn.microsoft.com/dotnet/aspire/community-toolkit/hosting-k3s
+[k3s-shields]: https://img.shields.io/nuget/v/CommunityToolkit.Aspire.Hosting.K3s
+[k3s-nuget]: https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.K3s/
+[k3s-shields-preview]: https://img.shields.io/nuget/vpre/CommunityToolkit.Aspire.Hosting.K3s?label=nuget%20(preview)
+[k3s-nuget-preview]: https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.K3s/absoluteLatest
 [nodejs-ext-integration-docs]: https://learn.microsoft.com/dotnet/aspire/community-toolkit/hosting-nodejs-extensions
 [nodejs-ext-shields]: https://img.shields.io/nuget/v/CommunityToolkit.Aspire.Hosting.JavaScript.Extensions
 [nodejs-ext-nuget]: https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.JavaScript.Extensions/

examples/k3s/CommunityToolkit.Aspire.Hosting.K3s.AppHost.Go/apphost.go

@@ -0,0 +1,131 @@
+// Aspire Go AppHost
+// For more information, see: https://aspire.dev
+
+package main
+
+import (
+	"apphost/modules/aspire"
+	"log"
+)
+
+func main() {
+	builder, err := aspire.CreateBuilder()
+	if err != nil {
+		log.Fatal(aspire.FormatError(err))
+	}
+
+	// ── Runtime path (actually executed) ─────────────────────────────────────────
+	// Single-node cluster: installs podinfo via Helm and exposes the service as an
+	// Aspire endpoint — validating the full add/build/run path. No agent nodes so
+	// the CI runner has enough CPU/RAM to schedule pods. withAgentCount is covered
+	// by the compile-time section below.
+	cluster := builder.AddK3sCluster("k8s")
+
+	_ = cluster.ApiEndpoint()
+
+	setupPodinfo := cluster.AddHelmRelease("podinfo", "podinfo", &aspire.AddHelmReleaseOptions{
+		Repo:      aspire.StringPtr("https://stefanprodan.github.io/podinfo"),
+		Version:   aspire.StringPtr("6.7.1"),
+		Namespace: aspire.StringPtr("podinfo"),
+	})
+
+	cluster.AddServiceEndpoint("podinfo-web", "podinfo", 9898, &aspire.AddServiceEndpointOptions{
+		Namespace: aspire.StringPtr("podinfo"),
+	}).WaitForCompletion(setupPodinfo)
+
+	// ── Compile-time coverage ─────────────────────────────────────────────────────
+	// Guards with false so these are type-checked but never executed.
+	// Covers the full exported API surface without requiring Docker/k3s in CI.
+	const includeCompileOnlyScenarios = false
+
+	if (includeCompileOnlyScenarios) {
+		// ── Cluster configuration ────────────────────────────────────────────────
+		// All K3sClusterOptions are now available as fluent builder methods.
+		configuredCluster := builder.AddK3sCluster("k8s-configured", 
+			&aspire.AddK3sClusterOptions{
+				ApiServerPort: aspire.Float64Ptr(6443),
+				AgentCount: aspire.Float64Ptr(2),
+			}).
+			WithK3sVersion("v1.32.3-k3s1").
+			WithPodSubnet("10.42.0.0/16").
+			WithServiceSubnet("10.43.0.0/16").
+			WithDisabledComponent("traefik").
+			WithExtraArg("--write-kubeconfig-mode=644").
+			WithDataVolume(&aspire.WithDataVolumeOptions{ Name: aspire.StringPtr("k8s-data") }).
+			WithHelmImage(&aspire.WithHelmImageOptions{ Tag: aspire.StringPtr("3.18.0") }).
+			WithKubectlImage(&aspire.WithKubectlImageOptions{ Tag: aspire.StringPtr("1.37.0") }).
+			WithLifetime(aspire.ContainerLifetimePersistent)
+
+		_ = configuredCluster.ApiEndpoint()
+
+		// ── Helm release — podinfo ────────────────────────────────────────────────
+		podinfo := configuredCluster.AddHelmRelease("podinfo", "podinfo", &aspire.AddHelmReleaseOptions{
+			Repo:      aspire.StringPtr("https://stefanprodan.github.io/podinfo"),
+			Version:   aspire.StringPtr("6.7.1"),
+			Namespace: aspire.StringPtr("podinfo"),
+		})
+
+		_ = podinfo.Parent()
+
+		_, _ = podinfo.ReleaseName()
+		_, _ = podinfo.Namespace()
+
+		// ── K8s manifest — plain YAML file ───────────────────────────────────────
+		appConfig := configuredCluster.
+			AddK8sManifest("app-config", "./k8s/app-config.yaml").
+			WaitForCompletion(podinfo)
+
+		_ = appConfig.Parent()
+		_, _ = appConfig.Path()
+
+		// ── K8s manifest — Kustomize overlay ─────────────────────────────────────
+		// Auto-detected because the directory contains kustomization.yaml.
+		monitoringConfig := configuredCluster.
+			AddK8sManifest("monitoring-config", "./k8s/monitoring").
+			WaitForCompletion(podinfo).
+			WaitForCompletion(appConfig)
+
+		_ = monitoringConfig.Parent()
+
+		// ── Service endpoint ─────────────────────────────────────────────────────
+		//   • Host processes receive  services__podinfo-web__url=http://localhost:{port}
+		//   • DCP containers receive  services__podinfo-web__url=http://host.docker.internal:{port}
+		podinfoWeb := configuredCluster.
+			AddServiceEndpoint("podinfo-web", "podinfo", 9898, &aspire.AddServiceEndpointOptions{
+				Namespace: aspire.StringPtr("podinfo"),
+			}).
+			WaitForCompletion(podinfo).
+			WaitForCompletion(monitoringConfig)
+
+		_ = podinfoWeb.Parent()
+		_, _ = podinfoWeb.ServiceName()
+		_, _ = podinfoWeb.ServicePort()
+		_, _ = podinfoWeb.Namespace()
+		_, _ = podinfoWeb.HostPort()
+
+		// ── WithReference — cluster kubeconfig injection ──────────────────────────
+		//   • Project/executable: KUBECONFIG=<host>/.k3s/k8s/local/kubeconfig.yaml
+		//   • Container: KUBECONFIG=/tmp/k3s-kubeconfig.yaml + bind-mount
+		_ = builder.
+			AddProject("operator", "../WidgetOperator/WidgetOperator.csproj").
+			WithReference(configuredCluster)
+
+		_ = builder.
+			AddContainer("sidecar", "myorg/sidecar").
+			WithReference(configuredCluster)
+
+		// ── WithReference — service endpoint URL injection ────────────────────────
+
+		_ = builder.
+			AddProject("api", "../WidgetApi/WidgetApi.csproj").
+			WithReference(podinfoWeb)
+	}
+
+	app, err := builder.Build()
+	if err != nil {
+		log.Fatal(aspire.FormatError(err))
+	}
+	if err := app.Run(); err != nil {
+		log.Fatal(aspire.FormatError(err))
+	}
+}

examples/k3s/CommunityToolkit.Aspire.Hosting.K3s.AppHost.Go/aspire.config.json

@@ -0,0 +1,15 @@
+{
+  "appHost": {
+    "path": "apphost.go",
+    "language": "go"
+  },
+  "features.experimentalPolyglot": {
+    "go": "true"
+  },
+  "sdk": {
+    "version": "13.4.3"
+  },
+  "packages": {
+    "CommunityToolkit.Aspire.Hosting.K3s": "../../../src/CommunityToolkit.Aspire.Hosting.K3s/CommunityToolkit.Aspire.Hosting.K3s.csproj"
+  }
+}

examples/k3s/CommunityToolkit.Aspire.Hosting.K3s.AppHost.Go/go.mod

@@ -0,0 +1,7 @@
+module apphost
+
+go 1.26
+
+require apphost/modules/aspire v0.0.0
+
+replace apphost/modules/aspire => ./.aspire/modules