Azure Kubernetes Service (AKS) integration

This article is the reference for the Aspire Azure Kubernetes Service (AKS) hosting integration. It enumerates the AppHost APIs — with examples for both AppHost.cs and apphost.mts — that you use to model an AKS environment and its node pools in your AppHost project.

The Aspire AKS hosting integration enables you to deploy your Aspire application to Azure Kubernetes Service (AKS) with full provisioning. Aspire creates the AKS cluster, Azure Container Registry (ACR), managed identity, and any Azure resources your app depends on — all from your AppHost definition.

Hosting integration

To get started with the Aspire AKS hosting integration, install the 📦 Aspire.Hosting.Azure.Kubernetes NuGet package in the AppHost project:

aspire add azure-kubernetes

The Aspire CLI is interactive, be sure to select the appropriate search result when prompted:

Select an integration to add:

> azure-kubernetes (Aspire.Hosting.Azure.Kubernetes)
> Other results listed as selectable options...

#:package Aspire.Hosting.Azure.Kubernetes@*

<PackageReference Include="Aspire.Hosting.Azure.Kubernetes" Version="*" />

Add AKS environment

After installing the package, add an AKS environment to your AppHost using AddAzureKubernetesEnvironment:

TypeScript
C#

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const aks = await builder.addAzureKubernetesEnvironment('aks');

const api = await builder
    .addNodeApp('api', './api', 'src/index.ts')
    .withHttpEndpoint({ env: 'PORT' })
    .withExternalHttpEndpoints();

await builder.build().run();

var builder = DistributedApplication.CreateBuilder(args);

var aks = builder.AddAzureKubernetesEnvironment("aks");

var api = builder.AddProject<Projects.MyApi>("api");

builder.Build().Run();

When an AKS environment is present, all compute resources are automatically deployed to AKS — no additional opt-in is required.

Configure the system node pool

Customize the system node pool VM size and scaling using WithSystemNodePool:

TypeScript
C#

const aks = await builder.addAzureKubernetesEnvironment('aks');
await aks.withSystemNodePool('Standard_D4s_v5', 1, 5);

builder.AddAzureKubernetesEnvironment("aks")
    .WithSystemNodePool("Standard_D4s_v5", minCount: 1, maxCount: 5);

Add node pools

Add additional node pools for workload isolation, GPU workloads, or specialized hardware requirements using AddNodePool:

TypeScript
C#

const aks = await builder.addAzureKubernetesEnvironment('aks');
const gpuPool = await aks.addNodePool('gpupool', 'Standard_NC6s_v3', 0, 5);

const worker = await builder.addContainer('ml-worker', 'my-ml-image');
await worker.withNodePool(gpuPool);

var aks = builder.AddAzureKubernetesEnvironment("aks");
var gpuPool = aks.AddNodePool("gpupool", "Standard_NC6s_v3", minCount: 0, maxCount: 5);

builder.AddContainer("ml-worker", "my-ml-image")
    .WithNodePool(gpuPool);

Add a persistent volume

Call AddPersistentVolume directly on the AKS environment to model durable storage without reaching through to the underlying Kubernetes integration. The call forwards to the AKS environment’s Kubernetes publisher, so the same configuration methods and workload-binding APIs described in Persistent volumes on Kubernetes apply:

TypeScript
C#

const aks = await builder.addAzureKubernetesEnvironment("aks");

const data = await aks.addPersistentVolume("data");
await data.withCapacity("20Gi");

const api = await builder
    .addNodeApp('api', './api', 'src/index.ts')
    .withHttpEndpoint({ env: 'PORT' })
    .withExternalHttpEndpoints()
    .withKubernetesPersistentVolumeMount(data, "/data");

var aks = builder.AddAzureKubernetesEnvironment("aks");

var data = aks.AddPersistentVolume("data")
    .WithCapacity("20Gi");

builder.AddProject<Projects.Api>("api")
    .WithPersistentVolume(data, "/data");

When you don’t set a storage class, the generated claim omits spec.storageClassName so the cluster’s default storage class provisions the disk. A standard AKS cluster dynamically provisions an Azure managed disk for such claims. To request Premium SSD storage explicitly, call WithStorageClass("managed-csi-premium") in C# or withStorageClass('managed-csi-premium') in TypeScript.

For the full set of configuration methods (storage class, capacity, access modes, annotations) and how to bind volumes to workloads, see Persistent volumes on Kubernetes.

Publishing and deployment

The AKS integration supports both aspire publish (generate Helm chart and Bicep artifacts) and aspire deploy (provision Azure infrastructure and deploy in a single command).

For a complete end-to-end walkthrough, see Deploy to AKS.