kubernetes-sigs/agent-sandbox

Website · Docs · DeepWiki · Getting Started · Examples · Roadmap

agent-sandbox는 격리된 상태 유지형 싱글톤 워크로드 (stateful, singleton workloads)의 쉬운 관리를 가능하게 하며, AI 에이전트 런타임 (AI agent runtimes)과 같은 유스케이스에 이상적입니다.

이 프로젝트는 SIG Apps의 산하에서 Kubernetes를 위한 Sandbox 커스텀 리소스 정의 (Custom Resource Definition, CRD) 및 컨트롤러 (controller)를 개발하고 있습니다. 목표는 Kubernetes 프리미티브 (primitives)를 기반으로 구축된 경량 싱글 컨테이너 VM 경험과 매우 유사하게, 안정적인 식별자를 가진 장기 실행 상태 유지형 싱글톤 컨테이너의 특성이 필요한 워크로드를 관리하기 위한 선언적이고 표준화된 API를 제공하는 것입니다.

Sandbox CRD는 agent-sandbox의 핵심입니다. 이는 안정적인 식별자와 영구 저장소 (persistent storage)를 가진 단일 상태 유지형 포드 (stateful pod)를 관리하기 위한 선언적 API를 제공합니다. 이는 Deployment의 무상태 복제 모델 (stateless, replicated model)이나 StatefulSet의 번호가 매겨진 안정적 모델 (numbered, stable model)에 잘 맞지 않는 워크로드에 유용합니다.

Sandbox CRD의 주요 기능은 다음과 같습니다:

안정적인 식별자 (Stable Identity): 각 Sandbox는 안정적인 호스트 이름 (hostname)과 네트워크 식별자를 가집니다.
영구 저장소 (Persistent Storage): Sandbox는 재시작 후에도 유지되는 영구 저장소로 구성할 수 있습니다.
생명주기 관리 (Lifecycle Management): Sandbox 컨트롤러는 생성, 예정된 삭제, 일시 중지 및 재개를 포함한 포드의 생명주기를 관리합니다.

extensions 모듈은 핵심 Sandbox API를 기반으로 더 고급 기능을 제공하는 추가적인 CRD 및 컨트롤러를 제공합니다.

SandboxTemplate: Sandbox를 생성하기 위한 재사용 가능한 템플릿을 정의하는 방법을 제공하여, 다수의 유사한 Sandbox를 더 쉽게 관리할 수 있게 합니다.
SandboxClaim: 사용자가 템플릿으로부터 Sandbox를 생성할 수 있게 하며, 하위 Sandbox 구성의 세부 사항을 추상화합니다.
SandboxWarmPool: 사용자에게 빠르게 할당될 수 있는 사전 준비된 (pre-warmed) Sandbox 풀을 관리하여, 새로운 Sandbox가 가동될 때까지 걸리는 시간을 단축합니다.

agent-sandbox는 Kubernetes 컨트롤러 패턴 (controller pattern)을 따릅니다. 사용자가 Sandbox 커스텀 리소스 (custom resource)를 생성하면, 컨트롤러가 하위의 런타임 리소스 (runtime resources)를 관리합니다.

flowchart LR
User[User]
Claim[SandboxClaim]
...

다음 명령어를 사용하여 agent-sandbox 컨트롤러와 그 CRD (Custom Resource Definitions)를 설치할 수 있습니다.

# "vX.Y.Z"를 https://github.com/kubernetes-sigs/agent-sandbox/releases 에 있는
# 특정 버전 태그(예: "v0.1.0")로 교체하세요.
export VERSION="vX.Y.Z"
...

agent-sandbox와 프로그래밍 방식으로 상호작용하려면 Python SDK를 사용할 수 있습니다. 이 클라이언트 라이브러리는 Sandbox를 생성하고 관리하기 위한 고수준 인터페이스 (high-level interface)를 제공합니다.

상세한 설치 및 사용 방법은 Python SDK README를 참조하십시오.

고급 규모 및 동시성 튜닝 (예: API QPS 및 워커 수)에 대해서는 설정 가이드 (Configuration Guide)를 참조하십시오.

컨트롤러를 설치한 후, 다음 YAML을 클러스터에 적용하여 간단한 Sandbox를 생성할 수 있습니다.

apiVersion: agents.x-k8s.io/v1alpha1
kind: Sandbox
metadata
...

이렇게 하면 사용자가 지정한 이미지를 실행하는 my-sandbox라는 이름의 새로운 Sandbox가 생성됩니다. 그 후 안정적인 호스트 이름(stable hostname)인 my-sandbox를 사용하여 Sandbox에 접속할 수 있습니다.

확장 기능 (extensions) 사용법을 포함한 더 복잡한 예제는 examples/ 및 extensions/examples/ 디렉토리를 참조하십시오.

Kubernetes는 상태가 없는 복제된 애플리케이션 (Deployments)과 안정적이고 번호가 매겨진 상태 저장 Pod 세트 (StatefulSets)를 관리하는 데 탁월합니다. 하지만 다음과 같은 유스케이스 (use cases)를 처리하기 위한 추상화 (abstraction)에 대한 필요성이 커지고 있습니다:

개발 환경 (Development Environments): 개발자를 위한 격리되고, 지속적이며, 네트워크 접속이 가능한 클라우드 환경.

AI 에이전트 런타임 (AI Agent Runtimes): 신뢰할 수 없는 LLM 생성 코드를 실행하기 위한 격리된 환경.

노트북 및 연구 도구 (Notebooks and Research Tools): Jupyter Notebooks와 같은 도구를 위한 지속적인 단일 컨테이너 세션.

