Azure Kubernetes Service (AKS) için aracıLı CLI'yi yükleme ve kullanma (önizleme)

Bu makalede, AKS kümeleriniz için yapay zeka destekli sorun giderme ve içgörüler elde etmek üzere istemci modunda veya küme modunda Azure Kubernetes Service (AKS) için aracı CLI'yi yükleme, yapılandırma ve kullanma işlemleri gösterilmektedir.

Daha fazla bilgi için AKS için Agentic CLI Genel Bakış'a bakın.

Önemli

AKS önizleme özellikleri self servis ve kabul temelinde kullanılabilir. Önizlemeler "olduğu gibi" ve "mevcut olduğu şekilde" sağlanmakta olup, hizmet seviyesi anlaşmalarına ve sınırlı garantilere dahil edilmemektedir. AKS önizlemeleri, müşteri desteği ekibi tarafından maksimum çaba gösterilerek kısmen ele alınmaktadır. Bu nedenle, bu özellikler üretim kullanımı için tasarlanmamıştır. Daha fazla bilgi için aşağıdaki destek makalelerine bakın:

Önkoşullar

  • Azure CLI sürüm 2.76 veya üzeri. komutunu kullanarak az version sürümünüzü denetleyin. Yüklemek veya güncelleştirmek için bkz. Azure CLI'yı yükleme.

  • Büyük bir dil modeli (LLM) API anahtarına sahip olun. Desteklenen sağlayıcılardan birinden kendi API anahtarınızı getirmelisiniz:

    • Azure OpenAI (önerilir)
    • OpenAI veya OpenAPI belirtimleriyle uyumlu diğer LLM sağlayıcıları

  • komutunu kullanarak az account set etkin Azure aboneliğinizi ayarlayın.

    az account set --subscription "your-subscription-id-or-name"

  • AKS işlevselliği için etken CLI sağlayan Azure CLI uzantısının aks-agent 1.0.0b16 veya daha yeni sürümü. Azure CLI'yi kullanarak uzantıyı yükleyebilir veya güncelleştirebilirsiniz.

  • Docker yerel makinenizde yüklü ve çalışıyor. Yükleme yönergeleri için bkz. Docker'ı Kullanmaya Başlama.
  • Yüklemeye devam etmeden önce Docker daemon'un başlatıldığından ve çalıştığından emin olun.
  • Azure kimlik bilgilerinizin düzgün yapılandırıldığından ve küme kaynaklarına erişmek için gerekli izinlere sahip olduğunuzdan emin olun.

AKS uzantısı için 'agentic' CLI'yi yükleyin

  1. az extension add komutunu kullanarak AKS uzantısı için ajan CLI'yi yükleyin. Uzantı zaten yüklüyse komutunu kullanarak en son sürüme az extension update güncelleştirebilirsiniz. Bu adımın tamamlanması 5-10 dakika sürebilir.

    # Install the extension
az extension add --name aks-agent --debug

