aks-deployment-troubleshooter_skill

Overview

This skill diagnoses and fixes Kubernetes deployment failures on AKS with a focus on container image and platform issues. It captures a battle-tested debugging flow that resolved 10+ failure modes during a 4-hour AKS session. The guidance includes concrete kubectl commands, buildx configuration, Helm tips, and registry authentication fixes.

How this skill works

The skill inspects pod status, events, pod descriptions, and container logs to classify failures as ImagePullBackOff, CrashLoopBackOff, Pending, or Helm/CI errors. It maps each class to targeted actions: verify image tags and registry auth, check node architecture, adjust buildx platforms/provenance, and correct Helm value handling. It also provides pre-deployment and CI build recommendations to prevent regressions.

When to use it

• Pods stuck in ImagePullBackOff
• Pods in CrashLoopBackOff with exec format error
• Errors: "no match for platform in manifest" or architecture mismatches
• Image registry authentication failures (401/403)
• Helm deploys failing due to --set parsing or timeouts

Best practices

• Check node architecture before building: kubectl get nodes -o jsonpath='{.items[*].status.nodeInfo.architecture}'
• Use docker/build-push-action platforms matching cluster (e.g., linux/arm64) and disable provenance for simpler manifests
• Use full SHA tags in CI to avoid short-vs-full-SHA mismatches and ensure builds finish before deploys
• Create and reference imagePullSecrets for private registries; verify workflow permissions (packages: write)
• When Helm needs complex values, pass a values file instead of --set to avoid comma parsing errors

Example use cases

• Resolve ImagePullBackOff due to wrong tag or registry path by verifying pushed tags and Helm values
• Fix CrashLoopBackOff with exec format error by rebuilding image for cluster architecture and clearing cache
• Recover from GHCR 403 by updating package visibility or workflow package permissions
• Handle "no match for platform" by matching buildx platforms to node architecture and disabling provenance
• Prevent Helm --set parsing problems by generating a temporary overrides.yaml and using --values