[Azure] Agent CLI for AKS와 AKS MCP 서버 연동으로 AI 기반 Kubernetes 관리 자동화

1. 문제 정의

Azure Kubernetes Service(AKS)는 관리형 Kubernetes 서비스이지만, 운영 관점에서는 다음과 같은 과제가 존재한다.

노드·파드·네임스페이스·애드온 등 상태를 종합적으로 파악하기 위해 다수의 kubectl·로그·메트릭을 수동으로 확인해야 한다.
클러스터 장애 원인(Upgrade 실패, 노드 NotReady, CoreDNS 장애 등)을 파악하려면 여러 소스를 분석해야 하며, 전문 지식이 요구된다. AKS 블로그+1
운영 자동화 스크립트는 팀·환경마다 흩어져 있어, 공통 운영 패턴을 재사용하기 어렵다.
*Agent CLI for AKS(Agentic CLI)**와 AKS MCP(Model Context Protocol) 서버를 결합하면, 이 문제를 “자연어 기반 AI 에이전트”로 해결할 수 있다.

2. 왜 Agent CLI for AKS + AKS MCP가 필요한가

2.1 Agent CLI for AKS의 역할

Agentic CLI for AKS는 az aks agent 명령 그룹으로 제공된다. 이 명령은 다음 기능을 제공한다. Microsoft Learn+3Microsoft Learn+3Microsoft Learn+3

자연어 질의를 받아 AKS 클러스터의 상태·구성·이슈를 분석
클러스터 메트릭, 이벤트, 로그, 진단 도구를 자동으로 호출
장애 원인 추론 및 조치 가이드를 제시
비용 최적화·업그레이드 평가 등 운영 인사이트 제공 AKS 블로그+1

핵심은 운영자가 직접 어떤 명령을 실행할지 고민하지 않고, “무엇이 궁금한지”만 자연어로 기술하면 된다는 점이다.

2.2 AKS MCP 서버의 역할

AKS MCP 서버는 AI 에이전트와 AKS API 사이의 표준화된 브리지 역할을 수행한다. YouTube+4GitHub+4LobeHub+4

MCP 규격을 사용하여, AI 에이전트가 kubectl, AKS API, 모니터링 데이터에 일관된 방식으로 접근하게 한다.
GitHub Copilot·Claude·기타 MCP 호환 에이전트와 동일한 인터페이스를 제공한다.
클러스터 리소스 목록 조회, 노드·파드 상태 점검, 이벤트·로그 탐색 등 AKS 특화 도구를 노출한다.

2.3 둘을 함께 사용하는 이유

Agent CLI for AKS는 --aks-mcp 옵션을 통해 AKS MCP 서버와 통합된다. Microsoft Learn+2Luminis+2

az aks agent는 LLM(예: Azure OpenAI gpt-4o)과 MCP 도구를 조합해,
- 진단 계획 수립 → 관련 도구 실행 → 결과 요약 → 권장 조치 흐름을 자동으로 수행한다. itnext.io+1
운영자는 “왜 노드가 NotReady 상태인가?”, “이 네임스페이스의 파드가 CrashLoopBackOff인 이유는?”처럼 도메인 문제를 기술하는 것에만 집중하면 된다.

3. 사전 준비사항

3.1 계정 및 권한

Azure 계정 및 AKS 클러스터가 있는 Subscription
az login 이 완료된 Azure CLI 환경
대상 AKS 클러스터에 대한 최소 Azure Kubernetes Service Cluster User Role 또는 그에 상응하는 RBAC 권한 Microsoft Learn+2Microsoft Learn+2

3.2 도구 버전

Azure CLI 최신 버전 (Agent CLI는 확장으로 제공되며, 최신 CLI를 권장) Microsoft Learn+1
aks-agent 확장 설치:

# 확장 설치
az extension add --name aks-agent

# 이미 설치된 경우 업데이트
az extension update --name aks-agent

# 설치 확인
az extension list --output table | grep aks-agent

# 도움말 확인
az aks agent --help

Microsoft Learn+1

3.3 LLM 구성

Azure OpenAI, OpenAI, Anthropic 등 지원되는 LLM 공급자 중 하나에 대한 API Key 및 엔드포인트 정보 Microsoft Learn
az aks agent-init 를 사용해 LLM 설정을 인터랙티브하게 저장할 수 있다. 설정 내용은 구성 파일(예: aksAgent.yaml)에 기록된다.

3.4 AKS MCP 서버

