Create a private Azure Kubernetes Service (AKS) cluster

• Terraform installed locally. For installation instructions, see Install Terraform.

Create a resource group

Create a resource group using the az group create command. You can also use an existing resource group for your AKS cluster.

az group create \
    --name <private-cluster-resource-group> \
    --location <location>

Create a private cluster with default basic networking using the az aks create command with the --enable-private-cluster flag.

Key parameters in this command:

• --enable-private-cluster: Enables private cluster mode.

az aks create \
    --name <private-cluster-name> \
    --resource-group <private-cluster-resource-group> \
    --load-balancer-sku standard \
    --enable-private-cluster \
    --generate-ssh-keys

1. Create a file named main.tf and add the following code to define the Terraform version and specify the Azure provider:

   terraform {
     required_version = ">= 1.3.0"
     required_providers {
       azurerm = {
         source  = "hashicorp/azurerm"
         version = "~> 4.0"
       }
     }
   }
   
   provider "azurerm" {
     features {}
     subscription_id = var.subscription_id
   }
   

2. Add the following code to main.tf to create input variables for your Azure subscription ID, resource group name, location, and AKS cluster name. You can modify the default values as needed.

   variable "subscription_id" {
     description = "The Azure subscription ID."
     type = string
   }
   
   variable "resource_group_name" {
     description = "The name of the resource group for the AKS cluster."
     type        = string
     default     = "rg-private-aks-basic"
   }
   
   variable "location" {
     description = "The Azure region where the resources will be created."
     type        = string
     default     = "eastus"
   }
   
   variable "aks_cluster_name" {
     description = "The name of the AKS cluster."
     type        = string
     default     = "aks-private-basic"
   }
   

3. Add the following code to main.tf to create an Azure resource group:

   resource "azurerm_resource_group" "this" {
     name     = var.resource_group_name
     location = var.location
   }
   

4. Add the following code to main.tf to create a private AKS cluster with basic networking:

   resource "azurerm_kubernetes_cluster" "this" {
     name                = var.aks_cluster_name
     location            = azurerm_resource_group.this.location
     resource_group_name = azurerm_resource_group.this.name
     dns_prefix          = "privatebasicaks"
   
     private_cluster_enabled = true
   
     default_node_pool {
       name       = "system"
       node_count = 1
       vm_size    = "Standard_DS2_v2"
     }
   
     identity {
       type = "SystemAssigned"
     }
   
     network_profile {
       load_balancer_sku = "standard"
       network_plugin    = "kubenet"
     }
   }
   

5. Follow the steps to initialize Terraform, format and validate the Terraform configuration, create a Terraform execution plan, apply the Terraform configuration, and connect to the AKS cluster.

Create a private cluster with advanced networking using the az aks create command.

Key parameters in this command:

• --enable-private-cluster: Enables private cluster mode.
• --network-plugin azure: Specifies the Azure CNI networking plugin.
• --vnet-subnet-id <subnet-id>: The resource ID of an existing subnet in a VNet.
• --dns-service-ip <dns-service-ip>: An available IP address within the Kubernetes service address range to use for the cluster DNS service. For example, 10.2.0.10.
• --service-cidr <service-cidr>: A CIDR notation IP range from which to assign service cluster IPs. For example, 10.2.0.0/24.

az aks create \
    --resource-group <private-cluster-resource-group> \
    --name <private-cluster-name> \
    --load-balancer-sku standard \
    --enable-private-cluster \
    --network-plugin azure \
    --vnet-subnet-id <subnet-id> \
    --dns-service-ip <dns-service-ip> \
    --service-cidr <service-cidr> \
    --generate-ssh-keys

1. Create a file named main.tf and add the following code to define the Terraform version and specify the Azure provider:

   terraform {
     required_version = ">= 1.3.0"
     required_providers {
       azurerm = {
         source  = "hashicorp/azurerm"
         version = "~> 4.0"
       }
     }
   }
   
   provider "azurerm" {
     features {}
     subscription_id = var.subscription_id
   }
   

2. Add the following code to main.tf to create input variables for your Azure subscription ID, resource group name, location, AKS cluster name, virtual network (VNet) name, and subnet name. You can modify the default values as needed.

   variable "subscription_id" {
     description = "The Azure subscription ID."
     type = string
   }
   
   variable "resource_group_name" {
     description = "The name of the resource group for the AKS cluster."
     type = string
     default = "rg-private-aks-advanced"
   }
   
   variable "location" {
     description = "The Azure region where the resources will be created."
     type = string
     default = "eastus"
   }
   
   variable "aks_cluster_name" {
     description = "The name of the AKS cluster."
     type = string
     default = "aks-private-advanced"
   }
   
   variable "vnet_name" {
     description = "The name of the virtual network."
     type = string
     default = "vnet-private-aks"
   }
   
   variable "subnet_name" {
     description = "The name of the subnet used by AKS."
     type = string
     default = "snet-aks"
   }
   

