Skip to content

Use valid AKS cluster names#

Operational Excellence · Azure Kubernetes Service · Rule · 2020_06 · Awareness

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:

Azure Bicep snippet
@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 Verified Modules

A pre-validated module supported by Microsoft is available from the Azure Bicep public registry. To reference the module, please use the following syntax:

br/public:avm/res/container-service/managed-cluster:<version>

To use the latest version:

br/public:avm/res/container-service/managed-cluster:0.9.0

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.
Azure Template snippet
{
  "$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.

Comments