Agent CLI에서 -aks-mcp 를 사용할 경우, 네이티브 통합을 통해 자동으로 AKS MCP 도구 세트를 로드한다. Luminis+1
추가적으로, VS Code·독립 실행형 바이너리 등으로 AKS MCP 서버를 직접 설치해 다른 MCP 호환 에이전트에서도 재사용할 수 있다. Luminis+4GitHub+4GitHub+4

4. 기술 개념 설명

4.1 Agent CLI for AKS (az aks agent)

az aks agent는 “AI 도우미를 실행하여 Kubernetes 클러스터를 분석하고 문제를 해결”하는 명령이다. Microsoft Learn+2Visual Studio Code+2

특징은 다음과 같다.

자연어 질의:Microsoft Learn+2Microsoft Learn+2
az aks agent "How many nodes are in my cluster?" \\ --name $CLUSTER_NAME \\ --resource-group $RESOURCE_GROUP
대화형 모드: 한 번 진입하면 /exit 입력까지 컨텍스트를 유지하며 연속 질문이 가능하다. Microsoft Learn+1
도구 세트 기반 실행:
- AKS 진단 명령, Kubernetes 이벤트·로그, Azure/AKS API 호출 등이 “도구 세트(toolset)”로 등록되어 있으며,
- 에이전트는 LLM의 추론 결과에 따라 적절한 도구를 호출하고 결과를 종합해 요약·권장 조치를 반환한다. Microsoft Learn+1
구성 파일 기반 LLM 설정:
- az aks agent-init 로 LLM 공급자·모델·API Key·MCP 서버 목록을 저장한다.
- 또는 -config-file 옵션으로 사용자 정의 YAML/JSON 구성 파일을 지정할 수 있다.

4.2 AKS MCP 서버

AKS MCP 서버는 다음과 같은 특징을 가진다. YouTube+6GitHub+6LobeHub+6

MCP 표준을 구현한 서버로, AI 에이전트가 AKS 클러스터와 상호작용할 수 있게 한다.
kubectl 수준의 리소스 조회·진단뿐 아니라, AKS 메트릭·이벤트·로그·업그레이드 상태 등 AKS 특화 도구를 포함한다.
VS Code·Cursor·Claude Desktop 등 다양한 MCP 클라이언트에서 공통적으로 사용할 수 있다.
단일 클러스터 또는 중앙 허브 클러스터에 배포하여 다수의 팀·에이전트가 공유할 수 있다. LinkedIn+1

4.3 Agent CLI와 AKS MCP 통합

az aks agent는 --aks-mcp 플래그를 사용해 AKS MCP 도구를 활성화한다. LinkedIn+4Microsoft Learn+4Microsoft Learn+4

예시:

az aks agent "list all my unhealthy nodepools" \\
  --aks-mcp \\
  --name $CLUSTER_NAME \\
  --resource-group $RESOURCE_GROUP

이 모드에서는 다음이 수행된다.

LLM 구성이 로드된다(모델, API Key, 엔드포인트).
AKS MCP 서버에 연결해 사용 가능한 도구 세트를 새로 고친다(-refresh-toolsets). Microsoft Learn
에이전트가 질의를 분석하여,
- 노드풀 상태 점검, 이벤트 조회, 진단 Pod 실행 등 여러 도구를 순차적으로 호출
- 결과를 요약해 “어떤 노드풀이, 어떤 이유로 건강하지 않은지, 어떤 조치가 필요한지”를 제시

5. 실제 구성 방법 (CLI / Portal 포함)

5.1 AKS Agent CLI 확장 설치

# 1. 확장 설치 또는 업데이트
az extension add --name aks-agent   # 최초 설치
az extension update --name aks-agent # 업데이트

# 2. 설치 확인
az aks agent --help

출력의 extensions 섹션에 aks-agent 버전 정보가 포함되어야 한다. Microsoft Learn+1

5.2 LLM 설정 – az aks agent-init

az aks agent-init

위 명령을 실행하면 다음 항목을 단계별로 입력하도록 안내한다. Microsoft Learn

LLM 공급자(예: azure / openai / anthropic)
모델 이름(예: azure/gpt-4o, gpt-4.1)
API Key 및 엔드포인트(URL, 버전)
기본 MCP 서버 목록(AKS MCP 포함)

설정 결과는 구성 파일(예: ~/.config/aksAgent.yaml 경로, 환경에 따라 상이)에 저장된다. 경로는 az aks agent --help 에서 확인할 수 있다.

5.3 AKS MCP 연동 활성화

Agent CLI는 자체적으로 AKS MCP와 통합되며, --aks-mcp 플래그를 켜면 MCP 도구 세트를 함께 사용한다. LinkedIn+3Luminis+3Microsoft Learn+3

