skilld
All skills
lukemurraynz avatar

/aks-cluster-architecture

@2cc2455
by Luke Murraylukemurraynz/hve-agent-skills1 stars
1

AKS cluster architecture decisions for new Azure Kubernetes Service projects: AKS Automatic vs Standard, networking topology, dual-stack (IPv4/IPv6), Kubernetes version and OS currency, node pool strategy, identity, production NetworkPolicy, namespaces, autoscaling, ingress and Gateway API, observability, operations, resilience, GPU and AI workloads, GPU partitioning (MIG, time-slicing, MPS), batch scheduling (Kueue), AKS on bare metal, AI Runway and KAITO model serving, AKS MCP server access, kars (Agent Reference Stack for Kubernetes) for agent isolation, Kata MicroVM pod sandboxing, Azure Kubernetes Fleet Manager, multi-cluster governance, update orchestration, resource placement, cross-cluster networking, and cost. WHEN: designing new AKS clusters, reviewing production readiness, choosing CNI or outbound connectivity, planning node pools, defining namespace, network and security controls, evaluating Fleet Manager, deploying AI agent runtimes on AKS, or making hard-to-reverse infrastructure decisions.

Ask your Agent

Use this Skill: https://skilld.dev/gh/lukemurraynz/hve-agent-skills/aks-cluster-architecture

This session only. Nothing lands on disk.

CHANGELOG.md

≈21k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Changelog

All notable changes to the aks-cluster-architecture skill. Versioning follows SemVer:

  • MAJOR - breaking restructure of bundles, routing, or contract.
  • MINOR - new capability surfaces, new bundles, additive content beyond drift correction.
  • PATCH - drift corrections, anchor fixes, currency refreshes, and editorial tightening.

3.21.0 - 2026-08-26

MINOR. Full-mode improve-skill audit (4.11.0), one day after the 3.20.0 full run; confirmed-correct carried forward and evidence concentrated on post-2026-08-25 drift. Primary drivers: two GA capability deltas missed by prior sweeps (control-plane metrics, eBPF Host Routing) plus a Critical stale-flag example in the fleet guide.

Added

  • SKILL.md — new "August 26, 2026 currency updates" section: Control plane metrics via Managed Prometheus GA (--enable-control-plane-metrics + --enable-azure-monitor-metrics, managed identity required, Private Link unsupported, self-hosted Prometheus excluded, default targets apiserver+etcd); ACNS eBPF Host Routing GA (June 2026) with the full incompatibility set (Static Egress Gateway, CVMs, Pod Sandboxing, Windows, Istio Ambient self-managed); Artifact Streaming on NAP pools via AKSNodeClass; fleet CLI surface correction stamp.
  • bundles/operations-resilience/guide.md — Observability Baseline gains the control-plane metrics bullet with the enabled≠collecting asymmetry warning (mirrors the existing omsAgent lesson), flag pairing, configmap schema-v2 note, and workspace-series verification command. SecurityPatch channel row gains the live-patch-in-place nuance and Windows-pool exclusion (verified against auto-upgrade-node-os-image).
  • bundles/cluster-foundations/guide.md — new "eBPF Host Routing (ACNS Container Network Performance, GA)" subsection: enable/disable flags, K8s ≥1.33 / CLI ≥2.71 / Azure Linux 3.0 or Ubuntu 24.04 gates, cluster-wide-only semantics, node label, rolling-upgrade-on-enable (Difficult classification), iptables bypass-and-block behaviour with the host-firewall-agent implication, and the verified mutual exclusions including Static Egress Gateway. Static Egress Gateway constraints row gains the reciprocal eBPF-host-routing exclusion pointer.
  • bundles/workload-platform/guide.md — NAP decision-matrix row concretized (Cilium-overlay requirement, named unsupported combinations, az aks show --query nodeProvisioningProfile check replacing the bare "verify" dead-end); autoscaling rules gain the Artifact Streaming × NAP note (AKSNodeClass spec.artifactStreaming, Premium ACR prerequisite).
  • SKILL.md Hidden API Surface Properties table — six rows added from the live 2026-06-01 spec diff: aiToolchainOperatorProfile, bootstrapProfile, httpProxyConfig, podIdentityProfile, diskEncryptionSetID, powerState. Glossary ACNS entry extended with Host Routing + per-feature gating. Output Contract §8 routes control-plane metrics.

Corrected

  • Critical — bundles/fleet-management/guide.md stale CLI flags. The auto-upgrade profile creation example used --upgrade-type NodeImage and --update-strategy-name; neither is a current flag of az fleet autoupgradeprofile create. Corrected to --channel NodeImage (channel enum documented inline: NodeImage/Rapid/SecurityPatch/Stable/TargetKubernetesVersion) and --update-strategy-id <resource-id>, verified against the az CLI reference (fleet extension, GA commands) fetched 2026-08-26.
  • High — link rot: fleet Security patch citation pointed at learn.microsoft.com/azure/kubernetes-fleet/updates-auto-upgrade-profiles, a URL that never existed under either docset root; replaced with update-automation and enriched the row with Linux-only/live-patching-first semantics and the SecurityPatch CLI value. All other body-cited learn.microsoft.com URLs (31 unique) resolved HTTP 200 this run.

Reviewed and deliberately not imported

ACNS WireGuard/Cilium mTLS encryption surfaces (transport-level detail below the architecture cut-line; revisit if a design question surfaces). CNL label-selector doc fix (skill documents no CNL configuration). schedulerProfile property (niche tuning, not an architecture decision). Cluster-level SecurityPatch wording left substantively intact after verification against Learn (only nuance added).

Validator

  • python scripts/validate-skill.py . → OK: 0 errors, 0 warning(s) (2026-08-26).

3.20.0 - 2026-08-25

MINOR. Full-mode improve-skill audit (4.8.0). Primary driver: AKS Release 2026-08-07 (published 2026-08-11) shipped after the 3.19.0 verification passes and was missing entirely; every material fact below verified against primary sources (AKS releases page, Learn pages ms.date 2026-08-05/08-19/08-24, azure-aks-docs commits through 2026-08-24, TypeSpec spec folder listing).

