az-aks-agent

What this skill does

# Azure AKS Agent CLI Skill

## Overview

The **Agentic CLI for Azure Kubernetes Service (AKS)** is an AI-powered troubleshooting and insights tool (currently in preview) that brings advanced diagnostics directly to your terminal. It allows you to ask natural language questions about your cluster's health, configuration, and issues without requiring deep Kubernetes expertise or knowledge of complex command syntax.

**Primary Command**: `az aks agent`

## Quick Reference

### Installation

```bash
# Prerequisites: Azure CLI version 2.76 or higher
az version

# Install the extension (takes 5-10 minutes)
az extension add --name aks-agent --debug

# Verify installation
az extension list
az aks agent --help

# Initialize LLM configuration (interactive wizard)
az aks agent-init

# Remove extension if needed
az extension remove --name aks-agent --debug
```

### Basic Usage

```bash
# Get cluster credentials first
az aks get-credentials --resource-group <rg-name> --name <cluster-name>

# Start interactive troubleshooting
az aks agent -g <resource-group> -n <cluster-name>

# Ask a specific question
az aks agent -g <resource-group> -n <cluster-name> --query "What's wrong with my cluster?"

# Non-interactive mode (batch processing)
az aks agent -g <resource-group> -n <cluster-name> --no-interactive --query "Check pod health"
```

## Workflow Decision Tree

```
What do you need to do?
├── Cluster Health Check?
│   └── Use: az aks agent --query "What's the health status of my cluster?"
├── Troubleshoot Pod Issues?
│   └── Use: az aks agent --query "Why are my pods failing?"
├── Networking Problems?
│   └── Use: az aks agent --query "Diagnose networking issues"
├── Storage Issues?
│   └── Use: az aks agent --query "Check storage configuration"
├── Security/RBAC Issues?
│   └── Use: az aks agent --query "Review RBAC configuration"
├── Node Pool Problems?
│   └── Use: az aks agent --query "Check node pool health"
└── Configuration Review?
    └── Use: az aks agent --query "Review cluster configuration"
```

## Command Reference

### Core Commands

| Command | Description |
|---------|-------------|
| `az aks agent` | Start interactive AI-powered troubleshooting |
| `az aks agent-init` | Initialize LLM provider configuration |
| `az aks agent --help` | Show help and available options |

### Command Parameters

| Parameter | Description | Default |
|-----------|-------------|---------|
| `-g, --resource-group` | Resource group name | Required |
| `-n, --name` | AKS cluster name | Required |
| `--api-key` | LLM API key | From env or config |
| `--config-file` | Config file path | `~/.azure/aksAgent.config` |
| `--max-steps` | Max investigation steps | 10 |
| `--model` | LLM model specification | From config |
| `--no-interactive` | Run in batch mode | false |
| `--show-tool-output` | Display tool call outputs | false |
| `--refresh-toolsets` | Refresh toolsets status | false |

### LLM Model Specifications

```bash
# Azure OpenAI
--model "azure/gpt-4o"
--model "azure/gpt-4o-mini"

# OpenAI
--model "gpt-4o"
--model "gpt-4o-mini"

# Anthropic
--model "anthropic/claude-sonnet-4"
--model "anthropic/claude-3-5-sonnet"

# Gemini
--model "gemini/gemini-pro"
```

## Configuration

### Environment Variables

```bash
# Azure OpenAI API Key
export AZURE_API_KEY="your-azure-openai-key"

# OpenAI API Key
export OPENAI_API_KEY="your-openai-key"

# Anthropic API Key
export ANTHROPIC_API_KEY="your-anthropic-key"
```

### Config File Structure (~/.azure/aksAgent.config)

```yaml
# Azure OpenAI Configuration
llm_provider: azure
azure_api_base: https://<your-endpoint>.openai.azure.com/
azure_api_version: 2025-04-01-preview
model: gpt-4o

# OR OpenAI Configuration
llm_provider: openai
model: gpt-4o

# OR Anthropic Configuration
llm_provider: anthropic
model: claude-sonnet-4
```

### Azure OpenAI Requirements

