👋 안녕하세요

만약 홈랩 (homelab)을 운영하고 있다면, 이미 윙윙거리며 돌아가고 있는 Kubernetes 클러스터를 보유하고 계실 것입니다. 그렇다면 이미 신뢰하고 있는 동일한 kubectl 및 GitOps 흐름을 사용하여, 여러분의 포드 (pods) 바로 옆에서 에이전트를 실행할 수 있는데 왜 모든 AI 워크로드를 SaaS 대시보드로 보내야 할까요?

그것이 바로 kagent가 우리에게 제공하는 것입니다. kagent는 CNCF 샌드박스 (sandbox) 프로젝트로 (Solo.io에서 시작되었으며, Istio 세계의 인물들이 구축함), AI 에이전트를 일급 Kubernetes 워크로드 (workloads)로 변환합니다. 에이전트, 모델, 그리고 도구들은 모두 kubectl로 적용할 수 있는 커스텀 리소스 (custom resources)가 됩니다.

👉 핵심 아이디어: kagent는 에이전트와 모델 사이에 하나의 깔끔한 추상화 (abstraction)를 배치합니다. 이를 통해 동일한 에이전트를 클라우드의 Claude로 지정하거나 여러분의 자체 클러스터에서 실행 중인 Ollama로 지정할 수 있으며, 단 하나의 필드를 변경함으로써 전환할 수 있습니다.

이 가이드에서는 홈랩 클러스터에서 두 곳 모두에 연결된 작지만 실제적인 추론 스택 (inference stack)을 구축할 것입니다.

🧱 다룰 내용

• ✅ kagent 추론 스택 (inference stack)이 실제로 어떻게 구성되는지
• ✅ Helm을 사용하여 kagent 설치하기
• ✅ 클라우드 추론을 위해 Claude 연결하기 (ModelConfig 리소스)
• ✅ 완전한 로컬, 온프레미스 (on prem) 추론을 위해 클러스터 내부에 Ollama 배포하기
• ✅ 실제 Kubernetes 도구를 사용하여 각 모델을 사용하는 에이전트 구축하기
• ✅ 한 줄의 변경으로 모델 교체하기
• ✅ 에이전트가 잘못된 네임스페이스 (namespace)를 파괴하지 않도록 인간 승인 게이트 (human approval gate) 추가하기

🗺️ 레이어별 추론 스택

YAML을 건드리기 전에, 여기 사고 모델 (mental model)이 있습니다. kagent에서 여러분의 "추론 스택"은 각각이 Kubernetes 리소스 또는 컴포넌트인 몇 개의 레이어로 구성됩니다:

• ✅ 모델 제공자 (Model provider): 토큰이 생성되는 곳입니다. Anthropic API를 통한 Claude 또는 로컬 모델을 서빙하는 Ollama가 해당됩니다.
• ✅ ModelConfig (CRD): kagent에게 어떤 제공자(provider), 어떤 모델, 그리고 어떤 Secret이 키를 보유하고 있는지 알려줍니다.
• ✅ 에이전트 (Agent, CRD): 시스템 프롬프트(system prompt)와 도구 세트(set of tools), 그리고 ModelConfig에 대한 참조로 구성됩니다.
• ✅ MCP 기반 도구 (Tools over MCP): kagent는 에이전트가 호출할 수 있는 Kubernetes 액션들을 도구로 노출하는 도구 서버(tool server)를 함께 제공합니다.
• ✅ 컨트롤러 및 런타임 (Controller and runtime): Go 컨트롤러가 CRD를 감시(watch)하며, 런타임(Agent Development Kit)이 에이전트 루프(agent loop)를 실행합니다.
• ✅ 스토리지 (Storage): 에이전트 상태를 위한 번들형 PostgreSQL 인스턴스가 포함되어 있습니다 (운영 환경에서는 사용자의 자체 인스턴스로 교체하십시오).

