Azure Kubernetes

AKS Automatic Readiness Assessment

AUTHORITATIVE GUIDANCE — MANDATORY COMPLIANCE

>

This skill assesses existing AKS clusters or local manifests for AKS Automatic compatibility.

For creating a new AKS Automatic cluster, use the azure-kubernetes skill instead.

See constraint spec for all safeguard rules, common fixes for YAML patterns, migration guide for end-to-end steps, and MCP integration for tool details and fallback handling.

You are an AKS Automatic compatibility assessment agent. Your job is to evaluate whether Kubernetes workloads and cluster configurations are compatible with AKS Automatic, identify issues, and help users fix them.

AKS Automatic enforces Deployment Safeguards (21 active policies, some deny, some warn only), Pod Security Standards (Baseline mandatory, Restricted optional), 2 active webhook mutators that auto-fix certain fields at admission (resource-requests defaults and anti-affinity/topology-spread), and 23 cluster-level configuration requirements.

Quick Reference

When to Use This Skill

• "Can I migrate to AKS Automatic?"
• "Check my cluster readiness for Automatic"
• "Validate manifests against AKS Automatic constraints"
• "Fix my deployment for Automatic compatibility"
• "Identify AKS Automatic migration blockers"
• Any mention of AKS Automatic + (migration | readiness | compatibility | assessment | validation)

Routing Rules

Route to azure-kubernetes instead:

• "Create an AKS cluster" / "What are AKS best practices?" / "How do I deploy to AKS?"
• General cluster creation, configuration, scaling, or AKS operations

Route to azure-diagnostics instead:

• "My pod is crashing" / "Debug my AKS cluster" / "Why is my deployment failing?"
• Live troubleshooting, debugging, error diagnosis on a running cluster

Guardrails — READ FIRST

1. Read-only: NEVER modify cluster state. Assessment is read-only. Do not run kubectl apply, az aks update, or any command that changes the cluster. 2. No secrets: Do NOT transmit, display, or include in diffs: Secret data values, ConfigMap data values, environment variable values from valueFrom.secretKeyRef, service account tokens, or connection strings. 3. User approval for file changes: Present every fix as a diff. The user must explicitly accept before you write to any file. 4. Scope boundaries: Route cluster creation/deletion questions → azure-kubernetes skill. Route live troubleshooting → azure-diagnostics skill.

MCP Tools

Workflow

Step 1: Determine Scope

Ask the user what they want to assess:

Option A — Cluster-connected assessment (via AKS MCP) Use when the user has a connected cluster context (subscription + resource group + cluster name).

Option B — Offline manifest validation Use when the user has local Kubernetes manifests, Helm charts, or Kustomize overlays in their workspace. Search for files containing apiVersion: and kind: matching Deployment, StatefulSet, DaemonSet, Job, CronJob, Pod, Service, PodDisruptionBudget, or StorageClass. For Helm charts, look for Chart.yaml and rendered templates under templates/.

Option C — Single manifest check If the user pastes or points to a single YAML manifest, validate it directly without asking for scope.

Step 2: Run Assessment

Cluster-Connected Mode

Call the AKS MCP tool — this is the preferred path. Always call discover first to get the available actions, then use the assessment action name returned in the response:

// Step 1: Discover available actions
mcp_azure_mcp_aks({ action: "discover" })

// Step 2: Use the assessment action name from the discover response
mcp_azure_mcp_aks({
  action: "<action-from-discover>",
  subscriptionId: "<subscription-id>",
  resourceGroupName: "<resource-group>",
  resourceName: "<cluster-name>",
  scope: {
    excludeNamespaces: ["kube-system", "gatekeeper-system"],
    workloadTypes: ["Deployment", "StatefulSet", "DaemonSet", "CronJob", "Job"]
  }
})

Required permissions:

• Microsoft.ContainerService/managedClusters/read
• Microsoft.ContainerService/managedClusters/listClusterUserCredential/action

For large clusters (500+ workloads), the API may return HTTP 202 with a Location header. Poll the location URL using the Retry-After interval until a 200 response is received.

Parsing the MCP response: 1. `summary` — aggregate counts: compatible, requiresChanges, incompatible, autoFixed, totalWorkloads, clusterConfigIssues 2. `clusterConfiguration` — cluster-level issues with constraintId, severity, remediation (az CLI commands), and documentationUrl 3. `workloads[]` — per-workload array, each with name, namespace, kind, overallStatus, and issues[]

Each issue in workloads[].issues[] contains: constraintId, severity (incompatible/requiresChanges/autoFixed/informational), description, field (JSON Pointer), suggestedPatch (JSON Patch for deterministic fixes), remediationGuide (for LLM-reasoned fixes).

Fallback Chain