3. Add the following code to main.tf to create an Azure resource group, VNet, and subnet:

   resource "azurerm_resource_group" "this" {
     name = var.resource_group_name
     location = var.location
   }
   
   resource "azurerm_virtual_network" "this" {
     name = var.vnet_name
     location = azurerm_resource_group.this.location
     resource_group_name = azurerm_resource_group.this.name
     address_space = ["10.0.0.0/8"]
   }
   
   resource "azurerm_subnet" "aks" {
     name = var.subnet_name
     resource_group_name  = azurerm_resource_group.this.name
     virtual_network_name = azurerm_virtual_network.this.name
     address_prefixes = ["10.240.0.0/16"]
   }
   

4. Add the following code to main.tf to create the AKS cluster with advanced networking:

   resource "azurerm_kubernetes_cluster" "this" {
     name = var.aks_cluster_name
     location = azurerm_resource_group.this.location
     resource_group_name = azurerm_resource_group.this.name
     dns_prefix = "privateadvancedaks"
   
     private_cluster_enabled = true
   
     default_node_pool {
       name = "system"
       node_count = 1
       vm_size = "Standard_DS2_v2"
       vnet_subnet_id = azurerm_subnet.aks.id
     }
   
     identity {
       type = "SystemAssigned"
     }
   
     network_profile {
       load_balancer_sku = "standard"
       network_plugin = "azure"
       dns_service_ip = "10.2.0.10"
       service_cidr = "10.2.0.0/24"
     }
   }
   

5. Follow the steps to initialize Terraform, format and validate the Terraform configuration, create a Terraform execution plan, apply the Terraform configuration, and connect to the AKS cluster.

Disable a public FQDN when creating a private AKS cluster using the az aks create command with the --disable-public-fqdn flag.

Key parameters in this command:

• --disable-public-fqdn: Disables the public fully qualified domain name (FQDN) for the API server.
• --assign-identity <resource-id>: Specifies the managed identity to use for the cluster.
• --private-dns-zone [system|none]: Specifies the private DNS zone to use for the cluster. system is the default value when configuring a private DNS zone. If you omit --private-dns-zone, AKS creates a private DNS zone in the node resource group. none disables the creation of a private DNS zone.

az aks create \
    --name <private-cluster-name> \
    --resource-group <private-cluster-resource-group> \
    --load-balancer-sku standard \
    --enable-private-cluster \
    --assign-identity <resource-id> \
    --private-dns-zone [system|none] \
    --disable-public-fqdn \
    --generate-ssh-keys

1. Follow steps 1-3 in Create a private AKS cluster with advanced networking or Create a private AKS cluster with default basic networking to set up the Terraform configuration and create the necessary resources depending on your scenario. This example uses advanced networking.

2. Add the following code to main.tf to create a private AKS cluster with a user-assigned identity and the public FQDN disabled:

   resource "azurerm_user_assigned_identity" "aks" {
     name = "id-private-aks-public-fqdn-off"
     location = azurerm_resource_group.this.location
     resource_group_name = azurerm_resource_group.this.name
   }
   resource "azurerm_kubernetes_cluster" "this" {
     name = var.aks_cluster_name
     location = azurerm_resource_group.this.location
     resource_group_name = azurerm_resource_group.this.name
     dns_prefix = "privateaks"
     private_cluster_enabled = true
     private_cluster_public_fqdn_enabled = false
   
     private_dns_zone_id = "System"
   
     default_node_pool {
       name = "system"
       node_count = 1
       vm_size = "Standard_DS2_v2"
       vnet_subnet_id = azurerm_subnet.aks.id
     }
     identity {
       type = "UserAssigned"
       identity_ids = [azurerm_user_assigned_identity.aks.id]
     }
     network_profile {
       load_balancer_sku = "standard"
       network_plugin = "azure"
       dns_service_ip = "10.2.0.10"
       service_cidr = "10.2.0.0/24"
     }
   }
   

3. Follow the steps to initialize Terraform, format and validate the Terraform configuration, create a Terraform execution plan, apply the Terraform configuration, and connect to the AKS cluster.

Disable a public FQDN on an existing AKS cluster using the az aks update command with the --disable-public-fqdn flag.

Key parameters in this command:

• --disable-public-fqdn: Disables the public fully qualified domain name (FQDN) for the API server.