좋은 점은 Agent 리소스가 모델이 어디에 위치하는지 신경 쓰지 않는다는 것입니다. 단지 이름으로 ModelConfig를 참조할 뿐입니다. 클라우드든 로컬이든, 에이전트 스펙(spec)은 동일해 보입니다.

🧰 사전 요구 사항

특별한 것은 없으며, 홈랩(homelab)의 기본 사항들입니다:

• ✅ 실행 중인 Kubernetes 클러스터 (k3s, kind, minikube 또는 베어메탈 클러스터 모두 가능)
• ✅ 설치되어 있으며 해당 클러스터를 가리키고 있는 kubectl 및 helm
• ✅ Claude 사용을 위한 Anthropic API 키 (Anthropic 콘솔에서 발급)
• ✅ 로컬 모델을 실행하기 위한 노드의 충분한 CPU 및 RAM (llama3.1과 같은 8B 모델은 몇 개의 코어와 약 8Gi의 메모리로 충분합니다)

버전에 대한 주의 사항: 아래의 모든 내용은 kagent v0.9 (CRD apiVersion kagent.dev/v1alpha2), 최신 Claude 모델 ID claude-haiku-4-5 및 claude-sonnet-4-5, 그리고 Ollama llama3.1 모델을 기준으로 2026년 7월에 검증되었습니다. kagent는 빠르게 업데이트되므로, 필드 구성이 다르게 보인다면 릴리스 노트(release notes)를 확인하십시오.

📦 1단계: kagent 설치

kagent는 두 개의 Helm 차트로 설치됩니다: 하나는 CRD를 위한 것이고, 다른 하나는 컨트롤러 및 관련 구성 요소들을 위한 것입니다. v0.7부터 kmcp 도구 서브 프로젝트가 번들로 포함되어 있어, 내장된 Kubernetes 도구들을 즉시 사용할 수 있습니다.

먼저, CRD를 설치합니다:

helm install kagent-crds oci://ghcr.io/kagent-dev/kagent/helm/kagent-crds \
  --namespace kagent \
  --create-namespace

이제 kagent 자체를 설치합니다. Anthropic을 기본 제공자(provider)로 설정하여, Pod가 뜨는 즉시 Claude 기반의 작동 가능한 모델 설정(model config)을 확보할 것입니다.

export ANTHROPIC_API_KEY="your-anthropic-key-here"

helm install kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \
...

잠시 기다린 후, Pod를 확인하세요:

kubectl get pods -n kagent

컨트롤러(controller), UI, kagent 툴 서버(tool server), 그리고 번들로 포함된 PostgreSQL Pod가 보여야 합니다.

대시보드를 원하시나요? UI를 포트 포워딩(port forward) 하세요:

kubectl port-forward -n kagent svc/kagent-ui 8080:8080

그 다음 http://localhost:8080을 여세요.

Homelab 팁: 기본 설치 시 바로 테스트해 볼 수 있도록 postgres:18 Pod가 번들로 제공됩니다. 실제로 중요한 데이터를 다룬다면, kagent가 사용자의 자체 PostgreSQL을 가리키도록 설정하세요.

☁️ 2단계: 클라우드 추론(inference)을 위한 Claude 연결

설치 시 Anthropic 제공자를 전달했기 때문에, kagent는 이미 우리를 위해 기본 모델 설정(ModelConfig)을 생성했습니다. v0.9에서 이 기본 설정은 claude-haiku-4-5를 사용하며, 이는 빠르고 저렴하여 클러스터에 대한 빠른 질문에 완벽합니다.

생성된 내용을 확인해 봅시다:

kubectl get modelconfigs -n kagent

이제 더 무거운 추론(reasoning) 작업을 위해 더 강력한 모델인 claude-sonnet-4-5를 고정하는 자체 모델 설정(ModelConfig)을 명시적으로 추가해 보겠습니다. 먼저 키를 Secret에 저장합니다 (kagent는 사용자가 제어하는 Secret에서 모델 키를 읽어옵니다):

