AKS Cluster Setup

Creating an AKS cluster involves setting up the Azure infrastructure (resource group, service principal, virtual network), creating the cluster control plane, configuring worker nodes, and connecting your local kubectl to the cluster. This guide covers the complete setup process from prerequisites to deploying your first application.

Prerequisites

Before creating an AKS cluster, ensure you have:

Azure Account Requirements

• Azure Subscription - Active Azure subscription with appropriate permissions
• Azure CLI - Installed and configured
• Service Principal or Managed Identity - For cluster and node pool permissions
• Resource Group - Azure resource group for your cluster
• Region Selection - Choose an Azure region where AKS is available

Local Tools

Install these tools on your local machine:

kubectl:

# macOS
brew install kubectl

# Linux
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

# Verify installation
kubectl version --client

Azure CLI:

# macOS
brew install azure-cli

# Linux
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

# Verify installation
az --version

Azure CLI Authentication:

# Login to Azure
az login

# Set default subscription
az account set --subscription "Your Subscription Name"

# Verify authentication
az account show

Understanding AKS Components

Before creating a cluster, understand what gets created:

AKS Cluster:

• Control plane managed by Azure
• API endpoint for cluster access
• Cluster configuration and version

Virtual Network and Networking:

• Virtual Network for cluster isolation
• Subnets for nodes and pods
• Network Security Groups for traffic control
• Route tables for traffic routing

Service Principal or Managed Identity:

• Service Principal - Azure AD identity for cluster operations
• Managed Identity - System-assigned or user-assigned managed identity
• Permissions for cluster and node operations

Node Pool:

• Virtual Machine Scale Set for worker nodes
• Virtual Machines running Kubernetes node components

Creating a Cluster

There are four main ways to create an AKS cluster:

Method 1: Azure CLI (Recommended)

Azure CLI is the official tool for AKS cluster creation:

Simple Cluster Creation:

# Create resource group
az group create --name myResourceGroup --location eastus

# Create AKS cluster with default settings
az aks create \
  --resource-group myResourceGroup \
  --name myAKSCluster \
  --node-count 3 \
  --generate-ssh-keys

This single command creates:

• AKS cluster
• Default node pool with 3 nodes
• Virtual Network (if not specified)
• Service Principal (if not specified)
• kubeconfig configuration

Advanced Cluster Configuration:

# Create cluster with custom configuration
az aks create \
  --resource-group myResourceGroup \
  --name production-cluster \
  --kubernetes-version 1.28.0 \
  --node-count 3 \
  --node-vm-size Standard_DS2_v2 \
  --enable-cluster-autoscaler \
  --min-count 1 \
  --max-count 10 \
  --network-plugin azure \
  --network-policy azure \
  --enable-managed-identity \
  --enable-azure-rbac \
  --enable-private-cluster \
  --enable-addons monitoring \
  --workspace-resource-id /subscriptions/.../resourcegroups/.../providers/Microsoft.OperationalInsights/workspaces/myWorkspace

Method 2: Azure Portal

Creating via the Azure Portal provides a visual interface:

1. Navigate to AKS:

   • Go to Azure Portal → Kubernetes services → Create

2. Configure Cluster:

   • Resource group
   • Cluster name
   • Kubernetes version
   • Node pool configuration
   • Networking (Azure CNI or kubenet)
   • Authentication (Azure AD or local accounts)
   • Add-ons (monitoring, HTTP application routing)

3. Create Cluster:

   • Click Review + create
   • Wait for cluster creation

4. Configure kubectl:

   • Go to cluster → Connect
   • Run the provided command

Method 3: Terraform

For infrastructure as code, use Terraform:

# main.tf
terraform {
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 3.0"
    }
  }
}

provider "azurerm" {
  features {}
}

resource "azurerm_resource_group" "aks" {
  name     = "my-aks-rg"
  location = "East US"
}