상태 저장 단일 Pod 서비스 (Stateful Single-Pod Services): StatefulSet의 오버헤드 없이 안정적인 ID가 필요한 단일 인스턴스 애플리케이션(예: 빌드 에이전트, 소규모 데이터베이스) 호스팅.

StatefulSet (크기 1), Service, 그리고 PersistentVolumeClaim을 조합하여 이를 유사하게 구현할 수는 있지만, 이 방식은 번거롭고 휴면 (hibernation)과 같은 특화된 생명주기 관리 (lifecycle management) 기능이 부족합니다.

우리는 Sandbox가 특정 벤더에 종속되지 않고(vendor-neutral) 다양한 런타임 (runtimes)을 지원하는 것을 목표로 합니다. 주요 특징은 다음과 같습니다:

강력한 격리 (Strong Isolation): gVisor 또는 Kata Containers와 같은 다양한 런타임을 지원하여 커널 및 네트워크 격리를 포함해 Sandbox와 호스트 간의 강화된 보안 및 격리를 제공합니다. 이는 신뢰할 수 없는 코드를 실행하거나 멀티 테넌트 (multi-tenant) 시나리오를 처리하는 데 매우 중요합니다.

심층 휴면 (Deep hibernation): 상태를 지속적 스토리지 (persistent storage)에 저장하고 잠재적으로 Sandbox 객체를 아카이브합니다.

자동 재개 (Automatic resume): 네트워크 연결 시 Sandbox를 재개합니다.

효율적인 지속성 (Efficient persistence): 탄력적이고 신속하게 프로비저닝되는 스토리지.

Sandbox 간 메모리 공유 (Memory sharing across sandboxes): Sandbox들이 기본적으로 비동질적 (non-homogeneous)이더라도 동일한 호스트 상의 Sandbox 간에 메모리를 공유할 수 있는 가능성을 탐색합니다. 이 기능은 특정 런타임의 기능이며, 사용자는 자신의 보안 및 성능 요구 사항에 부합하는 런타임을 선택해야 합니다.

풍부한 ID 및 연결성 (Rich identity & connectivity): 이중 사용자/Sandbox ID 및 Sandbox별 Service 없이도 효율적인 트래픽 라우팅을 탐색합니다.

프로그래밍 가능 (Programmable): 애플리케이션과 에이전트가 Sandbox API를 프로그래밍 방식으로 소비하도록 권장합니다.

현재 로드맵 (Roadmap)은 roadmap.md에서 확인할 수 있습니다.

이 프로젝트는 커뮤니티 주도의 노력이며, 협업을 환영합니다!

PR 속도(Velocity)에 관한 참고 사항: 높은 속도를 유지하고 큐(Queue)를 깨끗하게 관리하기 위해, 이 프로젝트는 stale PR 관리(활동이 없는 PR에 대해 30일 자동 stale 처리 및 15일 자동 close 처리)를 사용하며, 메인테이너(Maintainer)가 승인된 커뮤니티 PR을 패스트트랙(Fast-track)하거나 인수할 수 있도록 허용합니다. 전체 코드 리뷰 및 PR 정책에 대해서는 우리의 기여 가이드라인(Contributing Guidelines)을 읽어주시기 바랍니다.

리뷰 속도를 개선하기 위해, 우리는 현재 자동화된 1차 검토자(First-pass reviewer)로 GitHub Copilot을 시작으로 AI 지원 코드 리뷰(AI-assisted code reviews)를 실험하고 있습니다. 워크플로우는 다음과 같습니다:

• Copilot이 모든 오픈된 PR의 첫 번째 리뷰어로 할당됩니다 (서명된 CLA가 없는 PR은 제외).
• Copilot의 리뷰가 게시된 후, 해당 PR에는 action-required: resolve-copilot-comments 라벨이 붙습니다.

PR에서 Copilot으로부터 코드 제안을 받은 경우, GitHub UI를 통해 제안을 직접 적용하지 마십시오. 그렇게 하면 Copilot이 공동 저자(Co-author)로 설정되어 Kubernetes CLA 요구 사항을 위반하게 됩니다. 자세한 내용은 기여 가이드라인(Contributing Guidelines)을 참조하십시오.

⚠️ 중요한 기여 참고 사항:

• 모든 Copilot 리뷰가 해결(Resolved)로 표시된 후, PR에는 ready-for-review 라벨이 붙습니다.
• 메인테이너는 ready-for-review 상태의 PR을 리뷰하고 최종 승인을 제공합니다.

우리는 이러한 자동화된 리뷰의 품질, 관련성 및 유용성에 대한 여러분의 피드백을 적극적으로 환영합니다! 이 프로세스를 반복하면서, 프로젝트 워크플로우에 가장 적합한 도구를 찾기 위해 다양한 AI 리뷰 도구를 평가하고 테스트할 계획입니다.

커뮤니티 페이지에서 Kubernetes 커뮤니티에 참여하는 방법을 알아보세요.

이 프로젝트의 메인테이너에게는 다음을 통해 연락할 수 있습니다:

• #agent-sandbox Slack 채널
  • Kubernetes Slack에 처음 참여하는 경우, https://slack.k8s.io/ 를 방문하여 초대를 받으세요.
  • 채널에 참여하기 전에 먼저 Kubernetes Slack에 로그인해야 합니다.
• #sig-apps Slack 채널 (일반적인 sig-apps 논의용)
• SIG Apps 메일링 리스트 (Mailing List)

언제든지 이슈(Issue)를 제기하고, 기능을 제안하며, 코드를 기여해 주세요!

Kubernetes 커뮤니티 참여는 Kubernetes 행동 강령(Code of Conduct)의 적용을 받습니다.