az aks agent "why is my node unhealthy" \\
  --model=azure/gpt-4o \\
  --aks-mcp \\
  --name $CLUSTER_NAME \\
  --resource-group $RESOURCE_GROUP

실행 시 출력 예시(요약): Microsoft Learn+1

Loaded models: ['azure/gpt-4o']
Refreshing available datasources (toolsets)
..

[Summary]
- Node aks-nodepool1-12345 is NotReady.
- Kubelet reports disk pressure and failing liveness probes.
- Pods in namespace kube-system are CrashLoopBackOff.

[Recommended actions]
1. Check node disk usage and clean up unused images.
2. Consider scaling out the nodepool.
3. Restart impacted pods after remediation.

5.4 Portal을 통한 결과 검증

CLI 에이전트가 제시한 진단 결과와 권장 조치는 Portal에서 다음 위치로 교차 검증할 수 있다. Docker Hub+1

AKS 클러스터 → Insights(모니터링), Workloads, Nodes, Events
Azure Monitor → Container Insights(Log Analytics)
Metrics/Alerts → 관련 알림 규칙 및 메트릭 추세

6. 단계별 튜토리얼

6.1 Step 1 – 기본 환경 준비

# Azure 로그인
az login
az account set --subscription "<SUBSCRIPTION_ID>"

# AKS Agent 확장 설치
az extension add --name aks-agent

클러스터 컨텍스트를 점검한다.

az aks get-credentials -n $CLUSTER_NAME -g $RESOURCE_GROUP
kubectl cluster-info

6.2 Step 2 – LLM 초기 설정

az aks agent-init

공급자: azure
모델: AKS 문서에서 권장하는 azure/gpt-4o 또는 조직 정책에 따른 모델 선택 Microsoft Learn+1
API Key/엔드포인트: Azure OpenAI 리소스 기준 정보 입력

설정이 완료되면 aksAgent.yaml 또는 유사 파일이 생성된다.

6.3 Step 3 – 기본 질의 실행(비 MCP)

먼저 MCP 없이 Agent CLI만 사용해 본다.

az aks agent "What is the Kubernetes version on the cluster?" \\
  --name $CLUSTER_NAME \\
  --resource-group $RESOURCE_GROUP

또는:

az aks agent "How many nodes are in my cluster?" \\
  --name $CLUSTER_NAME \\
  --resource-group $RESOURCE_GROUP

Microsoft Learn+2Microsoft Learn+2

에이전트는 kubectl get nodes·AKS API 등 여러 도구를 호출해 요약 정보를 반환한다.

6.4 Step 4 – MCP 통합 질의 실행

이제 MCP 통합을 활성화한다.

az aks agent "Why is coredns not working in my cluster?" \\
  --aks-mcp \\
  --name $CLUSTER_NAME \\
  --resource-group $RESOURCE_GROUP

또는 보다 구체적인 질의:

az aks agent "Explain why pods in namespace 'payment' are CrashLoopBackOff" \\
  --aks-mcp \\
  --name $CLUSTER_NAME \\
  --resource-group $RESOURCE_GROUP

이때 AKS MCP는 다음 정보를 조합할 수 있다. YouTube+4GitHub+4LobeHub+4

해당 네임스페이스 파드의 이벤트·로그
관련 Deployment/ReplicaSet 설정
노드 상태 및 자원 사용량
CoreDNS/네트워크 구성 상태

Agent CLI는 이를 근거로 장애 원인과 조치 방안을 정리해 반환한다.

6.5 Step 5 – 구성 파일을 사용한 고급 설정

에이전트 구성 파일 예시는 문서의 exampleconfig.yaml 에 제공된다. GitHub

아래는 JSON 형식 예시(문서 내용 기반 재구성)이다.

llms:
  - provider: azure
    MODEL_NAME: gpt-4.1
    AZURE_API_KEY: ""
    AZURE_API_BASE: "https://.openai.azure.com/"
    AZURE_API_VERSION: "2025-04-01-preview"

mcp_servers:
  aks_mcp:
    type: http
    url: "<https://aks-mcp.example.com>"

toolsets:
  - name: aks-default
    enabled: true

구성 파일을 명시적으로 사용하려면:

az aks agent "Check kubernetes pod resource usage" \\
  --config-file /path/to/aksAgent.yaml \\
  --aks-mcp \\
  --name $CLUSTER_NAME \\
  --resource-group $RESOURCE_GROUP

7. 구성 예시 / 샘플 시나리오

7.1 비용 최적화 분석

az aks agent "How can I optimize the cost of my cluster?" \\
  --aks-mcp \\
  --name aks-prod \\
  --resource-group rg-aks-prod

Agent CLI는 다음과 같은 분석을 수행할 수 있다. AKS 블로그+1

