Skip to main content

Azure CAPI Override Reference

This page provides examples and references for overriding Cluster API (CAPI) properties on Azure clusters using Cluster API Provider Azure (CAPZ).

Azure IaaS​

Self-managed Azure IaaS clusters use the CAPZ self-managed path. Cluster-level overrides target the AzureCluster resource, and pool-level overrides target the AzureMachineTemplate resource.

LevelCAPI KindAPI References
All-CAPZ Book - API Reference
*Use with caution as this reference guide is not semantically versioned.
ClusterAzureClusterv1.18.0 AzureCluster API types
PoolAzureMachineTemplatev1.18.0 AzureMachineTemplate API types

Examples​

These examples demonstrate how to override CAPI properties using YAML directly targeting the underlying CAPZ self-managed resources.

Cluster-Level​

Set additional tags on the cluster
azureCluster:
  spec:
    additionalTags:
      env: day0
      owner: Anu

Pool-Level​

AzureMachineTemplate has an extra level of nesting. The spec wraps a template, which contains another spec field that holds the actual machine configuration. All pool-level Azure IaaS overrides use this structure.

Set the VM size
azureMachineTemplate:
  spec:
    template:
      spec:
        vmSize: Standard_D4s_v3
Set the OS disk size
azureMachineTemplate:
  spec:
    template:
      spec:
        osDisk:
          diskSizeGB: 128

Unsupported First-Class Properties​

The following properties are not exposed as first-class properties in the supported interfaces for Palette but can be configured using override. To learn more about the difference between first-class properties and override properties, refer to the First-Class Support vs. Override section.

CAPZ Resource TypeProperties
AzureClusteradditionalTags, bastionSpec, cloudProviderConfigOverrides, controlPlaneEnabled, controlPlaneEndpoint, extendedLocation, failureDomains
AzureMachineTemplateadditionalCapabilities, additionalCapabilities.ultraSSDEnabled, additionalTags, allocatePublicIP, dataDisks, diagnostics, enableIPForwarding, failureDomain, providerID, securityProfile.securityType, securityProfile.uefiSettings, systemAssignedIdentityRole, userAssignedIdentities

Azure AKS​

Azure AKS clusters use the CAPZ managed path. Cluster-level overrides target the AzureManagedControlPlane resource, and pool-level overrides target the AzureManagedMachinePool resource.

LevelCAPI KindAPI References
All-CAPZ Book - API Reference
*Use with caution as this reference guide is not semantically versioned.
ClusterAzureManagedControlPlanev1.18.0 AzureManagedControlPlane API types
PoolAzureManagedMachinePoolv1.18.0 AzureManagedMachinePool API types

Examples​

These examples demonstrate how to override CAPI properties using YAML directly targeting the underlying CAPZ resources.

Cluster-Level​

Enable OpenID Connect (OIDC) issuer and workload identity
azureManagedControlPlane:
  spec:
    autoUpgradeProfile:
      upgradeChannel: patch
    oidcIssuerProfile:
      enabled: true
    securityProfile:
      workloadIdentity:
        enabled: true
Set DNS prefix for control plane FQDN
azureManagedControlPlane:
  spec:
    dnsPrefix: aksdemo-updated

Pool-Level​

Set max pods, OS disk type, and disable node public IPs
azureManagedMachinePool:
  spec:
    maxPods: 30
    kubeletDiskType: OS
    enableNodePublicIP: false
Set VM size, OS disk size, and node labels
azureManagedMachinePool:
  spec:
    sku: Standard_D8s_v5
    osDiskSizeGB: 256
    nodeLabels:
      env: test
      updated: "true"

Whenever you use asoManagedClustersAgentPoolPatches on azureManagedMachinePool, you must include an entry that sets the osSKU field alongside any other patch entries.

Set osSKU to the value that matches the OS you selected for the node pool: AzureLinux, Ubuntu, or Windows2022.

Set the node pool OS SKU to Azure Linux
azureManagedMachinePool:
  spec:
    asoManagedClustersAgentPoolPatches:
      - '{"spec":{"upgradeSettings":{"maxSurge":"1"}}}'
      - '{"spec":{"osSKU":"AzureLinux"}}' # Other values include Ubuntu and Windows2022
info

The OS SKU is also exposed as a first-class OS SKU field on the node pool configuration in Palette, which is the recommended way to set it. Refer to Create and Manage Azure AKS Cluster for details.

The OS SKU is immutable after the node pool is created, overriding it on an existing node pool has no effect.

Encryption​

Host Encryption​

Host encryption encrypts the OS and temporary disks on the underlying VM host using platform-managed keys. You can configure it at the pool level using the enableEncryptionAtHost field on AzureManagedMachinePool.

warning

enableEncryptionAtHost is immutable and must be set when the node pool is first created. It cannot be enabled or disabled on an existing pool.

Enable host encryption on a node pool
azureManagedMachinePool:
  spec:
    enableEncryptionAtHost: true

Disk Encryption Sets​

CAPZ v1.18.0 does not expose a first-class Disk Encryption Set (DES) field for AKS node pools. The supported workaround is to use the asoManagedClusterPatches field on AzureManagedControlPlane, which applies a JSON merge patch directly to the underlying Azure Service Operator (ASO) ManagedCluster resource.

warning

The asoManagedClusterPatches field is intended for advanced use only. To avoid misconfiguration that conflicts with CAPZ's normal operation, test changes in a non-production environment before applying them to a production cluster.

Enable disk encryption set at the cluster level
azureManagedControlPlane:
  spec:
    asoManagedClusterPatches:
      - '{"spec": {"diskEncryptionSetReference":
        "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Compute/diskEncryptionSets/<disk-encryption-set-name>"}}'

Known Immutable Fields​

The following fields become immutable after an AKS cluster is created. Attempting to disable them via override after they have been enabled results in an error. You must revert the override change to clear the error and allow the cluster to reconcile.

FieldCAPI KindNotes
aadProfileAzureManagedControlPlaneCannot be disabled once enabled.
oidcIssuerProfileAzureManagedControlPlaneCannot be disabled once enabled.
enableEncryptionAtHostAzureManagedMachinePoolMust be set at node pool creation. Cannot be changed afterwards.

Unsupported First-Class Properties​

The following properties are not exposed as first-class properties in the supported interfaces for Palette but can be configured using override. To learn more about the difference between first-class properties and override properties, refer to the First-Class Support vs. Override section.

CAPZ Resource TypeProperties
AzureManagedControlPlanecontrolPlaneEndpoint, fleetsMember, fqdnSubdomain, securityProfile (partial support)
AzureManagedMachinePooladditionalTags, enableNodePublicIP, enableUltraSSD, name, nodeLabels, nodePublicIPPrefixID, osDiskType, scaleDownMode, scaleSetPriority, spotMaxPrice, taints