AzureKubernetesEnvironmentExtensions Methods

Docs/Reference/Search C# APIs/Aspire.Hosting.Azure.Kubernetes/AzureKubernetesEnvironmentExtensions/Methods

Methods

Docs Reference Search C# APIs Aspire.Hosting.Azure.Kubernetes AzureKubernetesEnvironmentExtensions Methods

ClassMethods8 members

Provides extension methods for adding Azure Kubernetes Service (AKS) environments to the application model.

AddAzureKubernetesEnvironment(IDistributedApplicationBuilder, string)extensionIResourceBuilder<AzureKubernetesEnvironmentResource>

Adds an Azure Kubernetes Service (AKS) environment to the distributed application. This provisions an AKS cluster and configures it as a Kubernetes compute environment.

public static class AzureKubernetesEnvironmentExtensions
{
    public static IResourceBuilder<AzureKubernetesEnvironmentResource> AddAzureKubernetesEnvironment(
        this IDistributedApplicationBuilder builder,
        string name)
    {
        // ...
    }
}

AzureKubernetesEnvironmentExtensions.cs#L54-L134

Parameters

builderIDistributedApplicationBuilderThe Hosting.IDistributedApplicationBuilder.

namestringThe name of the AKS environment resource.

Returns

IResourceBuilder<AzureKubernetesEnvironmentResource>A reference to the ApplicationModel.IResourceBuilder`1.

Remarks

This method internally creates a Kubernetes environment for Helm-based deployment and provisions an AKS cluster via Azure Bicep. It combines the functionality of AddKubernetesEnvironment with Azure-specific provisioning.

Examples

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

ATS export

Available to Polyglot AppHosts through the Aspire Type System.

AddLoadBalancer(IResourceBuilder<AzureKubernetesEnvironmentResource>, string, IResourceBuilder<AzureSubnetResource>)extensionIResourceBuilder<AzureKubernetesLoadBalancerResource>

Adds an Azure Application Gateway for Containers (AGC) ApplicationLoadBalancer to this AKS environment, bound to the supplied delegated subnet. Returns a resource builder that can be passed to gateway.WithLoadBalancer(lb) / ingress.WithLoadBalancer(lb) to route traffic through this load balancer.

public static class AzureKubernetesEnvironmentExtensions
{
    public static IResourceBuilder<AzureKubernetesLoadBalancerResource> AddLoadBalancer(
        this IResourceBuilder<AzureKubernetesEnvironmentResource> builder,
        string name,
        IResourceBuilder<AzureSubnetResource> subnet)
    {
        // ...
    }
}

AzureKubernetesEnvironmentExtensions.cs#L419-L488

Parameters

builderIResourceBuilder<AzureKubernetesEnvironmentResource>The AKS environment resource builder.

namestringThe name of the load balancer resource. Used to derive the in-cluster ApplicationLoadBalancer name ( alb-{name}) referenced by gateway/ingress annotations.

subnetIResourceBuilder<AzureSubnetResource>A subnet that will be associated with the AGC ALB. The subnet is automatically delegated to Microsoft.ServiceNetworking/trafficControllers; this is required by AGC and is idempotent across multiple AzureKubernetesEnvironmentExtensions.AddLoadBalancer calls against the same subnet.

Returns

IResourceBuilder<AzureKubernetesLoadBalancerResource>A reference to the ApplicationModel.IResourceBuilder`1.

Remarks

Each AGC ApplicationLoadBalancer caps at 5 frontends, so applications that need more should call AddLoadBalancer multiple times (each call may use the same or a different subnet) and pin gateways/ingresses to specific load balancers via AzureKubernetesIngressExtensions.WithLoadBalancer.

Calling this method opts the AKS cluster into the managed Gateway API installation ( ingressProfile.gatewayAPI.installation = 'Standard') and the AGC ALB controller add-on ( ingressProfile.applicationLoadBalancer.enabled = true). Both properties only exist in preview AKS Bicep API versions (oldest covering both: 2025-09-02-preview), so this implicitly bumps the cluster's emitted API version. Subscriptions/regions where the AKS preview features Microsoft.ContainerService/AKSGatewayAPIPreview and Microsoft.ContainerService/AKSAppGatewayContainersPreview are not registered will see deployment failures.

After provisioning, a per-LB pipeline step ( apply-alb-crd-{name}) waits for the azure-alb-external GatewayClass to appear in the cluster and then kubectl apply s the ApplicationLoadBalancer custom resource pointing at the supplied subnet.

Examples

var vnet = builder.AddAzureVirtualNetwork("vnet", "10.0.0.0/16");
var aksSubnet = vnet.AddSubnet("aks", "10.0.0.0/22");
var albSubnet = vnet.AddSubnet("alb", "10.0.4.0/24");