노드풀별 사용률과 스케일링 패턴 분석
미사용/저이용 리소스 탐지
Pod 리소스 요청/제한 설정 불균형 진단
권장 조치(노드풀 스케일 인, Spot 노드풀 도입, 리소스 요청 재조정 등) 제시

7.2 업그레이드 실패 진단

az aks agent "My AKS cluster is in a failed state after upgrade, what happened?" \\
  --aks-mcp \\
  --name aks-upgrade-test \\
  --resource-group rg-aks-upgrade

대표 진단 항목: PodDisruptionBudget 위반, 노드 이미지 업데이트 실패, IP 고갈, 애드온 상태 이상 등. AKS 블로그+1

7.3 규정 준수·보안 점검 보조

MCP 도구를 확장하거나 향후 제공되는 도구를 활용해, 다음과 같은 질의를 수행할 수 있다.

az aks agent "List namespaces and highlight any with privileged pods or hostPath volumes." \\
  --aks-mcp \\
  --name aks-sec \\
  --resource-group rg-aks-sec

에이전트는 Kubernetes 보안 설정을 기반으로 위험 요소를 요약하고, Pod Security 정책·네트워크 정책 적용을 권장하는 답변을 생성할 수 있다.

기타 질문에 대한 해결 결과

8. 발생 가능한 오류 및 해결 방법

8.1 LLM 구성 오류

증상

응답에 “LLM provider not configured”, “authentication failed”, 401/403 등 오류 표시
az aks agent 실행 시 즉시 실패

점검 항목

az aks agent-init로 설정한 구성 파일 경로에 값이 올바르게 저장되었는지 확인한다.
-config-file 를 사용하는 경우 파일 경로 및 YAML/JSON 문법이 정상인지 검증한다.
Azure OpenAI 사용 시 -model 매개 변수와 실제 배포 이름이 일치하는지 확인한다.

8.2 MCP 서버 연결 문제

증상

MCP 도구 목록이 비어 있거나, 응답에 “failed to connect to MCP server” 메시지 표시
-aks-mcp 사용 시 에이전트가 기본 도구만 사용하고 AKS 컨텍스트를 제대로 인식하지 못함

점검 항목

-aks-mcp 플래그가 실제로 지정되었는지 재확인한다. Microsoft Learn+1
외부 AKS MCP 서버를 사용하는 경우, MCP 서버 URL·포트·TLS 설정을 재확인하고 방화벽/NSG 정책을 점검한다. Docker Hub+3Evanth+3LobeHub+3
VS Code 통합 MCP 서버를 사용하는 경우, MCP: List Servers 또는 AKS 확장 메뉴에서 서버 상태를 확인한다. GitHub+2GitHub+2

8.3 클러스터 연결 문제

증상

에이전트가 “cluster not reachable” 또는 kubectl 관련 오류를 반환
동일 환경에서 kubectl cluster-info 도 실패

해결 방법

az aks get-credentials 를 다시 실행해 kubeconfig를 최신 상태로 동기화한다. Microsoft Learn
프라이빗 클러스터·방화벽·프록시 환경에서는 네트워크 경로가 열려 있는지 확인한다.
여전히 실패하면, Agent CLI의 문제가 아니라 네트워크·클러스터 구성이 원인일 가능성이 높으므로 해당 경로를 별도로 점검한다.

8.4 속도 저하 및 Rate Limit

증상

에이전트 응답이 매우 느리거나, 로그에 /chat/completions 재시도 메시지가 반복됨

대응

LLM 공급자 측 TPM(분당 토큰)·RPM(분당 요청 수) 제한을 확인하고, 필요 시 할당량을 조정한다.
한 번에 너무 광범위한 조사를 요구하는 대신, 네임스페이스·노드풀 단위로 범위를 줄여 질의한다.
구성 파일에서 보다 경량 모델을 임시로 사용해 속도를 개선할 수 있다.

9. 정리 및 Best Practice

9.1 요약

Agent CLI for AKS는 az aks agent 명령을 통해, 자연어 기반으로 AKS 클러스터를 진단·분석·최적화하는 AI 도우미를 제공한다. Microsoft Learn+4Microsoft Learn+4Microsoft Learn+4
AKS MCP 서버는 에이전트가 kubectl, AKS API, 모니터링 데이터를 일관되게 사용할 수 있도록 하는 표준화된 브리지로, Agent CLI에서 -aks-mcp 플래그로 연동된다. LinkedIn+5GitHub+5LobeHub+5
이를 통해 “문제 정의 → 진단 플랜 → 도구 실행 → 권장 조치” 전체 운영 흐름을 AI 에이전트가 자동으로 수행하고, 운영자는 결과를 검토·승인하는 역할에 집중할 수 있다.

