11. kagent adapter 운영과 경계

다른 이름: kagent adapter · kagent capability · kagent 격리 · kagent 공급망내용 검토: 2026. 08. 21.

결론부터

kagent는 맨 Kubernetes 기준선보다 구성형 runner와 선언 lifecycle의 비용을 실제로 줄일 때만 채택할 가치가 있다

이 장에서 처음 나오는 말3개

capability profileCapability Profile: target이 무엇을 지원하고 무엇을 지원하지 않는지 계약으로 선언한 것이다.
blast radius: 한 구성 요소가 뚫리거나 오작동했을 때 영향이 미치는 범위다.
admission policyAdmission Policy: resource가 cluster에 생성되기 전에 규칙 위반을 걸러 내는 검사다.

8~10장이 kagent의 구조·resource·연결이었다면 이 장은 adapter 구현자의 관점이다. 6장 adapter contract가 정의한 operation을 kagent에서 어떻게 채우고, 채울 수 없는 자리를 어떻게 드러낼 것인가를 정리한다.

공통 객체 매핑

공통 객체	kagent/Kubernetes 표현
`AgentVersion`	immutable image digest 또는 선언형 `Agent.spec` snapshot
`KnowledgeBinding`	versioned retrieval config와 index endpoint reference
`Trigger`	외부 scheduler·event consumer와 A2A invoke 설정
`DeploymentTarget`	cluster, namespace, ServiceAccount, node/security preset
`Deployment`	namespaced `Agent` resource와 생성된 workload
`providerRef`	cluster ID + namespace + Agent name + UID
`ToolBinding`	MCP/ToolServer reference와 tool allowlist
runtime identity	ServiceAccount와 workload credential

Grant와 Publication은 kagent resource에 억지로 넣지 않는다. portal API가 invoke 전 ACL을 검사하고, 외부 route는 승인된 publication만 kagent A2A endpoint로 연결한다.

맨 Kubernetes 기준선

영가설은 제품이 없는 상태가 아니라 KubernetesAdapter가 같은 공통 계약을 직접 구현하는 최소 운영안이다. 그래야 kagent를 썼을 때 무엇이 사라지고 무엇이 새로 생기는지 측정할 수 있다.

공통 계약	맨 Kubernetes 구현	회사가 소유할 부분
코드형 `AgentVersion`	immutable image digest의 Deployment·Service	A2A/HTTP conformance, manifest 생성, health 정규화
구성형 `AgentVersion`	회사 표준 runner image + immutable prompt/model/tool/knowledge config	reasoning loop와 streaming·HITL·session runner
`Trigger.REQUEST`	stable gateway가 Service endpoint 호출	ACL, session binding, streaming proxy
`Trigger.SCHEDULE`	CronJob이 stable invoke API를 호출하거나 승인된 Job 생성	timezone·중복·retry·service principal
`Trigger.EVENT`	queue consumer가 stable invoke API를 호출	schema·deduplication·acknowledgment
`ToolBinding`	runner config + tool gateway·NetworkPolicy	MCP client, allowlist, OBO/action policy
`KnowledgeBinding`	runner retrieval config + versioned index endpoint	ingestion·ACL filter·citation·index lifecycle
`Deployment`	server-side apply한 Deployment·Service·HPA/Job	reconciler, informer, drift·error 번역
session·memory	외부 store와 runner library	ownership, retention, portability

baseline adapter도 6장의 contract test를 모두 통과해야 한다. Kubernetes가 replica와 rollout을 맡아도 구성형 engine, A2A surface, tool event, session store와 사용자용 오류 번역은 제공하지 않는다. 이것이 직접 구축 비용이다.

kagent challenger는 같은 fixture로 다음 차이만 증명한다.

판단 항목	기준선 비용	kagent가 줄여야 할 비용	새로 생기는 비용
구성형 Agent	runner 개발·version 호환·HITL stream	내장 engine과 선언형 spec으로 대체	engine·CRD upgrade와 Postgres 운영
대화 장기 memory	memory store·embedding·prefetch client 구현	built-in PostgreSQL·pgvector memory로 대체	사용자 identity binding·TTL·삭제·portability 제약
model·tool wiring	회사 manifest와 client 구현	ModelConfig·MCP reference 제공	kagent schema와 controller 의존
lifecycle	adapter가 workload 직접 reconcile	Agent condition과 controller 제공	condition 정규화와 controller 장애 대응
코드형 Agent	Deployment·Service 생성	BYO A2A template·일관된 resource 제공	기준선과 기능 격차가 작을 수 있음
suspend·workspace	별도 sandbox control plane	SandboxAgent·AgentHarness 제공	Agent Substrate control/data plane·WorkerPool·snapshot storage

PoC decision record에는 기능 유무가 아니라 개발·운영 시간, upgrade rehearsal, 장애 복구와 실제 사용 Agent 수를 남긴다. 구성형 engine이나 suspend/workspace를 사용하지 않는다면 kagent를 유지할 근거가 약하다. Substrate도 별도 제품 점수로 더하지 않고 기본 Agent 대비 idle 절감·restore 지연·shared worker failure·고정 운영비를 같은 A2A fixture로 측정한다.

Capability profile

8장의 실행 수명주기 표에서 봤듯 kagent가 직접 표현하지 못하는 실행 성격이 있다. 이것을 최소 공통분모로 깎아 없애는 대신 capability로 드러낸다. kagent target이라면 다음처럼 답한다.

capabilities:
  residency: [resident, suspendable] # Agent · SandboxAgent
  ephemeralJob: manual # Job 직접 구성은 kagent 모델 밖
  scheduledInvoke: external # CronJob·Argo가 A2A invoke
  persistentFilesystem: agent-harness
  workloadExtensions:
    sidecarInjection: supported
    longLivedWorker: supported

