az-aks-agent

Azure AKS エージェント CLI スキル

概要

Azure Kubernetes Service（AKS）向けエージェント CLI は、AI を活用したトラブルシューティングと分析のツール（現在プレビュー中）で、高度な診断をターミナルから直接実行できます。Kubernetes の深い専門知識や複雑なコマンド構文の知識がなくても、クラスターの状態、構成、問題について自然言語で質問できます。

主なコマンド：az aks agent

クイックリファレンス

インストール

# 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

基本的な使い方

# 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"

ワークフローの判断ツリー

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"

コマンドリファレンス

基本コマンド

コマンド	説明
az aks agent	AI を活用した対話型トラブルシューティングを開始します
az aks agent-init	LLM プロバイダーの構成を初期化します
az aks agent --help	ヘルプと使用可能なオプションを表示します

コマンドパラメーター

パラメーター	説明	デフォルト
-g, --resource-group	リソースグループ名	必須
-n, --name	AKS クラスター名	必須
--api-key	LLM API キー	環境変数または構成から取得
--config-file	構成ファイルのパス	~/.azure/aksAgent.config
--max-steps	調査の最大ステップ数	10
--model	LLM モデルの指定	構成から取得
--no-interactive	バッチモードで実行します	false
--show-tool-output	ツール呼び出しの出力を表示します	false
--refresh-toolsets	ツールセットの状態を更新します	false

LLM モデルの指定

# 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"

構成

環境変数

# 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"

構成ファイルの構造（~/.azure/aksAgent.config）

# 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 の要件

• デプロイ名：モデル名と一致する必要があります
• 最小 TPM：1,000,000 以上（1 分あたりのトークン数）
• 最小コンテキストサイズ：128,000 トークン以上
• API ベースの形式：https://{endpoint}.openai.azure.com/（AI Foundry URI ではありません）

一般的なユースケース

クラスターの状態分析

# 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 のトラブルシューティング

# 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"

ネットワークの問題

# 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?"

ストレージのトラブルシューティング

# 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"

セキュリティ分析

# 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 イベントリファレンス

クラスターイベントの表示

# 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

イベントの種類

種類	説明
Normal	通常の操作と想定されるアクティビティ
Warning	注意が必要な、問題の可能性がある状況

一般的なイベントの理由

理由	説明
FailedScheduling	Pod をノードにスケジュールできませんでした
CrashLoopBackOff	コンテナーが再起動を繰り返しています
Scheduled	Pod がノードに正常に割り当てられました
Pulled	コンテナーイメージが正常にプルされました
Created	コンテナーが作成されました
Started	コンテナーが起動しました
OOMKilled	メモリ不足によりコンテナーが強制終了されました

イベントフィールド

フィールド	説明
type	Warning または Normal
reason	短い理由コード
message	人が読める説明
namespace	Kubernetes の名前空間
firstSeen	最初に確認された時刻
lastSeen	最も最近に確認された時刻
object	関連する Kubernetes オブジェクト

ベストプラクティス

効果的なクエリ戦略

1. 広く始めてから絞り込む

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

2. 症状に関するコンテキストを提供する

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

3. 具体的な推奨事項を求める

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

4. 過去の分析を依頼する

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

セキュリティに関する考慮事項

• 適切な RBAC 権限が構成されていることを確認します
• 認証には Azure AD 統合を使用します
• 最小権限の原則に従います
• Azure のアクティビティログでコマンドの使用状況を監査します
• 自動化にはサービスアカウントのトークンを使用します

統合のヒント

1. 従来の監視と組み合わせる：Azure Monitor および Container Insights と併用します
2. プロアクティブな監視：正常性チェックを定期的に実行します
3. 調査結果を記録する：重要な診断出力を保存します
4. Container Insights を有効にする：1 時間を超えて保持されるイベントを確認できます

エージェントのトラブルシューティング

インストールの問題

# Verify Azure CLI version
az version

# Upgrade Azure CLI if needed
az upgrade

# Force reinstall extension
az extension remove --name aks-agent
az extension add --name aks-agent --debug

認証の問題

# Verify Azure login
az account show

# Re-authenticate
az login

# Check subscription
az account set --subscription <subscription-id>

LLM 接続の問題

# Reinitialize LLM configuration
az aks agent-init

# Check API key environment variable
echo $AZURE_API_KEY

# Test with explicit API key
az aks agent -g myRG -n myCluster --api-key "your-key"

レート制限

• 症状：応答が遅い、またはエラーが発生する
• 解決策：Azure OpenAI のデプロイで TPM クォータを増やします
• 推奨される最小値：1,000,000 TPM

重要な注意事項

1. プレビュー機能：現在プレビュー中であり、保証範囲は限定されています
2. 本番環境の重要な用途には不向き：本番環境で重要な意思決定に使用することは推奨されません
3. イベントの保持期間：Kubernetes イベントは、デフォルトでは 1 時間のみ保持されます
4. コンテキストウィンドウ：最適なパフォーマンスを得るには、128,000 以上のトークンコンテキストが必要です
5. 認証：使用前に必ず az login で認証してください

リソース

参考資料

主な参考資料

• references/cli-commands.md - CLI コマンドの完全なリファレンス
• references/troubleshooting.md - 詳細なトラブルシューティングガイド
• references/examples.md - 実践的な使用例

診断と監視

• references/diagnostics.md - AKS の診断と問題解決ガイド
• references/monitoring.md - AKS の包括的な監視ガイド
• references/control-plane-metrics.md - コントロールプレーンのメトリック（API Server、etcd）

トラブルシューティングガイド

• references/kubelet-logs.md - Kubelet ログへのアクセスと分析
• references/memory-saturation.md - メモリ飽和状態の特定と解決
• references/node-auto-repair.md - ノード自動修復のプロセスと監視
• references/api-server-etcd.md - API サーバーと etcd のトラブルシューティング

外部ドキュメント

• AKS エージェントの概要
• AKS エージェントのインストール
• AKS イベント
• AKS の診断
• AKS の監視
• コントロールプレーンのメトリック
• Kubelet ログ
• メモリ飽和状態
• ノード自動修復
• API サーバー／etcd のトラブルシューティング
• AKS 監視リファレンス
• AKS エージェントのトラブルシューティング
• AKS エージェント FAQ
• GitHub リポジトリ
• 設定例

---

注意点

• エージェントは Azure-CLI のセッショントークンを使用します — セッションの有効期限が切れると、API 呼び出しは通知なく失敗し、「エージェントが応答しない」と表示されます。
• エージェントが参照するのは Kubernetes API イベントのみです。カスタムコントローラーのイベントは参照しないため、カスタムリソースの問題は認識されません。
• 主なイベントでは、理由とメッセージごとに集計されます — メッセージがわずかに異なる場合も別々に集計されるため、頻度のカウントは誤解を招くことがあります。
• クラスター MSI と Workload Identity：エージェントはクラスター MSI を使用します。Workload Identity を使うポッドの認証問題をトラブルシューティングするには、そのポッドのコンテキストから再認証する必要があります。
• プレビュー機能：AKS 管理の Prometheus と AKS エージェントの統合は、一部のリージョンでは GA で、ほかのリージョンではプレビューです。同じ CLI バージョンでも、リージョンによって動作が異なります。