Added

  • SKILL.md — new "August 25, 2026 currency updates" section adopting Release 2026-08-07: Node Pool Rollback GA; automatic availability-zone placement global (availabilityZones=["auto"], existing VMSS pools updatable); control-plane-only upgrades into LTS; K8s 1.37 preview Sep / GA Oct 2026; K8s 1.37+ immediate-reimage triggers (SSH config, IMDS restriction, bootstrap profile, outbound type; SP→MI conversion reimages all pools) gated via Node Disruption Policy; VMSS 1,000-instance surge validation preflight; EiT × Workload Identity for Azure Files GA; minor stamps (Istio Gateway API automount=false, MIG slice-width validation, Entra SSH rejected on ACL, NAP on restricted publicNetworkAccess, CRG association with existing pools).
  • bundles/operations-resilience/guide.md — Node Pool Rollback section upgraded Preview→GA with the full constraint set from Roll back node pool versions: OS-SKU changes not revertible, security-regression risk, Operation Status API monitoring, and a window-vs-triage note pairing the 7-day clock with maintenance-window design; NDP coverage bullet updated to the version-dependent 1.37+ surface; T-1 week checklist gains the surge-vs-VMSS-cap check.
  • bundles/fleet-management/guide.md — auto-upgrade channel table gains the Security patch channel (docs added 2026-08-21, #3738) with preview [VERIFY].
  • bundles/workload-platform/guide.md — Kueue gains the capacity-on-admission pattern: ProvisioningRequest AdmissionCheck driving the cluster autoscaler (ProvisioningRequestConfig + AdmissionCheck wired into the ClusterQueue), from configure-kueue-with-cluster-autoscaler; MIG slice-width validation note.

Corrected

  • SKILL.md — "AKS does not roll back a Kubernetes minor upgrade" rewritten pool-scoped: rollback is GA with constraints; control-plane non-rollback retained as the hard limit; parallel-cluster guidance preserved as durable strategy. Post-deployment checklist + "pools must match control plane" non-negotiable softened to skew-aware framing (N-3 permitted during staged/control-plane-only upgrades, equality remains best practice). AGC lesson updated: ALB add-on now aligned to AKS minor versions (controller image auto-selected at upgrade). ACNS citation URL fixed (doc moved to use-advanced-container-networking-services).
  • Link rot ×3 body files (structure-drift probe over 65 URLs): ACNS CLI doc → use-advanced-container-networking-services; Ray+Kueue doc family → ray-overview; Fleet cross-cluster networking → concepts-cross-cluster-networking.
  • bundles/cluster-foundations/guide.md — hyperscale etcd storage units GB→GiB and partition review threshold aligned to Microsoft's 50% guidance; ACL row notes Entra ID SSH rejection; zone-placement additions row updated Preview→GA/global.
  • Version stamps — catalog.yaml/bundle.yaml realigned 3.13.0 → 3.20.0 (had drifted six releases behind the release stream).

Reviewed and deliberately not imported

Flatcar Container Linux retirement (June 8, 2026) — new-cluster designs never select Flatcar and the skill doesn't reference it. Marketplace task sweep scoped out (skill body makes no deployment-marketplace claims). ryanpeters-MSFT/aks-upgrade-rollback demo repo classified not actionable.

Validator

  • python scripts/validate-skill.py . → OK: 0 errors, 0 warning(s).

3.19.0 - 2026-08-25

MINOR. Deep review of chengliangli0918/aks-automatic-foundry (AKS Automatic + Foundry samples, already cited as the worked example in workload-platform) surfaced three guidance items not yet captured. Additive only.

Added

  • bundles/workload-platform/guide.md — Serverless model serving section gains the Entra-only auth enforcement bullet: create the AIServices account with disableLocalAuth: true so API keys are rejected even if leaked; workload identity becomes the only auth path, not merely the preferred one (pattern from the repo's 03-create-foundry.sh, which provisions Foundry via az rest PUT with disableLocalAuth: true).
  • bundles/agent-runtime/guide.md — AKS MCP Server Deployment gains the session state vs replicas bullet: FastMCP-style streamable-HTTP servers default to stateful sessions that break behind a multi-replica Service with no session affinity; run stateless mode (FastMCP(..., stateless_http=True)) or pin to one replica / add session affinity.
  • bundles/agent-runtime/guide.md — Probe fallback sentence now explains why tcpSocket is the correct fallback for MCP servers lacking a dedicated health endpoint: streamable-HTTP endpoints require protocol headers on every request, so plain httpGet probes return 4xx even when healthy.

Reviewed and deliberately not imported

The repo's public LoadBalancer exposure of its MCP server and chatbot, missing PDB/NetworkPolicy/ResourceQuota/PodSecurity labels, and Guaranteed-QoS requests==limits all contradict existing bundle guidance (sample-grade shortcuts); the unverified --enable-hosted-system flag on az aks create --sku automatic was noted but not added pending documentation verification.

3.18.2 - 2026-08-23

PATCH. Two real bootstrap-time pitfalls found live standing up AKS App Routing + cert-manager + Let's Encrypt HTTP-01 from scratch for the first time on a project (Groundwork, groundwork-prod-2), both producing the identical symptom (context deadline exceeded, zero bytes on the HTTP-01 self-check) and easy to conflate — root-caused by checking NetworkPolicy and the ingress Service's externalTrafficPolicy directly rather than assuming a DNS or firewall problem.

Added

  • bundles/operations-resilience/guide.md Known Pitfalls table — two new rows: (1) App Routing's default externalTrafficPolicy: Local breaks in-cluster hairpin (a pod cannot reach the cluster's own external LB IP/hostname), which the NginxIngressController CRD does not expose a field to fix — the underlying nginx Service must be patched directly (externalTrafficPolicy: Cluster) and re-applied every provision since an add-on reconcile could revert it; (2) a default-deny-ingress NetworkPolicy silently drops traffic to cert-manager's dynamically-created, unpredictably-named HTTP-01 solver pods unless an explicit allow rule targets their acme.cert-manager.io/http01-solver: "true" label.
  • bundles/operations-resilience/guide.md HTTP-01 Chicken-and-egg section — cross-reference note: once the ingress controller exists, these two traps commonly stack and must both be checked, not just the first one found.

3.18.1 - 2026-08-23

PATCH. Resolved the [VERIFY] left by 3.18.0: the oauth2-proxy Entra provider surface was checked against the official 7.15.x provider documentation (ms_entra_id).

Verified

  • provider="entra-id" and entra_id_federated_token_auth (--entra-id-federated-token-auth) are current, documented options — boolean, default false; client_secret may be omitted when federated token auth is used. The GBB article's usage and 3.18.0 guidance are accurate as written; [VERIFY] marker removed.

Added

  • bundles/workload-platform/guide.md — secretless Entra app authentication section gains two production traps from the same provider docs: group overage (users with 200+ group memberships silently authenticate with zero groups unless scope=openid User.Read and a consent path for Graph transitiveMemberOf exists) and multi-tenant configuration (common issuer URL + insecure_oidc_skip_issuer_verification=true + explicit --entra-id-allowed-tenant restriction).

3.18.0 - 2026-08-23

MINOR. Azure Global Black Belt blog sweep (azureglobalblackbelts.com), 2026 posts reviewed against the bundles. Additive only; no corrections to existing content were required.

Added

  • bundles/workload-platform/guide.md — new "Secretless Entra app authentication (app-registration federation)" subsection under Service Account and Workload Identity Pattern, from "Secretless Microsoft Entra ID Authentication for AKS with Istio and oauth2-proxy" (2026-07-29): federating an Entra app registration (not just a managed identity) directly to a Kubernetes service account so OAuth middleware (oauth2-proxy behind Istio envoyExtAuthzHttp) redeems authorization codes with a projected SA token as client assertion instead of a client secret. Captures: exact-match issuer/subject/audience requirement, the "never run az ad app credential reset" trap (--entra-id-federated-token-auth=true replaces it), webhook-configures-at-pod-start → rollout-restart rule, cookie-secret-is-still-sensitive nuance, ClusterIP single-auth-boundary rule with narrow /oauth2/* + ACME path exclusions, and the merge-don't-replace rule for istio-shared-configmap-asm-<revision> extension providers.
  • bundles/workload-platform/guide.md — GPU/AI default guidance gains the TTFT-driven scaling bullet from "TTFT-Driven Autoscaling for Disaggregated LLM Inference with NVIDIA Dynamo on AKS" (2026-05-11): scale decode fleets on user-facing latency signals via KEDA querying Azure Managed Prometheus with podIdentity.provider: azure-workload and Monitoring Data Reader on the Azure Monitor Workspace; GPU utilisation alone is not an SLO signal.
  • bundles/production-workload-controls/guide.md — autoscaling guardrails gain the KEDA failure mode from the same article: setting authModes: "bearer" alongside podIdentity.provider: azure-workload makes the ScaledObject permanently READY=False; leave authModes unset.

Not propagated from the trigger articles

  • NVIDIA Dynamo/DGD specifics (DynamoGraphDeployment, NGC pull secrets, NATS) - product tooling, not architecture guidance; the transferable decision (SLO-metric-driven scaling + secretless metric access) is captured instead.
  • Pyroscope continuous-profiling stack, ICMP traffic deep dive, ARO/OpenShift, fuzz-testing, and platform-engineering essays - diagnostic or non-AKS content outside this skill's scope.

3.17.0 - 2026-08-19

MINOR. Hyperscale control plane deep pass, triggered by the PixelRobots article "AKS Hyperscale Control Plane Now in Preview" (2026-08-19). Every material fact was verified against the official Learn doc (hyperscale-configuration-aks) before writing; the blog was accurate on all claims except one (see below). Supersedes the 3.16.1 awareness-level bullet with architecture-grade coverage.

Added

  • bundles/cluster-foundations/guide.md — new "Hyperscale Control Plane Scaling Profile (Public Preview)" section after Pricing Tier and SLA: H2/H4/H8 capacity table (1,750/3,500/7,000 flow-control executing requests; 200/300/400 pods/sec; 6 etcd partitions × 8 GB for all tiers), etcd partition split by resource type with the ≤2 GB per-partition design rule, Permanent classification (creation-only, irremovable, delete-and-recreate to revert; in-tier resize via az aks update --control-plane-scaling-size is Difficult), requirements (Standard/Premium tier, K8s 1.33+, aks-preview ≥ 21.0.0b8, ControlPlaneScalingProfilePreview flag with silent-absence-if-unregistered trap), preview quota (one cluster per subscription per region), tooling surface (CLI/REST/ARM only — no Terraform/SDK, with the azurerm-standard-org implication), provisioning times (10/20 min), when-to-use / when-not-to-use guidance (default dynamic control plane remains the recommendation for most workloads), monitoring metrics (apiserver_flowcontrol_executing_seats, scheduler_schedule_attempts_rate, etcd_database_usage_percentage), Azure CNI Overlay recommendation, and list/watch hygiene. TOC entry added; Stop Conditions line for pricing tier extended to force the hyperscale question at design time.
  • SKILL.md — Azure Policy / Deployment Safeguards non-negotiable gains the hyperscale carve-out: the Azure Policy add-on is not recommended on large hyperscale clusters (increases API server load, per Learn); Deployment Safeguards is a different mechanism and remains recommended. This resolves a conflict where the non-negotiable, followed verbatim on a hyperscale cluster, violated Microsoft guidance.

Corrected

  • SKILL.md — Permanent-decision list now includes the control plane scaling profile (was absent from the skill's core decision-classification surface despite being the textbook Permanent decision).
  • SKILL.md — hyperscale currency bullet rewritten: the 3.16.1 [VERIFY] on scale limits is resolved (published in the official doc); [VERIFY] retained only for regional availability and H-tier pricing (genuinely unpublished). Wording fixed — hyperscale is preprovisioned fixed tiers vs the default dynamic control-plane scaling; the 3.16.1 bullet said "instead of fixed control-plane tiers", which was backwards. Now cross-links the cluster-foundations section.

Not propagated from the trigger article

  • PixelRobots' claim that scheduling throughput "doubles between each tier" is wrong — 200→300→400 pods/sec is linear; only API concurrency doubles (1,750→3,500→7,000). Not copied into the skill.

3.16.1 - 2026-08-19

PATCH. Drift corrections from the azdocswatch feed (MicrosoftDocs/azure-aks-docs), verified at the docs commits. First exercise of improve-skill 4.7.4 change-feed drift detection.

  • SKILL.md (App Routing Gateway API currency bullet): DNS/TLS integrations (Azure DNS + Key Vault TLS) now also reconcile Gateways with gatewayClassName: istio from the Istio service mesh add-on — previously unsupported; the two Gateway API control planes are mutually exclusive. Source: azure-aks-docs PR #3676 (app-routing-gateway-api-dns-tls.md, ms.date 08/06/2026, merged 2026-08-18).
  • SKILL.md (new currency bullet): hyperscale configuration via control plane scaling profile — Public Preview, [VERIFY] on limits/regions/pricing. Source: new doc hyperscale-configuration-aks (PR #3521, merged 2026-08-18).
  • Deferred: AEO (Azure Edge Operator) experimentation doc updates (5 commits) — niche preview experimentation surface, not architecture-grade; GPU-profiling Pyroscope-on-Blob-Storage and KMS kubectl replace procedure fixes — below skill cut-line.

3.16.0 - 2026-08-19

MINOR. Currency pass triggered by the PixelRobots Aug/Jul 2026 AKS articles (shared maintenance windows, automatic PDB management, node disruption policy, Inspektor Gadget), with every material fact re-verified against Microsoft Learn primary sources before writing.

Added

  • bundles/operations-resilience/guide.md — new "Shared Maintenance Windows (Public Preview)" subsection: standalone Microsoft.ContainerService/maintenanceWindows resource (RG scope), AKSSharedMaintenanceWindowPreview feature flag, az aks maintenancewindow create + maintenanceconfiguration add/update --maintenance-window-id linking, enforced mutual exclusivity (window ID vs inline flags vs --config-file), unlink semantics, CLI/ARM-only surface (Bicep 2026-04-02-preview, no portal/azurerm), Fleet Manager complementarity, preview gate.
  • bundles/operations-resilience/guide.md — Inspektor Gadget (AKS extension, Preview) tooling entry alongside Falco/NPD: microsoft.inspektorgadget extension type, krew gadget plugin, DaemonSet-restart-after-update and additive-update gotchas, non-production-first guidance.
  • bundles/fleet-management/guide.md — "Maintenance windows still apply" now cross-references shared maintenance windows for keeping member-cluster windows identical (windows = when, Fleet update runs = order).
  • bundles/cluster-foundations/guide.md — Shared Maintenance Windows row in the Post-Build'26 additions table.
  • SKILL.md — Output Contract §9 (upgrade and patch strategy) now requires stating the shared-windows convergence option for multi-cluster environments and Node Disruption Policy gating; last_verified metadata carries the 2026-08-19 evidence trail.

Corrected

  • bundles/production-workload-controls/guide.md — Automatic PDB Management factual drift fixed against Learn: (1) works with Deployments only, StatefulSets are not supported (previously claimed both); (2) the auto-created PDB sets minAvailable = current replica count / autoscaler minimum floor, continuously reconciled (previously claimed a generic maxUnavailable: 1); (3) added HPA (minReplicas raise) / KEDA (minReplicaCount on ScaledObject) surge mechanics, the unsupported KEDA + separate HPA → Degraded, no surge combination, the cluster-capacity precondition, namespace/deployment opt-in/out annotations, ownedBy lifecycle, and the config-change-requires-delete-and-recreate constraint; recommended install pattern is targeted namespace protection.
  • bundles/operations-resilience/guide.md + bundles/cluster-foundations/guide.md — Node Disruption Policy feature flag corrected NodeDisruptionPolicy → NodeDisruptionProfile (matches the nodeDisruptionProfile ARM property; per the azure-cli-extensions PRs), retained [VERIFY].
  • bundles/operations-resilience/guide.md — Node Disruption Policy section expanded with the three policy values table and the silent-fallback trap: AllowDuringMaintenanceWindow is satisfied only by aksManagedNodeOSUpgradeSchedule — the default and aksManagedAutoUpgradeSchedule windows do not qualify, and with no qualifying window the policy allows everything; plus the mixed covered+upgrade change escape, the never/not-yet-covered operation lists (outbound type, SSH, IMDS, bootstrap profile), the Azure emergency override, and Block-as-hard-gate semantics. Primary source link updated to the live Learn page.

Validator

  • python scripts/validate-skill.py . → OK: 0 errors, 0 warning(s) (2026-08-19).

3.15.1 - 2026-08-16

PATCH. Two pointer/anchor fixes surfaced by the azure-container-apps 1.0.13-1.0.14 audit's cross-skill sweep:

  • Phantom skill reference removed: "Do Not Use" pointed platform-selection questions to a nonexistent container-platform comparison skill (verified absent across the repo, 2026-08-16). Now points to Microsoft Learn compare-options + azure-container-apps (which carries the CMK/runtime-detection AKS steer).
  • Broken TOC anchor fixed: the production-workload-controls guide's TOC entry "Validation Commands" pointed at a heading that did not exist; restored the ## Validation Commands heading above the command block (validator 0 errors / 0 warnings, previously 2 warnings).

3.15.0 - 2026-08-15

MINOR. Expert Kubernetes tips and best practices pass — adds production-hardening guidance from the Kubernetes expert perspective, distributed into the appropriate bundles.

Added

  • bundles/cluster-foundations/guide.md — eBPF kube-proxy replacement guidance (Cilium kube-proxy-free mode); Service CIDR sizing rule (/16 minimum for production); admission webhook failurePolicy/timeoutSeconds hardening; new CRD Lifecycle and Operator Governance section (CRD scope, version upgrade ordering, pruning risk, operator ownership, post-upgrade CRD health check).
  • bundles/workload-platform/guide.md — topologySpreadConstraints minDomains (GA 1.28) guidance with example YAML; readinessGates for ALB/AGC traffic readiness; NUMA-aware scheduling for GPU/HPC workloads (topologyManagerPolicy, CPUManagerPolicy); native sidecar containers (Kubernetes 1.29+ restartPolicy: Always on initContainers) pattern with lifecycle and probe notes; QoS class strategy section (Burstable as default, Guaranteed only for latency-sensitive, BestEffort banned for production).
  • bundles/production-workload-controls/guide.md — ValidatingAdmissionPolicy (CEL-based, GA 1.30) with disallow-latest-tag and require-resource-limits examples, plus mutating webhook reinvocationPolicy: IfNeeded guidance; seccompProfile: RuntimeDefault non-negotiable callout with full security context example; allowPrivilegeEscalation: false always-set rule; imagePullPolicy: IfNotPresent as production default; ephemeral containers debugging workflow (kubectl debug) for distroless/scratch images.
  • bundles/operations-resilience/guide.md — KEDA ScaledJob pattern for batch/queue workloads with YAML example and design rules; VPA UpdateMode matrix (Off/Initial/Recreate/Auto) with recommendation (Initial as safe production default); Falco as complementary open-source runtime security add-on; Node Problem Detector (NPD) for kernel-level fault detection; kubectl-convert tool added to API deprecation inventory tooling; OOMKilled triage runbook (step-by-step identify/measure/mitigate); kubectl tooling table (krew, neat, tree, view-secret, kubelogin, ctx/ns).
  • bundles/agent-runtime/guide.md — mandatory readinessProbe and livenessProbe requirement for all MCP server containers (with minimum YAML example); one-ServiceAccount-per-agent-component non-negotiable rule.
  • SKILL.md — krew plugin ecosystem guidance with recommended plugin list; kube-score as advisory CI gate; Node Problem Detector reference in operating model tooling items 6 and 7.

Validator

  • python scripts/validate-skill.py . → pre-existing 3 errors (subdirectory SKILL.md stubs); no new errors introduced.

3.14.0 - 2026-08-15

MINOR. Gap-fill pass: propagated items previously documented only in SKILL.md into the authoritative bundle files where they should be discoverable.

Added

  • bundles/cluster-foundations/guide.md — Azure Container Linux (ACL) GA entry in Node OS currency section; --os-sku AzureContainerLinux with feature-parity [VERIFY] gates. Node OS default baseline table updated to include ACL as a third GA option (K8s 1.34+, reduced drift/fleet-maintenance focus).
  • bundles/cluster-foundations/guide.md — enableCustomCATrust retirement row added to active retirement deadlines table (September 14, 2026; action: --disable-custom-ca-trust; see Azure/AKS #5826).
  • bundles/cluster-foundations/guide.md — Node Disruption Policy (Public Preview, AKS 2026-07-17) added to the Post-Build'26 additions table — controls when nodes may be reimaged during routine config changes, enabling change-control discipline over the reimage surface.
  • bundles/workload-platform/guide.md — In-place node pool VM size change (Preview) added to Node Pool Baseline: az aks nodepool update --node-vm-size, rolling-upgrade engine, API 2026-01-02-preview gate, Difficult classification, drain/PDB impact note.
  • bundles/workload-platform/guide.md — NVIDIA RTX PRO 6000 Blackwell Server Edition GPU support (AKS 2026-06-19) added to GPU defaults — Ubuntu + NVIDIA GRID driver, [VERIFY] VM size/quota/driver.
  • bundles/production-workload-controls/guide.md — Automatic PDB Management (Preview) subsection after the PDB YAML example: microsoft.evictionautoscaler cluster extension, install CLI, namespace vs cluster-wide mode, "not a substitute for deliberate PDB design" guidance.
  • bundles/operations-resilience/guide.md — Node Disruption Policy subsection (Public Preview) in the Node OS auto-upgrade section: feature-register flow, change-control use case, scope distinction from upgrade windows, preview gate.

Validator

  • python scripts/validate-skill.py . → OK: 0 errors, 0 warning(s).

MINOR. Deep-research pass (context7/Microsoft Learn + Azure Updates MCP primary source + AKS releases 2026-07-17 / 06-19 / 05-29 + public GitHub codebase survey). Confirmed the most recent AKS release remains 2026-07-17 (no newer release as of 2026-08-11) and added the items from that release and the Azure Updates feed not yet captured.

Added

  • SKILL.md — new "August 11, 2026 research pass" section: AGC inference gateway Public Preview (Azure Updates 566516; Gateway API Inference Extension — InferencePool/InferenceObjective/EPP/BBR; Helm-only ALB controller --set albController.aiGateway=true, not via the AKS add-on; WAF pairing); Automatic zone placement Public Preview; Full caching mode for Ephemeral OS disks Public Preview; Secure TLS bootstrapping default-on in westcentralus/eastasia (Azure/AKS #5694); Trusted Launch enable/disable on existing Linux node pools + Secure Boot with GPUs on Azure Linux; NAP behavioral changes (kubernetes.azure.com/mode: user on default NodePool, In-VM spot rebalancing); kube-proxy nftables rejected pre-1.33; CNI Overlay Dual-Stack on Windows without preview registration; Deployment Safeguards Enforce resource-requests mutator extended to DaemonSets/Jobs; App Routing with Gateway API GA date corrected to July 2026 (Azure Updates 567944) with --enable-app-routing-istio flag and approuting-istio GatewayClass; AKS Automatic can now disable default app-routing to use the Istio add-on (1.36+); Kata gates (FIPS rejected, Standard_DadsV7 supported); CVM with Azure Linux GA; Windows gMSA CoreDNS conflict validation; Istio asm-1-30 (Istio CNI default + ISTIO-SECURITY-2026-005); GPU driver currency gate (NVadsA10v5/NCadsA10v4 need node image 202606.08.1+, Azure/AKS #5875); Karpenter v1.14.0 / KubeBuddy v0.0.35 / kaito v0.11.0 / kars-active currency.
  • SKILL.md — Resource Directories now cites the canonical reference implementations: Azure/AKS-Landing-Zone-Accelerator and Azure/Aks-Construction (noting aks-baseline repos 404 / absorbed into LZA), plus Terraform reference modules (Azure-Samples/aks-openai-terraform, paolosalvatori/private-aks-cluster-terraform-devops, XenitAB/terraform-modules) as live confirmation of the KEDA/identity patterns. AI/GPU routing section gains the inference-gateway routing bullet.
  • bundles/cluster-foundations/guide.md — "Post-Build'26 additions" table (Automatic zone placement, Full caching ephemeral, Secure TLS bootstrapping, Trusted Launch toggle, NAP default-pool label, nftables gate, Windows dual-stack, Safeguards DaemonSet/Job mutator) and a managed-system-node-pool security-restrictions paragraph (SSH keys, port-forward, kube-system secrets, externalIPs ValidatingAdmissionPolicy, mutating admission bindings, LocalDNS Required).
  • bundles/workload-platform/guide.md — new "Inference gateway for self-hosted LLM serving (AGC, Public Preview)" subsection; GPU driver-compatibility gate and Secure Boot-with-GPU notes added to GPU defaults.

Corrected

  • SKILL.md — App Routing with Gateway API flag trap documented: --enable-app-routing enables legacy NGINX mode; Gateway API mode requires --enable-app-routing-istio; GatewayClass approuting-istio; new AKS Automatic clusters on 1.36+ preconfigure Gateway API by default. GA date confirmed April 2026 (AKS release 2026-04-28, authoritative) — the Azure Updates 567944 post published 2026-07-28 is the formalized Azure Updates entry, not the GA date (initial 3.13.0 draft mis-read it as GA July 2026; corrected against the release notes).

Validator

  • python scripts/validate-skill.py . → green (0 errors, 0 warnings).

Honest unknowns

  • AGC inference gateway and Automatic zone placement are Preview — no GA date committed.
  • Secure TLS bootstrapping regional rollout schedule beyond westcentralus/eastasia unconfirmed.
  • Trusted Launch disable path edge cases unverified on live clusters.

3.12.0 - 2026-08-02

MINOR. AzureFeeds weekly sweep (25 Jul–01 Aug 2026) currency pass.

  • bundles/workload-platform/guide.md: new "Prepared Image Specification (Preview, July 2026)" subsection — node images preloaded with container images and initialisation tasks to cut node bootstrap/startup latency for large-scale, AI/GPU, and Windows workloads (Azure Updates, 2026-07-29); preview gate + trigger-on-measured-latency guidance.
  • bundles/fleet-management/guide.md: stamped resource placement (ClusterResourcePlacement) as GA (July 2026) in the recent-additions callout and the Resource Placement section (namespace-scoped ResourcePlacement stays preview); added maximum allowed failures for update runs (Preview, July 2026) to the callout and the update-run requirements.

3.11.0 - 2026-08-02

MINOR. Added the missing seam between AKS and Foundry/Azure OpenAI model serving — previously the skill had zero coverage of calling model endpoints from AKS.

  • bundles/workload-platform/guide.md: new "Serverless model serving via Microsoft Foundry / Azure OpenAI (no GPU pool required)" section — zero-secret pattern (workload identity + no API keys), AKS Automatic default-enabled OIDC/workload identity, Cognitive Services User data-plane role (not OpenAI User / Foundry roles), role-propagation retry, ACR cloud build for no-local-Docker CI, env-based endpoint/deployment config. Worked example: chengliangli0918/aks-automatic-foundry.
  • SKILL.md: added co-skill row (AKS + Foundry/Azure OpenAI model serving → microsoft-foundry + identity-managed-identity) and a Quick Routing row for LLM inference from AKS.

3.10.0 - 2026-07-21

MINOR. Skill-improvement-metaprompt run: parallel external-evidence pass (currency/supersession, local content+structural accuracy, veteran/beyond-quickstart) against authoritative Microsoft Learn, Azure/AKS GitHub, and Azure Updates. Closed 1 Critical and 3 High internal-contradiction must-fixes, added the flagship containerd 2.x breaking-change surface (previously uncovered), and refreshed node-OS currency. Also realigned stale bundle version stamps (3.7.0 → 3.10.0) to the skill release stream.

Round coverage:

  • Rounds run: 1 (evidence-driven; direct main-agent fixes)
  • Reviewer angles: content accuracy + structural cohesion (local); capability recency + supersession + latent capability (currency); veteran / beyond-quickstart / field-reality (production).
  • Aggregate result: pre-fix structural score 6/10 (internal contradictions on hard-to-reverse decisions); post-fix validator green, all Critical/High closed.

External validation baseline

  • Official docs: Microsoft Learn upgrade-os-version (2026-07-13), supported-kubernetes-versions (2026-07-15), availability-nat-gateway, whats-new-azure-linux-4.
  • Official source / release notes: Azure/AKS releases (2026-06-19), Azure/AKS issues #4700 (containerd 2.0), #5772 (AZNFS), containerd upstream #12808/#12612/#12636.
  • Community: node_exporter #3331 (CRI v1alpha2), GKE containerd-2 migration guide, Broadcom KB 401577 (deprecated-API upgrade gate), Ubuntu AppArmor userns spec.

Capability deltas considered

  • Added: containerd 2.x runtime-major-bump surface (CRI v1alpha2 removal, registry-mirror config_path trap, Docker Schema 1 drop); Azure Linux 4.0 preview watch note (not yet an AKS osSku); Ubuntu 24.04 first-class reframe + FIPS gap; AZNFS × Azure Files NFS EiT interaction risk; AKS deprecated-API-usage upgrade gate (12h window, add-on callers, force-upgrade footgun); Ubuntu 24.04 unprivileged-userns AppArmor restriction; LTS→Premium tier cost surprise.
  • Already covered: Kubernetes 1.36 GA/LTS (line already correct); Static Egress Gateway GA; managedNATGatewayV2 status; App Routing Gateway API GA.
  • Out of scope: Ubuntu 20.04 retirement (new clusters won't select it); Azure Linux 4.0 as a node SKU (not yet available); full de-duplication of cluster-foundations overlap sections (structural, deferred — see QUALITY-REVIEW).

Fixed (internal contradictions — must-fix)

  • C1 (Critical) — SKILL.md managedNATGateway zone-redundancy. SKILL.md "Lessons" asserted managedNATGateway is zone-redundant, directly contradicting cluster-foundations ("Single-zone — not zone-redundant") and full-reference and Azure's documented behavior (Standard NAT Gateway is zonal; only StandardV2/managedNATGatewayV2 is zone-redundant). Corrected SKILL.md to preserve the genuine IaC lesson (userAssignedNATGateway custom-VNet preflight failure) while removing the false zone-redundancy claim and cross-linking the authoritative outbound section.
  • H1 (High) — Arc Fleet Manager GA vs Preview. fleet-management and full-reference still called Fleet Manager for Arc-enabled clusters "Preview (November 2025)" while SKILL.md/cluster-foundations said GA. Verified GA at Build 2026 (member scale raised to 1,000); updated the fleet bundle and full-reference to GA, keeping the capability-parity caution.
  • H2 (High) — wrong node-OS upgrade channel + flag. cluster-foundations used the invalid channel NodeSecurityPatch and flag --node-image-channel; corrected to SecurityPatch and --node-os-upgrade-channel (matching SKILL.md, operations-resilience, quick-reference and the Anti-Hallucination rule); added the None channel row.
  • H3 (High) — "Ubuntu is a legacy choice." SKILL.md contradicted the bundles/reference, which present Ubuntu 24.04 as a current default. Reframed SKILL.md Non-Negotiable: Azure Linux 3.0 and Ubuntu 24.04 are both first-class/GA; dropped the misleading "(mariner)" gloss.
  • M2/M3 — cluster-foundations network-policy + ingress defaults. Fixed "Azure CNI powered by Cilium (built-in NPM)" (Cilium is not NPM) and "NPM vs Calico" (Azure NPM is deprecated) to Cilium Network Policy; removed "NGINX ingress with WAF" as a recommended new-cluster default (contradicted the avoid-NGINX EOL-cliff non-negotiable).
  • M4 — duplicate/hard-coded SLA numbers. Softened the first pricing table's hard-coded SLA percentages and per-cluster prices to [VERIFY] with a cross-link to the authoritative Pricing Tier and SLA section; noted the LTS→Premium auto-routing cost.
  • L1 — Confidential Containers tense. production-workload-controls still used future/ongoing tense for the March 31, 2026 retirement; corrected to past tense (consistent with cluster-foundations and today's date).

Added (currency + beyond-quickstart)

  • cluster-foundations — containerd 2.x section. New subsection: containerd 2.x is the default runtime on Azure Linux 3.0 (K8s 1.33+) and Ubuntu 24.04 (1.35+); a K8s minor upgrade silently crosses a runtime major version. Documents CRI v1alpha2 removal (silently breaks monitoring/security DaemonSets; kubelet is fine), the registry-mirror config_path silent-bypass/CRI-load-failure trap (with the second-order link to ACR throttling), Docker Schema 1 removal, and a canary pre-upgrade validation. Plus node-OS currency note (Azure Linux 3.0 default + AzureLinux3 SKU 1.36 ceiling; Azure Linux 4.0 preview/not-an-osSku; Ubuntu 24.04 GA/first-class + FIPS gap; AZNFS × Azure Files NFS EiT interaction) and the Ubuntu 24.04 unprivileged-userns AppArmor gotcha.
  • operations-resilience — deprecated-API upgrade gate. New callout: AKS preflight hard-blocks the control-plane upgrade on live deprecated-API usage (~12h window), often triggered by add-ons that watch deprecated APIs (not your manifests), and the force-upgrade override is a footgun.
  • SKILL.md — node-OS Non-Negotiable rewrite (containerd/OS-SKU), managedNATGateway correction, and cross-links to the new sections.

Validator

  • python scripts/validate-skill.py . → OK: 0 errors, 0 warning(s).
  • Parity checks: bundle.yaml/catalog.yaml versions realigned to 3.10.0 (agent-runtime remains on its independent 1.0.0 line).

Honest unknowns

  • No live Azure subscription: az aks, crictl, and sysctl checks (containerd build number in the current AKS node image; whether AKS 24.04 keeps apparmor_restrict_unprivileged_userns=1) remain verification gates, marked [VERIFY].
  • AKS Node Disruption Policy official Azure Update ID unconfirmed (GitHub Azure/AKS#5017 only) — retained [VERIFY].
  • Azure Linux 4.0 AKS availability date is "coming soon" with no committed date.

3.10.3 - 2026-08-02

PATCH. Added Bicep BCP120 name-anchor pitfall to the kubelet-identity AcrPull grant in cluster-foundations (Kubelet identity vs control-plane identity): the kubelet objectId is a runtime property that exists only after the managedClusters resource is provisioned, so the role assignment's name must derive from a static property such as cluster.id, never the kubelet objectId itself. Source: .apm/known-pitfalls.md (AcrPull kubelet-identity entry).

3.10.2 - 2026-07-29

PATCH (currency refresh). Skill-improvement-metaprompt run: Phase 1-2 external-evidence pass verified against AKS releases 2026-07-17, 2026-06-19, 2026-05-29 and current Microsoft Learn. No internal-contradiction must-fixes — skill remains internally consistent at 9.4/10. Additive currency updates only.

Added

  • SKILL.md: New "July 29, 2026 currency updates" section covering:
    • Artifact Streaming → GA (was Preview)
    • Windows Server 2025 → GA (was Preview; default for K8s 1.37+)
    • In-place node pool resize (Preview) — az aks nodepool update --node-vm-size
    • Automatic PDB Management (Preview) — az k8s-extension create --extension-type microsoft.evictionautoscaler
    • Azure Container Linux (ACL) — GA, K8s 1.34+
    • NVIDIA RTX PRO 6000 Blackwell GPU support
    • FIPS on Ubuntu 22.04 — GA
    • enableCustomCATrust — retiring September 14, 2026
    • K8s 1.30 deprecated; K8s 1.33 now LTS-only
  • SKILL.md last_verified updated to 2026-07-29 with 3.10.2 summary.

External validation baseline

  • Official source: AKS Release 2026-07-17 (GitHub Azure/AKS), AKS Release 2026-06-19, AKS Release 2026-05-29
  • Official docs: Microsoft Learn — artifact-streaming, resize-node-pool, automatic-pod-disruption-budget-management, upgrade-windows-os, azure-container-linux-overview, supported-kubernetes-versions (all 2026-07-29)
  • Community: Azure/AKS #3928 (Artifact Streaming GA), #5826 (enableCustomCATrust retirement)
  • Item already covered: Node Disruption Policy (confirmed in AKS 2026-07-17 release — skill already had it from July 18 platform updates)

Validator

  • python scripts/validate-skill.py . → OK: 0 errors, 0 warning(s).

3.10.1 - 2026-07-24

PATCH (cost-model and autoscaling-operations depth). Added five targeted guidance updates aligned to AKS FinOps practice while keeping existing architecture decisions intact.

Added

  • production-workload-controls: Added a four-layer capacity model (Provisioned / Allocatable / Requested / Consumed) under node allocatable guidance for consistent rightsizing and scheduler-aware capacity analysis.
  • operations-resilience: Added two explicit FinOps efficiency ratios in Cost Controls:
    • request efficiency (usage / requested)
    • allocation efficiency (requested / allocatable)
  • operations-resilience: Added a cost-anomaly correlation playbook step to tie spend spikes to rollout/scaling/node-pool/telemetry changes.
  • workload-platform: Added an autoscaler control-loop failure-mode table (HPA/KEDA/VPA/cluster autoscaler/NAP interaction risks and mitigations).
  • cluster-foundations: Added Spot fallback guidance to prefer Spot with fallback (affinity + toleration) over strict Spot-only placement unless pending-on-eviction is explicitly accepted.

3.9.4 - 2026-07-12

PATCH (link integrity). Fixes three pre-existing validator errors for broken sibling-skill cross-links in the agent-runtime bundle and SKILL.md. The links were syntactically close but off by one directory level, so they resolved to non-existent paths. No content guidance changed.

Fixed

  • bundles/agent-runtime/guide.md sibling-skill links. The file lives at bundles/agent-runtime/guide.md (two directories below the skill root), so a link to a sibling skill needs ../../../<sibling>/SKILL.md to climb out of the aks skill entirely. The links used ../../<sibling>/SKILL.md, which resolved back inside the aks skill to a path that does not exist. Corrected microsoft-agent-framework, mcp-server-design, and azure-container-apps links to ../../../. These were the three ERROR ... does not exist lines reported by scripts/validate-skill.py.
  • SKILL.md sibling-skill links. The router file lives at the skill root, so a sibling link needs ../<sibling>/SKILL.md to reach .github/skills/<sibling>/. The links used ../../<sibling>/SKILL.md, resolving to .github/<sibling>/ (wrong). These did not surface as validator errors because the resolver escapes the skill ROOT and is skipped, but the links were broken for any reader. Corrected microsoft-agent-framework and mcp-server-design links in the routing table and the kars deep-dive paragraph to ../.

Validation

  • python scripts/validate-skill.py . → OK: 0 errors, 0 warning(s) (previously 3 errors, 0 warnings).

3.9.3 - 2026-07-12

MINOR (additive). Coverage of two architectural gaps surfaced by a gap analysis of the skill: dual-stack (IPv4/IPv6) networking and batch/AI training scheduling (Kueue), plus a GPU partitioning strategies subsection (MIG, time-slicing, MPS). Deep-researched against authoritative Microsoft Learn documentation.

Added

  • Dual-Stack Networking (IPv4/IPv6) subsection in cluster-foundations/guide.md under CIDR Planning. Covers the --ip-families ipv4,ipv6 flag, the Permanent-at-creation classification, the Azure CNI Overlay/Cilium overlay requirement, the K8s 1.29+ requirement for Cilium dual-stack, the IPv6-only-not-supported constraint for nodes/pods, the standard NAT Gateway exclusion and IPv6 egress path (LB/UDR; managedNATGatewayV2 IPv6 support is evolving [VERIFY]), Azure Linux externalTrafficPolicy: Local and virtual-nodes limitations, IPv6 service CIDR /108 cap, and a "when to choose dual-stack" driver table. Added a dual-stack Stop Condition.
  • GPU Partitioning subsection in workload-platform/guide.md with a comparison table (MIG = AKS-managed hardware isolation on A100/H100/H200, static at node-pool level; time-slicing = user-managed via NVIDIA GPU Operator for experimentation; MPS = user-managed CUDA-level multiplexing), plus the managed GPU node pool preview (gpuProfile.nvidia.managementMode/migStrategy [VERIFY] GA). Source: GPU node partitioning strategies, Create a managed MIG node pool.
  • Batch and AI Training Scheduling (Kueue) subsection in workload-platform/guide.md. Covers the two-level queuing model (ClusterQueue resource pool + LocalQueue tenant queue), fair sharing across cohorts, when to adopt (multi-tenant GPU quota contention, gang scheduling for distributed training, Ray+Kueue for distributed AI workloads), and the open-source/community-supported boundary (excluded from AKS SLA). Sources: Kueue on AKS overview, Run Ray AI workloads with Kueue on AKS.
  • Stop Conditions in workload-platform/guide.md for GPU partitioning strategy choice and Kueue adoption (ownership/SLA boundary).
  • Routing table entries in SKILL.md for dual-stack CIDR planning, GPU partitioning, and batch/Kueue scheduling.
  • AI/GPU routing bullets in SKILL.md cross-linking the two new subsections.
  • Glossary entries: Dual-stack, Kueue, MIG, MPS.

Sources (all fetched 2026-07-12)

3.9.2 - 2026-07-11

PATCH (currency). Verification and currency refresh of feature-status claims using authoritative Microsoft Learn documentation (fetched 2026-07-11). Supersedes the 3.8.3 determination that Static Egress Gateway public-IP mode was still Preview.

Currency corrections

  • Static Egress Gateway is GA (both public-IP and private-IP modes). Updated from "(Preview)" to "(GA)" in cluster-foundations/guide.md (outbound connectivity table and dedicated subsection). The 3.8.3 quality review (item S-003) distinguished a GA private-IP mode from a still-Preview public-prefix mode — as of 2026-07-03 both modes are GA; private-IP mode requires Kubernetes 1.34+ and --vm-set-type VirtualMachines on the gateway node pool. Feature flag is no longer required. Source: Microsoft Learn — Configure Static Egress Gateway (updated 2026-07-03).
  • NAT Gateway V2 status clarified: SKU is GA, AKS outbound type is Preview. The StandardV2 NAT Gateway SKU is GA (zone-redundant by default, higher throughput, IPv6 outbound, flow logs), but the AKS managedNATGatewayV2 outbound type remains in Preview (requires ManagedNATGatewayV2Preview feature flag on Microsoft.ContainerService and the aks-preview CLI extension). Corrected in cluster-foundations/guide.md outbound table and references/full-reference.md zonal-egress guidance. Source: AKS egress outbound types (updated 2026-07-03) and NAT Gateway reliability.
  • New none and block outbound types (Preview) for Network Isolated Clusters. Added both rows to the outbound connectivity table. none configures no egress path and pulls artifacts from a private ACR (--bootstrap-artifact-source Cache); block additionally writes NSG rules that actively block all public egress. Source: AKS Network Isolated Cluster concepts.
  • Default outbound access retired March 31, 2026. Added a callout to the outbound connectivity section. New AKS-managed VNet clusters deploy subnets as private subnets (defaultOutboundAccess = false); BYO-VNet clusters remain responsible for their own egress. Source: Azure update announcement.
  • outboundType is now mutable post-creation with defined migration paths. Updated the IaC anchors note (previously described switching outbound type as "difficult and disruptive" with "no supported path out of managedNATGatewayV2"). AKS now supports managed-VNet migrations including loadBalancer → any, managedNATGateway → managedNATGatewayV2/none/block, and none/block → any. Migrating away from managedNATGatewayV2 to any other type remains "Not Supported" on a managed VNet — it is a one-way destination once chosen. Any migration that changes the outbound public IPs requires updating API server authorized IP ranges first. SKILL.md "Difficult decision" category updated accordingly. Source: AKS egress outbound types (updated 2026-07-03).
  • Confidential Containers retired March 2026 (past tense). Corrected future-tense retirement notices in cluster-foundations/guide.md to past tense ("retired") and added the GitHub tracking reference (Azure/AKS#3781). Node images were removed 2026-03-31. Confidential VM node pools (AMD SEV-SNP) remain supported.

Research method

  • Context7 has no AGC-specific library and the /microsoft/learn library did not resolve AKS egress/network-isolated docs. All status claims were verified by fetching the authoritative Microsoft Learn docs directly (web_fetch + microsoft_docs_search) and reading the current feature banners, feature-flag requirements, and "updated" dates. [VERIFY] markers retained only where a field is genuinely version-sensitive and may shift between skill refreshes (e.g., exact DRS version string, ARM resource ID format, regional availability of Preview features).

PATCH (correctness). Verified the AGC WAF SecurityPolicy CRD example introduced in 3.9.0 against authoritative Microsoft Learn. The example was materially wrong and has been corrected.

Correctness fix

  • AGC WAF K8s CRD is WebApplicationFirewallPolicy, not SecurityPolicy; and it binds an Azure WAF policy by ARM resource ID, it does not hold inline WAF rules. The 3.9.0 example used a fictitious kind: SecurityPolicy with an inline spec.policy.settings.waf.rules[].managedRuleSet block (version "DRS 2.1"). Verified against Microsoft Learn — WAF on AGC with the Gateway API and AGC components: the authoritative K8s CRD is kind: WebApplicationFirewallPolicy (alb.networking.azure.io/v1) with spec.targetRef (Gateway / HTTPRoute / listener sectionNames) and spec.webApplicationFirewall.id (full ARM resource ID of a Microsoft.Network/applicationGatewayWebApplicationFirewallPolicies resource). WAF mode, exclusions, custom rules, and the managed rule set (DRS version) are configured on the Azure WAF policy in ARM, not in the K8s manifest. Corrected in operations-resilience/guide.md, production-workload-controls/guide.md, and this changelog. [VERIFY] retained on the ARM resource ID and DRS version.
  • DRS version currency: as of 2026 the recommended managed rule set is DRS 2.2 (OWASP CRS 3.3.4); DRS 2.1 is the prior version. Only the latest three DRS releases are supported for new policies. Source: WAF DRS and CRS rule groups and rules.
  • Clarified that WAF on AGC is current and supported. A web search claimed WAF on AGC was deprecated; the official AGC components doc states the opposite — "the only security policy type offered is waf". No deprecation applies.

Note on research method

  • Context7 has no AGC library. The authoritative schema was resolved by fetching the official Microsoft Learn how-to doc directly and reading the documented kubectl apply example, not by trusting search summaries (which returned a conflicting, hallucinated schema).

3.9.0 - 2026-07-09

MINOR. Cross-checked the skill against the Microsoft Tech Community blog "Lock down AKS end-to-end with Application Gateway for Containers and Managed Cilium" (session MAIS09, Azure Infrastructure Summit 2026) and the underlying Microsoft Learn — Use ACNS on your AKS cluster (cilium) guidance. Surfaced one correctness defect, one bonus pitfall, and two additive content gaps.

Correctness fix (High)

  • --enable-acns alone enables only FQDN filtering; L7 policy requires --acns-advanced-networkpolicies L7. The skill previously stated az aks update --enable-acns was sufficient for L7 policy. Microsoft Learn is explicit: --enable-acns enables FQDN filtering by default; L7 and FQDN policy requires the additional --acns-advanced-networkpolicies L7 flag on both az aks create and az aks update. Without it, a CiliumNetworkPolicy containing toPorts.rules.http/rules.grpc is silently ignored (no admission error). Fixed in production-workload-controls/guide.md sections 7, 8, 9 and the Network Policy Strategy cautions.

Bonus pitfall (High)

  • L7 rules are not supported in CiliumClusterwideNetworkPolicy (CCNP) — only in namespaced CiliumNetworkPolicy. An L7 rule placed in a CCNP is likewise silently ignored. Added to the Network Policy Strategy cautions and the RBAC table footnote in production-workload-controls/guide.md.

Additive content

  • Layered AKS ingress and east-west security (AGC + WAF + Cilium L7) — new architectural-pattern subsection in production-workload-controls/guide.md framing the four-layer concentric defense model with the WAF↔Cilium-L7 complementarity rationale (WAF catches payload attacks Cilium L7 permits; Cilium L7 catches method/path and east-west traffic WAF cannot see), cross-referencing the existing default-deny, DNS carve-out, ingress-allow, L7, and FQDN egress examples.
  • AGC WAF WebApplicationFirewallPolicy (OWASP DRS) CRD example — new subsection in operations-resilience/guide.md. Verified against Microsoft Learn — WAF on AGC with the Gateway API: the K8s CRD is kind: WebApplicationFirewallPolicy (alb.networking.azure.io/v1), which binds a pre-provisioned Azure WAF policy by ARM resource ID (spec.webApplicationFirewall.id + spec.targetRef); WAF rules, mode, and DRS version live on the ARM WAF policy, not inline in the manifest. Current recommended managed rule set is DRS 2.2 (OWASP CRS 3.3.4); DRS 2.1 is the prior version; only the latest three DRS releases are supported for new policies. Earlier draft incorrectly used a fictitious inline SecurityPolicy schema; corrected. [VERIFY] retained on version-sensitive fields.

Glossary and references

  • SKILL.md and references/glossary.md ACNS entries enriched with the FQDN-filtering-vs-L7 flag distinction so the glossary is not misleading on its own.
  • references/full-reference.md Network Policy design cautions gained the L7 flag and CCNP limitation bullet.
  • SKILL.md "Lessons from production deployments" gained a bullet for the --acns-advanced-networkpolicies L7 silent-no-enforcement trap, matching the existing AGC trap entries in severity and style.

Validator

  • python scripts/validate-skill.py . → OK: 0 errors, 0 warning(s).

3.8.3 - 2026-06-30

Supersession review pass. Training data recency bias gate applied — cross-referenced skill claims against current AKS feature GA/Preview status for 8 patterns. Three actions taken; 5 confirmed current.

Supersession Register outcomes

  • S-001 — App Routing Gateway API GA (Apr 28, 2026). SKILL.md line 249 updated from "H1 2026 per Microsoft Learn" to "GA April 2026; --enable-app-routing enables Gateway API by default on AKS 1.36+". operations-resilience/guide.md traffic management table updated to reflect GA status; preview/GA verification instruction replaced with limitations-only check. (High)
  • S-003 — Static Egress Gateway Private IP Support GA. Distinguished from public-prefix mode (still Preview). Cluster-foundations guidance updated to split the two modes' preview status. (Low)
  • SS-B — Windows Server 2019 retirement (March 1, 2026). Added explicit retirement date to Windows node pool OS lifecycle guidance in cluster-foundations/guide.md. (Low)
  • SS-C — Flatcar Container Linux (support ended June 8, 2026). Added Flatcar retirement date to OS lifecycle reference. (Low)
  • S-002, S-004, S-005, S-006, S-007, S-008, SS-A — Confirmed current against research. No change needed.

Review round

  • Round 1 angles: Capability recency (trusting track), Hostile review (skeptical track)
  • Score: 7/10 (Capability recency) — three supersession signals found, but all were low-severity timeliness issues, not factual errors
  • All 8 supersession register items dispositioned

Validator

  • python scripts/validate-skill.py . → OK: 0 errors, 0 warning(s).

3.8.0 - 2026-06-27

Production deployment lessons from a full azd up + AKS deployment (australiaeast, AKS API 2026-03-01, AGC/Gateway API, KEDA, Workload Identity, private networking). All lessons verified through real deployment failures and fixes.

Added

  • SKILL.md - Lessons from production deployments (7 new entries):
    • KEDA moved from addonProfiles to workloadAutoScalerProfile in API 2026-03-01 — silent failure pattern and fix.
    • AKS LoadBalancer services fail when cluster identity lacks Network Contributor on the workload VNet — symptom (EXTERNAL-IP: <pending> + LinkedAuthorizationFailed), root cause, and Bicep fix.
    • NetworkPolicy default-deny blocks Azure LoadBalancer traffic — source IP after SNAT may not be in VNet CIDR; add 0.0.0.0/0 to ingress allowlist for LB-fronted pods.
    • AGC ALB Controller version-coupling trap with managed Gateway API add-on — deadlock symptom, Helm install resolution path, and the add-on vs Helm decision.
    • BYO AGC requires alb-id annotation (not alb-name/alb-namespace) — wrong annotation causes infinite "ApplicationLoadBalancer CRD not found" errors.
    • BYO AGC ALB controller data-plane permission — ARM RBAC (Contributor/Owner) is insufficient; AGC uses a separate gRPC permission model.
    • Workload identity per-SA token projection — AZURE_CLIENT_ID env var does NOT override SA annotation; need dedicated SA per identity.
    • PodSecurity restricted rejects jobs without explicit securityContext — every Job manifest must include full security context block.
    • Foundry/AI model deployment names must not be hardcoded in K8s manifests — model name change (e.g., gpt-4o-mini to gpt-5-mini) broke all AI calls because K8s Deployment YAML had old deployment name hardcoded as value: string.
    • Entra ID app registrations need redirect URIs for browser-based MSAL auth — new domain (e.g., Front Door, Application Gateway) must be added as redirect URI after deployment.

3.7.0 - 2026-06-16

Capability-coverage pass. Closes practical / real-world gaps identified in a post-3.6.3 gap analysis. Additive only — no contract, routing, or dependency changes. Validator green; new feature-status claims grounded against live Microsoft Learn.

Added

  • bundles/cluster-foundations/guide.md:
    • New Storage and Stateful Data section — StorageClass selection (Azure Disk / Files / Blob / Azure Container Storage), the zonal-disk trap (managed disks are zone-pinned; WaitForFirstConsumer binding; cross-zone replication vs ZRS), StatefulSet/fsGroup/backup rules, and IaC surface anchors.
    • New CoreDNS at scale subsection under DNS — ndots:5 amplification, CoreDNS overload/throttling, NodeLocal DNSCache / LocalDNS, and Corefile safety.
    • New Static Egress Gateway (Preview) row + subsection in Outbound Connectivity — per-namespace fixed egress IP, gateway-mode node pool, StaticGatewayConfiguration CRD, and constraints (no Pod Subnet, Windows excluded, NetworkPolicy not applied to gateway egress). Verified against Microsoft Learn.
    • New Pricing Tier and SLA section — Free vs Standard vs Premium control-plane SLA and tier-gated features (Cost Analysis, LTS).
    • Added storage and pricing-tier stop conditions; corrected a threat-model mitigation from "gVisor" (not an AKS sandbox) to Pod Sandboxing (Kata) / Confidential VM node pools.
  • bundles/production-workload-controls/guide.md:
    • New Node allocatable vs capacity subsection — reserved CPU/memory/eviction headroom, sizing quotas against allocatable, and the Pending-on-an-empty-looking-node failure mode.
    • New Image pull performance and registry resilience subsection — ACR throttling, ACR geo-replication, and Artifact Streaming (Preview) for large GPU/AI images. Verified against Microsoft Learn.
  • bundles/workload-platform/guide.md: New Windows node pools subsection — mixed-OS reality, OS lifecycle, image size/pull, Calico-only NetworkPolicy, PSA gap, HostProcess/gMSA, scheduling isolation. Plus a node-allocatable cross-link.
  • bundles/operations-resilience/guide.md:
    • New Resilience Validation section — fault-injection / chaos discipline (Azure Chaos Studio, zone/node/dependency drills) to prove the HA design.
    • New Cost visibility and showback tooling subsection in Cost Controls — AKS Cost Analysis add-on (GA), Kubecost/OpenCost, tag-based allocation, budgets. Verified against Microsoft Learn.
    • New Cluster certificate rotation subsection — az aks rotate-certs, expiry monitoring, SP-credential rotation.
    • Added two Known Pitfalls rows giving the CoreDNS split-DNS trap and CoreDNS overload their own symptom/fix entries (the SKILL.md and cluster-foundations cross-references now resolve to real "full symptom and fix" content).
    • Added resilience-validation, cost-attribution, and cert-rotation items to the Production Readiness Checklist.
  • SKILL.md: Quick Routing rows for storage, per-namespace egress, CoreDNS-at-scale, and cost attribution; a storage non-negotiable (zonal-disk/allocatable); expanded the cluster-foundations bundle-catalog description; last_verified updated with the 3.7.0 summary.
  • references/quick-reference.md: Added the storage non-negotiable to mirror SKILL.md.

External validation (new claims)

  • Static Egress Gateway — Preview; --enable-static-egress-gateway, gateway-mode node pool, StaticGatewayConfiguration CRD, not supported with Azure CNI Pod Subnet, Windows excluded, NetworkPolicy not applied to gateway egress (Microsoft Learn).
  • AKS Cost Analysis add-on — GA; --enable-cost-analysis, OpenCost-based, namespace-scoped cost in Cost Management, Standard/Premium tier, EA/MCA offers (Microsoft Learn).
  • Artifact Streaming — Preview; streams ACR layers, best for images < ~30 GB (Microsoft Learn).
  • Node-allocatable reservation percentages, ZRS-disk availability, SLA percentages, and Windows version support are left as [VERIFY] markers (version/region-sensitive), consistent with the skill's freshness discipline.

Versioning

  • bundles/catalog.yaml five entries and all five bundles/*/bundle.yaml bumped 3.6.3 → 3.7.0 (MINOR — additive capability surfaces); top-level schema version: 3 unchanged.

Validator

  • python scripts/validate-skill.py . → OK: 0 errors, 0 warning(s).

3.7.1 - 2026-06-26

PATCH release. AKS managedClusters schema-coverage hardening pass in the full reference. No routing or bundle dependency changes.

Added

  • references/full-reference.md:
    • New ManagedClusters API Volatility and Pinning section with production guidance to prefer GA APIs, pin API versions, and require ADR + rollback + revalidation when preview APIs are used.
    • New ManagedClusters Property Coverage Watchlist section with high-impact IaC property checkpoints for architecture reviews, including:
      • cluster-level controls (networkProfile.advancedNetworking, apiServerAccessProfile, azureMonitorProfile, ingressProfile, securityProfile, hostedSystemProfile, nodeProvisioningProfile, nodeResourceGroupProfile, supportPlan, upgradeSettings.overrideSettings)
      • agent-pool controls (upgradeSettings.maxUnavailable and undrainableNodeBehavior, localDNSProfile, agent-pool networkProfile and securityProfile, podIPAllocationMode, artifactStreamingProfile, virtualMachinesProfile)

Why this patch

  • The skill already had strong architecture guidance, but explicit ARM/Bicep property-surface checks were sparse. This patch closes the practical gap and reduces drift risk caused by preview-to-GA property churn.

Versioning

  • Documentation-only patch. SemVer PATCH increment from 3.7.0 to 3.7.1.

3.6.3 - 2026-06-16

Correctness and cross-reference repair pass. Validator green before and after; all findings closed in a single direct fix pass after baseline discovery and a proportional external-evidence pass against live Microsoft Learn.

Round coverage:

  • Rounds run: 1 (direct review + fix). Reviewer angles: content accuracy, cross-reference quality, surface parity, production deployment / upgrade currency, final correctness / prose.
  • Aggregate result: 2 High and 1 Critical correctness findings fixed; 3 leaked-scaffolding cross-reference findings fixed; 2 Low (prose, glossary parity) fixed; 1 candidate finding refuted by external evidence.

External validation baseline

  • Official docs (Microsoft Learn): Confidential Containers on AKS is preview and retiring (node images removed 2026-03-31) — "Retirement: Confidential Containers preview on AKS is Closing Down." Pod Sandboxing runtimeClassName is exactly kata-vm-isolation. App Routing add-on ingress class is exactly webapprouting.kubernetes.azure.com.
  • Release notes / blog: ingress-nginx maintenance ends March 2026; AKS App Routing managed NGINX critical security patches through November 2026; Application Routing with Gateway API (Istio control plane) planned H1 2026 — skill verified correct, no change.

Fixed

  • bundles/operations-resilience/guide.md: Corrected the AKS Application Routing managed-NGINX ingress class from webapprouting.azure.com to webapprouting.kubernetes.azure.com in all four places (two ClusterIssuer HTTP-01 solvers, the explanatory sentence, and the ingress-shim example). Verified against Microsoft Learn "Managed NGINX ingress with the application routing add-on." Removed a leaked editorial note ("adjust if Pack S renames it") from the CVE-response cross-reference.
  • bundles/production-workload-controls/guide.md: Aligned the container-escape/sandboxing section with the Confidential Containers retirement documented in cluster-foundations. The isolation-tiers table now leads with Confidential VM node pools (AMD SEV-SNP) as the supported "data in use" pattern; per-pod AKS Confidential Containers (Kata + SEV-SNP) is flagged as a retiring preview (node images removed 2026-03-31) with a deprecation callout and a cross-link to cluster-foundations. Verified Pod Sandboxing runtimeClassName: kata-vm-isolation is correct (no change).
  • SKILL.md: Repointed the CoreDNS split-DNS trap reference from the non-existent known-pitfalls.md to the real section bundles/operations-resilience/guide.md#known-pitfalls. Updated last_verified to 2026-06-16 with the correction summary.
  • bundles/cluster-foundations/guide.md: Replaced the stale "Cross-link … once that exists" placeholder in API Server Hardening with a live cross-link to the operations-resilience audit policy / SIEM forwarding section (which now exists).
  • bundles/workload-platform/guide.md: Removed the leaked editorial note ("verify after Pack O lands") from the API Server Hardening cross-reference.
  • references/full-reference.md: Fixed broken prose — "are but should not become defaults" → "are advanced options but should not become defaults."
  • references/glossary.md: Added the missing MCP (Model Context Protocol) row to restore parity with the SKILL.md glossary.

What was confirmed correct (external evidence, no change)

  • Pod Sandboxing runtimeClassName: kata-vm-isolation (Microsoft Learn).
  • ingress-nginx March 2026 / AKS managed NGINX November 2026 EOL dates and Gateway API (Istio control plane, H1 2026) direction (AKS blog 2025-11-13, GitHub Azure/AKS#5516, Microsoft Learn).

Versioning

  • bundles/catalog.yaml five bundle entries and all five bundles/*/bundle.yaml bumped 3.6.2 → 3.6.3; top-level schema version: 3 unchanged.

Validator

  • python scripts/validate-skill.py . → OK: 0 errors, 0 warning(s).

Token efficiency

  • Before: ~57,551 est tokens; after: ~57,551 est tokens (wc -w × 1.3 proxy). Net-neutral — correctness pass, not compression. Partial-loading structure (router + lazy bundles) preserved.

Honest constraints

  • Validation performed within available tooling: skill validator (markdown links + anchors + YAML + bundle/catalog version parity) plus proportional external validation against live Microsoft Learn, the AKS Engineering Blog, and GitHub Azure/AKS. No live Azure subscription or installed Azure CLI was available; az aks/kubectl runtime commands remain verification gates, not locally executed checks. The skill is markdown guidance — no unit-test, build, or smoke-test harness exists (recorded as not available, not as passed).

3.6.2 - 2026-06-15

Quality validation and metadata sync pass.

Fixed

  • bundles/operations-resilience/guide.md: Fixed six stale Markdown anchors so the skill validator now reports 0 warnings. Links now target existing sections for secrets/data-at-rest, bootstrap ordering, pre-upgrade API inventory, add-on/operator compatibility, autoscaler/NAP upgrade behaviour, and PDB-induced drain stalls.
  • bundles/operations-resilience/guide.md: Corrected the stop-condition wording for SecurityPatch so it no longer implies the channel requires a preview feature flag; Microsoft Learn documents SecurityPatch as an available node OS auto-upgrade channel, while production use still requires explicit ownership of cadence and maintenance windows.
  • bundles/catalog.yaml and all five bundles/*/bundle.yaml manifests: synchronized bundle versions from 3.5.2 to 3.6.2 to match the current release stream after the 3.6.x content additions.

External validation

  • Verified AKS Automatic managed system node pool limitations, LocalDNS default, security restrictions, unsupported operations, and Azure CLI 2.86.0+ requirement against Microsoft Learn.
  • Verified ingress-nginx upstream maintenance ending March 2026, AKS Application Routing managed NGINX critical security patch support through November 2026, and Gateway API / AGC migration options against Microsoft Learn.
  • Verified aksManagedAutoUpgradeSchedule, aksManagedNodeOSUpgradeSchedule, NodeImage, and SecurityPatch node OS channel guidance against Microsoft Learn planned maintenance and node OS auto-upgrade documentation.
  • Verified Fleet Manager NodeImage auto-upgrade profile and az fleet autoupgradeprofile generate-update-run behavior against Microsoft Learn.
  • Verified managedNATGatewayV2 remains Preview and requires the ManagedNATGatewayV2Preview feature flag against Microsoft Learn.
  • Rechecked AKS issue #4525 as an already-covered ACNS/Cilium FQDN policy pitfall.

Validator

  • python scripts/validate-skill.py . → OK: 0 errors, 0 warning(s).

Honest constraints

  • Background explore/librarian review agents were attempted but three failed due to workspace billing balance. The pass used direct repository tools plus Microsoft Learn and web search instead.

3.6.1 - 2026-06-08

Added

  • bundles/operations-resilience/guide.md:
    • New "MaxUnavailable fallback (Preview)" subsection documenting the three-strategy fallback for node pool upgrades (full surge → surge of 1 → in-place maxUnavailable). Updated the existing --max-surge note to reference the new section. Requires aks-preview CLI extension, Azure CLI 2.34.1+, and Kubernetes >= 1.35 for the single-surge fallback step.
    • New "Node pool rollback (Preview)" subsection documenting az aks nodepool rollback and az aks nodepool get-rollback-versions for reverting node pools to pre-upgrade Kubernetes version and node image. Updated the "Upgrade Irreversibility and Recovery" section to clarify that rollback is unavailable for the control plane but available in preview for node pools. 7-day window, one-step only, must disable auto-upgrade. Requires aks-preview extension and Azure CLI 2.64.0+.
    • Added "Cluster Health Monitor (Preview)" to the Observability Baseline — AKS-managed add-on for in-cluster health checks (DNS, API server, metrics-server) with Prometheus metrics and CoreDNS auto-remediation. Requires aks-preview extension and Azure CLI 2.73.0+.
    • New "Pre-Upgrade Checklist and Runbook" section — time-bucketed quick-reference runbook (T-1 week, T-1 day, T-1 hour, During, Rollback decision flow, Post-upgrade) consolidating upgrade guidance from across the bundle into actionable checklists. Adds new content from Microsoft Learn: force upgrade (--enable-force-upgrade), undrainable node behavior (--undrainable-node-behavior Cordon, --max-blocked-nodes), node soak time, zone-balanced surge (multiples of 3 for zonal pools), AKS built-in pre-upgrade validations (quota, subnet IPs, certs/SPs, resource locks, PDB config), structured post-upgrade validation (cluster → node → platform → app), targeted upgrade event monitoring (source=upgrader), and AKS Communication Manager notifications. Cross-references fleet-management bundle for multi-cluster staged upgrades.
  • bundles/cluster-foundations/guide.md: Added managedNATGatewayV2 (Preview) to the Outbound Connectivity table — zone-redundant StandardV2 NAT gateway with IPv6 and flow log support. Documented the permanent IP model decision (Azure-managed vs customer-defined locked at cluster creation) and the one-way migration constraint with a [!IMPORTANT] callout. Updated IaC surface anchors to include managedNATGatewayV2 and the ManagedNATGatewayV2Preview feature flag requirement.
  • SKILL.md: Bumped last_verified to 2026-06-08; added MaxUnavailable fallback, node pool rollback, managedNATGatewayV2, Cluster Health Monitor, and Pre-Upgrade Checklist and Runbook to the version list.

3.6.0 - 2026-06-05

Post-Microsoft Build 2026 deep review.

Added

  • New "Build 2026 platform additions" section in SKILL.md: AKS on bare metal (Public Preview, 2026-06-02, AKS Engineering Blog); AI Runway as the model-serving umbrella (KAITO now one provider alongside NVIDIA Dynamo / KubeRay; vLLM/SGLang/TensorRT-LLM/llama.cpp); Kata MicroVM / AKS Pod Sandboxing per-pod isolation; AKS Automatic managed system node pools GA; Azure Kubernetes Fleet Manager for Arc-enabled clusters GA; Anyscale on Azure (managed Ray) Public Preview. Each Preview/GA-flagged with bundle routing and [VERIFY].
  • Cross-linked the KAITO GPU/AI guidance to AI Runway; added bare-metal / AI Runway / Kata keywords to the description for triggering.

Verified (no change)

  • Kubernetes version-currency discipline (latest GA minor, Azure Linux 3 / Ubuntu 24.04), the two-stage NGINX EOL cliff (OSS end-of-maintenance March 2026; App Routing managed NGINX critical patches through November 2026), and AGC / App Routing with Gateway API direction all current. Validator: 0 errors, 0 warnings.

3.5.3 - 2026-05-29

Currency refresh pass.

Added

  • bundles/fleet-management/guide.md: Cross-cluster networking (Preview, March 2026) alert banner. Fleet Manager recent additions summary (multi-cluster auto-upgrade GA, GitHub-attached deployments, placement drift detection, namespace-scoped placement, Arc-enabled clusters, update run approval gates, DNS-based load balancing).
  • SKILL.md: Bumped last_verified to 2026-05-29.

3.5.2 - 2026-05-14

PATCH release. External validation against current Microsoft Learn, GitHub upstream sources, and community signal surfaced nine drift findings. All have been corrected in-place; no contract or routing changes.

Drift corrections

  • cluster-foundations

    • Corrected the AKS Security Bulletin worked example to AKS-2026-0003 / CVE-2026-31431 (algif_aead kernel LPE - Copy Fail). Prior fabricated CVE IDs replaced with the verified bulletin reference and an explicit "verify against the current AKS Security Bulletins feed" caveat.

  • Added Confidential Containers deprecation banner - Microsoft has announced retirement of AKS Confidential Containers (Kata + AMD SEV-SNP) in March 2026. New AKS projects should use Confidential VM node pools (AMD SEV-SNP) for data-in-use protection; existing confidential-container workloads need a migration plan.

  • Documented AKS Automatic structural limits verified 2026-05-14: West US region cannot use availability zones on AKS Automatic; Deployment Safeguards level is fixed and cannot be relaxed via Azure Policy exemption.

  • operations-resilience

    • Flagged kubent / kube-no-trouble as stale upstream (no release since August 2024). Recommended pluto as the actively-maintained alternative for pre-upgrade API deprecation inventory.

  • Added AKS Capacity-Based Surge note (April 2026 AKS release) - maxSurge and maxUnavailable can now coexist on the same node-pool upgrade, useful when subscription vCPU quota is the binding constraint.

  • Promoted SecurityPatch node OS upgrade channel from preview to GA in the channel comparison table (verified against Microsoft Learn).

  • Documented ingress NGINX retirement clifftops: upstream ingress-nginx reaches end-of-life in March 2026; AKS managed-NGINX (legacy nginxIngress) reaches end of support in November 2026. Treat App Routing on Gateway API or Application Gateway for Containers (AGC) as the migration target.

  • production-workload-controls

    • Updated Ratify references to reflect the move from ratify-project/ratify to notaryproject/ratify (CNCF Sandbox). Pinned to config.ratify.deislabs.io/v1beta1 for production today; flagged v2alpha1 as in development.

  • Documented AKS issue #4525 - Cilium FQDN egress policy combined with a default-deny NetworkPolicy that does not also allow CoreDNS egress causes Cilium DNS lookups to crash-loop pods. Recommended pairing every FQDN egress rule with an explicit DNS allow rule and non-prod validation.

  • SKILL.md

    • Removed the preview qualifier from SecurityPatch references to match the channel's current GA status.

Versioning

  • bundles/catalog.yaml - five bundle entries bumped to version: 3.5.2; top-level schema version: 3 unchanged.
  • All five bundles/*/bundle.yaml files bumped to version: 3.5.2.
  • Validator green: 0 errors, 0 warnings.

Out of scope for 3.5.2

  • No contract or routing changes - bundle dependencies, capability names, and top-level SKILL.md non-negotiables remain identical to 3.5.1.
  • No new bundles or sections - additive surface stays unchanged.

3.5.1 - earlier 2026

Prior PATCH release covering Round 5 micro fix-pack (named gaps closed across all five bundles, cross-bundle anchor warnings resolved). Superseded by 3.5.2.

3.5.0

Round 4 baseline with full Fleet Manager bundle, NodeImage auto-upgrade profile guidance, and emergency CVE response runbook. Superseded by 3.5.1.

3.19.1 - 2026-08-25

PATCH. Full improve-skill rerun (2026-08-25-full, improve-skill v4.8.0). Fixed Rule-23 metadata defect: frontmatter last_verified held a multi-thousand-word changelog narrative instead of a date (same defect class microsoft-foundry fixed at 1.1.58); reduced to a bare ISO date - the history already lives in this CHANGELOG. Fresh probes: Azure/AKS releases (newest 2026-08-07, covered by 3.13.0+), azure-aks-docs commit sweep (no commits since morning run), kubectl v1.34.1 client on machine consistent with documented version currency.

Source: SKILL.md on GitHub

Third-party checks

No alerts8d3 checks · Risk SAFE
  • Gen Agent Trust Hub8d

    The skill is a comprehensive architecture and configuration guide for Azure Kubernetes Service (AKS). it emphasizes security best practices, including RBAC, NetworkPolicy, workload identity, and kernel-level isolation for AI agents. No malicious patterns or security risks were detected.

  • Socket8d

    No alerts

  • Snyk8d

    Risk: LOW · No issues

Provenance

Signed by skilld at 2cc2455. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated last month

Capability

metadata
{
  "last_verified": "2026-08-26"
}
Other metadata
argument-hint
workload=<type>; region=<azure-region>; availability=<SLO>; network=<hub-spoke|standalone>; scope=<new-cluster|production-review|fleet>

README badge

README badge for lukemurraynz/hve-agent-skills/aks-cluster-architecture