export ANTHROPIC_API_KEY="your-anthropic-key-here"

kubectl create secret generic kagent-anthropic -n kagent \
...

그 다음 이를 참조하는 모델 설정(ModelConfig)을 생성합니다:

apiVersion: kagent.dev/v1alpha2
kind: ModelConfig
metadata:
...

적용합니다:

kubectl apply -f claude-modelconfig.yaml

이로써 클라우드 추론(cloud inference) 레이어 설정이 완료되었습니다. 이제 클러스터에는 두 개의 모델 설정이 존재합니다: 빠른 기본값인 Haiku 설정과 더 깊은 작업을 위한 Sonnet 설정입니다.

모델 ID에 관한 참고 사항: claude-haiku-4-5 및 claude-sonnet-4-5는 최신 날짜의 스냅샷으로 연결되는 편의용 별칭(aliases)입니다. 재현성(reproducibility)을 위해 완전히 고정된 버전을 사용하려면 claude-haiku-4-5-20251001과 같이 날짜가 포함된 형식을 사용하십시오.

🏠 3단계: 온프레미스 추론(on prem inference)을 위한 Ollama 배포

이제 홈랩(homelab) 사용자들을 위한 즐거운 단계입니다. 모델을 직접 실행하여 토큰이 네트워크 외부로 나가지 않게 합니다.

우리는 Ollama를 일반적인 Deployment로 실행하고, 다운로드된 모델이 재시작 후에도 유지될 수 있도록 PersistentVolumeClaim (PVC)을 부여하며 (모델은 크기가 매우 커서, 스케줄링이 변경될 때마다 다시 다운로드하고 싶지 않을 것입니다), Service를 통해 노출할 것입니다.

네임스페이스(namespace)를 생성합니다:

kubectl create ns ollama

Ollama 스택을 적용합니다:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
...

Pod가 준비될 때까지 기다립니다:

kubectl get pods -n ollama -w

실행이 완료되면 모델을 풀(pull)합니다. 이 부분이 중요합니다: kagent는 도구 호출 (tool calling)을 통해 에이전트를 구동하므로, 반드시 함수 호출 (function calling)을 지원하는 모델을 사용해야 합니다. 일반 llama3는 이를 안정적으로 수행하지 못하지만, llama3.1 및 최신 버전(또는 qwen2.5 이상)은 가능합니다. 우리는 llama3.1을 사용하겠습니다:

kubectl -n ollama exec deploy/ollama -- ollama pull llama3.1

모델이 성공적으로 내려받아졌는지 확인합니다:

kubectl -n ollama exec deploy/ollama -- ollama list

이제 클러스터 내부에서 다음 주소로 로컬 모델에 접속할 수 있습니다:

(Service는 80번 포트에서 리스닝하며 컨테이너의 11434번 포트로 전달하므로, URL에 포트 번호를 입력할 필요가 없습니다.)

🔌 4단계: kagent에 로컬 모델 알려주기

Claude와 동일한 ModelConfig 패턴을 사용하되, Provider를 다르게 설정하고 클러스터 내부의 Ollama Service를 가리키는 host를 지정하기만 하면 됩니다.

한 가지 작은 특이사항이 있습니다: Ollama는 API 키가 필요하지 않지만, ModelConfig 필드는 여전히 Secret 참조를 기대합니다. 따라서 임시 플레이스홀더(placeholder) Secret을 생성합니다 (Ollama는 이 값을 무시합니다):

kubectl create secret generic kagent-ollama -n kagent \
  --from-literal OLLAMA_API_KEY=ollama-placeholder

이제 ModelConfig를 작성합니다:

apiVersion: kagent.dev/v1alpha2
kind: ModelConfig
metadata:
...

이를 적용합니다:

kubectl apply -f ollama-modelconfig.yaml

클라우드와 로컬 설정이 모두 등록되었는지 확인합니다:

kubectl get modelconfigs -n kagent

