hoangminhung/devops-ai-kit / claude/skills/playbook-aks
playbook-aks
VerifiedPlaybook for building or reworking an Azure Kubernetes Service (AKS) environment with Terraform — state backend, network and CIDR planning, Azure CNI Overlay, private vs public API server, Entra ID with Azure RBAC, workload identity, system and user node pools, upgrade channels and maintenance windows, monitoring and Log Analytics cost, policy, and a verification checklist. Use whenever the task is to build, extend, upgrade or review AKS or the Azure infrastructure around it.
Playbook: Build AKS with Terraform
Attribute names of azurerm_kubernetes_cluster change between major versions of the azurerm provider: some attributes were renamed or removed. Ask infra-researcher to check them for the exact provider version that is pinned before you write code.
1. Design questions (the plan must answer them)
Tier & size
- Baseline / Production / Enterprise (see
cloud-platforms). - How many clusters, which environments, which regions. Are Availability Zones needed?
Terraform
- Backend
azurerm,use_azuread_auth = true. - Separate state: network / cluster / add-on.
- Provider
azurermpinned with~>major. - CI logs in with OIDC (workload identity federation).
Network & CIDR (hard to change later, decide carefully)
- VNet and subnet for nodes; pod CIDR (overlay); service CIDR; DNS service IP.
- No overlap with VNets that are or will be peered, VPN, on-prem, and no overlap between clusters that will connect to each other.
- Network plugin: Azure CNI Overlay is the default choice for new clusters; it avoids running out of subnet IPs. The Azure-managed Cilium dataplane is CONTEXT (when you need advanced NetworkPolicy / network observability).
- Outbound: Load Balancer (default), or NAT Gateway (many outbound connections, fixed IP), or User Defined Routing through a firewall (enterprise).
API server
- Private cluster, or public with an IP limit (authorized IP ranges).
- If private: how do operators / CI / jump servers reach it (VPN, peering, jump host in the VNet)?
Identity & access
- Entra ID integration + Azure RBAC for Kubernetes; turn off local accounts on production.
- Which Entra groups get which permissions.
- A break-glass path for when Entra has problems.
- Turn on OIDC issuer + Workload Identity. Pods use federated credentials, not service principal secrets.
Node pools
- A separate system pool with taint
CriticalAddonsOnly(only for system add-ons), at least 2–3 nodes, spread across zones. - User pool for workloads; separate pools for stateful / GPU if needed.
- VM SKU, autoscaler min / max, max surge during upgrades, OS disk (ephemeral if the SKU supports it).
- CONTEXT Spot pool for workloads that can handle interruptions.
Upgrades
- Auto-upgrade channel for the cluster and for the node OS image; a maintenance window in low-traffic hours.
- Who watches the notices about AKS versions that will lose support.
Storage
- The default Azure Disk StorageClass uses
WaitForFirstConsumer(correct zone). - Important data uses a StorageClass with
reclaimPolicy: Retain(you usually need to create it).
Observability
- Managed Prometheus + Managed Grafana, or self-hosted (see
playbook-monitoring-stack). - Container Insights / diagnostic logs: choose only the tables / namespaces you need. Log Analytics charges per GB.
Security & policy
- Azure Policy add-on (baseline pod security).
- Images only from allowed ACRs (ACR attached to the cluster with a managed identity, not the ACR admin user).
- Key Vault + ESO (or Secrets Store CSI driver).
- Defender for Containers: CONTEXT.
Cost
-
infracostfor Terraform; also estimate Log Analytics, egress, public IPs, disks. - Budget + alerts.
GitOps / add-ons
- How Argo CD or Flux (AKS extension) is installed.
- Which add-ons Terraform manages and which GitOps manages. Make the boundary clear so two tools never manage the same thing.
2. Common risks
| Risk | How to avoid it |
|---|---|
| CIDR overlap found after peering / VPN | A CIDR plan table in the plan, reviewed before apply |
| An attribute change makes Terraform replace the whole cluster / node pool | Read the plan carefully: any -/+ on a cluster / node pool means stop; many node pool attributes are immutable |
| Private cluster, but CI / jump servers have no way in | Design the access path first; test with kubectl get nodes from the right machine |
| Local accounts turned off before the Entra admin group works | Assign and test Entra permissions first; have break-glass |
| Log Analytics bill jumps | Selective data collection rules; watch ingest in the first week |
| Auto-upgrade breaks workloads without PDB / probes | PDB + probes for important workloads; maintenance window |
3. Verification checklist
| Check | Suggested command | Expected |
|---|---|---|
| Cluster | az aks show -g <rg> -n <name> --query "{state:provisioningState,power:powerState.code,k8s:currentKubernetesVersion}" | Succeeded · Running · correct version |
| Nodes | kubectl get nodes -o wide | Ready; correct number of nodes / zones / pools |
| System pool | kubectl get nodes -l kubernetes.azure.com/mode=system + check taints | Has taint CriticalAddonsOnly |
| Identity | kubectl auth can-i with the Entra groups; local accounts turned off (prod) | Permissions match the design |
| Workload Identity | A test pod uses a ServiceAccount with a federated credential and reads Key Vault | Works, no secret needed |
| Network | A test pod resolves internal / external DNS, reaches the needed egress endpoints | Works; outbound IP matches the design |
| Storage | Create a test PVC on each StorageClass, mount it in a pod, write / read, delete | Bound in the right zone; data can be read back |
| Monitoring | Cluster metrics / logs show up in the observability system | New data arrives |
| Terraform | terraform plan right after apply | No changes |
4. Docs to leave behind
- A CIDR plan table (ADR or runbook).
- A cluster runbook: access (VPN / jump host), upgrade, scaling node pools, rotating credentials, break-glass.
- A concept note on AKS networking (CNI Overlay, outbound) if the user is new to it.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |