--- name: apex-azure-kubernetes user-invocable: true disable-model-invocation: false argument-hint: "workload requirements, environment type, region and constraints" description: '**ANALYSIS SKILL** — Day-0 AKS design advice: Automatic vs Standard, networking, identity, observability, upgrades, node pools, autoscaling and Spot. WHEN: "design AKS", "AKS Automatic or Standard", "AKS networking", "AKS node pools", "rightsize AKS pods", "AKS spot nodes". DO NOT USE FOR: AKS troubleshooting (apex-azure-diagnostics), provisioning or IaC (05-IaC Planner, 06b/06t).' license: MIT metadata: author: Microsoft version: "1.2.2" --- # Azure Kubernetes Service Design Adapted from upstream `azure-kubernetes`. This skill recommends an AKS configuration and separates **Day-0 decisions** (networking, API server access, identity — hard to change later) from **Day-1 features** that can be enabled after creation. It advises; it never creates or changes a cluster. ## Quick Reference | Property | Value | | --------------- | --------------------------------------------------------------------------------------- | | Best for | AKS cluster planning and Day-0 decisions in Steps 2 and 4 | | MCP tools | `mcp_azure-mcp_aks` (read-only discovery of existing clusters) | | Implementation | AVM `avm/res/container-service/managed-cluster` (Bicep) or `Azure/avm-res-containerservice-managedcluster/azurerm` (Terraform) through 06b/06t | | Related skills | `apex-azure-diagnostics` (troubleshooting), `apex-azure-quotas` (node SKU availability and quota), `apex-azure-defaults` (naming, regions, AVM) | ## Rules 1. Start from the user's requirements; ask only for missing Day-0 inputs. 2. Default to **AKS Automatic** unless a requirement needs Standard (custom node pools, networking or autoscaling that Node Auto-Provisioning doesn't support). Confirm the chosen features are exposed by the AVM module before recommending them. 3. Record each Day-0 decision with its rationale; they are expensive to change after creation. 4. Apply the APEX baseline: private API server access (API Server VNet Integration or a private cluster) for production, Microsoft Entra ID authentication with local accounts disabled, Workload Identity for pods, and the default region from `apex-azure-defaults` with availability zones. 5. Confirm node VM sizes with the `apex-azure-quotas` [SKU availability](../apex-azure-quotas/references/sku-availability.md) check. Price only through `cost-estimate-subagent`; don't quote discounts or savings percentages. 6. Never run `az aks` or `kubectl` commands that change state. Hand the configuration to 05-IaC Planner and 06b/06t; existing-cluster changes need an approved change owner. ## Required Inputs Use safe defaults when the user is unsure. - Environment type (dev/test or production), region and zones - Expected scale (nodes, clusters, workload size) and preferred node VM sizes - Networking: API server access, pod IP model, ingress and egress control - Security and identity, including the image registry - Upgrade and observability preferences, and cost constraints ## Design Checklist ### 1. Cluster Type - **AKS Automatic** (default): curated security, reliability and performance defaults for most production workloads. - **AKS Standard**: full control of node pools, networking and autoscaling at the cost of more operations work. ### 2. Networking (Day-0) - **Pod IP model**: Azure CNI Overlay (recommended; pod IPs from a private overlay range) or Azure CNI with VNet-routable pod IPs when pods must be addressable from the VNet or on-premises. See [Azure CNI Overlay](https://learn.microsoft.com/azure/aks/azure-cni-overlay). - **Dataplane and network policy**: Azure CNI powered by Cilium. - **Egress**: Static Egress Gateway for stable outbound IPs; UDR with Azure Firewall or an NVA for restricted egress. - **Ingress**: App Routing add-on with Gateway API by default; Istio with Gateway API for mTLS and canary releases; Application Gateway for Containers for L7 load balancing with WAF. - **DNS**: enable LocalDNS on all node pools. ### 3. Security - Microsoft Entra ID everywhere (control plane, Workload Identity for pods, node access); no static credentials. See [workload identity](references/workload-identity.md). - Azure Key Vault through the Secrets Store CSI Driver. - Azure Policy with [Deployment Safeguards](references/safeguards.md). - Encryption at rest and in transit; only signed, policy-approved images, preferably from Azure Container Registry. - Isolate with namespaces, network policies and scoped logging. ### 4. Observability - Managed Prometheus, Container Insights and Grafana for metrics and logs. - Diagnostic settings sending control plane and audit logs to Log Analytics. ### 5. Upgrades and Patching - Maintenance windows, and auto-upgrade for the control plane and node OS. - LTS versions (Premium tier) for enterprise stability; AKS Fleet Manager for staged rollouts across environments. ### 6. Performance - Ephemeral OS disks, Azure Linux node OS, and KEDA for event-driven autoscaling beyond HPA. ### 7. Node Pools and Compute - A dedicated system node pool of at least 2 nodes, tainted `CriticalAddonsOnly`. - Node Auto-Provisioning where supported; latest-generation VM sizes with at least 4 vCPUs for production. - Avoid B-series (burstable) VMs; spread pods across hosts and zones with topology spread constraints. ### 8. Reliability - Three availability zones, the Standard tier (zone-redundant control plane with an SLA), PodDisruptionBudgets for production workloads, and Microsoft Defender for Containers. ### 9. Cost - Spot node pools only for interruptible workloads; stop dev/test clusters outside working hours through an approved operational runbook; consider reservations or savings plans for steady-state capacity. ## Deep-Dive Scenarios Load only the reference that matches the request; if a prompt matches several, ask which one the user means. | Scenario | Trigger keywords | Reference | | ------------------ | ----------------------------------------------------------- | ----------------------------------------------------------- | | Pod rightsizing | over-provisioned pods, CPU or memory requests | [azure-aks-rightsizing.md](references/azure-aks-rightsizing.md) | | VPA | vertical pod autoscaler, VPA recommendations | [azure-aks-vpa.md](references/azure-aks-vpa.md) | | Cluster autoscaler | idle nodes, scale-down profile, node utilization | [azure-aks-autoscaler.md](references/azure-aks-autoscaler.md) | | Spot node pools | Spot VMs, batch workloads, cheaper nodes | [azure-aks-spot.md](references/azure-aks-spot.md) | ## Guardrails - Don't request or output secrets, tokens or keys, and don't ask the user to paste subscription IDs; discover scope with `mcp_azure-mcp_subscription_list` or `az account show`. - For ambiguous Day-0 requirements, ask. For Day-1 features, offer two or three safe options with trade-offs. - Don't promise zero downtime; recommend PodDisruptionBudgets, probes, replicas and staged upgrades. - Inspect existing clusters only with the read-only commands in the [CLI reference](references/cli-reference.md). ## Reference Index | Reference | When to Load | | ------------------------------------- | ---------------------------------------------------- | | `references/azure-aks-rightsizing.md` | Pod request and limit rightsizing | | `references/azure-aks-vpa.md` | Vertical Pod Autoscaler recommendations | | `references/azure-aks-autoscaler.md` | Cluster autoscaler tuning | | `references/azure-aks-spot.md` | Spot node pool design | | `references/workload-identity.md` | Workload Identity setup for pods | | `references/safeguards.md` | Deployment Safeguards rules for workload manifests | | `references/cli-reference.md` | Read-only inspection commands |