Add localdns config

Author: anson627

examples/localdns_config/README.md

@@ -0,0 +1,89 @@
+# LocalDNS Configuration Example
+
+This example demonstrates how to use the `localdns_config` feature in the terraform-azurerm-aks module to configure LocalDNS settings for your AKS cluster.
+
+## Overview
+
+LocalDNS in AKS allows you to customize DNS resolution behavior for pods with different DNS policies:
+
+- **VNet DNS Overrides**: Configuration for pods using `dnsPolicy: default` (uses VNet DNS)
+- **Kube DNS Overrides**: Configuration for pods using `dnsPolicy: ClusterFirst` (uses Kubernetes CoreDNS)
+
+## Configuration Features
+
+This example configures:
+
+1. **Mode**: Set to `Required` to enforce LocalDNS usage
+2. **VNet DNS Overrides**:
+   - Root zone (`.`) configured to use VNet DNS with caching and stale serving
+   - Custom zone (`example.local`) with round-robin policy
+3. **Kube DNS Overrides**:
+   - Cluster-local zone (`cluster.local`) using CoreDNS with enhanced caching
+   - Service discovery zone (`svc.cluster.local`) for Kubernetes services
+
+## Key Configuration Options
+
+### DNS Zone Configuration
+
+Each zone can be configured with:
+
+- **Query Logging**: Set to `Error` or `Log` for different verbosity levels
+- **Protocol**: `PreferUDP` (default) or `ForceTCP` for transport protocol
+- **Forward Destination**: `VnetDNS` or `ClusterCoreDNS` based on the zone type
+- **Forward Policy**: `Random`, `RoundRobin`, or `Sequential` for upstream server selection
+- **Caching**: Configure cache duration and stale serving policies
+- **Concurrency**: Control maximum concurrent queries
+
+### Important Constraints
+
+- Root zone (`.`) under `vnet_dns_overrides` cannot use `ClusterCoreDNS`
+- Zone `cluster.local` cannot use `VnetDNS` as forward destination
+- When protocol is `ForceTCP`, serve_stale cannot be `Verify`
+
+## Usage
+
+1. Set your Azure credentials:
+   ```bash
+   export ARM_CLIENT_ID="your-client-id"
+   export ARM_CLIENT_SECRET="your-client-secret"
+   export ARM_SUBSCRIPTION_ID="your-subscription-id"
+   export ARM_TENANT_ID="your-tenant-id"
+   ```
+
+2. Initialize and apply Terraform:
+   ```bash
+   terraform init
+   terraform plan
+   terraform apply
+   ```
+
+3. Connect to your AKS cluster:
+   ```bash
+   az aks get-credentials --resource-group $(terraform output -raw resource_group_name) --name $(terraform output -raw aks_cluster_name)
+   ```
+
+## Testing LocalDNS Configuration
+
+After deployment, you can test the LocalDNS configuration:
+
+```bash
+# Test DNS resolution from a pod
+kubectl run -it --rm debug --image=busybox --restart=Never -- nslookup kubernetes.default.svc.cluster.local
+
+# Check LocalDNS pods
+kubectl get pods -n kube-system -l k8s-app=node-local-dns
+
+# View LocalDNS configuration
+kubectl get configmap node-local-dns -n kube-system -o yaml
+```
+
+## Cleanup
+
+```bash
+terraform destroy
+```
+
+## More Information
+
+- [Azure LocalDNS Documentation](https://learn.microsoft.com/en-us/azure/aks/localdns-custom)
+- [Kubernetes DNS Policies](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#pod-s-dns-policy)

examples/localdns_config/main.tf

@@ -0,0 +1,129 @@
+resource "random_id" "prefix" {
+  byte_length = 8
+}
+
+resource "random_id" "name" {
+  byte_length = 8
+}
+
+resource "azurerm_resource_group" "main" {
+  count = var.create_resource_group ? 1 : 0
+
+  location = var.location
+  name     = coalesce(var.resource_group_name, "${random_id.prefix.hex}-rg")
+}
+
+locals {
+  resource_group = {
+    name     = var.create_resource_group ? azurerm_resource_group.main[0].name : var.resource_group_name
+    location = var.location
+  }
+}
+
+resource "azurerm_virtual_network" "test" {
+  address_space       = ["10.52.0.0/16"]
+  location            = local.resource_group.location
+  name                = "${random_id.prefix.hex}-vn"
+  resource_group_name = local.resource_group.name
+}
+
+resource "azurerm_subnet" "test" {
+  address_prefixes     = ["10.52.0.0/24"]
+  name                 = "${random_id.prefix.hex}-sn"
+  resource_group_name  = local.resource_group.name
+  virtual_network_name = azurerm_virtual_network.test.name
+}
+
+module "aks" {
+  source = "../.."
+
+  location                  = local.resource_group.location
+  prefix                    = random_id.name.hex
+  rbac_aad_tenant_id        = data.azurerm_client_config.current.tenant_id
+  resource_group_name       = local.resource_group.name
+  kubernetes_version        = "1.30" # don't specify the patch version!
+  automatic_channel_upgrade = "patch"
+  agents_availability_zones = ["1", "2"]
+  agents_count              = null
+  agents_max_count          = 2
+  agents_max_pods           = 100
+  agents_min_count          = 1
+  agents_pool_name          = "testnodepool"
+  agents_size               = "Standard_DS2_v2"
+  auto_scaling_enabled      = true
+  client_id                 = var.client_id
+  client_secret             = var.client_secret
+  enable_auto_scaling       = true
+  log_analytics_workspace_enabled = true
+  net_profile_dns_service_ip      = "10.0.0.10"
+  net_profile_service_cidr        = "10.0.0.0/16"
+  network_plugin                  = "azure"
+  orchestrator_version            = "1.30"
+  os_disk_size_gb                 = 60
+  private_cluster_enabled         = false
+  rbac_aad                        = true
+  rbac_aad_managed                = true
+  role_based_access_control_enabled = true
+  sku_tier                        = "Standard"
+  vnet_subnet_id                  = azurerm_subnet.test.id
+
+  # LocalDNS configuration example
+  localdns_config = {
+    mode = "Required"
+
+    # Configuration for pods using dnsPolicy:default (VNet DNS)
+    vnet_dns_overrides = {
+      zones = {
+        # Root zone configuration - uses VNet DNS
+        "." = {
+          query_logging                   = "Error"
+          protocol                       = "PreferUDP"
+          forward_destination            = "VnetDNS"
+          forward_policy                 = "Random"
+          max_concurrent                 = 150
+          cache_duration_in_seconds      = 300
+          serve_stale_duration_in_seconds = 86400
+          serve_stale                    = "Immediate"
+        }
+        # Custom zone configuration
+        "example.local" = {
+          query_logging       = "Log"
+          protocol           = "PreferUDP"
+          forward_destination = "VnetDNS"
+          forward_policy     = "RoundRobin"
+          max_concurrent     = 100
+        }
+      }
+    }
+
+    # Configuration for pods using dnsPolicy:ClusterFirst (Kubernetes DNS)
+    kube_dns_overrides = {
+      zones = {
+        # Cluster-local zone - uses Kubernetes CoreDNS
+        "cluster.local" = {
+          query_logging                   = "Error"
+          protocol                       = "PreferUDP"
+          forward_destination            = "ClusterCoreDNS"
+          forward_policy                 = "Sequential"
+          max_concurrent                 = 200
+          cache_duration_in_seconds      = 600
+          serve_stale_duration_in_seconds = 3600
+          serve_stale                    = "Verify"
+        }
+        # Service discovery zone
+        "svc.cluster.local" = {
+          query_logging       = "Log"
+          protocol           = "PreferUDP"
+          forward_destination = "ClusterCoreDNS"
+          forward_policy     = "Random"
+        }
+      }
+    }
+  }
+
+  depends_on = [
+    azurerm_subnet.test,
+  ]
+}
+
+data "azurerm_client_config" "current" {}

examples/localdns_config/outputs.tf

@@ -0,0 +1,59 @@
+output "aks_cluster_name" {
+  description = "Name of the AKS cluster"
+  value       = module.aks.cluster_name
+}
+
+output "aks_cluster_id" {
+  description = "ID of the AKS cluster"
+  value       = module.aks.cluster_id
+}
+
+output "cluster_ca_certificate" {
+  description = "Base64 encoded certificate data required to communicate with the cluster"
+  value       = module.aks.cluster_ca_certificate
+  sensitive   = true
+}
+
+output "client_certificate" {
+  description = "Base64 encoded public certificate used by clients to authenticate to the cluster"
+  value       = module.aks.client_certificate
+  sensitive   = true
+}
+
+output "client_key" {
+  description = "Base64 encoded private key used by clients to authenticate to the cluster"
+  value       = module.aks.client_key
+  sensitive   = true
+}
+
+output "host" {
+  description = "The Kubernetes cluster server host"
+  value       = module.aks.host
+  sensitive   = true
+}
+
+output "kube_config" {
+  description = "Raw Kubernetes config to be used by kubectl and other compatible tools"
+  value       = module.aks.kube_config_raw
+  sensitive   = true
+}
+
+output "localdns_config" {
+  description = "LocalDNS configuration applied to the cluster"
+  value       = module.aks.localdns_config
+}
+
+output "resource_group_name" {
+  description = "Name of the resource group"
+  value       = local.resource_group.name
+}
+
+output "subnet_id" {
+  description = "ID of the subnet used by the AKS cluster"
+  value       = azurerm_subnet.test.id
+}
+
+output "vnet_id" {
+  description = "ID of the virtual network used by the AKS cluster"
+  value       = azurerm_virtual_network.test.id
+}

examples/localdns_config/providers.tf

@@ -0,0 +1,23 @@
+terraform {
+  required_providers {
+    azapi = {
+      source  = "Azure/azapi"
+      version = ">=2.0, < 3.0"
+    }
+    azurerm = {
+      source  = "hashicorp/azurerm"
+      version = ">= 4.16.0, < 5.0"
+    }
+    random = {
+      source  = "hashicorp/random"
+      version = "~>3.0"
+    }
+  }
+  required_version = ">= 1.3"
+}
+
+provider "azurerm" {
+  features {}
+}
+
+provider "azapi" {}

examples/localdns_config/variables.tf

@@ -0,0 +1,27 @@
+variable "client_id" {
+  description = "The Client ID which should be used."
+  type        = string
+  default     = ""
+}
+
+variable "client_secret" {
+  description = "The Client Secret which should be used."
+  type        = string
+  default     = ""
+}
+
+variable "create_resource_group" {
+  description = "Whether to create resource group and use it for all networking resources"
+  default     = true
+}
+
+variable "location" {
+  default     = "East US"
+  description = "The location where the Managed Kubernetes Cluster should be created."
+}
+
+variable "resource_group_name" {
+  description = "The resource group name to be imported"
+  type        = string
+  default     = null
+}

main.tf

@@ -745,3 +745,57 @@ resource "azapi_update_resource" "aks_cluster_http_proxy_config_no_proxy" {
     replace_triggered_by = [null_resource.http_proxy_config_no_proxy_keeper[0].id]
   }
 }
+
+# LocalDNS configuration trigger resource
+resource "null_resource" "localdns_config_keeper" {
+  count = var.localdns_config != null ? 1 : 0
+  triggers = {
+    localdns_config = jsonencode(var.localdns_config)
+  }
+}
+
+# Apply LocalDNS configuration using azapi
+resource "azapi_update_resource" "aks_cluster_localdns_config" {
+  count = var.localdns_config != null ? 1 : 0
+
+  resource_id = azurerm_kubernetes_cluster.main.id
+  type        = "Microsoft.ContainerService/managedClusters@2024-02-01"
+  body = {
+    properties = {
+      localDNSConfig = {
+        mode = var.localdns_config.mode
+        vnetDNSOverrides = var.localdns_config.vnet_dns_overrides != null ? {
+          for zone_name, zone_config in var.localdns_config.vnet_dns_overrides.zones : zone_name => {
+            queryLogging                = zone_config.query_logging
+            protocol                    = zone_config.protocol
+            forwardDestination          = zone_config.forward_destination
+            forwardPolicy               = zone_config.forward_policy
+            maxConcurrent               = zone_config.max_concurrent
+            cacheDurationInSeconds      = zone_config.cache_duration_in_seconds
+            serveStaleDurationInSeconds = zone_config.serve_stale_duration_in_seconds
+            serveStale                  = zone_config.serve_stale
+          }
+        } : null
+        kubeDNSOverrides = var.localdns_config.kube_dns_overrides != null ? {
+          for zone_name, zone_config in var.localdns_config.kube_dns_overrides.zones : zone_name => {
+            queryLogging                = zone_config.query_logging
+            protocol                    = zone_config.protocol
+            forwardDestination          = zone_config.forward_destination
+            forwardPolicy               = zone_config.forward_policy
+            maxConcurrent               = zone_config.max_concurrent
+            cacheDurationInSeconds      = zone_config.cache_duration_in_seconds
+            serveStaleDurationInSeconds = zone_config.serve_stale_duration_in_seconds
+            serveStale                  = zone_config.serve_stale
+          }
+        } : null
+      }
+    }
+  }
+
+  depends_on = [azapi_update_resource.aks_cluster_post_create]
+
+  lifecycle {
+    ignore_changes       = all
+    replace_triggered_by = [null_resource.localdns_config_keeper[0].id]
+  }
+}