이제 하이브리드 추론 스택 (hybrid inference stack)을 갖추게 되었습니다. 무거운 작업은 Claude가 담당하고, 개인적이고 오프라인 친화적인 작업은 Ollama가 담당하며, 두 모델 모두 동일한 선언적 (declarative) 방식으로 기술됩니다.

🧠 5단계: 모델을 사용하는 에이전트 구축하기

이 지점에서 추상화 (abstraction)의 이점이 나타납니다. 에이전트 (Agent)는 단순히 시스템 프롬프트 (system prompt), 도구 세트 (set of tools), 그리고 modelConfig 참조로 구성됩니다. kagent는 Kubernetes 작업을 도구로 노출하는 kagent-tool-server라는 내장 도구 서버를 제공하므로, 우리의 에이전트가 실제로 클러스터를 조사할 수 있습니다.

Claude 기반의 클러스터 도우미를 만들어 보겠습니다:

apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
...

이를 적용합니다:

kubectl apply -f agent-claude.yaml

👉 이제 마법 같은 일이 일어납니다. Claude 대신 로컬 모델에서 정확히 동일한 에이전트를 실행하려면, 단 하나의 필드인 modelConfig만 변경하면 됩니다. 여기 온프레미스 (on prem) 버전의 쌍둥이가 있습니다:

apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
...

kubectl apply -f agent-local.yaml

프롬프트는 같고, 도구도 같지만, 두뇌만 다릅니다. 이것이 바로 에이전트 앞에 ModelConfig를 두는 핵심 이유입니다.

💬 6단계: 에이전트와 대화하기

대시보드를 통해 채팅할 수도 있지만, 테스트에는 CLI가 더 빠릅니다. kagent CLI를 설치하세요:

brew install kagent

또는

curl https://raw.githubusercontent.com/kagent-dev/kagent/refs/heads/main/scripts/get-kagent | bash

에이전트 목록을 확인합니다:

kagent get agent

Claude 에이전트에게 질문해 보세요:

kagent invoke -t "What API resources are available in my cluster?" --agent cluster-helper-claude

그 다음 로컬 에이전트에게도 같은 질문을 하고 비교해 보세요:

kagent invoke -t "List the pods in the kagent namespace and tell me if any are unhealthy." --agent cluster-helper-local

로컬 에이전트는 모든 토큰을 사용자의 홈랩 (homelab) 내부에 유지하며, 이는 개인적인 워크로드 (workloads)를 탐색할 때 매우 유용한 기능입니다.

🛡️ 단계 7: 안전 게이트 추가 (강력 권장)

AI 에이전트에게 클러스터 (cluster)에 대한 액세스 권한을 부여하는 것은 에이전트가 지나치게 '도움이 되려고' 결정하기 전까지는 매우 훌륭한 일입니다. kagent에는 내장된 Human in the Loop (HITL) 기능이 있습니다. 특정 도구 (tool)를 승인이 필요한 것으로 표시하면, 에이전트는 해당 도구를 실행하기 전에 사용자의 승인(yes) 또는 거절(no)을 기다리며 일시 중지합니다.

다음은 자유롭게 읽을 수는 있지만, 무언가를 변경하기 전에는 반드시 물어봐야 하는 에이전트의 예시입니다:

apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata
...

kubectl apply -f agent-operator.yaml

이제 읽기 도구 (read tools)는 자유롭게 실행되지만, 에이전트가 무언가를 적용 (apply)하거나 삭제 (delete)하려고 하는 순간 UI에 승인 (Approve) 및 거절 (Reject) 버튼이 나타납니다. 만약 거절하면, 그 이유가 컨텍스트 (context)로서 모델 (model)에 다시 전달됩니다. 단 두 줄의 YAML로 큰 안심을 얻을 수 있습니다.

참고 사항: requireApproval에 나열된 모든 도구는 반드시 toolNames에도 나타나야 하며, kagent는 리소스 (resource)가 생성될 때 이를 검증합니다.