durable recovery 보장은 이 target profile에 넣지 않는다. 승인 대기가 며칠 걸리거나 중단 지점부터 이어져야 하는 수요가 확인되면 target을 바꾸는 대신 보류한 결정 B를 열고 별도 ExecutionProfile을 조합한다. 이때 target capability는 그 profile에 필요한 sidecar·worker 배치가 가능한지만 답한다.

인증과 인가의 빈칸

kagent v0.9.9 검토 기준으로 oauth2-proxy 기반 OIDC 인증을 지원하지만 공식 release note는 access control이 아직 구현되지 않았다고 명시한다. 로그인한 사용자의 identity를 안다는 것과 Agent별 실행·수정 권한을 판단하는 것은 다르다.

Kubernetes RBAC도 직접적인 답은 아니다. 이것은 creator나 controller가 Kubernetes API의 Agent resource를 만질 권한을 제어한다. 일반 임직원이 chat/API로 Agent를 호출할 entitlement는 portal 또는 gateway가 강제한다.

두 경로를 실제로 어떻게 막는지는 10장 부서별 접근 통제에 있다.

격리와 공급망

namespace 하나를 사용자마다 자동 생성하는 것만으로 격리가 끝나지 않는다. target preset에 다음을 고정한다.

non-root, seccomp, privilege escalation 금지
read-only root filesystem과 제한된 volume
ServiceAccount token 불필요 시 자동 mount 금지
기본 deny NetworkPolicy와 승인된 model·MCP egress
ResourceQuota, LimitRange, PriorityClass
signed image와 admission policy
code 실행 Agent는 SandboxAgent 또는 별도 sandbox class 검증

controller가 모든 namespace를 watch하는 기본값보다 허용 namespace 목록을 명시해 blast radius를 줄인다.

공급망 입구는 image만이 아니다. 9장에서 본 container skill의 OCI·Git 참조, MCP server image, BYO image가 모두 code 실행 경계이므로 같은 검사를 받는다.

Adapter 동작

target capability와 image architecture/A2A contract를 검증한다.
deploymentId label과 deterministic resource name을 만든다.
secret value가 아니라 namespaced reference를 준비한다.
Agent resource를 server-side apply한다.
condition과 실제 Pod·Service health를 함께 읽어 normalized status로 바꾼다.
synthetic invoke와 ACL deny test 뒤 portal publication을 연다.
이전 version은 별도 resource로 READY까지 만들고, platform core가 publication pointer를 돌린다.

CR spec을 제자리에서 덮어써 이전 version의 조사 가능성을 없애지 않는다.

5번의 정규화가 특히 중요하다. Agent CR의 condition이 Ready여도 Pod가 재시작을 반복하거나 model endpoint에 닿지 못할 수 있다. adapter는 condition·Pod·Service를 함께 읽어 사용자에게 보여 줄 하나의 상태로 바꾸고, 원인 문자열은 진단용으로 따로 남긴다.

잘 맞는 경우와 불리한 경우

잘 맞는다: 실행과 data가 온프렘에 남아야 하고, Kubernetes 운영 역량·GitOps·policy 기반이 이미 있으며, 로컬 model·MCP에 낮은 지연으로 접근해야 한다.

불리하다: platform team이 controller·Postgres·upgrade·capacity·sandbox를 직접 운영할 여력이 없거나, session별 강한 격리를 빠르게 제공해야 한다. kagent가 Kubernetes 운영 책임을 없애지는 않는다.

비교 상대는 AgentCore만이 아니다. 기준선은 어댑터가 kagent 없이 Deployment·Service를 직접 만드는 맨 Kubernetes다. 특히 코드형(BYO) 위주라면 kagent BYO는 “Deployment 생성 + A2A 계약 기대”에 가까워 기준선과의 격차가 얇다. kagent를 정당화하는 것은 구성형 Agent를 runner 개발 없이 실행해 주는 engine과 선언형 lifecycle이고, 이 가치가 실제로 쓰이는지는 18장의 PoC에서 판정한다.

11장 요약

Grant·Publication은 kagent resource에 넣지 않고 portal이 소유한다.
맨 Kubernetes 기준선은 구성형 runner·A2A·session·reconciler를 회사가 직접 소유하는 실제 구현안이다.
kagent는 같은 contract test에서 구성형 engine·선언 lifecycle·sandbox의 순가치를 증명해야 한다.
표현하지 못하는 실행 성격은 깎지 말고 capability로 선언한다.
OIDC 인증이 있다는 것과 Agent별 권한 판단은 다른 문제다.
image·skill·MCP server가 모두 공급망 입구이므로 같은 검사를 받는다.
condition만으로 성공을 판정하지 않고 Pod·Service health와 함께 정규화한다.

참고 자료

kagent v0.9 release notes — OIDC 인증과 access control 경계
운영 고려사항 — HA, secret, security context
kagent BYO Agent — image와 A2A runtime 계약
kagent 실습 덱 9장 — BYO image를 kind cluster에 올려 보기
kagent 실습 덱 11~13장 — 같은 cluster에서 Substrate를 추가하고 일반 Agent와 비교해 도입 판정하기
Kubernetes Deployments — 기준선 adapter가 직접 만드는 workload lifecycle.
Kubernetes Server-Side Apply — 기준선과 kagent adapter가 공유하는 idempotent apply 기반.

12. 보류한 결정 — durable executiondurable execution 층을 지금 도입하지 않는 이유와 비용, 재개 조건, Temporal·Dapr Agents 비교 기준을 기록한다.