1. MCP tool (mcp_azure_mcp_aks)  → preferred, live cluster data
   ↓ fails (tool not found — Azure MCP server not configured)
2. Offline validation            → works on local manifests without any cluster

If mcp_azure_mcp_aks is not available, inform the user:

"The Azure MCP server is not configured in your editor. To enable live cluster assessment, follow the setup guide at aka.ms/azure-mcp-setup. For now, I can validate your local manifests offline."

Then proceed to offline mode.

Offline Mode

Load the constraint spec from references/constraint-spec-v1.yaml and evaluate each manifest. The check field tells you what to check for and what fields to check. The fix field will tell you any allowed values and possible fixes. You should evaluate each of the safeguards with each of the manifests to determine if the manifests are compatible. Suggest any fixes that are needed.

Key Checks: Per container (containers, initContainers, ephemeralContainers):

• Resource requests/limits → safeguard-container-resource-requests
• Readiness and liveness probes → safeguard-probes-configured (warning-only — not blocked at admission; treat as informational)
• Image tag not :latest → safeguard-images-no-latest
• securityContext.privileged not true → safeguard-no-privileged-containers
• capabilities.add only adds allowed capabilities → safeguard-container-capabilities
• seccompProfile is RuntimeDefault/Localhost → safeguard-allowed-seccomp-profiles
• no host field in any container probes and lifecycle hooks → safeguard-host-probes

Per pod spec:

• hostPID/hostIPC not true → safeguard-block-host-namespaces (incompatible)
• hostNetwork/hostPort not true → safeguard-host-network-ports (incompatible)
• No hostPath volumes → safeguard-no-host-path-volumes (incompatible)

Per workload type:

• Deployments/StatefulSets with replicas > 1: podAntiAffinity or topologySpreadConstraints → safeguard-pod-enforce-antiaffinity
• StorageClass: CSI provisioner (not in-tree) → safeguard-csi-driver-storage-class

Severity Classification

Step 3: Present Findings

Always start with the summary:

## AKS Automatic Readiness Assessment

| Status | Count |
|--------|-------|
| ✅ Compatible | X workloads |
| ⚠️ Requires changes | Y workloads |
| ❌ Incompatible | Z workloads |
| 🔧 Auto-fixed by Automatic | W workloads |
| 🏗️ Cluster config issues | N issues |

Grouping: ≤ 10 issues → list individually; > 10 → group by constraint ID. Always show incompatible first (migration blockers), then requiresChanges, then autoFixed, then cluster config.

Per-issue format:

### ❌ [constraint-id] — Short description
**Severity:** incompatible | requiresChanges
**Affected:** namespace/resource-name (Kind)
**Current:** <what the manifest has>
**Required:** <what AKS Automatic requires>
**Fix:** <remediation summary>
**Docs:** <documentation URL>

Step 4: Offer Fixes

Deterministic fixes (have suggestedPatch — generate YAML diff directly):

• safeguard-container-resource-requests — add resources.requests
• safeguard-container-capabilities — remove capabilities.add
• safeguard-allowed-seccomp-profiles — patch only when seccompProfile.type: Unconfined is present, or when the MCP suggestedPatch explicitly requires a seccomp change
• safeguard-enforce-apparmor — add AppArmor annotation
• safeguard-csi-driver-storage-class — replace in-tree provisioner

Use patterns in references/common-fixes.md and generate a before/after diff. Starting resource values use safe defaults — VPA (enabled on Automatic) will auto-tune after deployment.

LLM-reasoned fixes (require app context; use remediationGuide):

• safeguard-images-no-latest — correct tag is user- and release-specific; ask the user: _"What specific version tag or SHA digest should I pin this image to?"_ Do not guess
• safeguard-pod-enforce-antiaffinity — needs app labels for selector
• safeguard-no-host-path-volumes — replacement depends on what hostPath is used for
• safeguard-block-host-namespaces — may require architecture redesign
• safeguard-host-network-ports — needs alternative networking approach

For incompatible findings (e.g., hostPath volumes), explain the issue and propose alternatives. For log-collection hostPath, suggest: Azure Monitor Container Insights (recommended, auto-enabled), Azure Files CSI volume, emptyDir, or sidecar pattern.

Fix application flow: 1. Generate the fix as a YAML diff 2. Show the diff with explanation 3. Wait for explicit approval: "apply", "edit", or "skip" 4. On approval, apply the change to the file 5. Move to the next finding

If the user says "fix all" or "apply all deterministic fixes", first generate a single combined diff containing all eligible suggestedPatch-based fixes, show that combined diff with an explanation, and wait for one explicit approval before applying any writes. After approval, apply the batched changes and then suggest re-validation.

Step 5: Recommend Next Steps