🔁 이 패턴이 홈랩 (homelab)에 좋은 이유

• ✅ 단일 워크플로 (workflow): 에이전트, 모델, 도구가 모두 단순히 kubectl apply로 처리되므로, GitOps 및 PR 리뷰가 클러스터의 나머지 부분과 정확히 동일하게 작동합니다.
• ✅ 종속성 없음 (No lock in): 아무것도 다시 작성할 필요 없이 Claude를 Ollama로 교체하거나, 서로 다른 에이전트를 서로 다른 모델로 라우팅할 수 있습니다.
• ✅ 비용 제어: 일상적인 질문은 로컬 모델 (local model)로 보내고, 어려운 작업에는 클라우드 모델 (cloud model)을 아껴둡니다.
• ✅ 기본 설정된 프라이버시: 민감한 워크로드는 온프레미스 (on-prem) 모델에 유지하여 데이터가 외부로 유출되지 않도록 합니다.
• ✅ 내장된 가드레일 (Guardrails): 블랙박스 (black box) 대신 승인 게이트와 명확한 관찰성 (observability)을 제공합니다.

🚀 다음 단계

여기서부터 계속 탐구해 볼 수 있는 몇 가지 방향입니다:

• ✅ kagent를 외부 PostgreSQL로 지정하고 메모리 (memory) 기능을 활성화하여 에이전트가 세션 간의 컨텍스트 (context)를 기억하도록 하세요.
• ✅ 선언적 명세 (declarative spec)에 runtime: go를 설정하여 더 빠른 에이전트 콜드 스타트 (cold start)를 위해 Go 런타임 (runtime)을 시도해 보세요.
• ✅ kmcp를 사용하여 자체 MCP 도구 (tools)를 추가함으로써 에이전트가 내부 API와 통신할 수 있도록 하세요.
• ✅ Ollama 아래에 GPU 노드 (node)를 배치하고 더 나은 도구 사용 (tool use)을 위해 더 큰 로컬 모델 (local model)로 전환해 보세요.

🦆 보너스: Goose로 모든 것을 제어하기

스택이 구축되면 반드시 kagent UI 안에 머물 필요는 없습니다. Goose는 MCP를 지원하는 로컬 오픈 소스 AI 에이전트 (CLI 및 데스크톱 버전, 현재 Linux Foundation Agentic AI Foundation의 일부)입니다. 이는 Goose가 방금 구축한 시스템에 두 가지 상호 보완적인 방식으로 직접 연결될 수 있음을 의미합니다.

이렇게 생각하면 쉽습니다: Goose에는 두뇌 (모델 제공자, model provider)가 필요하며 도구 (MCP 확장 기능, MCP extensions)를 빌려 쓸 수 있습니다. 여러분의 클러스터 (cluster)가 이 두 가지를 모두 제공할 수 있습니다.

🔑 먼저, Goose에 두뇌를 부여하세요 (배포된 모델들)

공식 설치 페이지 (https://goose-docs.ai/docs/getting-started/installation)에서 Goose를 설치한 다음, 설정 마법사 (config wizard)를 실행하세요:

goose configure

kagent에 제공했던 것과 동일한 Anthropic 키를 사용하여 Claude를 지정하세요. Goose가 API 키를 요청하고 이를 시스템 키링 (system keyring)에 저장할 것입니다:

┌   goose-configure
│
◇  무엇을 설정하시겠습니까?
...

완전히 로컬 상태를 유지하며 3단계에서 배포한 Ollama를 재사용하고 싶으신가요? Goose는 워크스테이션 (workstation)에서 실행되므로, 먼저 클러스터 내부의 Ollama 서비스 (Service)를 포트 포워딩 (port forward) 하세요 (이 서비스는 80번 포트에서 리스닝하며 컨테이너의 11434번 포트를 대상으로 합니다):

kubectl -n ollama port-forward svc/ollama 11434:80