resource "azurerm_kubernetes_cluster" "aks" {
  name                = "my-aks-cluster"
  location            = azurerm_resource_group.aks.location
  resource_group_name = azurerm_resource_group.aks.name
  dns_prefix          = "myakscluster"
  kubernetes_version  = "1.28.0"

  default_node_pool {
    name                = "default"
    node_count          = 3
    vm_size             = "Standard_DS2_v2"
    enable_auto_scaling = true
    min_count           = 1
    max_count           = 10
  }

  identity {
    type = "SystemAssigned"
  }

  network_profile {
    network_plugin    = "azure"
    network_policy    = "azure"
    load_balancer_sku = "standard"
  }

  addon_profile {
    http_application_routing {
      enabled = false
    }

    oms_agent {
      enabled                    = true
      log_analytics_workspace_id = azurerm_log_analytics_workspace.aks.id
    }
  }
}

resource "azurerm_log_analytics_workspace" "aks" {
  name                = "my-aks-workspace"
  location            = azurerm_resource_group.aks.location
  resource_group_name = azurerm_resource_group.aks.name
  sku                 = "PerGB2018"
}

Apply with:

terraform init
terraform plan
terraform apply

Method 4: ARM Templates

For Azure Resource Manager templates:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "clusterName": {
      "type": "string",
      "defaultValue": "myAKSCluster"
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.ContainerService/managedClusters",
      "apiVersion": "2023-01-01",
      "name": "[parameters('clusterName')]",
      "location": "[parameters('location')]",
      "properties": {
        "kubernetesVersion": "1.28.0",
        "dnsPrefix": "[parameters('clusterName')]",
        "agentPoolProfiles": [
          {
            "name": "default",
            "count": 3,
            "vmSize": "Standard_DS2_v2",
            "osType": "Linux",
            "mode": "System"
          }
        ],
        "networkProfile": {
          "networkPlugin": "azure"
        }
      }
    }
  ]
}

Cluster Configuration Options

Kubernetes Version

Choose a Kubernetes version supported by AKS:

# List available versions
az aks get-versions --location eastus --output table

# Create cluster with specific version
az aks create \
  --resource-group myResourceGroup \
  --name myAKSCluster \
  --kubernetes-version 1.28.0

Version Considerations:

• Use a recent stable version for new features
• Check AKS version support lifecycle
• Consider upgrade path when choosing version
• Test version compatibility with your applications

Virtual Network Configuration

AKS requires a Virtual Network with specific configuration:

Subnet Requirements:

• At least one subnet for nodes
• Sufficient IP addresses for pods (Azure CNI uses VNet IPs)
• Private subnets for nodes (recommended)
• Public subnets for load balancers (if needed)

CIDR Planning:

IP Address Planning:

• Reserve IPs for nodes (1 per node)
• Reserve IPs for pods (varies by node size with Azure CNI)
• Reserve IPs for Azure services (load balancers, etc.)
• Plan for growth and scaling

Networking Modes

AKS supports two networking modes:

Azure CNI (Advanced Networking):

• Pods get real VNet IP addresses
• Better performance and integration
• Requires IP address planning
• More complex setup

kubenet (Basic Networking):

• Pods use overlay network
• Simpler setup
• Less IP address planning
• NAT required for external access

# Create cluster with Azure CNI
az aks create \
  --resource-group myResourceGroup \
  --name myAKSCluster \
  --network-plugin azure \
  --vnet-subnet-id /subscriptions/.../resourceGroups/.../providers/Microsoft.Network/virtualNetworks/myVnet/subnets/mySubnet

# Create cluster with kubenet
az aks create \
  --resource-group myResourceGroup \
  --name myAKSCluster \
  --network-plugin kubenet

Initial Node Pool Setup

After creating the cluster, configure node pools:

Creating Node Pools

