terraform-azure-aks | Architecture

Executive Summary

Production-grade Terraform module for deploying Azure Kubernetes Service (AKS) clusters with enterprise features. Provisions a private AKS cluster with system/user node pools across three availability zones, Azure CNI Overlay networking with Cilium dataplane, workload identity (OIDC), Microsoft Defender for Containers, Azure Policy, Key Vault CSI driver, image cleaner, and integrated ACR pull access. Designed for organizations requiring a secure, scalable, GitOps-ready Kubernetes platform on Azure.

Overview Cards

Resources

AKS Cluster, Node Pools, ACR Role

Variables

6 required, 15 optional

Outputs

Cluster IDs, FQDN, Identities

Provider

azurerm

>= 3.80.0

Terraform

>= 1.5.0

HCL Configuration

Network

CNI + Cilium

Overlay mode, eBPF dataplane

Architecture Diagram

AKS Control Plane

Private API Server

↓

System Node Pool

AZ1/AZ2/AZ3 - Critical Addons

User Node Pool(s)

General / GPU / Spot

↓

Azure CNI Overlay

Cilium Network Policy + Dataplane

VNet Subnet

vnet_subnet_id

↓

Workload Identity

OIDC Issuer

Microsoft Defender

Threat Detection

Azure Policy

Compliance

Key Vault CSI

Secret Rotation

↓

Log Analytics

Container Insights / OMS

ACR Integration

AcrPull Role Assignment

Component Breakdown

Component	Resource Type	Purpose	Configuration
AKS Cluster	`azurerm_kubernetes_cluster`	Managed Kubernetes control plane + default node pool	Private, Standard SKU, SystemAssigned identity
Additional Node Pools	`azurerm_kubernetes_cluster_node_pool`	User workload node pools (GPU, spot, memory-optimized)	for_each map, auto-scaling, taints/labels
ACR Pull Role	`azurerm_role_assignment`	Grants kubelet identity AcrPull on Container Registry	Conditional on acr_id
Network Profile	Inline block	Azure CNI Overlay + Cilium eBPF	Pod CIDR 10.244.0.0/16, Service CIDR 10.0.0.0/16
Workload Identity	Inline feature	OIDC-based pod identity federation	Enabled by default
Key Vault CSI	Inline add-on	Mount Key Vault secrets into pods	Secret rotation every 2m
Defender	Inline block	Runtime threat detection for containers	Requires Log Analytics
Maintenance Window	Inline block	Scheduled cluster maintenance	Allowed/not-allowed windows

Data Flow

Developer pushes container image to Azure Container Registry (ACR).

AKS kubelet identity pulls images from ACR via AcrPull role assignment.

Pods are scheduled on system or user node pools across availability zones.

Azure CNI Overlay with Cilium routes traffic; network policies enforce microsegmentation.

Workload Identity federates pod service accounts with Azure AD for passwordless Azure resource access.

Key Vault CSI driver injects secrets directly into pod volumes with auto-rotation.

OMS Agent ships logs/metrics to Log Analytics; Defender monitors for runtime threats.

Security Controls

Control	Implementation	Default
Private Cluster	API server accessible only within VNet	Enabled
RBAC	Kubernetes RBAC + Azure AD RBAC	Enabled (always on)
Workload Identity	OIDC issuer + federated credentials	Enabled
Network Policy	Cilium eBPF-based pod network policies	Cilium
Microsoft Defender	Runtime threat detection, vulnerability scanning	Enabled
Azure Policy	Enforce organizational standards on clusters	Enabled
Key Vault Integration	CSI driver with secret rotation (2m)	Enabled
Image Cleaner	Automatic stale image cleanup (48h)	Enabled
API Server Access	Authorized IP ranges whitelist	Optional

Industry Adaptation

Capability	Healthcare	Finance	Government	Retail	SaaS
Private Cluster	✓	✓	✓	✓	✓
Azure Policy	✓ HIPAA	✓ PCI-DSS	✓ FedRAMP	✓	✓
Defender	✓	✓	✓	✓	✓
Workload Identity	✓	✓	✓	✓	✓
Network Policy	✓	✓	✓	✓	✓
Multi-AZ	✓	✓	✓	✓	✓
Audit Logging	✓	✓	✓	Optional	Optional

Production Readiness Checklist

Enable private cluster (private_cluster_enabled = true)
Configure Azure AD admin group for RBAC
Set authorized IP ranges for API server access
Enable Microsoft Defender and Azure Policy
Attach Log Analytics workspace for monitoring
Enable workload identity and OIDC issuer
Configure maintenance windows for planned updates
Set up node pool auto-scaling with appropriate min/max
Integrate ACR with AcrPull role for image pulls
Enable Key Vault CSI driver for secret management
Spread node pools across 3 availability zones
Separate system and user node pools (CriticalAddonsOnly)

Configuration Reference

Variable	Type	Default	Description
`cluster_name`	string	required	Name of the AKS cluster
`kubernetes_version`	string	required	Kubernetes version
`vnet_subnet_id`	string	required	Subnet ID for default node pool
`private_cluster_enabled`	bool	true	Enable private API server
`sku_tier`	string	Standard	Free, Standard, or Premium
`network_policy`	string	cilium	Network policy engine
`default_node_pool`	object	required	System node pool configuration
`additional_node_pools`	map(object)	{}	User node pools map
`enable_workload_identity`	bool	true	Workload identity federation
`enable_defender`	bool	true	Microsoft Defender for Containers
`acr_id`	string	null	ACR ID for AcrPull role

Deployment

# Initialize
terraform init

# Plan
terraform plan -out=tfplan \
  -var="cluster_name=my-aks" \
  -var="resource_group_name=rg-aks" \
  -var="location=eastus" \
  -var="kubernetes_version=1.29" \
  -var="dns_prefix=myaks" \
  -var='vnet_subnet_id=/subscriptions/.../subnets/aks'

# Apply
terraform apply tfplan

# Get credentials
az aks get-credentials --resource-group rg-aks --name my-aks

Links

Azure AKS Documentation | Terraform AKS Resource | Module README | Examples