AKS-MCP는 AI 어시스턴트가 Azure Kubernetes Service (AKS) 클러스터와 상호작용할 수 있도록 지원하는 Model Context Protocol (MCP) 서버입니다. 이는 AI 도구(GitHub Copilot, Claude 및 기타 MCP 호환 AI 어시스턴트 등)와 AKS 사이의 가교 역할을 하며, 자연어 요청을 AKS 작업으로 변환하고 AI 도구가 이해할 수 있는 형식으로 결과를 반환합니다.

이를 통해 AI 도구는 다음과 같은 작업을 수행할 수 있습니다:

• AKS 리소스 조작 (CRUD)
• AKS 클러스터와 관련된 세부 정보 조회 (VNets, Subnets, NSGs, Route Tables 등)
• 멀티 클러스터 시나리오를 위한 Azure Fleet 작업 관리

AKS-MCP는 Azure SDK를 사용하여 Azure에 연결하며, AI 어시스턴트가 AKS 리소스와 상호작용하는 데 사용할 수 있는 도구 세트를 제공합니다. 이는 Model Context Protocol (MCP)을 활용하여 이러한 통신을 촉진하며, AI 도구가 Azure에 API 호출을 수행하고 응답을 해석할 수 있도록 합니다.

AKS-MCP는 AKS 작업을 위해 Azure CLI (az)를 사용합니다. Azure CLI 인증은 다음 순서로 시도됩니다:

서비스 주체 (Service Principal, client secret): AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID 환경 변수가 존재하는 경우, 다음 명령어를 사용하여 서비스 주체 로그인을 수행합니다: az login --service-principal -u CLIENT_ID -p CLIENT_SECRET --tenant TENANT_ID

워크로드 ID (Workload Identity, federated token): AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_FEDERATED_TOKEN_FILE 환경 변수가 존재하는 경우, 다음 명령어를 사용하여 페더레이션 토큰 로그인을 수행합니다: az login --service-principal -u CLIENT_ID --tenant TENANT_ID --federated-token TOKEN

사용자 할당 관리 ID (User-assigned Managed Identity, managed identity client ID): AZURE_CLIENT_ID 환경 변수만 존재하는 경우, 다음 명령어를 사용하여 사용자 할당 관리 ID 로그인을 수행합니다: az login --identity -u CLIENT_ID

시스템 할당 관리 ID (System-assigned Managed Identity): AZURE_MANAGED_IDENTITY가 system으로 설정된 경우

, 다음 명령어를 사용하여 시스템 할당 관리 ID (System-assigned Managed Identity) 로그인이 수행됩니다:
az login --identity

기존 로그인 (Existing Login): 위의 환경 변수 중 어느 것도 설정되지 않은 경우, AKS-MCP는 사용자가 이미 인증(예: az login을 통해)을 완료했다고 가정하고 기존 세션을 사용합니다.

선택적 구독 선택 (Optional subscription selection):

• AZURE_SUBSCRIPTION_ID가 설정된 경우, AKS-MCP는 로그인 후 az account set --subscription SUBSCRIPTION_ID를 실행합니다.

참고 및 보안 (Notes and security):

• 연합 토큰 (Federated token) 파일은 반드시 /var/run/secrets/azure/tokens/azure-identity-token이어야 하며 엄격하게 검증됩니다. 다른 경로는 거부됩니다. - 각 로그인 후, AKS-MCP는 az account show --query id -o tsv를 통해 인증을 확인합니다. - Azure CLI가 설치되어 있고 PATH에 등록되어 있는지 확인하십시오.

사용된 환경 변수 (Environment variables used):

AZURE_TENANT_ID
AZURE_CLIENT_ID
AZURE_CLIENT_SECRET
AZURE_FEDERATED_TOKEN_FILE
AZURE_SUBSCRIPTION_ID
AZURE_MANAGED_IDENTITY (시스템 할당 관리 ID를 사용하려면 system으로 설정)

AKS-MCP 서버는 AKS 클러스터와 상호 작용하기 위한 통합된 도구들을 제공합니다. 기본적으로 서버는 더 유연한 인터페이스를 제공하는 통합 도구 (unified tools) (Azure 작업을 위한 call_az 및 Kubernetes 작업을 위한 call_kubectl)를 사용합니다. 하위 호환성을 위해, 환경 변수 USE_LEGACY_TOOLS=true를 설정하여 **레거시 특화 도구 (legacy specialized tools)**를 활성화할 수 있습니다.

