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:

C#
TypeScript

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

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();

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:

C#
TypeScript

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

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

Add node pools

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

C#
TypeScript

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);

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);

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.