ChatGPT 이후 AI는 정말 빠르게 발전했습니다. 이제 AI는 단순히 답변하는 것을 넘어, 스스로 계획을 세우고 행동하는 Agent(에이전트) 로 진화했습니다. 앞으로는 여러 에이전트가 하나의 팀을 꾸려서 지속적으로 생산, 운영, 관리하는 시대가 올 것입니다.
Kubernetes 역시 예외가 아닙니다. 구축한 이후의 kubernetes의 Pod 장애 분석, 로그 조회, 리소스 스케일링, Application 설치와 같은 작업을 AI가 직접 수행해준다면 어떨까요? 그것을 가능하게 해주는 오픈소스가 바로 Kagent입니다.
요즘 주목받는 AI × Kubernetes 오픈소스
kagent를 이해하기 전에, 관련 프로젝트들을 간략히 알아두면 좋습니다.
프로젝트 | 한 줄 설명 |
K8sGPT | 클러스터 문제를 AI로 분석·진단 (읽기 전용) |
Kubeflow | 머신러닝 워크플로 자동화 플랫폼 |
Ollama | 로컬 PC에서 LLM을 실행하는 도구 |
LangChain | LLM 기반 앱 개발 프레임워크 |
kagent | Kubernetes 안에서 AI 에이전트를 직접 실행·운영 |
기존 K8sGPT가 "분석"에 집중한다면, kagent는 분석 이후 직접 행동까지 수행합니다.
kagent란?
kagent는 Solo.io가 개발하고 CNCF에 기여한 오픈소스 AI 에이전트 프레임워크입니다.
핵심 개념은 AI 에이전트를 Kubernetes의 CRD(Custom Resource)로 선언적으로 관리하는 것입니다.
kagent에서 자연어로 'helm application 설치' 요청을 하면 스스로 적절한 에이전트를 조회하고, Helm 에이전트를 찾아 helm 설치를 하고, YAML로 설정을 관리할 수 있습니다. 기존 Kubernetes 운영 방식을 토대로 에이전트는 수행을 합니다.
kagent 구성 요소
•
Tools: AI가 실제로 호출하는 함수 (로그 조회, 리소스 삭제 등)
•
Agents: 도구를 조합해 목표를 달성하는 자율 실행 단위
•
Framework: 이 모든 것을 K8s 위에서 관리하는 Controller·CLI·UI
프로젝트 현황
kagent는 2025년 5월 CNCF Sandbox 프로젝트로 공식 승인되었습니다. 공개 2주 만에 365 Stars, CNCF 채택 후 현재 2850 Stars 이상을 달성한 빠르게 성장하는 프로젝트입니다.
kagent 설치하고 직접 써보기
사전 준비 (k8s 클러스터가 없는 경우)
# 빠른 시작을 위한 설치
brew install kind helm kubectl
Bash
복사
kind: kubernetes를 docker 환경에 빠르고 쉽게 실행할 수 있는 프로젝트
Step 1 — 로컬 클러스터 생성
아래 명령어는 실습용 Kubernetes 클러스터를 로컬 PC에 빠르게 띄우고, kubectl이 해당 클러스터를 바라보는지 확인합니다.
•
kind create cluster --name kagent-demo: Docker 기반의 kind로 kagent-demo 클러스터를 생성합니다.
•
kubectl cluster-info --context kind-kagent-demo: 생성된 클러스터의 Control Plane 주소와 기본 구성 요소(CoreDNS 등)가 정상 동작하는지 확인합니다.
kind create cluster --name kagent-demo
kubectl cluster-info --context kind-kagent-demo
# 실행 예시
k8s-cluster/kind $ kind create cluster --name kagent-demo
Creating cluster "kagent-demo" ...
✓ Ensuring node image (kindest/node:v1.35.0) 🖼
✓ Preparing nodes 📦
✓ Writing configuration 📜
✓ Starting control-plane 🕹️
✓ Installing CNI 🔌
✓ Installing StorageClass 💾
Set kubectl context to "kind-kagent-demo"
You can now use your cluster with:
kubectl cluster-info --context kind-kagent-demo
Thanks for using kind! 😊
k8s-cluster/kind $ kubectl cluster-info --context kind-kagent-demo
Kubernetes control plane is running at https://127.0.0.1:44567
CoreDNS is running at https://127.0.0.1:44567/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.
Bash
복사
Step 2 — kagent CLI 설치
kagent를 설치하고 조작하기 위한 CLI를 내려받아 설치한 뒤, 설치된 버전을 확인합니다.
•
curl ... | bash: kagent 설치 스크립트를 내려받아 실행합니다.
•
kagent version: kagent CLI가 정상 설치되었는지 버전 정보를 출력해 확인합니다.
curl https://raw.githubusercontent.com/kagent-dev/kagent/refs/heads/main/scripts/get-kagent | bash
kagent version
Bash
복사
Step 3 — kagent 설치 (OpenAI 기준)
OpenAI를 기본 LLM Provider로 사용하도록 환경 변수를 설정한 뒤, 데모 프로필로 kagent를 설치합니다.
•
export OPENAI_API_KEY=...: kagent가 OpenAI API를 호출할 때 사용할 키를 환경 변수로 설정합니다.
•
kagent install --profile demo: kagent 구성 요소와 샘플 에이전트를 포함한 데모 구성을 한 번에 설치합니다.
export OPENAI_API_KEY="your-api-key"
kagent install --profile demo
# 기본 설치의 경우 helm 사용
# - CRD(커스텀 리소스 정의)를 먼저 설치해 kagent의 리소스 타입(예: Agent, Tool 등)을 클러스터에 등록합니다.
helm install kagent-crds oci://ghcr.io/kagent-dev/kagent/helm/kagent-crds \
--namespace kagent \
--create-namespace
# ollama 사용 시
# - 외부 API 대신 로컬 LLM(Ollama)을 기본 Provider로 지정해 설치합니다.
helm install kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \
--namespace kagent \
--set providers.default=ollama
Bash
복사
--profile demo 옵션을 붙이면 샘플 에이전트가 함께 설치됩니다.
Step 4 — 설치 확인 및 대시보드 접속
kagent가 정상적으로 설치되었는지 확인하고, UI 대시보드에 접속합니다.
•
kubectl get pods -n kagent: kagent 네임스페이스에 설치된 Pod들이 Running 상태인지 확인합니다. (문제가 있다면 STATUS, READY, RESTARTS 값을 먼저 확인하세요.)
•
kagent dashboard: 로컬에서 kagent UI 대시보드를 열어 상태를 확인합니다. 기본적으로 브라우저가 열리며, 접속 주소는 http://localhost:8082 입니다.
•
kubectl port-forward -n kagent svc/kagent-ui 8080:8080: kagent dashboard 사용이 어렵거나, Helm으로만 설치한 경우에 UI 서비스 포트를 로컬로 포워딩해서 브라우저로 접속합니다. 이후 http://localhost:8080 으로 접속하면 됩니다.
# - `kubectl get pods -n kagent`: kagent 네임스페이스에 설치된 Pod들이 정상 기동(Running) 상태인지 확인합니다.
kubectl get pods -n kagent
# - `kagent dashboard`: 로컬에서 kagent UI 대시보드를 열어 상태를 확인합니다.
kagent dashboard # http://localhost:8082 자동 오픈
# 혹은 helm 사용 시,
# - `kubectl port-forward ...`: 클러스터 내부의 kagent UI 서비스를 로컬 포트로 포워딩해 브라우저로 접속할 수 있게 합니다.
kubectl port-forward -n kagent svc/kagent-ui 8080:8080
# 실행 예시
dev/k8s-cluster $ kubectl port-forward -n kagent svc/kagent-ui 8080:8080
Forwarding from 127.0.0.1:8080 -> 8080
Forwarding from [::1]:8080 -> 8080
Bash
복사
웹 페이지에 접속한 뒤, 설정을 마치면 아래와 같이 기본 제공되는 에이전트를 확인할 수 있습니다.
AI Agent의 위험성과 로컬 LLM
AI가 클러스터를 직접 조작한다는 건 강력하지만, 동시에 위험합니다.
이제부터의 운영 자동화는 단순한 추천이나 진단 수준을 넘어, 실제로 리소스를 만들고 변경하며 때로는 삭제까지 수행할 수 있습니다. 직접 명령을 수행하는 에이전트는 편의성과 생산성을 크게 높이지만, 한 번의 잘못된 판단이 곧바로 서비스 장애나 보안 사고로 이어질 수 있다는 점에서 더 엄격한 안전장치가 필요합니다.
따라서 kagent를 도입할 때는 어떤 위험이 있는지 먼저 이해하고, 이를 줄이기 위한 운영 원칙과 기술적 선택지(예: 로컬 LLM)를 함께 고려해야 합니다.
위험 요소 | 설명 |
할루시네이션 | 잘못된 판단으로 의도치 않은 리소스 삭제 가능 |
데이터 유출 | 클러스터 내부 정보가 외부 LLM API로 전송될 수 있음 |
과도한 권한 | RBAC 미흡 시 에이전트가 필요 이상의 작업 수행 가능 |
기본 안전 수칙
•
처음엔 읽기 전용 도구만 허용
•
삭제·변경 작업은 사람이 최종 승인하는 구조 유지
•
에이전트 ServiceAccount에 최소 권한 원칙 적용
로컬 LLM으로 데이터 유출 방지 (Ollama)
가장 근본적인 해결책은 외부 API를 쓰지 않는 것입니다. Ollama를 사용하면 모든 처리가 로컬에서 완료됩니다.
brew install ollama
ollama serve
ollama pull llama3.1:8b # 원하는 모델 선택
# kagent 설치 시 Ollama 지정
helm install kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \
--namespace kagent \
--set providers.default=ollama
Bash
복사
사내 AI 연동 방법
사내에서 외부 API 대신 안전하게 LLM을 사용하기 위해 사내 LLM 인프라에 연동하는 방법을 안내합니다. 아래는 사내 LLM 인프라가 준비되어 있는 경우에 kagent에서 해당 LLM 인프라를 사용하는 방법입니다.
# kagent가 사내 LLM Provider를 호출할 때 사용할 인증 정보를 Kubernetes Secret으로 저장합니다.
# (매니페스트에 키를 직접 적지 않고 Secret을 참조하는 방식이라 관리와 회수에 유리합니다.)
kubectl create secret generic kagent-corp-llm \
-n kagent \
--from-literal=PROVIDER_API_KEY="your-api-key-here"
# kagent가 사용할 모델 Provider, 엔드포인트, Secret 참조 정보를 ModelConfig CR로 등록합니다.
# 여기서는 OpenAI 호환 API를 제공하는 사내 엔드포인트(baseUrl)를 지정합니다.
kubectl apply -f - <<EOF
apiVersion: kagent.dev/v1alpha2
kind: ModelConfig
metadata:
name: corp-llm-config
namespace: kagent
spec:
apiKeySecret: kagent-corp-llm
apiKeySecretKey: PROVIDER_API_KEY
provider: OpenAI
model: "" # 적절한 모델 입력
openAI:
# 사내 LLM 엔드포인트
baseUrl: "http://1.1.1.1:1111/v1"
EOF
Plain Text
복사
UI로 사내 LLM 추가하기
•
화면 구성은 버전에 따라 일부 차이가 있을 수 있습니다.
•
실제 운영 환경에서는 조회(읽기 전용) 요청부터 시작하는 것을 권장합니다.
아래 절차는 kagent UI에서 사내 LLM(사내 OpenAI 호환 API 등) 을 새로운 Provider로 등록하고, 기본 모델로 선택하는 흐름을 기준으로 정리했습니다.
1.
kagent UI 접속 후 좌측 메뉴에서 Settings 또는 Models(Provider) 로 이동합니다.
2.
이미 등록된 모델(OpenAI, Ollama 등)이 있다면 목록에서 확인할 수 있습니다.
1.
Add model / Add provider 를 클릭합니다.
2.
Provider 유형은 사내 LLM이 OpenAI 호환 API 인 경우 보통 OpenAI 를 선택합니다.
3.
아래 값을 입력합니다.
•
Base URL: 사내 엔드포인트 (예: http://1.1.1.1:1111/v1)
•
Model: 사내에서 제공하는 모델명 (예: gpt-4o-mini 또는 사내 모델 식별자)
Base URL은 반드시 /v1 까지 포함해 입력하는 것을 권장합니다. (사내 게이트웨이 구현에 따라 다를 수 있습니다.)
사내 LLM이 토큰 인증을 요구한다면, UI에서 아래 중 하나 방식으로 설정합니다.
•
Secret/Existing Secret 선택: 앞에서 만든 Kubernetes Secret(kagent-corp-llm)을 선택
•
직접 입력: 테스트 환경에서만 임시로 입력 (운영에서는 Secret 권장)
UI에서 Secret을 고르는 옵션이 보이지 않는 버전이라면, 위에서 작성한 ModelConfig CR 방식(kubectl apply)으로 등록한 뒤 UI에서 생성된 ModelConfig를 선택하세요.
에이전트 실행 화면에서 조회성 요청으로 먼저 테스트합니다.
•
예: “kagent namespace의 pod 목록만 조회해줘”
•
실패 시 확인 순서
◦
사내 엔드포인트가 kagent Pod에서 라우팅 가능한지(NetworkPolicy, DNS, 프록시)
◦
Base URL 경로(/v1) 및 TLS 설정
◦
API Key 권한 및 Secret 참조 키 이름(PROVIDER_API_KEY) 일치 여부
◦
kagent Controller/Provider 로그
운영 환경에서는 기본 모델을 바꾸기 전에 특정 에이전트(예: observability-agent)만 사내 LLM을 사용하도록 제한해 단계적으로 적용하는 것을 권장합니다.
실제 사용 예시
에이전트 목록 확인
# 현재 클러스터에 등록된 에이전트 목록과 준비 상태(DEPLOYMENT_READY 등)를 확인합니다.
kagent get agent
# 실행 예시
aiml/kagent $ kagent get agent
+----+---------------------------------------+---------------------------+------------------+----------+
| # | NAME | CREATED | DEPLOYMENT_READY | ACCEPTED |
+----+---------------------------------------+---------------------------+------------------+----------+
| 1 | kagent/kgateway-agent | 2026-02-25T15:53:23+09:00 | true | true |
| 2 | kagent/observability-agent | 2026-02-25T15:53:23+09:00 | true | true |
| 3 | kagent/promql-agent | 2026-02-25T15:53:23+09:00 | true | true |
| 4 | kagent/argo-rollouts-conversion-agent | 2026-02-25T15:53:23+09:00 | true | true |
| 5 | kagent/basic-agent | 2026-02-25T16:18:28+09:00 | true | true |
| 6 | kagent/cilium-policy-agent | 2026-02-25T15:53:23+09:00 | true | true |
| 7 | kagent/istio-agent | 2026-02-25T15:53:23+09:00 | true | true |
| 8 | kagent/k8s-agent | 2026-02-25T15:53:23+09:00 | true | true |
| 9 | kagent/cilium-debug-agent | 2026-02-25T15:53:23+09:00 | true | true |
| 10 | kagent/cilium-manager-agent | 2026-02-25T15:53:23+09:00 | true | true |
| 11 | kagent/helm-agent | 2026-02-25T15:53:23+09:00 | true | true |
+----+---------------------------------------+---------------------------+------------------+----------+
# 설명
| helm-agent | Helm 관련 질의응답 |
| observability-agent | 모니터링·로그 분석 |
| istio-agent | Istio 서비스 메시 관리 |
...
Bash
복사
AI에게 클러스터 질문하기
# 지정한 에이전트에게 자연어 작업 지시를 내려 실제 클러스터를 조회하도록 실행합니다.
# - `-t`: 에이전트에게 전달할 작업 요청 문장
# - `--agent`: 사용할 에이전트 이름(예: basic-agent)
kagent invoke -t "kagent namespace에 이상한 pod가 있는 지 확인" --agent basic-agent
Bash
복사
# 실행 예시
kagent namespace의 pod 목록을 확인했습니다. 모든 pod가 Running 상태이고 READY 1/1 상태입니다. '이상한 pod'라는 기준이 명확하지 않지만, 현재 상태를 요약해서 알려드리겠습니다.
## kagent namespace Pod 현황
kagent namespace에서 실행 중인 Pod들을 확인했습니다. 현재 **17개**의 pod가 있으며, **모두 정상적으로 Running 상태**입니다.
### Pod 목록 요약
| Pod 이름| 상태| 실행 시간||---------|------|----------|| argo-rollouts-conversion-agent| ✅ Running| 28m|
| basic-agent| ✅ Running| 6m|
| cilium-debug-agent| ✅ Running| 28m|
| cilium-manager-agent| ✅ Running| 28m|
| cilium-policy-agent| ✅ Running| 28m|
| helm-agent| ✅ Running| 28m|
| istio-agent| ✅ Running| 28m|
| k8s-agent| ✅ Running| 28m|
| kagent-controller| ✅ Running| 31m|
| kagent-grafana-mcp| ✅ Running| 31m|
| kagent-kmcp-controller-manager| ✅ Running| 31m|
| kagent-querydoc| ✅ Running| 31m|
| kagent-tools| ✅ Running| 31m|
| kagent-ui| ✅ Running| 31m|
| kgateway-agent| ✅ Running| 28m|
| observability-agent| ✅ Running| 28m|
| promql-agent| ✅ Running| 28m|
### 이상 유무
현재 **모든 pod가 정상적으로 Running 상태**이고, Restarts도 0회로 충돌이나 재시작 이력이 없습니다. 따라서 '이상한 pod'는 발견되지 않았습니다.
특정 pod에 대해 더 자세한 정보가 필요하시면 말씀해 주세요!
Markdown
복사
Kagent를 사용한 helm application 자동 설치
홈 화면에서 Create를 클릭한 다음 Agent를 선택합니다.
Helm 설치 전용 Agent는 아래와 같이 작성합니다.
다음으로 Helm 설치 권한을 부여하기 위해 Tool 설정에서 설치 관련 기능을 선택합니다.
예시로 echo-server 차트를 설치하도록 요청했습니다.
설치 과정에서 오류가 발생하면, 에이전트는 클러스터 상태와 관련 정보를 참고해 원인을 파악하고, 목표를 달성하기 위해 가능한 Tool을 최대한 활용해 자동으로 재시도합니다.
아래 예시는 대상 네임스페이스가 없어 Helm 차트 설치에 실패했지만, 에이전트가 네임스페이스를 생성한 뒤 설치를 다시 수행해 최종적으로 완료하는 흐름을 보여줍니다.
결과적으로 클러스터에 echo-server가 정상 설치되었습니다.
마치며
kagent는 Kubernetes 환경에서 AI 에이전트를 운영하기 위한 실용적인 오픈소스 도구입니다. 아직 초기 프로젝트이지만, 공개 100일 만에 커뮤니티가 빠르게 성장하고 있다는 점은 충분히 주목할 만합니다.
모든 상황에 적합한 도구는 아닙니다. AI의 판단에 100% 의존할 수는 없으며, 프로덕션 환경에서는 여전히 사람의 검증이 필요합니다. 하지만 반복적인 진단 작업을 줄이거나, 신입 엔지니어의 온보딩을 돕는 용도로는 유용하게 활용될 수 있습니다.
에이전트의 추론 능력이 개선되고, 지원하는 도구가 확대되고, 커뮤니티 경험이 쌓일수록 활용 범위도 자연스럽게 넓어질 것 같습니다. 언젠가는 복잡한 인프라 문제의 자동 해결, 성능 최적화 같은 일들도 에이전트가 자율적으로 처리하는 시대가 올 수 있다는 뜻입니다.
에스코어 기술 블로그에서는 Kubernetes, 클라우드 네이티브 생태계의 최신 오픈소스와 운영 경험을 지속적으로 공유하고 있습니다. 앞으로도 실무에서 검증된 기술들을 소개할 예정입니다. 다음 글도 기대해주세요.
이현승 프로
클라우드와 오픈소스 SW 관련 연구 개발 프로젝트들을 진행해왔고, 지금은 OSS 기술서비스와 아키텍처를 담당하고 있어요