var aks = builder.AddAzureKubernetesEnvironment("aks").WithSubnet(aksSubnet);
var lb = aks.AddLoadBalancer("lb", albSubnet);

aks.AddGateway("public").WithLoadBalancer(lb);

ATS export

Available to Polyglot AppHosts through the Aspire Type System.

AddNodePool(IResourceBuilder<AzureKubernetesEnvironmentResource>, string, string, int, int)extensionIResourceBuilder<AksNodePoolResource>

Adds a node pool to the AKS cluster.

public static class AzureKubernetesEnvironmentExtensions
{
    public static IResourceBuilder<AksNodePoolResource> AddNodePool(
        this IResourceBuilder<AzureKubernetesEnvironmentResource> builder,
        string name,
        string vmSize = "Standard_D2s_v5",
        int minCount = 1,
        int maxCount = 3)
    {
        // ...
    }
}

AzureKubernetesEnvironmentExtensions.cs#L170-L188

Parameters

builderIResourceBuilder<AzureKubernetesEnvironmentResource>The AKS environment resource builder.

namestringThe name of the node pool.

vmSizestringoptionalThe VM size for nodes. Defaults to Standard_D2s_v5 if not specified.

minCountintoptionalThe minimum node count for autoscaling. Defaults to 1.

maxCountintoptionalThe maximum node count for autoscaling. Defaults to 3.

Returns

IResourceBuilder<AksNodePoolResource>A reference to the ApplicationModel.IResourceBuilder`1 for the new node pool.

Remarks

The returned node pool resource can be passed to KubernetesEnvironmentExtensions.WithNodePool on compute resources to schedule workloads on this pool.

Examples

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

// With defaults (Standard_D2s_v5, 1-3 nodes)
var pool = aks.AddNodePool("workload");

// With explicit VM size and scaling
var gpuPool = aks.AddNodePool("gpu", "Standard_NC6s_v3", 0, 5);

ATS export

Available to Polyglot AppHosts through the Aspire Type System.

WithContainerRegistry(IResourceBuilder<AzureKubernetesEnvironmentResource>, IResourceBuilder<AzureContainerRegistryResource>)extensionIResourceBuilder<AzureKubernetesEnvironmentResource>

Configures the AKS environment to use a specific Azure Container Registry for image storage. When set, this replaces the auto-created default container registry.

public static class AzureKubernetesEnvironmentExtensions
{
    public static IResourceBuilder<AzureKubernetesEnvironmentResource> WithContainerRegistry(
        this IResourceBuilder<AzureKubernetesEnvironmentResource> builder,
        IResourceBuilder<AzureContainerRegistryResource> registry)
    {
        // ...
    }
}

AzureKubernetesEnvironmentExtensions.cs#L325-L358

Parameters

builderIResourceBuilder<AzureKubernetesEnvironmentResource>The AKS environment resource builder.

registryIResourceBuilder<AzureContainerRegistryResource>The Azure Container Registry resource builder.

Returns

IResourceBuilder<AzureKubernetesEnvironmentResource>A reference to the ApplicationModel.IResourceBuilder`1 for chaining.

Remarks

If not called, a default Azure Container Registry is automatically created. The registry endpoint is flowed to the inner Kubernetes environment so that Helm deployments can push and pull images.

ATS export

Available to Polyglot AppHosts through the Aspire Type System.

WithSubnet(IResourceBuilder<AzureKubernetesEnvironmentResource>, IResourceBuilder<AzureSubnetResource>)extensionIResourceBuilder<AzureKubernetesEnvironmentResource>

Configures the AKS cluster to use a VNet subnet for node pool networking. Unlike AzureVirtualNetworkExtensions.WithDelegatedSubnet, this does NOT add a service delegation to the subnet — AKS uses plain (non-delegated) subnets.

public static class AzureKubernetesEnvironmentExtensions
{
    public static IResourceBuilder<AzureKubernetesEnvironmentResource> WithSubnet(
        this IResourceBuilder<AzureKubernetesEnvironmentResource> builder,
        IResourceBuilder<AzureSubnetResource> subnet)
    {
        // ...
    }
}

AzureKubernetesEnvironmentExtensions.cs

Parameters

builderIResourceBuilder<AzureKubernetesEnvironmentResource>The AKS environment resource builder.

subnetIResourceBuilder<AzureSubnetResource>The subnet to use for AKS node pools.

Returns