az aks update \
    --name <private-cluster-name> \
    --resource-group <private-cluster-resource-group> \
    --disable-public-fqdn

1. Add the following code to the existing main.tf to disable the public FQDN on an existing AKS cluster. This example uses advanced networking. You can modify it to use default basic networking by changing the relevant Terraform resources and parameters.

   resource "azurerm_kubernetes_cluster" "this" {
     name = var.aks_cluster_name
     location = azurerm_resource_group.this.location
     resource_group_name = azurerm_resource_group.this.name
     dns_prefix = "privateaks"
   
     private_cluster_enabled = true
     private_cluster_public_fqdn_enabled = false
     private_dns_zone_id = "System"
   
     default_node_pool {
       name = "system"
       node_count = 1
       vm_size = "Standard_DS2_v2"
       vnet_subnet_id = azurerm_subnet.aks.id
     }
   
     identity {
       type = "UserAssigned"
       identity_ids = [azurerm_user_assigned_identity.aks.id]
     }
   
     network_profile {
       load_balancer_sku = "standard"
       network_plugin = "azure"
       dns_service_ip = "10.2.0.10"
       service_cidr = "10.2.0.0/24"
     }
   }
   

2. Apply the updated Terraform configuration using the terraform plan and terraform apply commands.

   terraform plan
   terraform apply
   

Configuration options for private DNS

You can configure private DNS settings for a private AKS cluster using the Azure CLI (with the --private-dns-zone parameter) or an Azure Resource Manager (ARM) template (with the privateDNSZone property). The following table outlines the options available for the --private-dns-zone parameter / privateDNSZone property:

Considerations for private DNS

Keep the following considerations in mind when configuring private DNS for a private AKS cluster:

• If the private DNS zone is in a different subscription than the AKS cluster, you need to register the Microsoft.ContainerService Azure provider in both subscriptions.
• If your AKS cluster is configured with an Active Directory service principal, AKS doesn't support using a system-assigned managed identity with custom private DNS zone. The cluster must use user-assigned managed identity authentication.

Create a private AKS cluster with a private DNS zone using the az aks create command.

Key parameters in this command:

• --enable-private-cluster: Enables private cluster mode.
• --private-dns-zone [system|none]: Configures the private DNS zone for the cluster. system is the default value when configuring a private DNS zone. If you omit --private-dns-zone, AKS creates a private DNS zone in the node resource group. none disables the creation of a private DNS zone.
• --assign-identity <resource-id>: The resource ID of a user-assigned managed identity with the Private DNS Zone Contributor and Network Contributor roles.

az aks create \
    --name <private-cluster-name> \
    --resource-group <private-cluster-resource-group> \
    --load-balancer-sku standard \
    --enable-private-cluster \
    --assign-identity <resource-id> \
    --private-dns-zone [system|none] \
    --generate-ssh-keys

1. Follow steps 1-3 in Create a private AKS cluster with advanced networking or Create a private AKS cluster with default basic networking to set up the Terraform configuration and create the necessary resources depending on your scenario. This example uses advanced networking.

2. Add the following code to main.tf to create a private AKS cluster with an AKS-managed private DNS zone:

   resource "azurerm_kubernetes_cluster" "this" {
    name                = var.aks_cluster_name
    location            = azurerm_resource_group.this.location
    resource_group_name = azurerm_resource_group.this.name
    dns_prefix          = "aks-system-dns"
    private_cluster_enabled = true
    private_dns_zone_id     = "System"
    default_node_pool {
      name           = "system"
      node_count     = 1
      vm_size        = "Standard_DS2_v2"
      vnet_subnet_id = azurerm_subnet.aks.id
    }
    identity {
      type = "SystemAssigned"
    }
    network_profile {
      network_plugin    = "azure"
      load_balancer_sku = "standard"
      dns_service_ip    = "10.2.0.10"
      service_cidr      = "10.2.0.0/24"
    }
   }
   

3. Follow the steps to initialize Terraform, format and validate the Terraform configuration, create a Terraform execution plan, apply the Terraform configuration, and connect to the AKS cluster.

Create a private AKS cluster without a private DNS zone

1. Follow steps 1-3 in Create a private AKS cluster with advanced networking or Create a private AKS cluster with default basic networking to set up the Terraform configuration and create the necessary resources depending on your scenario. This example uses advanced networking.