All issues resolved (or only autoFixed remaining):

Your workloads are ready for AKS Automatic! Next steps:
1. Review auto-fixed items — AKS Automatic will mutate N fields at admission.
2. Apply cluster configuration changes (see cluster config issues above).
3. Perform the SKU switch — follow the migration guide.
4. Verify — after migration, check all workloads are running and healthy.

See references/migration-guide-summary.md for the full migration checklist.

Incompatible findings remain: List blockers and offer three options: redesign workloads, keep on a separate AKS Standard cluster, or use Automatic for compatible + Standard for incompatible workloads.

Cluster config issues remain (Day-0 decisions): API Server VNet Integration, node pool OS SKU (requires recreating system node pools), and ephemeral OS disks require a new cluster — redirect to azure-kubernetes skill for cluster creation help.

Error Handling

Reference Files

⚠️ Warning: This skill bundles constraint spec v1.1.1 (2026-03-15), covering 23 cluster-level constraints, 21 active Deployment Safeguards policies (9 best practices policies, 12 Pod Security Standards policies), and 2 active mutators. Always note the spec version in assessment output.

Common Fix Patterns for AKS Automatic Compatibility

Loaded on demand when generating YAML fixes during assessment. Maps to constraint IDs in constraint-spec-v1.yaml.

---

safeguard-container-resource-requests — Add resource requests/limits

Before:

containers:
  - name: web
    image: myapp:v1.0.0

After:

containers:
  - name: web
    image: myapp:v1.0.0
    resources:
      requests:
        cpu: "250m"
        memory: "256Mi"
      limits:
        cpu: "500m"
        memory: "512Mi"

💡 Tip: Use safe minimums as starting values. VPA (auto-enabled on AKS Automatic) will tune these after deployment based on actual usage.

---

safeguard-container-capabilities — Drop all capabilities

Before:

securityContext:
  capabilities:
    add: ["NET_ADMIN"]

After:

securityContext:
  capabilities:
    drop: ["ALL"]

⚠️ Warning: If the app genuinely requires NET_ADMIN or similar, it is incompatible with AKS Automatic. Do not silently drop — explain the incompatibility and suggest redesign.

---

safeguard-allowed-seccomp-profiles — Add seccomp profile

Before:

spec:
  containers:
    - name: web

After:

spec:
  securityContext:
    seccompProfile:
      type: RuntimeDefault
  containers:
    - name: web

---

safeguard-allowed-seccomp-profiles — Remove 'Unconfined' seccomp profile

Before:

spec:
  securityContext:
    seccompProfile:
      type: Unconfined
  containers:
    - name: web

After:

spec:
  containers:
    - name: web

---

safeguard-enforce-apparmor — Add AppArmor annotation

Before:

metadata:
  name: my-deployment

After:

metadata:
  name: my-deployment
  annotations:
    container.apparmor.security.beta.kubernetes.io/web: runtime/default

💡 Tip: Replace web with the actual container name. Add one annotation per container.

---

safeguard-images-no-latest — Pin image tag (LLM-reasoned — ask user)

Before:

image: myapp:latest

After:

image: myapp:v1.2.3   # ← version confirmed with user

⚠️ Warning: Do not guess the version. Ask the user: _"What specific version tag or SHA digest should I pin this image to?"_ If from a public registry, suggest checking Docker Hub or the registry for the latest stable tag.

---

safeguard-probes-configured — Add probes (best-practice recommendation — warning-only, not blocked at admission)

HTTP app (most common):

readinessProbe:
  httpGet:
    path: /healthz        # ← ask user for their health endpoint
    port: 8080            # ← ask user for port
  initialDelaySeconds: 5
  periodSeconds: 10
  failureThreshold: 3
livenessProbe:
  httpGet:
    path: /healthz
    port: 8080
  initialDelaySeconds: 15
  periodSeconds: 20
  failureThreshold: 3

TCP-only app (databases, Redis, etc.):

readinessProbe:
  tcpSocket:
    port: 6379           # ← service port
  initialDelaySeconds: 5
  periodSeconds: 10
livenessProbe:
  tcpSocket:
    port: 6379
  initialDelaySeconds: 15
  periodSeconds: 20

gRPC app:

readinessProbe:
  grpc:
    port: 50051
  initialDelaySeconds: 5
  periodSeconds: 10

---

safeguard-host-probes — Remove host field in probes and lifecycle hooks

Before:

spec:
  containers:
  - name: my-container
    image: nginx:v1.2.3
    livenessProbe:
      httpGet:
        host: "my-host"
        path: /healthz
        port: 8080
      initialDelaySeconds: 15
      periodSeconds: 20
      failureThreshold: 3

After: Remove the host field Example:

spec:
  containers:
  - name: my-container
    image: nginx:v1.2.3
    livenessProbe:
      httpGet:
        path: /healthz
        port: 8080
      initialDelaySeconds: 15
      periodSeconds: 20
      failureThreshold: 3

---

safeguard-pod-enforce-antiaffinity — Add topology spread (LLM-reasoned — ask user for label)

Ask user: _"What label key/value identifies your workload's pods?"_

spec:
  template:
    spec:
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: kubernetes.io/hostname
          whenUnsatisfiable: DoNotSchedule
          labelSelector:
            matchLabels:
              app: <app-label>     # ← from user
      containers:
        - name: web

---

safeguard-csi-driver-storage-class — Migrate in-tree to CSI

Before (Azure Disk in-tree):

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: fast-storage
provisioner: kubernetes.io/azure-disk
parameters:
  skuName: Premium_LRS
reclaimPolicy: Delete
volumeBindingMode: Immediate

After (Azure Disk CSI):

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: fast-storage
provisioner: disk.csi.azure.com
parameters:
  skuName: Premium_LRS
reclaimPolicy: Delete
volumeBindingMode: WaitForFirstConsumer   # ← preferred for zonal disks

---

PodDisruptionBudget — Add missing PDB

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: <app-name>-pdb
  namespace: <namespace>
spec:
  maxUnavailable: 1
  selector:
    matchLabels:
      app: <app-label>

PodDisruptionBudget — Fix blocking maxUnavailable: 0

Before:

spec:
  maxUnavailable: 0

After:

spec:
  maxUnavailable: 1

⚠️ Warning: maxUnavailable: 0 completely blocks node drain during AKS Automatic upgrades. At least 1 pod must be allowed unavailable for upgrades to proceed.

---

safeguard-no-host-path-volumes — Replace hostPath (incompatible — suggest alternatives)

emptyDir example:

volumes:
  - name: scratch
    emptyDir: {}

Azure Files CSI PVC example:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: logs-pvc
spec:
  accessModes:
    - ReadWriteMany
  storageClassName: azurefile-csi
  resources:
    requests:
      storage: 10Gi

MCP Integration Reference

Loaded when troubleshooting MCP tool calls, debugging the fallback chain, or understanding the API response format.

---

Tool Discovery

Always call mcp_azure_mcp_aks first to discover the current available tool surface. Do not assume a fixed action name — the available actions depend on the MCP server version deployed to the client.

mcp_azure_mcp_aks({ action: "discover" })

The response lists available actions and their parameter schemas. Use the returned schema — do not hardcode parameter names.

---

Assessment Call

After calling discover, use the assessment action name returned in the response. Pass parameters according to the discovered schema — do not hardcode action names or API versions.

Typical parameters include:

• subscriptionId — Azure subscription ID
• resourceGroupName — resource group containing the cluster
• resourceName — AKS cluster name
• scope (optional) — filter by namespaces or workload types

Example shape (use actual action name and schema from discover output):

mcp_azure_mcp_aks({
  action: "<action-from-discover>",
  subscriptionId: "<subscription-id>",
  resourceGroupName: "<resource-group>",
  resourceName: "<cluster-name>",
  scope: {
    excludeNamespaces: ["kube-system", "gatekeeper-system", "azure-arc"],
    workloadTypes: ["Deployment", "StatefulSet", "DaemonSet", "CronJob", "Job"]
  }
})

All scope parameters are optional. If omitted, the API assesses all workloads excluding kube-system and gatekeeper-system.

---

Required Permissions

# Check current role assignments
az role assignment list \
  --assignee $(az ad signed-in-user show --query id -o tsv) \
  --scope /subscriptions/<subscription-id>/resourceGroups/<rg>/providers/Microsoft.ContainerService/managedClusters/<cluster>

# Minimum permissions required:
# - Microsoft.ContainerService/managedClusters/read
# - Microsoft.ContainerService/managedClusters/listClusterUserCredential/action

# Assign if missing (requires Owner or User Access Administrator)
az role assignment create \
  --assignee <principal-id> \
  --role "Azure Kubernetes Service Cluster User Role" \
  --scope /subscriptions/<subscription-id>/resourceGroups/<rg>/providers/Microsoft.ContainerService/managedClusters/<cluster>

---

Response Schema

The API returns three top-level sections:

summary

{
  "summary": {
    "totalWorkloads": 42,
    "compatible": 27,
    "requiresChanges": 12,
    "incompatible": 3,
    "autoFixed": 8,
    "clusterConfigIssues": 4
  }
}

clusterConfiguration

{
  "clusterConfiguration": [
    {
      "constraintId": "cluster-oidc-issuer",
      "severity": "requiresChanges",
      "description": "OIDC issuer not enabled",
      "remediation": "az aks update --enable-oidc-issuer --resource-group <rg> --name <cluster>",
      "documentationUrl": "https://learn.microsoft.com/azure/aks/..."
    }
  ]
}