9.2 실무 적용 팁

읽기 전용부터 시작
- Agent CLI는 기본적으로 읽기 전용 모드에서 동작하지만, 운영 프로세스상 “에이전트 결과는 제안일 뿐이며 실제 변경은 사람·파이프라인에서 수행”이라는 원칙을 명확히 한다. Microsoft Learn
표준 프롬프트 템플릿 정의
- 예:
  - “클러스터 상태 요약”
  - “특정 네임스페이스의 장애 진단”
  - “업그레이드 전 리스크 분석”
  - “비용 최적화 추천”
- 팀 공용 템플릿으로 관리하면 운영 품질을 균일하게 유지할 수 있다. AKS 블로그+2Microsoft Learn+2
AKS MCP 서버 중앙화 전략 고려
- 여러 클러스터를 운영하는 조직이라면, 중앙 허브 AKS 클러스터에 AKS MCP 서버를 배포해 모든 에이전트가 공통 MCP 인스턴스를 사용하도록 설계할 수 있다. Docker Hub+3LinkedIn+3Luminis+3
- 이때 Workload Identity·Managed Identity를 활용해 세밀한 권한 제어를 구성하는 것이 바람직하다. LinkedIn
기존 모니터링·IaC와 연계
- Agent CLI가 제공하는 권장 조치는 결국 기존 파이프라인(Terraform, Bicep, GitOps)과 연동하여 구현해야 한다.
- 예를 들어, 에이전트가 제시한 노드풀 스케일링 전략을 Terraform 변수·Helm values에 반영하고, CI/CD 파이프라인을 통해 적용하는 방식으로 일관성을 유지한다. NVIDIA Docs
Preview 단계 인식
- Agent CLI와 AKS MCP는 Public Preview 단계이므로, 미션 크리티컬 워크로드보다는 운영 분석·테스트 환경부터 적용하여 안정성과 조직 내 신뢰를 확보하는 것이 좋다. AKS 블로그+2Microsoft Learn+2

이 글이 Agent CLI for AKS와 AKS MCP를 활용한 AI 기반 Kubernetes 운영 전략을 설계하는 데 도움이 되었다면, 추후 다시 참고할 수 있도록 북마크하거나 팀·동료와 공유하는 것을 권장한다.

'AI' 카테고리의 다른 글

[AI] Genspark AI 소개 (0)	2026.02.20
[AI] Claude Code 확장 구조 이해하기 (0)	2026.02.19
[DevOps/AI] Claude Code와 Skill을 활용해 ‘엔지니어링 팀’ 수준의 AI 에이전트 만들기 (0)	2026.02.19
[MCP] Model Context Protocol 이해하기 (0)	2025.12.01
[AI] Azure MCP + GitHub Copilot으로 자연어 기반 Azure 리소스 관리·운영 자동화 (0)	2025.11.28

1. 문제 정의

2. 왜 Agent CLI for AKS + AKS MCP가 필요한가

2.1 Agent CLI for AKS의 역할

2.2 AKS MCP 서버의 역할

2.3 둘을 함께 사용하는 이유

3. 사전 준비사항

3.1 계정 및 권한

3.2 도구 버전

3.3 LLM 구성

3.4 AKS MCP 서버

4. 기술 개념 설명

4.1 Agent CLI for AKS (az aks agent)

4.2 AKS MCP 서버

4.3 Agent CLI와 AKS MCP 통합

5. 실제 구성 방법 (CLI / Portal 포함)

5.1 AKS Agent CLI 확장 설치

5.2 LLM 설정 – az aks agent-init

5.3 AKS MCP 연동 활성화

5.4 Portal을 통한 결과 검증

6. 단계별 튜토리얼

6.1 Step 1 – 기본 환경 준비

6.2 Step 2 – LLM 초기 설정

6.3 Step 3 – 기본 질의 실행(비 MCP)

6.4 Step 4 – MCP 통합 질의 실행

6.5 Step 5 – 구성 파일을 사용한 고급 설정

7. 구성 예시 / 샘플 시나리오

7.1 비용 최적화 분석

7.2 업그레이드 실패 진단

7.3 규정 준수·보안 점검 보조

8. 발생 가능한 오류 및 해결 방법

8.1 LLM 구성 오류

8.2 MCP 서버 연결 문제

8.3 클러스터 연결 문제

8.4 속도 저하 및 Rate Limit

9. 정리 및 Best Practice

9.1 요약

9.2 실무 적용 팁

'AI' 카테고리의 다른 글

티스토리툴바