2. Add the following code to main.tf to create the AKS cluster without a private DNS zone:

   resource "azurerm_kubernetes_cluster" "this" {
    name                = var.aks_cluster_name
    location            = azurerm_resource_group.this.location
    resource_group_name = azurerm_resource_group.this.name
    dns_prefix          = "aks-no-dns"
    private_cluster_enabled = true
    private_dns_zone_id     = "None"
    default_node_pool {
      name           = "system"
      node_count     = 1
      vm_size        = "Standard_DS2_v2"
      vnet_subnet_id = azurerm_subnet.aks.id
    }
    identity {
      type = "SystemAssigned"
    }
    network_profile {
      network_plugin    = "azure"
      load_balancer_sku = "standard"
      dns_service_ip    = "10.2.0.10"
      service_cidr      = "10.2.0.0/24"
    }
   }
   

3. Follow the steps to initialize Terraform, format and validate the Terraform configuration, create a Terraform execution plan, apply the Terraform configuration, and connect to the AKS cluster.

Create a private AKS cluster with a custom private DNS zone or subzone using the az aks create command.

Key parameters in this command:

• --enable-private-cluster: Enables private cluster mode.
• --private-dns-zone [<custom-private-dns-zone-resource-id>|<custom-private-dns-subzone-resource-id>]: The resource ID of an existing private DNS zone or subzone in the following format for Azure global cloud: privatelink.<region>.azmk8s.io or <subzone>.privatelink.<region>.azmk8s.io.
• --assign-identity <resource-id>: The resource ID of a user-assigned managed identity with the Private DNS Zone Contributor and Network Contributor roles.

az aks create \
    --name <private-cluster-name> \
    --resource-group <private-cluster-resource-group> \
    --load-balancer-sku standard \
    --enable-private-cluster \
    --assign-identity <resource-id> \
    --private-dns-zone [<custom-private-dns-zone-resource-id>|<custom-private-dns-subzone-resource-id>] \
    --generate-ssh-keys

When using a custom private DNS zone, you're responsible for creating and managing the DNS infrastructure instead of relying on Azure-managed DNS. This includes creating the DNS zone, linking it to your VNet, and assigning the necessary permissions for AKS to manage records.

For custom DNS configurations, you must use a user-assigned managed identity with the Private DNS Zone Contributor and Network Contributor roles.

1. Follow steps 1-3 in Create a private AKS cluster with advanced networking or Create a private AKS cluster with default basic networking to set up the Terraform configuration and create the necessary resources depending on your scenario. This example uses advanced networking.

2. Add the code to main.tf to create a private AKS cluster with a custom private DNS zone or subzone:

   resource "azurerm_user_assigned_identity" "aks" {
    name                = "aks-custom-dns-id"
    location            = azurerm_resource_group.this.location
    resource_group_name = azurerm_resource_group.this.name
   }
   resource "azurerm_private_dns_zone" "aks" {
    name                = "privatelink.eastus.azmk8s.io"
    resource_group_name = azurerm_resource_group.this.name
   }
   resource "azurerm_private_dns_zone_virtual_network_link" "link" {
    name                  = "aks-dns-link"
    resource_group_name   = azurerm_resource_group.this.name
    private_dns_zone_name = azurerm_private_dns_zone.aks.name
    virtual_network_id    = azurerm_virtual_network.this.id
   }
   resource "azurerm_role_assignment" "dns" {
    scope                = azurerm_private_dns_zone.aks.id
    role_definition_name = "Private DNS Zone Contributor"
    principal_id         = azurerm_user_assigned_identity.aks.principal_id
   }
   resource "azurerm_role_assignment" "network" {
    scope                = azurerm_virtual_network.this.id
    role_definition_name = "Network Contributor"
    principal_id         = azurerm_user_assigned_identity.aks.principal_id
   }
   resource "azurerm_kubernetes_cluster" "this" {
    name                = var.aks_cluster_name
    location            = azurerm_resource_group.this.location
    resource_group_name = azurerm_resource_group.this.name
    dns_prefix          = "aks-custom-dns"
    private_cluster_enabled = true
    private_dns_zone_id     = azurerm_private_dns_zone.aks.id
    default_node_pool {
      name           = "system"
      node_count     = 1
      vm_size        = "Standard_DS2_v2"
      vnet_subnet_id = azurerm_subnet.aks.id
    }
    identity {
      type         = "UserAssigned"
      identity_ids = [azurerm_user_assigned_identity.aks.id]
    }
    network_profile {
      network_plugin    = "azure"
      load_balancer_sku = "standard"
      dns_service_ip    = "10.2.0.10"
      service_cidr      = "10.2.0.0/24"
    }
    depends_on = [
      azurerm_role_assignment.dns,
      azurerm_role_assignment.network
    ]
   }
   

3. Follow the steps to initialize Terraform, format and validate the Terraform configuration, create a Terraform execution plan, apply the Terraform configuration, and connect to the AKS cluster.