workloads[]

{
  "workloads": [
    {
      "name": "sample-app",
      "namespace": "default",
      "kind": "Deployment",
      "overallStatus": "requiresChanges",
      "issues": [
        {
          "constraintId": "safeguard-images-no-latest",
          "severity": "requiresChanges",
          "description": "Container 'web' uses :latest image tag",
          "field": "/spec/containers/0/image",
          "suggestedPatch": null,
          "remediationGuide": "Pin the image to a specific version or SHA digest"
        }
      ]
    }
  ]
}

---

Async Response Handling (HTTP 202 — Large Clusters)

For clusters with 500+ workloads, the API returns HTTP 202 Accepted with a Location header. Poll until complete:

// Initial call returns: { status: 202, headers: { Location: "...", "Retry-After": "30" } }
async function pollAssessment(locationUrl, retryAfterSeconds) {
  while (true) {
    await new Promise(r => setTimeout(r, retryAfterSeconds * 1000));
    const response = await mcp_azure_mcp_aks({
      action: "pollOperation",
      locationUrl: locationUrl
    });
    if (response.status === "Succeeded") return response.result;
    if (response.status === "Failed") throw new Error(response.error.message);
    retryAfterSeconds = response.retryAfter ?? retryAfterSeconds;
  }
}

---

Fallback Chain

Attempt each step in order. Do not ask the user which is available — just try:

1. mcp_azure_mcp_aks → discover, then call the assessment action returned
   ↓ fails (tool not found — Azure MCP server not configured)

2. Inform user to install Azure MCP, then fall back to offline validation
   kubectl get deployment,statefulset,daemonset,job,cronjob -A -o yaml > /tmp/workloads.yaml
   kubectl get pdb,storageclass -A -o yaml > /tmp/policies.yaml

If mcp_azure_mcp_aks is not available, say:

"The Azure MCP server is not configured. To enable live cluster assessment, install it following aka.ms/azure-mcp-setup. For now, I can validate your local manifests offline — export them with kubectl get ... -o yaml or share your manifest files."

Then proceed to offline manifest validation against constraint-spec-v1.yaml.

---

Prerequisites Verification

Run these before attempting MCP or CLI assessment:

# 1. Verify Azure login
az account show --query "{name:name, id:id, state:state}" -o table

# 2. Verify cluster exists and is accessible
az aks show \
  --resource-group <rg> \
  --name <cluster> \
  --query "{name:name, provisioningState:provisioningState, sku:sku.name}" \
  -o table

# 3. Verify kubectl context
kubectl config current-context
kubectl cluster-info

// 4. Verify MCP server is reachable (Azure MCP)
// If this returns available actions, MCP is configured
mcp_azure_mcp_aks({ action: "discover" })

---

Common MCP Errors

AKS Automatic Migration Guide

Loaded when user asks about migration steps or after assessment is complete.

---

Migration Checklist

Phase 1 — Assessment (this skill)

• [ ] Run the AKS Automatic compatibility assessment (via mcp_azure_mcp_aks({ action: "discover" }) then the assessment action returned, or the offline manifest scan)
• [ ] Resolve all incompatible findings — these are hard blockers
• [ ] Apply all requiresChanges fixes — these will be denied at admission
• [ ] Review autoFixed items — understand what AKS Automatic will mutate at runtime
• [ ] Address cluster-level Day-0 config issues (see below)

Phase 2 — Create AKS Automatic Cluster (use azure-kubernetes skill)

az aks create \
  --resource-group <resource-group> \
  --name <new-cluster-name> \
  --sku automatic \
  --location <location> \
  --generate-ssh-keys

💡 Tip: AKS Automatic auto-enables: OIDC issuer, workload identity, Azure CNI Overlay, NAP, VPA, Azure Monitor Container Insights, Deployment Safeguards, and Pod Security Standards (Baseline). No manual configuration needed for these.

Phase 3 — Validate on New Cluster

# Get credentials
az aks get-credentials \
  --resource-group <resource-group> \
  --name <new-cluster-name>

# Dry-run server-side apply — catches admission policy rejections
kubectl apply --dry-run=server -f <manifests-directory>/

# Deploy to a staging namespace first
kubectl create namespace staging
kubectl apply -f <manifests-directory>/ -n staging

# Watch pod startup
kubectl get pods -n staging -w

# Check events for admission rejections
kubectl get events -n staging --sort-by=.lastTimestamp | grep -i "denied\|error\|failed"

⚠️ Keep the old cluster running for a rollback window (recommended: 48 hours minimum) while you validate workloads on the new AKS Automatic cluster.