- **Deployment name**: Must match model name
- **Minimum TPM**: 1,000,000+ (Tokens Per Minute)
- **Minimum context size**: 128,000+ tokens
- **API Base Format**: `https://{endpoint}.openai.azure.com/` (NOT AI Foundry URI)

## Common Use Cases

### Cluster Health Analysis

```bash
# General health check
az aks agent -g myRG -n myCluster --query "What's the overall health of my cluster?"

# Node status
az aks agent -g myRG -n myCluster --query "Are all nodes healthy and ready?"

# Resource utilization
az aks agent -g myRG -n myCluster --query "Show me resource utilization across nodes"
```

### Pod Troubleshooting

```bash
# Failed pods analysis
az aks agent -g myRG -n myCluster --query "Why are pods in CrashLoopBackOff?"

# Pending pods
az aks agent -g myRG -n myCluster --query "Why are some pods stuck in Pending state?"

# OOMKilled pods
az aks agent -g myRG -n myCluster --query "Investigate OOMKilled containers"
```

### Networking Issues

```bash
# Network policy review
az aks agent -g myRG -n myCluster --query "Are there network policies blocking traffic?"

# DNS troubleshooting
az aks agent -g myRG -n myCluster --query "Diagnose DNS resolution issues"

# Service connectivity
az aks agent -g myRG -n myCluster --query "Why can't pods reach external services?"
```

### Storage Troubleshooting

```bash
# PVC issues
az aks agent -g myRG -n myCluster --query "Why are PersistentVolumeClaims pending?"

# Storage class review
az aks agent -g myRG -n myCluster --query "Review storage class configuration"
```

### Security Analysis

```bash
# RBAC review
az aks agent -g myRG -n myCluster --query "Are RBAC permissions configured correctly?"

# Security best practices
az aks agent -g myRG -n myCluster --query "What security improvements do you recommend?"
```

## AKS Events Reference

### Viewing Cluster Events

```bash
# Get cluster credentials first
az aks get-credentials --resource-group $RESOURCE_GROUP --name $AKS_CLUSTER

# List all events
kubectl get events

# Filter by namespace
kubectl get events --namespace default

# Watch auto-repair events
kubectl get events --field-selector=source=aks-auto-repair --watch

# Detailed pod events
kubectl describe pod $POD_NAME
```

### Event Types

| Type | Description |
|------|-------------|
| `Normal` | Routine operations and expected activities |
| `Warning` | Potentially problematic situations requiring attention |

### Common Event Reasons

| Reason | Description |
|--------|-------------|
| `FailedScheduling` | Pod failed to be scheduled on a node |
| `CrashLoopBackOff` | Container is in a restart loop |
| `Scheduled` | Pod successfully assigned to a node |
| `Pulled` | Container image successfully pulled |
| `Created` | Container created |
| `Started` | Container started |
| `OOMKilled` | Container killed due to out of memory |

### Event Fields

| Field | Description |
|-------|-------------|
| `type` | Warning or Normal |
| `reason` | Short reason code |
| `message` | Human-readable description |
| `namespace` | Kubernetes namespace |
| `firstSeen` | First observation timestamp |
| `lastSeen` | Most recent observation |
| `object` | Associated Kubernetes object |

## Best Practices

### Effective Query Strategies

1. **Start broad, then narrow**

   ```bash
   # Start with general health
   "What's wrong with my cluster?"
   # Then focus on specific issues
   "Why are pods in namespace X failing?"
   ```

2. **Provide context about symptoms**

   ```bash
   "Pods are restarting frequently in the production namespace"
   "Services are experiencing intermittent timeouts"
   ```

3. **Ask for specific recommendations**

   ```bash
   "What changes do you recommend to improve cluster performance?"
   "How can I fix the networking issues you identified?"
   ```

4. **Request historical analysis**

   ```bash
   "What patterns do you see in recent pod failures?"
   "Have there been any unusual events in the last 24 hours?"
   ```

### Security Considerations

- Ensure proper RBAC permissions are configured
- Use Azure AD integration for authentication
- Follow principle of least privilege
- Audit command usage through Azure activity logs
- Se