IResourceBuilder<AzureKubernetesEnvironmentResource>A reference to the ApplicationModel.IResourceBuilder`1 for chaining.

Examples

var vnet = builder.AddAzureVirtualNetwork("vnet", "10.0.0.0/16");
var subnet = vnet.AddSubnet("aks-subnet", "10.0.0.0/22");
var aks = builder.AddAzureKubernetesEnvironment("aks")
    .WithSubnet(subnet);

ATS export

Available to Polyglot AppHosts through the Aspire Type System.

WithSubnet(IResourceBuilder<AksNodePoolResource>, IResourceBuilder<AzureSubnetResource>)extensionIResourceBuilder<AksNodePoolResource>

Configures a specific AKS node pool to use its own VNet subnet. When applied, this node pool's subnet overrides the environment-level subnet set via AzureKubernetesEnvironmentExtensions.WithSubnet.

public static class AzureKubernetesEnvironmentExtensions
{
    public static IResourceBuilder<AksNodePoolResource> WithSubnet(
        this IResourceBuilder<AksNodePoolResource> builder,
        IResourceBuilder<AzureSubnetResource> subnet)
    {
        // ...
    }
}

AzureKubernetesEnvironmentExtensions.cs

Parameters

builderIResourceBuilder<AksNodePoolResource>The node pool resource builder.

subnetIResourceBuilder<AzureSubnetResource>The subnet to use for this node pool.

Returns

IResourceBuilder<AksNodePoolResource>A reference to the ApplicationModel.IResourceBuilder`1 for chaining.

Examples

var vnet = builder.AddAzureVirtualNetwork("vnet", "10.0.0.0/16");
var defaultSubnet = vnet.AddSubnet("default", "10.0.0.0/22");
var gpuSubnet = vnet.AddSubnet("gpu-subnet", "10.0.4.0/24");

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

var gpuPool = aks.AddNodePool("gpu", AksNodeVmSizes.StandardNCSv3.StandardNC6sV3, 0, 5)
    .WithSubnet(gpuSubnet);

ATS export

Available to Polyglot AppHosts through the Aspire Type System.

WithSystemNodePool(IResourceBuilder<AzureKubernetesEnvironmentResource>, string, int, int)extensionIResourceBuilder<AzureKubernetesEnvironmentResource>

Replaces the default system node pool with a customized configuration.

public static class AzureKubernetesEnvironmentExtensions
{
    public static IResourceBuilder<AzureKubernetesEnvironmentResource> WithSystemNodePool(
        this IResourceBuilder<AzureKubernetesEnvironmentResource> builder,
        string vmSize = "Standard_D2s_v5",
        int minCount = 1,
        int maxCount = 3)
    {
        // ...
    }
}

AzureKubernetesEnvironmentExtensions.cs#L223-L233

Parameters

builderIResourceBuilder<AzureKubernetesEnvironmentResource>The AKS environment resource builder.

vmSizestringoptionalThe VM size for system pool nodes. Defaults to Standard_D2s_v5 if not specified.

minCountintoptionalThe minimum node count for autoscaling. Defaults to 1.

maxCountintoptionalThe maximum node count for autoscaling. Defaults to 3.

Returns

IResourceBuilder<AzureKubernetesEnvironmentResource>A reference to the ApplicationModel.IResourceBuilder`1 for chaining.

Remarks

Every AKS cluster requires exactly one system node pool for hosting system pods. By default, the system pool uses Standard_D2s_v5. Use this method to change the VM size when the default SKU is not available in your subscription or region. Calling this method multiple times replaces the previous system pool configuration.

Examples

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

// With explicit scaling
var aks2 = builder.AddAzureKubernetesEnvironment("aks2")
    .WithSystemNodePool("Standard_B2s", minCount: 2, maxCount: 5);

ATS export

Available to Polyglot AppHosts through the Aspire Type System.

WithWorkloadIdentity(IResourceBuilder<AzureKubernetesEnvironmentResource>, bool)extensionIResourceBuilder<AzureKubernetesEnvironmentResource>

Enables or disables workload identity on the AKS environment, allowing pods to authenticate to Azure services using federated credentials.

public static class AzureKubernetesEnvironmentExtensions
{
    public static IResourceBuilder<AzureKubernetesEnvironmentResource> WithWorkloadIdentity(
        this IResourceBuilder<AzureKubernetesEnvironmentResource> builder,
        bool enabled = true)
    {
        // ...
    }
}

AzureKubernetesEnvironmentExtensions.cs#L509-L513

Parameters

builderIResourceBuilder<AzureKubernetesEnvironmentResource>The resource builder.

enabledbooloptionaltrue to enable workload identity (the default); false to disable it.

Returns

IResourceBuilder<AzureKubernetesEnvironmentResource>A reference to the ApplicationModel.IResourceBuilder`1 for chaining.

Remarks

This ensures the AKS cluster is configured with OIDC issuer and workload identity enabled. Workload identity is automatically wired when compute resources have an Azure.AppIdentityAnnotation, which is added by WithAzureUserAssignedIdentity or auto-created by AzureResourcePreparer.

ATS export

Available to Polyglot AppHosts through the Aspire Type System.