Phase 4 — Decommission Old Cluster

# Only after confirming workloads are stable on AKS Automatic
az aks delete \
  --resource-group <resource-group> \
  --name <old-cluster-name> \
  --yes --no-wait

---

Day-0 Decisions — Cluster-Level Configuration Requirements

Some settings require creating a new cluster; others can be enabled on existing clusters. Route to azure-kubernetes skill for cluster creation.

---

What AKS Automatic Auto-Enables

No manual setup needed for these — show this list when user asks "what do I get for free":

---

Post-Migration Verification Commands

# Verify all pods running
kubectl get pods -A | grep -v Running | grep -v Completed

# Check for pods stuck in Pending (may indicate resource quota or node issues)
kubectl get pods -A --field-selector status.phase=Pending

# Check Deployment Safeguards are active
kubectl get constrainttemplate -A

# Verify VPA is running
kubectl get vpa -A

# Check NAP node pools
az aks nodepool list \
  --resource-group <resource-group> \
  --cluster-name <cluster-name> \
  --query "[].{name:name, mode:mode, osType:osType, count:count}" \
  -o table

# View Container Insights metrics
az aks show \
  --resource-group <resource-group> \
  --name <cluster-name> \
  --query addonProfiles.omsagent.enabled

AKS Cluster Autoscaler (CAS)

Enable and tune the Cluster Autoscaler to automatically scale down idle nodes.

Check CAS Status

az aks show \
  --name "<CLUSTER_NAME>" --resource-group "<RESOURCE_GROUP>" \
  --query "agentPoolProfiles[].{name:name, casEnabled:enableAutoScaling, min:minCount, max:maxCount, count:count}" \
  -o table

az aks show \
  --name "<CLUSTER_NAME>" --resource-group "<RESOURCE_GROUP>" \
  --query "autoScalerProfile" -o json

Check Node Utilization (7 days)

Follow the metrics discovery steps in azure-aks-rightsizing.md to list available metric definitions and query node CPU utilization. Use metric names such as node_cpu_usage_percentage or cpuUsagePercentage depending on what's available on the cluster.

Enable CAS

# Cluster-level
az aks update \
  --name "<CLUSTER_NAME>" --resource-group "<RESOURCE_GROUP>" \
  --enable-cluster-autoscaler \
  --min-count <MIN_NODES> --max-count <MAX_NODES>

# Specific node pool
az aks nodepool update \
  --cluster-name "<CLUSTER_NAME>" --resource-group "<RESOURCE_GROUP>" \
  --name "<NODEPOOL_NAME>" \
  --enable-cluster-autoscaler \
  --min-count <MIN_NODES> --max-count <MAX_NODES>

Recommended min/max Defaults

Risk: Low. CAS only scales down when pods can be safely rescheduled. Set min-count >= 2 for production HA.

Tune CAS Profile

Apply when CAS is already on but idle nodes persist:

⚠️ Warning: Setting skip-nodes-with-system-pods=false allows CAS to evict system pods. Ensure all system pods in kube-system have PodDisruptionBudgets before enabling this.

az aks update \
  --name "<CLUSTER_NAME>" --resource-group "<RESOURCE_GROUP>" \
  --cluster-autoscaler-profile \
    scale-down-delay-after-add=10m \
    scale-down-unneeded-time=10m \
    scale-down-utilization-threshold=0.5 \
    max-graceful-termination-sec=600 \
    skip-nodes-with-system-pods=false

To roll back to CAS defaults:

az aks update \
  --name "<CLUSTER_NAME>" --resource-group "<RESOURCE_GROUP>" \
  --cluster-autoscaler-profile ""

Profile Comparison

Risk: High for aggressive tuning. Ensure PodDisruptionBudgets (PDBs) are set on critical workloads before tuning. Always confirm with user before applying.

>

Check existing PDBs before tuning:

```bash

kubectl get pdb --all-namespaces

```

AKS Pod Rightsizing

Identify pods requesting far more CPU/memory than they use and recommend reduced resource requests.

Prerequisites — Check Monitoring State First

Before collecting usage data, determine what monitoring is available on the cluster:

# 1. Check if Azure Managed Prometheus is enabled
az aks show \
  --name "<CLUSTER_NAME>" --resource-group "<RESOURCE_GROUP>" \
  --query "azureMonitorProfile.metrics.enabled" -o tsv

# 2. Check if Container Insights (Log Analytics) is enabled
az aks show \
  --name "<CLUSTER_NAME>" --resource-group "<RESOURCE_GROUP>" \
  --query "addonProfiles.omsagent.enabled" -o tsv

# 3. Check if Metrics Server is running (pre-installed on AKS, but may be unhealthy)
kubectl get deployment metrics-server -n kube-system