Create a private AKS cluster with a custom private DNS zone and subdomain using the az aks create command.

Key parameters in this command:

• --enable-private-cluster: Enables private cluster mode.
• --private-dns-zone <custom-private-dns-zone-resource-id>: The resource ID of an existing private DNS zone in the following format for Azure global cloud: privatelink.<region>.azmk8s.io.
• --fqdn-subdomain <subdomain>: The subdomain to use for the cluster FQDN within the custom private DNS zone.
• --assign-identity <resource-id>: The resource ID of a user-assigned managed identity with the Private DNS Zone Contributor and Network Contributor roles.

az aks create \
    --name <private-cluster-name> \
    --resource-group <private-cluster-resource-group> \
    --load-balancer-sku standard \
    --enable-private-cluster \
    --assign-identity <resource-id> \
    --private-dns-zone <custom-private-dns-zone-resource-id> \
    --fqdn-subdomain <subdomain> \
    --generate-ssh-keys

1. Follow steps 1-3 in Create a private AKS cluster with advanced networking or Create a private AKS cluster with default basic networking to set up the Terraform configuration and create the necessary resources depending on your scenario. This example uses advanced networking.

2. Add the following code to main.tf to create a private AKS cluster with a custom private DNS zone and subdomain:

   resource "azurerm_kubernetes_cluster" "this" {
    name                = var.aks_cluster_name
    location            = azurerm_resource_group.this.location
    resource_group_name = azurerm_resource_group.this.name
    dns_prefix          = "aks-subdomain"
    private_cluster_enabled = true
    private_dns_zone_id     = azurerm_private_dns_zone.aks.id
    fqdn_subdomain          = "team1"
    default_node_pool {
      name           = "system"
      node_count     = 1
      vm_size        = "Standard_DS2_v2"
      vnet_subnet_id = azurerm_subnet.aks.id
    }
    identity {
      type         = "UserAssigned"
      identity_ids = [azurerm_user_assigned_identity.aks.id]
    }
    network_profile {
      network_plugin    = "azure"
      load_balancer_sku = "standard"
      dns_service_ip    = "10.2.0.10"
      service_cidr      = "10.2.0.0/24"
    }
   }
   

3. Follow the steps to initialize Terraform, format and validate the Terraform configuration, create a Terraform execution plan, apply the Terraform configuration, and connect to the AKS cluster.

You can only update from byo (bring your own) or system to none. No other combination of update values is supported.

Update a private cluster from byo or system to none using the az aks update command with the --private-dns-zone parameter set to none.

az aks update \
    --name <private-cluster-name> \
    --resource-group <private-cluster-resource-group> \
    --private-dns-zone none

1. Add the following code to the existing main.tf to update the private AKS cluster from a private DNS zone to public. This example uses advanced networking. You can modify it to use default basic networking by changing the relevant Terraform resources and parameters.

   resource "azurerm_kubernetes_cluster" "this" {
    name                = var.aks_cluster_name
    location            = azurerm_resource_group.this.location
    resource_group_name = azurerm_resource_group.this.name
    dns_prefix          = "aks-update"
    private_cluster_enabled = true
    private_dns_zone_id     = "None"
    default_node_pool {
      name           = "system"
      node_count     = 1
      vm_size        = "Standard_DS2_v2"
      vnet_subnet_id = azurerm_subnet.aks.id
    }
    identity {
      type         = "UserAssigned"
      identity_ids = [azurerm_user_assigned_identity.aks.id]
    }
    network_profile {
      network_plugin    = "azure"
      load_balancer_sku = "standard"
      dns_service_ip    = "10.2.0.10"
      service_cidr      = "10.2.0.0/24"
    }
   }
   

2. Apply the updated Terraform configuration using the terraform plan and terraform apply commands.

   terraform plan
   terraform apply
   

Initialize Terraform

Initialize Terraform in the directory containing your main.tf file using the terraform init command. This command downloads the Azure provider required to manage Azure resources with Terraform.

terraform init

Format and validate the Terraform configuration

Format and validate the Terraform configuration using the terraform fmt and terraform validate commands.

terraform fmt
terraform validate

Create a Terraform execution plan

Create a Terraform execution plan using the terraform plan command. This command shows you the resources that Terraform will create or modify in your Azure subscription.

terraform plan -var="subscription_id=<your-subscription-id>"

Apply the Terraform configuration

After reviewing and confirming the execution plan, apply the Terraform configuration using the terraform apply command. This command creates or modifies the resources defined in your main.tf file in your Azure subscription.

terraform apply -var="subscription_id=<your-subscription-id>"