aks-troubleshooting

Diagnose and resolve AKS pod, node, and control plane issues using Azure CLI and kubectl.

Updated Feb 25, 2026
One-click install
npx skills add https://github.com/pauldotyu/aks-skills --skill aks-troubleshooting
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: aks-troubleshooting
Source: https://github.com/pauldotyu/aks-skills/tree/main/aks-troubleshooting
Command: npx skills add https://github.com/pauldotyu/aks-skills --skill aks-troubleshooting

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill helps diagnose and resolve common issues within Azure Kubernetes Service (AKS) clusters, including problems with pods, nodes, and the control plane.

Core Features & Use Cases

  • Pod Troubleshooting: Addresses issues like pods stuck in Pending, CrashLoopBackOff, OOMKilled, or ImagePullBackOff states.
  • Node Troubleshooting: Helps resolve nodes in a NotReady state or experiencing disk pressure.
  • Resource & Quota Issues: Provides commands to check resource quotas and usage.
  • Control Plane Diagnostics: Offers steps to check API server reachability and system component health.
  • Use Case: When your application pods are repeatedly crashing with CrashLoopBackOff, this skill provides the exact kubectl commands to view logs and identify the root cause.

Quick Start

Use the aks-troubleshooting skill to check the status of all nodes in your AKS cluster.

Frequently Asked Questions about aks-troubleshooting

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I troubleshoot pods stuck in CrashLoopBackOff or OOMKilled states in AKS?

To troubleshoot AKS pods in CrashLoopBackOff or OOMKilled states, you need to inspect container logs and resource limits. This diagnostic process utilizes specific kubectl commands to retrieve logs and identify the root cause of the application crashes or memory exhaustion.

What is the best way to diagnose an AKS node that is in a NotReady state?

Diagnosing an AKS node in a NotReady state involves checking node conditions and resource pressures like disk space. You can use kubectl commands to inspect node details and Azure CLI to query the underlying virtual machine status for deeper infrastructure analysis.

How do I resolve ImagePullBackOff errors for Kubernetes pods on Azure?

Resolving ImagePullBackOff errors for AKS pods requires verifying container image names, registry credentials, and network access. The diagnostic workflow uses kubectl to describe the pod and pinpoint exact registry authentication failures or missing image references.

Can I use Azure CLI to check AKS control plane API server reachability?

Yes, you can use Azure CLI alongside kubectl to check AKS control plane API server reachability and system component health. This diagnostic approach helps verify network configurations, API routing, and core Kubernetes service availability.

Why do persistent volume claims fail to bind in AKS and how can I diagnose them?

Persistent volume claims in AKS fail to bind due to missing storage classes, capacity limits, or node affinity mismatches. You can diagnose these binding failures by running kubectl commands to inspect PVC events and Azure CLI to check underlying disk provisioning.

Do I need Azure CLI installed to troubleshoot resource quota exceedances in AKS?

Yes, Azure CLI is required alongside kubectl to effectively troubleshoot AKS resource quota exceedances. The diagnostic process uses kubectl to check namespace resource usage and limits, while Azure CLI provides deeper visibility into cluster-level capacity and configuration.