Based on the result, follow the appropriate path:

If nothing is enabled, Metrics Server is pre-installed on AKS — confirm it is healthy and use it for live rightsizing data:

```bash

kubectl get deployment metrics-server -n kube-system

kubectl top pods --all-namespaces --sort-by=cpu

```

For historical P95 trends (more accurate rightsizing), recommend enabling Azure Managed Prometheus. Warn user this incurs cost and wait for confirmation before proceeding.

---

Detection

# Authenticate to cluster
az aks get-credentials --name "<CLUSTER_NAME>" --resource-group "<RESOURCE_GROUP>"

# List requests/limits for ALL containers per pod (includes sidecars)
# Using [*] ensures multi-container pods are not misrepresented
kubectl get pods --all-namespaces \
  -o custom-columns="NAMESPACE:.metadata.namespace,POD:.metadata.name,CONTAINERS:.spec.containers[*].name,CPU_REQ:.spec.containers[*].resources.requests.cpu,MEM_REQ:.spec.containers[*].resources.requests.memory,CPU_LIM:.spec.containers[*].resources.limits.cpu,MEM_LIM:.spec.containers[*].resources.limits.memory"

# Live per-container usage (shows each container individually, including sidecars)
kubectl top pods --all-namespaces --containers --sort-by=cpu

Historical Metrics (Azure Monitor — use when Prometheus or Container Insights is enabled)

First discover available metric names, then query:

az monitor metrics list-definitions \
  --resource "<AKS_RESOURCE_ID>" \
  --query "[].name.value" -o tsv

az monitor metrics list \
  --resource "<AKS_RESOURCE_ID>" \
  --metric "<METRIC_NAME_FROM_ABOVE>" \
  --interval PT1H --aggregation Average \
  --start-time "<YYYY-MM-DDTHH:mm:ssZ>" \
  --end-time "<YYYY-MM-DDTHH:mm:ssZ>"

Optimization Rules

For VPA setup and configuration, see azure-aks-vpa.md.

YAML Patch Format

# Rightsizing patch for <NAMESPACE>/<DEPLOYMENT_NAME>
# Current: CPU request=<CURRENT>, P95 actual=<ACTUAL>
# Recommended: CPU request=<NEW> (P95 * 1.2 buffer)
apiVersion: apps/v1
kind: Deployment
metadata:
  name: <DEPLOYMENT_NAME>
  namespace: <NAMESPACE>
spec:
  template:
    spec:
      containers:
      - name: <CONTAINER_NAME>
        resources:
          requests:
            cpu: "<NEW_CPU>"
            memory: "<NEW_MEM>"
          limits:
            cpu: "<NEW_CPU_LIMIT>"     # e.g. CPU limit = 1.5x CPU request, or preserve existing limit-to-request ratio
            memory: "<NEW_MEM_LIMIT>"  # e.g. memory limit = 1.25x memory request, or preserve existing limit-to-request ratio

Risk: Medium-High. Always review patches before applying. Test in non-production first. Get explicit user confirmation before applying to production.

AKS Spot Node Pools

Recommend and create Spot VM node pools for batch, dev/test, or fault-tolerant workloads (60-90% cost reduction vs regular nodes).

Check Existing Node Pools

az aks nodepool list \
  --cluster-name "<CLUSTER_NAME>" --resource-group "<RESOURCE_GROUP>" \
  --query "[].{name:name, vmSize:vmSize, priority:scaleSetPriority, count:count, mode:mode}" \
  -o table

Identify Spot-Suitable Workloads

Before creating a Spot pool, identify which workloads can tolerate interruptions:

# List deployments without PodDisruptionBudgets (single-replica or no PDB = higher eviction risk)
kubectl get deployments --all-namespaces -o json | \
  jq -r '.items[] | select(.spec.replicas == 1) | "\(.metadata.namespace)/\(.metadata.name)"'

# Check which pods already have spot tolerations
kubectl get pods --all-namespaces -o json | \
  jq -r '.items[] | select(.spec.tolerations[]?.key == "kubernetes.azure.com/scalesetpriority") | "\(.metadata.namespace)/\(.metadata.name)"'

Use the suitability table below to decide which workloads to migrate.

Mixed Node Pool Pattern (Spot + Regular)

For workloads that need resilience but want cost savings, use a mixed approach:

# Keep existing regular node pool as fallback (min 1-2 nodes)
az aks nodepool update \
  --cluster-name "<CLUSTER_NAME>" --resource-group "<RESOURCE_GROUP>" \
  --name "<REGULAR_POOL>" \
  --enable-cluster-autoscaler --min-count 1 --max-count 3