일부 도구는 클러스터에서 디버깅용 포드 (debugging pods)를 실행하기 위해 읽기-쓰기 (read-write) 또는 관리자 (admin) 권한을 요구합니다. AKS-MCP 서버에 읽기-쓰기 또는 관리자 권한을 부여하려면 MCP 설정 파일에 액세스 수준 (access level) 파라미터를 추가하십시오:

• mcp.json 파일로 이동하거나, 명령 팔레트 (Command Palette) (VSCode의 경우 Windows/Linux에서는 Ctrl+Shift+P, macOS에서는 Cmd+Shift+P)에서 MCP: List Servers -> AKS-MCP -> Show Configuration Details를 선택합니다. - AKS-MCP의 "args" 섹션에 다음 파라미터를 추가합니다: "--access-level", "readwrite" / "admin"

예시:

"args": [
"--transport",
"stdio",
...

이 도구들은 통합된 인터페이스를 통해 포괄적인 기능을 제공하도록 설계되었습니다:

Azure CLI 작업 (통합 도구)

도구: call_az

(기본값, USE_LEGACY_TOOLS가 설정되지 않았거나 false로 설정된 경우 사용 가능)

Azure CLI 명령을 직접 실행하기 위한 통합 도구입니다. 이 도구는 모든 Azure CLI 명령을 실행할 수 있는 유연한 인터페이스를 제공합니다.

매개변수 (Parameters):

cli_command

: 실행할 전체 Azure CLI 명령 (예: az aks list --resource-group myRG, az vm list --subscription <sub-id>)

timeout

: 선택 사항인 초 단위 타임아웃 (기본값: 120)

사용 예시:

{
"cli_command": "az aks list --resource-group myResourceGroup --output json"
}

액세스 제어 (Access Control):

readonly: 읽기 작업만 허용됨
readwrite/admin: 읽기 및 쓰기 작업 모두 허용됨

중요: 명령은 파이프(|), 리다이렉트(>, <), 명령 치환(command substitution) 또는 세미콜론(;)과 같은 셸(shell) 기능이 없는 단순한 Azure CLI 호출이어야 합니다.

AKS 클러스터 관리 (레거시 도구)

도구: az_aks_operations

(USE_LEGACY_TOOLS=true인 경우 사용 가능)

Azure Kubernetes Service (AKS) 클러스터 및 관련 작업을 관리하기 위한 통합 도구입니다.

사용 가능한 작업 (Available Operations):

Read-Only (모든 액세스 수준):
show: 클러스터 상세 정보 표시
list: 구독/리소스 그룹 내 클러스터 목록 표시
get-versions: 사용 가능한 Kubernetes 버전 가져오기
check-network: 아웃바운드 네트워크 연결성 확인 수행
nodepool-list: 클러스터 내 노드 풀(node pool) 목록 표시
nodepool-show: 노드 풀 상세 정보 표시
account-list: Azure 구독 목록 표시

Read-Write (readwrite / admin 액세스 수준):
create: 새 클러스터 생성
delete: 클러스터 삭제
scale: 클러스터 노드 수 확장/축소
start: 중지된 클러스터 시작
stop: 실행 중인 클러스터 중지
update: 클러스터 구성 업데이트
upgrade: Kubernetes 버전 업그레이드
nodepool-add: 클러스터에 노드 풀 추가
nodepool-delete: 노드 풀 삭제
nodepool-scale: 노드 풀 확장/축소
nodepool-upgrade: 노드 풀 업그레이드

nodepool-upgrade: 노드 풀 업그레이드
account-set: 계정 세트 설정

login: 활성 구독 설정

Azure 인증

관리자 전용(admin 액세스 레벨):
get-credentials: kubectl 액세스를 위한 클러스터 자격 증명 가져오기

네트워크 리소스 관리 (Network Resource Management)

도구 (Tool): aks_network_resources

AKS 클러스터에서 사용되는 Azure 네트워크 리소스 정보를 가져오기 위한 통합 도구입니다.

사용 가능한 리소스 유형 (Available Resource Types):

all: 모든 네트워크 리소스에 대한 정보 가져오기
vnet: 가상 네트워크 (Virtual Network) 정보
subnet: 서브넷 (Subnet) 정보
nsg: 네트워크 보안 그룹 (Network Security Group) 정보
route_table: 라우트 테이블 (Route Table) 정보
load_balancer: 부하 분산 장치 (Load Balancer) 정보
private_endpoint: 프라이빗 엔드포인트 (Private endpoint) 정보

모니터링 및 진단 (Monitoring and Diagnostics)

도구 (Tool): aks_monitoring

AKS 클러스터에 대한 Azure 모니터링 및 진단 작업을 위한 통합 도구입니다.

사용 가능한 작업 (Available Operations):

metrics: 리소스에 대한 메트릭 (Metric) 값 목록 표시
resource_health: AKS 클러스터의 리소스 상태 (Resource health) 이벤트 검색
app_insights: Application Insights 텔레메트리 (Telemetry) 데이터에 대해 KQL 쿼리 실행
diagnostics: AKS 클러스터에 진단 설정 (Diagnostic settings)이 구성되어 있는지 확인
control_plane_logs: 안전 제약 조건 및 시간 범위 검증을 포함하여 AKS 컨트롤 플레인 (Control plane) 로그 쿼리

컴퓨팅 리소스 (Compute Resources)

도구 (Tool): get_aks_vmss_info

• AKS 클러스터 내 노드 풀에 대한 상세한 VMSS 구성 가져오기

도구 (Tool): collect_aks_node_logs

디버깅 및 문제 해결을 위해 AKS VMSS 노드에서 시스템 로그를 수집합니다.

매개변수 (Parameters):

aks_resource_id: AKS 클러스터 리소스 ID
vmss_name: VMSS 이름 (get_aks_vmss_info 또는 kubectl get nodes에서 획득)
instance_id: VMSS 인스턴스 ID
log_type: 수집할 로그 유형 (kubelet, containerd, kernel, syslog)
lines: 반환할 최근 로그 라인 수 (기본값: 500, 최대: 2000)
since: 로그 시간 범위 (예: 1h, 30m, 2d) - lines보다 우선순위가 높음
level: 로그 레벨 필터 (ERROR, WARN, INFO)
filter: 키워드로 로그 필터링 (대소문자 구분 없는 텍스트 일치)

사용 예시 (Example Usage):

{
"aks_resource_id": "/subscriptions/.../managedClusters/myAKS",
"vmss_name": "aks-nodepool1-12345678-vmss",
...

제한 사항 (Limitations):

• Linux VMSS 노드만 지원합니다 (Windows 노드 및 단독 VM은 아직 지원되지 않습니다)
• VMSS 인스턴스당 한 번에 하나의 실행 명령(run command)만 실행할 수 있습니다

도구 (Tool): az_compute_operations

AKS에서 사용되는 Azure 가상 머신 (VMs) 및 가상 머신 확장 집합 (VMSS) 관리를 위한 통합 도구입니다.

사용 가능한 작업 (Available Operations):

show
: VM/VMSS의 상세 정보 가져오기
list
: 구독(subscription) 또는 리소스 그룹(resource group) 내의 VM/VMSS 목록 나열
get-instance-view
: 런타임 상태(runtime status) 가져오기
start
: VM 시작
stop
: VM 중지
restart
: VM/VMSS 인스턴스 재시작
reimage
: VMSS 인스턴스 재이미지화 (VM은 재이미지화가 지원되지 않음)

리소스 유형 (Resource Types): vm (단일 가상 머신), vmss (가상 머신 확장 집합)

플릿 관리 (Fleet Management)

도구 (Tool): az_fleet

멀티 클러스터 시나리오를 위한 포괄적인 Azure Fleet 관리 도구입니다.

사용 가능한 작업 (Available Operations):

플릿 작업 (Fleet Operations): list, show, create, update, delete, get-credentials
멤버 작업 (Member Operations): list, show, create, update, delete
업데이트 실행 작업 (Update Run Operations): list, show, create, start, stop, delete
업데이트 전략 작업 (Update Strategy Operations): list, show, create, delete
클러스터 리소스 배치 작업 (ClusterResourcePlacement Operations): list, show, get, create, delete

Azure Fleet 관리 및 Kubernetes ClusterResourcePlacement CRD 작업을 모두 지원합니다.

진단 탐지기 (Diagnostic Detectors)

도구 (Tool): aks_detector

AKS 진단 탐지기(diagnostic detector) 작업을 실행하기 위한 통합 도구입니다.

사용 가능한 작업 (Available Operations):

list
: 사용 가능한 모든 AKS 클러스터 탐지기 목록 나열
run
: 특정 AKS 진단 탐지기 실행
run_by_category
: 특정 카테고리의 모든 탐지기 실행

매개변수 (Parameters):

operation (필수): 수행할 작업 (list, run, 또는 run_by_category)
aks_resource_id (필수): AKS 클러스터 리소스 ID
detector_name (run 작업 시 필수): 실행할 탐지기의 이름
category (run_by_category 작업 시 필수)

operation): Detector category
start_time (required for run and run_by_category operations): UTC ISO 형식의 시작 시간 (최근 30일 이내)
end_time (required for run and run_by_category operations): UTC ISO 형식의 종료 시간 (최근 30일 이내, 시작 시간으로부터 최대 24시간 이내)

사용 가능한 카테고리 (Available Categories):

• Best Practices (권장 사항)
• Cluster and Control Plane Availability and Performance (클러스터 및 컨트롤 플레인 가용성 및 성능)
• Connectivity Issues (연결 문제)
• Create, Upgrade, Delete and Scale (생성, 업그레이드, 삭제 및 확장)
• Deprecations (지원 종료 예정 사항)
• Identity and Security (ID 및 보안)
• Node Health (노드 상태)
• Storage (스토리지)

사용 예시 (Example Usage):

{
"operation": "list",
"aks_resource_id": "/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ContainerService/managedClusters/xxx"
...
}

{
"operation": "run",
"aks_resource_id": "/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ContainerService/managedClusters/xxx",
...
}

Azure Advisor

도구 (Tool): aks_advisor_recommendation

AKS 클러스터에 대한 Azure Advisor 권장 사항을 검색하고 관리합니다.

사용 가능한 작업 (Available Operations):

list: 필터링 옵션을 사용하여 권장 사항 목록을 나열합니다.
report: 권장 사항 보고서를 생성합니다.

필터 옵션 (Filter Options): resource_group, cluster_names, category (Cost, HighAvailability, Performance, Security), severity (High, Medium, Low)

Kubernetes Operations

참고: 모든 Kubernetes 도구 (kubectl, helm, cilium, hubble)는 기본적으로 활성화되어 있습니다. 특정 구성 요소만 선택적으로 활성화하려면 --enabled-components를 사용하세요.

도구 (Tool): call_kubectl

(기본값, USE_LEGACY_TOOLS가 설정되지 않았거나 false로 설정된 경우 사용 가능)

kubectl 명령을 직접 실행하기 위한 통합 도구입니다. 이 도구는 모든 인자 (argument)를 지원하며 임의의 kubectl 명령을 실행할 수 있는 유연한 인터페이스를 제공합니다.

매개변수 (Parameters):

args: kubectl 명령 인자 (예: get pods, describe node mynode, apply -f deployment.yaml)

사용 예시 (Example Usage):

{
"args": "get pods -n kube-system -o wide"
}

액세스 제어 (Access Control): 작업은 구성된 액세스 수준에 따라 제한됩니다:

readonly: 읽기 작업(get, describe, logs 등)만 허용됩니다.
readwrite/admin: 상태를 변경하는 명령(create, delete, apply 등)을 포함한 모든 작업이 허용됩니다.

USE_LEGACY_TOOLS=true일 때 사용 가능:

Read-Only(모든 액세스 수준):
kubectl_resources
: 리소스 조회 (get, describe) - readonly 모드에서는 읽기 전용 작업으로 필터링됩니다.
kubectl_diagnostics
: 디버깅 및 진단 (logs, events, top, exec, cp)
kubectl_cluster
: 클러스터 정보 (cluster-info, api-resources, api-versions, explain)
kubectl_config
: 구성 관리 (diff, auth, config) - readonly 모드에서는 읽기 전용 작업으로 필터링됩니다.

Read-Write/Admin(readwrite/admin