feat: CommunityToolkit.Aspire.Hosting.K3s — k3s Kubernetes cluster hosting integration #1322
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,14 @@ | ||
| <Project Sdk="Aspire.AppHost.Sdk/13.3.0"> | ||
|
|
||
| <PropertyGroup> | ||
| <OutputType>Exe</OutputType> | ||
| <ImplicitUsings>enable</ImplicitUsings> | ||
| <Nullable>enable</Nullable> | ||
| <IsAspireHost>true</IsAspireHost> | ||
| </PropertyGroup> | ||
|
|
||
| <ItemGroup> | ||
| <ProjectReference Include="..\..\..\src\CommunityToolkit.Aspire.Hosting.K3s\CommunityToolkit.Aspire.Hosting.K3s.csproj" IsAspireProjectResource="false" /> | ||
| </ItemGroup> | ||
|
|
||
| </Project> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,53 @@ | ||
| // K3s hosting example | ||
| // ────────────────────────────────────────────────────────────────────────────── | ||
| // Prerequisites (host machine): | ||
| // • A container runtime that supports privileged Linux containers: | ||
| // - Linux: Docker Engine 20.10+ or rootful Podman 4.0+ | ||
| // - macOS / Windows: Docker Desktop (WSL2 / Hyper-V) | ||
| // No host-side helm or kubectl required — both run as containers. | ||
| // | ||
| // What this demonstrates: | ||
| // 1. A k3s cluster starts inside a Docker container. | ||
| // 2. app-config ConfigMap applied via AddK8sManifest (plain YAML file). | ||
| // 3. monitoring-config ConfigMap applied via AddK8sManifest (Kustomize overlay — | ||
| // auto-detected from kustomization.yaml; adds namespace + common labels). | ||
| // 4. podinfo installed via Helm, waiting for both manifests first. | ||
| // 5. A K3sServiceEndpointResource exposes the podinfo service: | ||
| // • Host processes reach it at http://localhost:{port} | ||
| // • DCP-network containers reach it at http://host.docker.internal:{port} | ||
| // 6. WithDataVolume keeps the cluster state alive across AppHost restarts. | ||
| // ────────────────────────────────────────────────────────────────────────────── | ||
|
|
||
| var builder = DistributedApplication.CreateBuilder(args); | ||
|
|
||
| var cluster = builder | ||
| .AddK3sCluster("k8s") | ||
| .WithDataVolume() | ||
| .WithLifetime(ContainerLifetime.Persistent); | ||
|
|
||
| var podinfo = cluster.AddHelmRelease( | ||
| name: "podinfo", | ||
| chart: "podinfo", | ||
| repo: "https://stefanprodan.github.io/podinfo", | ||
| version: "6.7.1", | ||
| @namespace: "podinfo"); | ||
|
|
||
| // Plain YAML file — a ConfigMap in the default namespace. | ||
| var appConfig = cluster.AddK8sManifest("app-config", "./k8s/app-config.yaml") | ||
| .WaitForCompletion(podinfo); | ||
|
|
||
| // Kustomize overlay — auto-detected because the directory contains kustomization.yaml. | ||
| // Kustomize injects the 'monitoring' namespace and common labels into every resource | ||
| // without modifying the source files. | ||
| var monitoringConfig = cluster.AddK8sManifest("monitoring-config", "./k8s/monitoring") | ||
| .WaitForCompletion(podinfo) | ||
| .WaitForCompletion(appConfig); | ||
|
|
||
| // Expose the podinfo service as an Aspire endpoint resource. | ||
| // WaitForCompletion waits for the helm install container to exit with code 0 | ||
| // before starting the port-forward — no NodePort required. | ||
| cluster.AddServiceEndpoint("podinfo-web", "podinfo", servicePort: 9898, @namespace: "podinfo") | ||
| .WaitForCompletion(podinfo) | ||
| .WaitForCompletion(monitoringConfig); | ||
|
|
||
| builder.Build().Run(); |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,30 @@ | ||
| { | ||
| "$schema": "https://json.schemastore.org/launchsettings.json", | ||
| "profiles": { | ||
| "https": { | ||
| "commandName": "Project", | ||
| "dotnetRunMessages": true, | ||
| "launchBrowser": true, | ||
| "applicationUrl": "https://localhost:53201;http://localhost:53202", | ||
| "environmentVariables": { | ||
| "ASPNETCORE_ENVIRONMENT": "Development", | ||
| "DOTNET_ENVIRONMENT": "Development", | ||
| "DOTNET_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:53203", | ||
| "DOTNET_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:53204" | ||
| } | ||
| }, | ||
| "http": { | ||
| "commandName": "Project", | ||
| "dotnetRunMessages": true, | ||
| "launchBrowser": true, | ||
| "applicationUrl": "http://localhost:53202", | ||
| "environmentVariables": { | ||
| "ASPNETCORE_ENVIRONMENT": "Development", | ||
| "DOTNET_ENVIRONMENT": "Development", | ||
| "ASPIRE_ALLOW_UNSECURED_TRANSPORT": "true", | ||
| "DOTNET_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:53205", | ||
| "DOTNET_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:53206" | ||
| } | ||
| } | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,10 @@ | ||
| apiVersion: v1 | ||
| kind: ConfigMap | ||
| metadata: | ||
| name: app-config | ||
| namespace: default | ||
| data: | ||
| environment: development | ||
| log-level: info | ||
| # podinfo endpoint — matches the AddServiceEndpoint name in Program.cs | ||
| api-endpoint: http://podinfo:9898 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| apiVersion: kustomize.config.k8s.io/v1beta1 | ||
| kind: Kustomization | ||
|
|
||
| # Kustomize places every resource in this namespace. | ||
| namespace: default | ||
|
|
||
| # Common labels applied to all resources in this overlay. | ||
| labels: | ||
| - includeSelectors: true | ||
| pairs: | ||
| app.kubernetes.io/managed-by: aspire | ||
| environment: development | ||
|
|
||
|
|
||
| resources: | ||
| - monitoring-config.yaml |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| apiVersion: v1 | ||
| kind: ConfigMap | ||
| metadata: | ||
| name: monitoring-config | ||
| data: | ||
| scrape-interval: 30s | ||
| retention: 7d | ||
| log-level: info |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,82 @@ | ||
| import { createBuilder, ContainerLifetime } from './.modules/aspire.js'; | ||
|
|
||
| const builder = await createBuilder(); | ||
|
|
||
| // ── Runtime path (actually executed) ───────────────────────────────────────── | ||
| // Minimal cluster startup — validates that the core add/build/run path works. | ||
| const cluster = builder.addK3sCluster('k8s'); | ||
| const clusterResource = await cluster; | ||
| const _apiEndpoint = await clusterResource.apiEndpoint.get(); | ||
|
|
||
| // ── 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 ──────────────────────────────────────────────── | ||
| const configuredCluster = builder.addK3sCluster('k8s-configured') | ||
| .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({ name: 'k8s-data' }) | ||
| .withLifetime(ContainerLifetime.Persistent); | ||
|
|
||
| const configuredClusterResource = await configuredCluster; | ||
| const _configuredApiEndpoint = await configuredClusterResource.apiEndpoint.get(); | ||
|
|
||
| // ── Helm release ───────────────────────────────────────────────────────── | ||
| const argocd = configuredCluster.addHelmRelease('argocd', 'argo-cd', { | ||
| repo: 'https://argoproj.github.io/argo-helm', | ||
| version: '7.8.0', | ||
| namespace: 'argocd', | ||
| }) | ||
| .withHelmValue('server.insecure', 'true') | ||
| .withHelmValuesFile('./deploy/argocd-values.yaml'); | ||
|
|
||
| const argocdResource = await argocd; | ||
| const _argocdParent = await argocdResource.parent.get(); | ||
| const _argocdReleaseName = await argocdResource.releaseName.get(); | ||
| const _argocdNamespace = await argocdResource.namespace.get(); | ||
|
|
||
| // ── K8s manifest / Kustomize overlay ───────────────────────────────────── | ||
| const widgetCrd = configuredCluster.addK8sManifest('widget-crd', './k8s/crds/'); | ||
|
|
||
| const widgetCrdResource = await widgetCrd; | ||
| const _crdParent = await widgetCrdResource.parent.get(); | ||
| const _crdPath = await widgetCrdResource.path.get(); | ||
|
|
||
| // ── Service endpoint ───────────────────────────────────────────────────── | ||
| const ui = configuredCluster.addServiceEndpoint('argocd-ui', 'argocd-server', 443, { | ||
| namespace: 'argocd', | ||
| }); | ||
|
|
||
| const uiResource = await ui; | ||
| const _uiParent = await uiResource.parent.get(); | ||
| const _uiServiceName = await uiResource.serviceName.get(); | ||
| const _uiServicePort = await uiResource.servicePort.get(); | ||
| const _uiNamespace = await uiResource.namespace.get(); | ||
| const _uiHostPort = await uiResource.hostPort.get(); | ||
|
|
||
| // ── WithReference — cluster kubeconfig injection ────────────────────────── | ||
| // Project: receives KUBECONFIG=.../.k3s/k8s/local/kubeconfig.yaml | ||
| const _projectRef = builder | ||
| .addProject('operator', { projectPath: '../WidgetOperator/WidgetOperator.csproj' }) | ||
| .withReference(configuredCluster); | ||
|
|
||
| // Container: receives a bind-mounted kubeconfig and KUBECONFIG=/var/k3s/kubeconfig.yaml | ||
| const _containerRef = builder | ||
| .addContainer('sidecar', 'myorg/sidecar') | ||
| .withReference(configuredCluster); | ||
|
|
||
| // ── WithReference — service endpoint URL injection ──────────────────────── | ||
| // Host: receives services__argocd-ui__url=https://localhost:{port} | ||
| const _endpointRef = builder | ||
| .addProject('api', { projectPath: '../WidgetApi/WidgetApi.csproj' }) | ||
| .withReference(ui); | ||
| } | ||
|
|
||
| await builder.build().run(); |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,26 @@ | ||
| { | ||
| "appHost": { | ||
| "path": "apphost.ts", | ||
| "language": "typescript/nodejs" | ||
| }, | ||
| "profiles": { | ||
| "https": { | ||
| "applicationUrl": "https://localhost:17149;http://localhost:15243", | ||
| "environmentVariables": { | ||
| "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:21065", | ||
| "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:22170" | ||
| } | ||
| }, | ||
| "http": { | ||
| "applicationUrl": "http://localhost:15243", | ||
| "environmentVariables": { | ||
| "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:19027", | ||
| "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:20141", | ||
| "ASPIRE_ALLOW_UNSECURED_TRANSPORT": "true" | ||
| } | ||
| } | ||
| }, | ||
| "packages": { | ||
| "CommunityToolkit.Aspire.Hosting.K3s": "" | ||
|
Contributor
There was a problem hiding this comment. Hey @sebastienros, is this correct? I always forget... |
||
| } | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| { | ||
| "name": "validationapphost", | ||
| "version": "1.0.0", | ||
| "type": "module", | ||
| "scripts": { | ||
| "start": "aspire run", | ||
| "build": "tsc", | ||
| "dev": "tsc --watch" | ||
| }, | ||
| "dependencies": { | ||
| "vscode-jsonrpc": "^8.2.0" | ||
| }, | ||
| "devDependencies": { | ||
| "@types/node": "^20.0.0", | ||
| "nodemon": "^3.1.11", | ||
| "tsx": "^4.19.0", | ||
| "typescript": "^5.3.0" | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| { | ||
| "compilerOptions": { | ||
| "target": "ES2022", | ||
| "module": "NodeNext", | ||
| "moduleResolution": "NodeNext", | ||
| "esModuleInterop": true, | ||
| "forceConsistentCasingInFileNames": true, | ||
| "strict": true, | ||
| "skipLibCheck": true, | ||
| "outDir": "./dist", | ||
| "rootDir": "." | ||
| }, | ||
| "include": [ | ||
| "apphost.ts", | ||
| ".modules/**/*.ts" | ||
| ], | ||
| "exclude": [ | ||
| "node_modules" | ||
| ] | ||
| } |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is the name of this file common, or is this a play on words leaning on the
kfrom Kubernetes?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yes, check here https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/