# Create additional node pool
az aks nodepool add \
  --resource-group myResourceGroup \
  --cluster-name myAKSCluster \
  --name compute-pool \
  --node-count 3 \
  --node-vm-size Standard_DS4_v2 \
  --enable-cluster-autoscaler \
  --min-count 1 \
  --max-count 10 \
  --node-taints compute=true:NoSchedule \
  --labels workload-type=compute

Node Pool Configuration Options:

• Virtual machine sizes and types
• Minimum, maximum, and initial node count
• Auto-scaling configuration
• Labels and taints
• Spot VMs for cost savings
• Windows node pools

Cluster Authentication

Configure kubectl to access your cluster:

Get Cluster Credentials

# Get cluster credentials
az aks get-credentials \
  --resource-group myResourceGroup \
  --name myAKSCluster

This updates ~/.kube/config with cluster credentials.

Verify Access

# Test cluster access
kubectl get nodes

# Should show your worker nodes
NAME                                STATUS   ROLES   AGE   VERSION
aks-default-12345678-vmss000000     Ready    agent   5m    v1.28.0
aks-default-12345678-vmss000001     Ready    agent   5m    v1.28.0
aks-default-12345678-vmss000002     Ready    agent   5m    v1.28.0

Azure AD Integration

Enable Azure AD integration for authentication:

# Enable Azure AD integration
az aks update \
  --resource-group myResourceGroup \
  --name myAKSCluster \
  --enable-aad \
  --enable-azure-rbac

Azure AD Benefits:

• Use Azure AD for Kubernetes authentication
• RBAC with Azure AD groups
• Multi-factor authentication support
• Centralized identity management

Post-Setup Configuration

After cluster creation, configure essential components:

Enable Monitoring

# Enable Azure Monitor for Containers
az aks enable-addons \
  --resource-group myResourceGroup \
  --name myAKSCluster \
  --addons monitoring \
  --workspace-resource-id /subscriptions/.../resourcegroups/.../providers/Microsoft.OperationalInsights/workspaces/myWorkspace

Enable Network Policy

# Enable network policy (requires Azure CNI)
az aks update \
  --resource-group myResourceGroup \
  --name myAKSCluster \
  --network-policy azure

Enable Private Cluster

# Enable private cluster
az aks update \
  --resource-group myResourceGroup \
  --name myAKSCluster \
  --enable-private-cluster

Best Practices

1. Use Azure CLI or Terraform - Avoid manual Portal creation for reproducibility

2. Plan VNet CIDR Carefully - Ensure sufficient IP space for pods and growth

3. Use Private Subnets for Nodes - More secure, use NAT gateway for outbound access

4. Enable Azure AD Integration - For enterprise authentication

5. Enable Monitoring - Set up Azure Monitor for Containers

6. Use Managed Identity - Instead of service principals when possible

7. Set Appropriate Scaling Limits - Configure min/max to prevent cost overruns

8. Tag Everything - Helps with cost allocation and resource management

9. Test in Non-Production First - Validate configuration before production

10. Document Your Setup - Keep track of configuration decisions and rationale

Common Issues

Insufficient IP Addresses

Problem: Pods can’t get IP addresses

Solution:

• Increase subnet CIDR size
• Use larger subnet for Azure CNI
• Consider using kubenet for simpler setup

Cluster Creation Fails

Problem: Cluster creation times out or fails

Solution:

• Check service principal permissions
• Verify resource group exists
• Check subscription quotas
• Review Azure Activity Log

kubectl Access Denied

Problem: Can’t access cluster with kubectl

Solution:

• Verify credentials are updated
• Check Azure AD permissions (if enabled)
• Verify cluster endpoint access
• Check Network Security Group rules

Next Steps

After cluster setup:

• Networking - Configure Azure CNI and networking
• Storage - Set up Azure Disk and Azure Files
• Security - Configure Azure AD, Workload Identity, and security
• Node Management - Manage and optimize node pools

See Also

• AKS Overview - Understanding AKS architecture
• Cluster Operations - General Kubernetes cluster management
• Troubleshooting - Common issues and solutions