AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

aks-troubleshooting

Debug live Azure Kubernetes Service (AKS) incidents with a read-only, evidence-first investigation. WHEN: pod crashes or Pending, CrashLoopBackOff, OOMKilled, ImagePullBackOff, node NotReady, DNS or ingress failure, connectivity timeout, network policy, SNAT exhaustion, node-pool scaling blocked by QuotaExceeded or InsufficientVCPUQuota, upgrade stuck, spot or zone disruption, a bare VMExtensionProvisioningError or AllocationFailed wrapper, an uncataloged capacity symptom, or 'investigate my AKS cluster'. DO NOT USE FOR: packet capture (use aks-network-capture); GPU or model-serving issues (use aks-gpu-inference); cluster creation or provisioning (use azure-kubernetes); cost (use cost-analysis from the optional azure-cost plugin); pod rightsizing (use azure-kubernetes); a fully qualified documented AKS signature with every required nested qualifier (use aks-known-issues); standalone failures on non-AKS Azure resources (use azure-diagnostics). Unqualified errors and open-ended incidents stay here only for AKS.

Original source
microsoft
License
MIT
Pinned revision
3f5b461b2314e01c400564051e92469114c5b68f

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read microsoft--aks-troubleshooting at revision 3f5b461b2314e01c400564051e92469114c5b68f, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 18

references/structured-input-modes.md

AKS Structured Input Modes

Use this reference when the troubleshooting request already contains structured inputs.

Detector-backed Mode

Use when AKS-aware detectors or AppLens-style insights are available.

Decision rules:

  • Ignore findings where the detector is emergingIssues.
  • Prefer critical findings over warnings.
  • Prefer findings with more concrete remediation detail when choosing the likely root problem.
  • Preserve per-insight output: problem summary, root-problem flag, affected resources, suggested commands.

Warning Events Mode

Use when the request includes Kubernetes warning events.

Expected output:

  • summary of the events and their impact
  • likely cause or causes
  • next kubectl checks
  • monitoring follow-up

Metrics Scan Mode

Use when the request includes CPU or memory time-series data.

Expected output:

  • healthy or unhealthy status
  • anomaly timestamps and explanations
  • suggestion tied to the observed metric pressure

Generic Symptoms Mode

Use when the request includes resource symptoms but not detector results, warning events, or time-series metrics.

Expected output:

  • symptom summary by resource
  • likely failure domain
  • next evidence-collection steps

Control-Plane Resource Logs (Historical Evidence)

Use when the question is about past API-server, scheduler, controller-manager, or cluster-autoscaler behavior. AKS control-plane logs are Azure Monitor resource logs: they exist only if a diagnostic setting routed the category to a destination before the incident window. Missing setting or history means the evidence is unavailable, never "no events occurred."

Category → table mapping (resource-specific mode; legacy Azure diagnostics mode lands everything in AzureDiagnostics with a Category column):

| Diagnostic category | Resource-specific table | Content | |---|---|---| | kube-audit | AKSAudit | All API-server audit events, including get/list | | kube-audit-admin | AKSAuditAdmin | Audit events excluding get/list (modifying requests) | | kube-apiserver, kube-scheduler, kube-controller-manager, cluster-autoscaler, cloud-controller-manager, guard, csi-*-controller | AKSControlPlane (filter on Category) | Component logs |

az monitor diagnostic-settings list --resource <cluster-resource-id> -o table
az monitor diagnostic-settings show --resource <cluster-resource-id> -n <setting> --query '{logs:logs,workspace:workspaceId,resourceSpecific:logAnalyticsDestinationType}'

Decision rules:

  • Query AKSControlPlane | where Category == "kube-scheduler" (or the matching AzureDiagnostics filter) only after the setting shows that category enabled for the incident window and the workspace is readable to the user.
  • If the category is disabled, the setting is absent, or the workspace retention does not cover the window, report the evidence as unavailable and name the exact category and table that would have answered it.
  • Enabling or changing a diagnostic setting is a mutation with ingestion and retention cost (kube-audit in particular); propose it for owner approval, never apply it as part of diagnosis.

Sources: Monitor AKS — resource logs, AKS monitoring data reference, AKSAudit, AKSControlPlane.

Learn Grounding Fallback

If the first troubleshooting pass is incomplete, search Microsoft Learn using:

  • the user prompt
  • the parsed problem names
  • the AKS troubleshooting context

Use Learn grounding to refine or validate the root-cause hypothesis, not to replace observed evidence.