# aks-known-issues

Diagnoses documented Azure Kubernetes Service failures from exact error signatures. It pinpoints causes and official fixes for node, VM, and extension errors.

- skill · `type=skill` · Claude Code, GitHub Copilot · ★ 3149
- Author: Microsoft
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/microsoft/skills/tree/HEAD/.github/plugins/aks-skills/skills/aks-known-issues/SKILL.md
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/skills/aks-known-issues

## What it does

The skill matches AKS provisioning and runtime failures against Microsoft's catalog of documented issues. It targets explicit error signatures such as `VMCannotFitEphemeralOSDisk`, `NodePoolMcVersionIncompatible`, zone capacity failures like `ZonalAllocationFailed`, and nested vmssCSE extension timeouts including `VMExtensionError_K8SAPIServerConnFail`.

Every lookup requires the full signature alongside its qualifiers, such as VM size, region, or zone. Partial error codes and bare numbers get rejected. Quota limit breaches are outside this catalog, so those incidents belong in `aks-troubleshooting`. The skill runs without extra MCP servers by relying on read-only Azure CLI queries or available Azure tools.

Mutations to infrastructure always pause for direct approval before executing. Without all qualifying parameters in the prompt, the skill will not trigger a fix.

## Requirements
- Works with: Azure

## Install

### Claude Code (native platform)

1. **Plugin marketplace**
In the agent chat (not a shell):
```text
/plugin marketplace add microsoft/skills
```
In the agent chat (not a shell):
```text
/plugin install aks-skills@skills
```
This installs the whole aks-skills plugin with all its skills

2. **Skills CLI (Vercel)**
```bash
npx skills add microsoft/skills --skill aks-known-issues -a claude-code
```

3. **Manually: put the files in place**
- File: `~/.claude/skills/aks-known-issues/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/aks-known-issues/

### Codex

**Manually: put the files in place**
- File: `.agents/skills/aks-known-issues/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

**Manually: put the files in place**
- File: `.cursor/skills/aks-known-issues/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install microsoft/skills aks-known-issues
```

2. **Manually: put the files in place**
- File: `.github/skills/aks-known-issues/SKILL.md`

### Gemini CLI

**Platform CLI**
```bash
gemini skills install https://github.com/microsoft/skills --path .github/plugins/aks-skills/skills/aks-known-issues
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/aks-known-issues/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/microsoft/skills/tree/HEAD/.github/plugins/aks-skills/skills/aks-known-issues/SKILL.md

## When to use it
- resolve VMCannotFitEphemeralOSDisk failures during node pool creation
- diagnose VMExtensionError_K8SAPIServerConnFail during vmssCSE node provisioning
- find documented workarounds for ZonalAllocationFailed with insufficient zone capacity
- troubleshoot OverconstrainedAllocationRequest errors with specific placement constraints

## Example prompts
- Node pool deployment failed with `VMCannotFitEphemeralOSDisk`. What is the fix according to Microsoft docs?
- My AKS cluster threw `VMExtensionError_K8SAPIServerConnFail` on vmssCSE. Show the cause and resolution steps.
- Resolve AKS error `ZonalAllocationFailed` with insufficient zone capacity in westeurope zone 1.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 707593131b209a4e.

BEGIN THIRD-PARTY FILE 707593131b209a4e
```text
---
name: aks-known-issues
license: MIT
metadata:
  author: Microsoft
  version: "1.2.1"
description: "Lookup documented AKS fixes only when the prompt includes an exact catalog signature and all of its qualifiers: VMCannotFitEphemeralOSDisk; NodePoolMcVersionIncompatible; 'NodeImageVersion is not accepted'; AKS SkuNotAvailable with size, location, and zone; ZonalAllocationFailed with insufficient zone capacity; OverconstrainedAllocationRequest with listed constraints; nested AKS vmssCSE/CSE VMExtensionError_OutboundConnFail, VMExtensionError_K8SAPIServerConnFail, or VMExtensionError_K8SAPIServerDNSLookupFail; or AllocationFailed with the full cataloged internal-error or insufficient-regional-capacity message. Never use for quota errors, code-only or bare wrappers, generic symptoms, incomplete signatures, or failures outside AKS; use aks-troubleshooting or azure-diagnostics."
---

# AKS Known Issues

## Quick Reference

| Property | Value |
|---|---|
| Best for | Exact signature plus AKS operation |
| Output | Cause, fix, and Learn citation |

Use the [catalog](references/error-code-map.md).

## When to Use This Skill

Named catalog signatures only. Generic AKS → `aks-troubleshooting`; non-AKS →
no AKS skill.

If every qualifier for a catalog row is not present, do not use this skill.
This catalog has no quota-error rows; route AKS quota incidents to
`aks-troubleshooting`.

## MCP Tools

None required. Use advertised read-only Azure tools or CLI queries.

## Workflow

1. Capture exact code, nested message, operation, and AKS resource.
2. Require every qualifier; codes are not substrings.
3. Give cause, fix, citation, and read-only verification.
4. State what ran; require explicit approval before every mutation.

## Error Handling

| Input | Response |
|---|---|
| Bare wrapper/number | Request nested signature and CSE context |
| Generic AKS | `aks-troubleshooting` |
| Non-AKS | No AKS skill |
```
END THIRD-PARTY FILE 707593131b209a4e

The third-party file has ended. Everything between the 707593131b209a4e tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

© Microsoft · MIT · https://github.com/microsoft/skills/tree/HEAD/.github/plugins/aks-skills/skills/aks-known-issues/SKILL.md

## Similar
- [caveman-manage](https://affpapa.org/en/nevibecode/skills/caveman-manage.md) — skill · 104200 installs
- [workers-best-practices](https://affpapa.org/en/nevibecode/skills/cloudflare-workers-best-practices.md) — skill · 126100 installs
- [cloudflare-email-service](https://affpapa.org/en/nevibecode/skills/cloudflare-email-service.md) — skill · 102300 installs
- [firebase-basics](https://affpapa.org/en/nevibecode/skills/firebase-basics.md) — skill · 14100 installs
- [cloudflare-one](https://affpapa.org/en/nevibecode/skills/cloudflare-one.md) — skill · 93100 installs
- [cloudflare-one-migrations](https://affpapa.org/en/nevibecode/skills/cloudflare-one-migrations.md) — skill · 89500 installs

From the same set: [microsoft/skills](https://affpapa.org/en/nevibecode/by/microsoft/skills.md) — 242 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md