# Add Spot pool for the majority of workload capacity
# -1 means pay up to on-demand price (no cap); set e.g. 0.05 to cap hourly spend
az aks nodepool add \
  --cluster-name "<CLUSTER_NAME>" --resource-group "<RESOURCE_GROUP>" \
  --name "<SPOT_POOL_NAME>" \
  --priority Spot --eviction-policy Delete --spot-max-price -1 \
  --node-vm-size "<VM_SIZE>" \
  --node-count 3 --min-count 0 --max-count 10 \
  --enable-cluster-autoscaler \
  --node-taints "kubernetes.azure.com/scalesetpriority=spot:NoSchedule" \
  --labels "kubernetes.azure.com/scalesetpriority=spot"

Pods that tolerate Spot but don't require it (no nodeSelector or required node affinity pinning them to the Spot pool) will be rescheduled onto the regular pool after eviction. Pods pinned to Spot via nodeSelector cannot reschedule and will remain pending until a Spot node is available again.

Workload Toleration (add to Deployment YAML)

tolerations:
- key: "kubernetes.azure.com/scalesetpriority"
  operator: "Equal"
  value: "spot"
  effect: "NoSchedule"
nodeSelector:
  kubernetes.azure.com/scalesetpriority: spot

Suitability

Risk: Low for batch/dev. High for production stateful workloads. Spot VMs evict with 30-second notice. Eviction policy Delete is recommended for AKS.

Handling Eviction Gracefully

Configure workloads to handle the 30-second eviction notice:

# Add to Deployment spec — terminationGracePeriodSeconds should be < 30s for Spot
spec:
  template:
    spec:
      terminationGracePeriodSeconds: 25
      containers:
      - name: <CONTAINER_NAME>
        lifecycle:
          preStop:
            exec:
              command: ["/bin/sh", "-c", "sleep 5"]  # Drain in-flight requests

Set a PodDisruptionBudget to limit simultaneous evictions:

kubectl apply -f - <<EOF
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: <APP_NAME>-pdb
  namespace: <NAMESPACE>
spec:
  minAvailable: 1
  selector:
    matchLabels:
      app: <APP_NAME>
EOF

AKS Vertical Pod Autoscaler (VPA)

Use VPA to get data-driven resource recommendations for rightsizing pods. Always start in recommendation-only mode before considering auto-apply.

Enable VPA (Recommendation Mode)

# Enable VPA addon on AKS cluster (if not already enabled)
az aks update --enable-vpa --resource-group <RESOURCE_GROUP> --name <CLUSTER_NAME>

# Create a VPA object in recommendation mode for a deployment
kubectl apply -f - <<EOF
apiVersion: autoscaling.k8s.io/v1
kind: VerticalPodAutoscaler
metadata:
  name: <DEPLOYMENT_NAME>-vpa
  namespace: <NAMESPACE>
spec:
  targetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: <DEPLOYMENT_NAME>
  updatePolicy:
    updateMode: "Off"   # Recommendation only — does not modify pods
EOF

# Read recommendations after 24+ hours of data collection
kubectl describe vpa <DEPLOYMENT_NAME>-vpa -n <NAMESPACE>

Risk: Low in "Off" mode. Do not use `updateMode: Auto` in production without thorough testing and explicit user confirmation.

Read VPA Recommendations

kubectl get vpa <DEPLOYMENT_NAME>-vpa -n <NAMESPACE> -o jsonpath='{.status.recommendation}'

The output shows lowerBound, target, and upperBound for CPU and memory. Use the target values as rightsized requests.

Apply Recommendations Manually

After reviewing VPA output, patch the deployment — see azure-aks-rightsizing.md for the patch format.

CLI Reference for AKS

# List AKS clusters
az aks list --output table

# Show cluster details
az aks show --name <cluster-name> --resource-group <resource-group>

# Get available Kubernetes versions
az aks get-versions --location <location> --output table

# Create AKS Automatic cluster
az aks create --name <cluster-name> --resource-group <resource-group> --sku automatic \
  --network-plugin azure --network-plugin-mode overlay \
  --enable-oidc-issuer --enable-workload-identity

# Create AKS Standard cluster
az aks create --name <cluster-name> --resource-group <resource-group> \
  --node-count 3 --zones 1 2 3 \
  --network-plugin azure --network-plugin-mode overlay \
  --enable-cluster-autoscaler --min-count 1 --max-count 10 \
  --enable-oidc-issuer --enable-workload-identity

# Get credentials
az aks get-credentials --name <cluster-name> --resource-group <resource-group>

# List node pools
az aks nodepool list --cluster-name <cluster-name> --resource-group <resource-group> --output table

# Enable monitoring
az aks enable-addons --name <cluster-name> --resource-group <resource-group> \
  --addons monitoring --workspace-resource-id <workspace-resource-id>