Use valid AKS cluster names

November 27, 2025 ยท View on GitHub

SYNOPSIS

Azure Kubernetes Service (AKS) cluster names should meet naming requirements.

DESCRIPTION

When naming Azure resources, resource names must meet service requirements. The requirements for AKS cluster names are:

  • Between 1 and 63 characters long.
  • Alphanumerics, underscores, and hyphens.
  • Start and end with alphanumeric.
  • Cluster names must be unique within a resource group.

RECOMMENDATION

Consider using names that meet AKS cluster naming requirements. Additionally consider naming resources with a standard naming convention.

EXAMPLES

Configure with Bicep

To deploy clusters that pass this rule:

  • Set the name property to a string that matches the naming requirements.
  • Optionally, consider constraining name parameters with minLength and maxLength attributes.

For example:

@minLength(1)
@maxLength(63)
@description('The name of the resource.')
param name string

@description('The location resources will be deployed.')
param location string = resourceGroup().location

resource cluster 'Microsoft.ContainerService/managedClusters@2025-07-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 clusters that pass this rule:

  • Set the name property to a string that matches the naming requirements.
  • Optionally, consider constraining name parameters with minLength and maxLength attributes.
{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "name": {
      "type": "string",
      "metadata": {
        "description": "The name of the AKS cluster."
      }
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]",
      "metadata": {
        "description": "Optional. The Azure region to deploy to."
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.ContainerService/managedClusters",
      "apiVersion": "2025-07-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"
            }
          }
        }
      }
    }
  ]
}

NOTES

This rule does not check if cluster names are unique.

Cluster DNS prefix has different naming requirements then cluster name. The requirements for DNS prefixes are:

  • Between 1 and 54 characters long.
  • Alphanumerics and hyphens.
  • Start and end with alphanumeric.