# Update the extension
az extension update --name aks-agent --debug

  2. komutunu kullanarak yüklemenin başarılı olduğunu az extension list doğrulayın.

    az extension list

    Çıktınız içinde aks-agent bir giriş içermelidir.

  3. [c0][][/cli/azure/aks#az-aks-agent] komutunu parametresi ile kullanarak AKS komutlarının ajan CLI’si için kullanılabilir olduğunu doğrulayın.

    az aks agent --help

    Çıkışınız, aks-agent bölümünde sürüm bilgileriyle extensions'i göstermelidir. Örneğin:

    ...
"extensions": {
"aks-agent": "1.0.0b17",
}

LLM API anahtarınızı ayarlama

Yüklemeye devam etmeden önce LLM API anahtarınızı ayarlamanız gerekir. Daha iyi performans için GPT-5 veya Claude Opus MINI gibi daha yeni modelleri kullanmanızı öneririz. Bağlam boyutu en az 128.000 veya daha yüksek olan bir model seçtiğinizden emin olun.

  1. Azure OpenAI kaynağı oluşturun.
  2. Modeli dağıtın. Dağıtım adı için, erişime bağlı olarak gpt-4o veya gpt-4o-mini gibi model adıyla aynı adı kullanın. Model için erişiminiz ve kotanız olan herhangi bir bölgeyi kullanabilirsiniz. Dağıtımda, mümkün olduğunca yüksek bir dakika başına belirteç (TPM) sınırı seçin. İyi bir performans için 1 milyon TPM'nin yukarısını öneririz.
  3. Dağıtım tamamlandıktan sonra API temel URL'nizi ve API anahtarınızı not edin. API sürümü model sürümü değildir. Microsoft Foundry Models v1 API'sinde Azure OpenAI'de kullanılabilen ve desteklenen herhangi bir API sürümünü kullanabilirsiniz. Azure API tabanı, Foundry'deki dağıtımın hedef URI'si yerine (genellikle openai.azure.com/ ile biten) Azure OpenAI uç noktasını ifade eder.

Microsoft Entra Id (anahtarsız kimlik doğrulaması) ile Azure OpenAI

LLM sağlayıcınız olarak "Azure Open AI (Microsoft Entra ID)" seçeneğini belirlediğinizde, Microsoft Entra Id kullanarak anahtarsız kimlik doğrulamayı yapılandırabilirsiniz. Bu seçenekle api anahtarı sağlamanız gerekmez. Bunun yerine, bu kimlik doğrulama yöntemi aşağıdaki rol atamalarını gerektirir:

  • İstemci modu: Yerel Azure CLI kimlik bilgilerine Azure OpenAI kaynağında Bilişsel Hizmetler Kullanıcısı veya Azure AI Kullanıcısı rolü atanmalıdır.
  • Küme modu: İş yükü kimliğine Azure OpenAI kaynağında Bilişsel Hizmetler Kullanıcısı veya Azure AI Kullanıcısı rolü atanmalıdır.

Diğer LLM sağlayıcıları

OpenAI uyumlu başka bir sağlayıcı kullanıyorsanız, hesap oluşturma ve API anahtarını alma yönergeleri için bu sağlayıcının belgelerini izleyin.

Docker yüklemesini doğrulama ve Docker daemon'ı başlatma

  1. Aşağıdaki komutları kullanarak Docker'ın yüklendiğini ve Docker daemon'un çalıştığını doğrulayın:

    docker --version
docker ps

  2. Docker daemon'unun çalışmadığını belirten bir hata alırsanız, işletim sisteminiz için uygun adımları kullanarak Docker hizmetini başlatın:

    • macOS / Windows:

      • Uygulamalarınızdan Docker Desktop'ı başlatın.
      • Docker'ın başlamasını bekleyin.

    • Linux:

      • Aşağıdaki komutları kullanarak Docker hizmetini başlatın:

        sudo systemctl start docker
sudo systemctl enable docker  # Enable Docker to start on boot

  3. Aşağıdaki komutu kullanarak Docker'ın çalıştığını doğrulayın:

    docker info

    Bu komut Docker sistem bilgilerini hatasız döndürmelidir.

İstemci modunu başlatma

  1. az aks agent-init komutunu kullanarak istemci modunda agentic CLI'yi başlatın. Yer tutucu değerlerini gerçek kaynak grubunuz ve küme adınızla değiştirdiğinizden emin olun.

    az aks agent-init --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME

  2. Bir dağıtım modu seçmeniz istendiğinde, istemci modu için 2 girin.

    🚀 Welcome to AKS Agent initialization!

Please select the mode you want to use:
  1. Cluster mode - Deploys agent as a pod in your AKS cluster
     Uses service account and workload identity for secure access to cluster and Azure resources
  2. Client mode - Runs agent locally using Docker
     Uses your local Azure credentials and cluster user credentials for access

Enter your choice (1 or 2): 2

  3. LLM sağlayıcı ayrıntılarınızı yapılandırın. Örneğin:

    Welcome to AKS Agent LLM configuration setup. Type '/exit' to exit.
 1. Azure Open AI (API Key)
 1. Azure Open AI (Microsoft Entra ID)
 3. OpenAI
 4. Anthropic
 5. Gemini
 6. Openai Compatible
Enter the number of your LLM provider: 1
Your selected provider: azure
Enter value for MODEL_NAME:  (Hint: should be consistent with your deployed name, e.g., gpt-4.1) gpt-4.1
Enter your API key: 
Enter value for AZURE_API_BASE:  (Hint: https://{your-custom-endpoint}.openai.azure.com/) https://test-example.openai.azure.com
Enter value for AZURE_API_VERSION:  (Default: 2025-04-01-preview)
LLM configuration setup successfully.

    Uyarı

    API anahtarı, güvenlik amacıyla siz yazarken boş görünür. Doğru API anahtarını girdiğinizden emin olun.

  4. Başlatmanın başarılı olduğunu doğrulayın. aracı, ilk komutunuzu çalıştırdığınızda gerekli Docker görüntülerini otomatik olarak çeker.

Küme modunu başlatma

  1. az aks agent-init komutunu kullanarak küme modunda agentic CLI'yi başlatın. Yer tutucu değerlerini gerçek kaynak grubunuz ve küme adınızla değiştirdiğinizden emin olun.

    az aks agent-init --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME

  2. Bir dağıtım modu seçmeniz istendiğinde küme modu için 1 girin.

    🚀 Welcome to AKS Agent initialization!

Please select the mode you want to use:
  1. Cluster mode - Deploys agent as a pod in your AKS cluster
     Uses service account and workload identity for secure access to cluster and Azure resources
  2. Client mode - Runs agent locally using Docker
     Uses your local Azure credentials and cluster user credentials for access

Enter your choice (1 or 2): 1

  3. Hedef ad alanını belirtmeniz istendiğinde, hizmet hesabını oluşturduğunuz ad alanını girin. Aşağıdaki örnek yer tutucu olarak kullanır your-namespace . Kullandığınız gerçek ad alanıyla değiştirdiğinizden emin olun.

    ✅ Cluster mode selected. This will set up the agent deployment in your cluster.

Please specify the namespace where the agent will be deployed.

Enter namespace (e.g., 'kube-system'): your-namespace

  4. LLM sağlayıcı ayrıntılarınızı yapılandırın. Örneğin:

    📦 Using namespace: your-namespace
No existing LLM configuration found. Setting up new configuration...
Please provide your LLM configuration. Type '/exit' to exit.
 1. Azure OpenAI
 2. OpenAI
 3. Anthropic
 4. Gemini
 5. OpenAI Compatible
 6. For other providers, see https://aka.ms/aks/agentic-cli/init
Please choose the LLM provider (1-5): 1

  5. Aracı dağıtımı için oluşturduğunuz Kubernetes hizmet hesabını kullanarak hizmet hesabı ayrıntılarını sağlayın. Aşağıdaki örnek, aks-mcp 'yi hizmet hesabı adı için bir yer tutucu olarak kullanır. Bunu hizmet hesabınızın gerçek adıyla değiştirdiğinden emin olun.

    👤 Service Account Configuration
The AKS agent requires a service account with appropriate permissions in the 'your-namespace'
namespace.
Please ensure you have created the necessary Role and RoleBinding in your namespace for 
this service account.

Enter service account name: aks-mcp

  6. Dağıtımın tamamlanmasını bekleyin. Başlatma, Helm ile aracının dağıtımını gerçekleştirir.

    🚀 Deploying AKS agent (this typically takes less than 2 minutes)...
✅ AKS agent deployed successfully!
Verifying deployment status...
✅ AKS agent is ready and running!

🎉 Initialization completed successfully!

  7. Dağıtımın başarılı olduğunu doğrulamak ve az aks agent komutunu --status parametresiyle kullanarak aracının durumunu kontrol etmek.

    az aks agent \
--status \
--resource-group $RESOURCE_GROUP \
--name $CLUSTER_NAME \
--namespace $NAMESPACE

    Çıkışınız, aşağıdakine benzer şekilde aracının hazır ve çalışır durumda olduğunu göstermelidir:

    📊 Checking AKS agent status...

✅ Helm Release: deployed

📦 Deployments:
  • aks-agent: 1/1 ready
  • aks-mcp: 1/1 ready

🐳 Pods:
  • aks-agent-xxxxx-xxxxx: Running ✓
  • aks-mcp-xxxxx-xxxxx: Running ✓

📋 LLM Configurations:
  • azure/gpt-4o
    API Base: https://your-service.openai.azure.com/
    API Version: 2025-04-01-preview

✅ AKS agent is ready and running!

    Uyarı

    Ayrıca kubectl kullanarak podları ve dağıtımları denetleyerek hedef ad alanında dağıtımın başarılı olduğunu doğrulayabilirsiniz.

    kubectl get pods --namespace $NAMESPACE | grep aks-
kubectl get deployment --namespace $NAMESPACE | grep aks-

AKS için etkin CLI kullanma

Başlatıldıktan sonra, kümelerinizin sorunlarını gidermek ve doğal dil sorgularını kullanarak akıllı içgörüler elde etmek için AKS için aracıLı CLI'yi kullanabilirsiniz. Komut söz dizimi ve işlevselliği, --mode ve --namespace parametreleri dışında hem istemci modu hem de küme modu için aynıdır. Küme modu varsayılan dağıtım modudur, bu nedenle yalnızca istemci modunu kullanırken belirtmeniz --mode client gerekir. Küme modu için, aracının dağıtıldığı ad alanını --namespace parametresi ile belirtmeniz gerekir.

Temel sorgular

Uyarı

Birden çok model ayarladıysanız parametresini kullanarak --model her sorgu için kullanılacak modeli belirtebilirsiniz. Örneğin, --model=azure/gpt-4o.

Aşağıda, istemci modunda AKS için aracı CLI ile çalıştırabileceğiniz temel sorgu örnekleri verilmiştir:

az aks agent "How many nodes are in my cluster?" --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --mode client
az aks agent "What is the Kubernetes version on the cluster?" --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --mode client
az aks agent "Why is coredns not working on my cluster?" --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --mode client
az aks agent "Why is my cluster in a failed state?" --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --mode client

Aşağıda, küme modunda AKS için aracı CLI ile çalıştırabileceğiniz temel sorgu örnekleri verilmiştir:

az aks agent "How many nodes are in my cluster?" --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --namespace $NAMESPACE
az aks agent "What is the Kubernetes version on the cluster?" --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --namespace $NAMESPACE
az aks agent "Why is coredns not working on my cluster?" --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --namespace $NAMESPACE
az aks agent "Why is my cluster in a failed state?" --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --namespace $NAMESPACE

Varsayılan olarak etkileşimli modu kullanan deneyim, çıkmak isteyene kadar bağlamı koruyarak soru sormaya devam etmenize olanak tanır. Deneyimden çıkmak için /exit girin.

Komut parametreleri

Komutun az aks agent sorun giderme deneyimini özelleştirmenize olanak sağlayan çeşitli parametreleri vardır. Aşağıdaki tabloda, sorgularınızı çalıştırırken kullanabileceğiniz anahtar parametreler açıklanmaktadır:

Parametre Description
--max-steps LLM'nin sorunu araştırmak için atabileceği en fazla adım sayısı. Varsayılan: 40.
--mode Ajanın nasıl dağıtılacağını mod belirler. İzin verilen değerler: client, cluster. Varsayılan: cluster.
--model AI yardımcısı için kullanılacak LLM sağlayıcısını ve modelini veya dağıtımını belirtin.
--name, -n Yönetilen kümenin adı. (Gerekli)
--namespace AKS Aracısı'nın dağıtıldığı Kubernetes ad alanı. Küme modu için gereklidir.
--no-echo-request Çıkışta AKS Aracısı'na verilen soruyu geri döndürmeyi devre dışı bırakın.
--no-interactive Etkileşimli modu devre dışı bırakın. Ayarlandığında, ajan giriş istemez ve toplu modda çalışır.
--refresh-toolsets Araç setlerinin durumunu yenileyin.
--resource-group, -g Kaynak grubunun adı. (Gerekli)
--show-tool-output Çağrılan her aracın çıkışını gösterin.
--status AKS aracısının yapılandırma ve durum bilgilerini gösterin.

Model belirtimi

--model parametresi, kümenizi hangi LLM ve sağlayıcının çözümlediğini belirler. Örneğin:

  • OpenAI: Model adını doğrudan kullanın (örneğin, gpt-4o).
  • Azure OpenAI: Kullanın azure/<deployment name> (örneğin, azure/gpt-4o).
  • Antropik: kullanın anthropic/claude-sonnet-4.

Etkileşimli komutlar

, az aks agent sorun giderme deneyimine yardımcı olan bir alt komut kümesine sahiptir. Bunlara erişmek için etkileşimli mod deneyiminin içine girin / .

Aşağıdaki tabloda kullanılabilir etkileşimli komutlar açıklanmaktadır:

Komut Description
/exit Etkileşimli moddan çıkın.
/help Tüm komutlarla yardım iletilerini gösterin.
/clear Ekranı temizleyin ve konuşma bağlamını sıfırlayın.
/tools Mevcut araç setlerini ve durumlarını gösterin.
/auto Yanıtlardan sonra çıktıların görüntülenmesine geçiş yapın.
/last Son yanıtın tüm araç çıktısını gösterin.
/run Bir Bash komutu çalıştırın ve isteğe bağlı olarak LLM ile paylaşın.
/shell Etkileşimli kabuğa girin ve isteğe bağlı oturumu LLM ile paylaşın.
/context Konuşma bağlamı boyutunu ve belirteç sayısını gösterin.
/show Belirli bir araç çıkışını kaydırılabilir bir görünümde gösterin.
/feedback Temsilcinin yanıtı hakkında geri bildirim verin.

Etkileşimli modu devre dışı bırakma

Komutunuzla bayrağını --no-interactive kullanarak etkileşimli modu devre dışı bırakabilirsiniz. Örneğin:

az aks agent "How many pods are in the kube-system namespace" --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --mode client --model=azure/gpt-4o --no-interactive
az aks agent "Why are the pods in Crashloopbackoff in the kube-system namespace" --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --mode client --model=azure/gpt-4o --no-interactive --show-tool-output

az aks agent "How many pods are in the kube-system namespace" --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --namespace $NAMESPACE --model=azure/gpt-4o --no-interactive
az aks agent "Why are the pods in Crashloopbackoff in the kube-system namespace" --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --namespace $NAMESPACE --model=azure/gpt-4o --no-interactive --show-tool-output

Araç Setleri

AKS için aracılı CLI, araç kümeleri aracılığıyla popüler izleme ve gözlemlenebilirlik araçları için önceden oluşturulmuş tümleştirmeler içerir. Bazı tümleştirmeler Kubernetes ile otomatik olarak çalışır. Diğer tümleştirmeler API anahtarları veya yapılandırma gerektirir.

AKS için sorun giderme deneyimine yardımcı olan belirli araç kümeleri vardır. Bu araç kümeleri, deneyimin başlangıcında çıktıda görünür:

...
✅ Toolset kubernetes/kube-prometheus-stack
✅ Toolset internet
✅ Toolset bash
✅ Toolset runbook
✅ Toolset kubernetes/logs
✅ Toolset kubernetes/core
✅ Toolset kubernetes/live-metrics
✅ Toolset aks/core
✅ Toolset aks/node-health
Using 37 datasources (toolsets). To refresh: use flag `--refresh-toolsets`

AKS MCP sunucu tümleştirmesi

AKS Modeli Bağlam Protokolü (MCP) sunucusu, AKS için aracı CLI ile varsayılan olarak etkindir. Bu deneyim AKS MCP sunucusunu yerel olarak (veya küme moduyla kümede) oluşturur ve telemetri kaynağı olarak kullanır.

Ajan CLI dağıtımını temizleme

Komutunu az aks agent-cleanup ve parametresiyle --mode client kullanarak istemci modu dağıtımınızı temizleyin. Bu komut yerel yapılandırma dosyasını kaldırır ve aracı yapılandırmasını sıfırlar.

az aks agent-cleanup --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --mode client

komutunu kullanarak az aks agent-cleanup küme modu dağıtımınızı temizleyin. --namespace parametresini, aracın dağıtıldığı ad alanı ile birlikte belirtin. Bu komut, belirtilen ad alanından aracı podunu kaldırır ve kümede depolanan LLM yapılandırmasını siler.

az aks agent-cleanup --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --namespace $NAMESPACE

Temizleme işleminin başarılı olduğunu doğrulama

Aşağıdaki komutları kullanarak yerel yapılandırma dosyasının ve Docker görüntülerinin kaldırılıp kaldırılmadığını denetleyin:

# Check if configuration file was removed
ls ~/.azure/aksAgent.config

# Check for remaining Docker images
docker images | grep aks-agent

Uygun ad alanına sahip aşağıdaki komutları kullanarak aracı podunun ve ilgili kaynakların kümeden kaldırılıp kaldırılmadığını denetleyin:

# Check if agent pod was removed
kubectl get pods --namespace $NAMESPACE

# Check if service account was removed
kubectl get serviceaccount --namespace $NAMESPACE

# Check if namespace was removed (if it was created during init)
kubectl get namespace $NAMESPACE

AKS uzantısı için etmen CLI'sini kaldırın

az extension remove komutunu kullanarak AKS uzantısının aracı CLI'yi kaldırın.

az extension remove --name aks-agent --debug

İlgili içerik

  • Son güncelleştirme: