Kubernetes Cluster version is not automatically upgraded

March 27, 2025 ยท View on GitHub

SYNOPSIS

New versions of Kubernetes are released regularly. Upgrading each release manually can add operational overhead without realizing equivalent value.

DESCRIPTION

In additional to performing manual upgrades, AKS supports auto-upgrades. Auto-upgrades reduces manual intervention required to maintain an AKS cluster.

To configure auto-upgrades select a release channel instead of the default none. The following release channels are available:

  • none - Disables auto-upgrades. The default setting.
  • patch - Automatically upgrade to the latest supported patch version of the current minor version.
  • stable - Automatically upgrade to the latest supported patch release of the recommended minor version. This is N-1 of the current AKS non-preview minor version.
  • rapid - Automatically upgrade to the latest supported patch of the latest support minor version.
  • node-image - Automatically upgrade to the latest node image version. Normally upgraded weekly.

RECOMMENDATION

Consider enabling auto-upgrades for AKS clusters by setting an auto-upgrade channel.

EXAMPLES

Configure with Bicep

To deploy AKS clusters that pass this rule:

  • Set properties.autoUpgradeProfile.upgradeChannel to an upgrade channel such as stable.

For example:

resource cluster 'Microsoft.ContainerService/managedClusters@2024-10-01' = {
  location: location
  name: name
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${identity.id}': {}
    }
  }
  properties: {
    kubernetesVersion: kubernetesVersion
    disableLocalAccounts: true
    enableRBAC: true
    dnsPrefix: dnsPrefix
    agentPoolProfiles: allPools
    aadProfile: {
      managed: true
      enableAzureRBAC: true
      adminGroupObjectIDs: clusterAdmins
      tenantID: subscription().tenantId
    }
    networkProfile: {
      networkPlugin: 'azure'
      networkPolicy: 'azure'
      loadBalancerSku: 'standard'
      serviceCidr: serviceCidr
      dnsServiceIP: dnsServiceIP
    }
    apiServerAccessProfile: {
      authorizedIPRanges: [
        '0.0.0.0/32'
      ]
    }
    autoUpgradeProfile: {
      upgradeChannel: 'stable'
    }
    oidcIssuerProfile: {
      enabled: true
    }
    addonProfiles: {
      azurepolicy: {
        enabled: true
      }
      omsagent: {
        enabled: true
        config: {
          logAnalyticsWorkspaceResourceID: workspaceId
        }
      }
      azureKeyvaultSecretsProvider: {
        enabled: true
        config: {
          enableSecretRotation: 'true'
        }
      }
    }
  }
}

Configure with Azure template

To deploy AKS clusters that pass this rule:

  • Set properties.autoUpgradeProfile.upgradeChannel to an upgrade channel such as stable.

For example:

{
  "type": "Microsoft.ContainerService/managedClusters",
  "apiVersion": "2024-10-01",
  "name": "[parameters('name')]",
  "location": "[parameters('location')]",
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "[format('{0}', resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('identityName')))]": {}
    }
  },
  "properties": {
    "kubernetesVersion": "[parameters('kubernetesVersion')]",
    "disableLocalAccounts": true,
    "enableRBAC": true,
    "dnsPrefix": "[parameters('dnsPrefix')]",
    "agentPoolProfiles": "[variables('allPools')]",
    "aadProfile": {
      "managed": true,
      "enableAzureRBAC": true,
      "adminGroupObjectIDs": "[parameters('clusterAdmins')]",
      "tenantID": "[subscription().tenantId]"
    },
    "networkProfile": {
      "networkPlugin": "azure",
      "networkPolicy": "azure",
      "loadBalancerSku": "standard",
      "serviceCidr": "[variables('serviceCidr')]",
      "dnsServiceIP": "[variables('dnsServiceIP')]"
    },
    "apiServerAccessProfile": {
      "authorizedIPRanges": [
        "0.0.0.0/32"
      ]
    },
    "autoUpgradeProfile": {
      "upgradeChannel": "stable"
    },
    "oidcIssuerProfile": {
      "enabled": true
    },
    "addonProfiles": {
      "azurepolicy": {
        "enabled": true
      },
      "omsagent": {
        "enabled": true,
        "config": {
          "logAnalyticsWorkspaceResourceID": "[parameters('workspaceId')]"
        }
      },
      "azureKeyvaultSecretsProvider": {
        "enabled": true,
        "config": {
          "enableSecretRotation": "true"
        }
      }
    }
  },
  "dependsOn": [
    "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('identityName'))]"
  ]
}

Configure with Azure CLI

az aks update -n '<name>' -g '<resource_group>' --auto-upgrade-channel 'stable'

Configure with Azure Policy

To address this issue at runtime use the following policies: