type: Project Overview audience: End User, Developer topics: [introduction, features, installation, documentation] llm_priority: high entry_point: true last_updated: 2025-01-06
SBKube is a CLI tool for automating Kubernetes deployments on k3s clusters. It integrates Helm charts, YAML manifests, and Git repositories into a unified declarative configuration.
SBKube는 YAML, Helm, Git 리소스를 로컬에서 정의하고 k3s 등 Kubernetes 환경에 일관되게 배포할 수 있는 CLI 도구입니다.
Kubernetes deployment automation CLI tool for k3s with Helm, YAML, and Git integration k3s용 헬름+yaml+git 배포 자동화 CLI 도구
pip install sbkube# Unified workflow (recommended)
sbkube apply --app-dir config --namespace production
# Or step-by-step execution
sbkube prepare --app-dir config # Download Helm charts and Git repos
sbkube build --app-dir config # Build custom images (if needed)
sbkube template --app-dir config # Render Kubernetes manifests
sbkube deploy --app-dir config --namespace production # Deploy to clusterCreate a config.yaml file:
namespace: production
apps:
grafana:
type: helm
chart: grafana/grafana
version: 6.50.0
values:
- grafana.yaml
backend:
type: helm
chart: ./charts/backend
depends_on:
- grafanaThen deploy:
sbkube apply --app-dir . --namespace production- PRODUCT.md - 제품 개요 (무엇을, 왜): 문제 정의, 사용자 시나리오, 핵심 기능
- SPEC.md - 기술 명세 (어떻게): 시스템 아키텍처, 워크플로우, API 명세
💡 PRODUCT.md는 "무엇을 만들고 왜 만드는가"를, SPEC.md는 "어떻게 구현하는가"를 설명합니다.
- 📋 Product Definition - 제품 정의 및 해결 과제
- 📖 Feature Specification - 전체 기능 및 사용자 시나리오
- 🗺️ Vision & Roadmap - 장기 비전 및 개발 계획
- 👥 Target Users - 사용자 페르소나 및 여정
- 📖 Getting Started - 설치 및 빠른 시작
- ⚙️ Features - 명령어 및 기능 설명
- 🔧 Configuration - 설정 파일 가이드
- 📖 Examples - 다양한 배포 시나리오
- 🔍 Troubleshooting - 일반적인 문제 및 해결책
- 👨💻 Developer Guide - 개발 환경 설정
- 🤖 AI Agent Guide - AI 에이전트 통합 가이드
- 🏗️ Architecture - 상세 아키텍처 설계 (SPEC.md 기반)
- 📄 API Contract - API 참조 (SPEC.md 기반)
- 🤖 LLM Guide - AI 최적화 참조 (다른 프로젝트에서 SBKube 사용 시)
- 빠른 명령어 참조
- 설정 예제
- 일반 패턴 및 문제 해결
- AI 어시스턴트용 설계 (Claude, ChatGPT 등)
전체 문서 인덱스: docs/INDEX.md
SBKube supports multiple output formats optimized for LLM agents and automation:
# Human-friendly (default)
sbkube apply
# LLM-optimized (80-90% token savings)
sbkube --format llm apply
# Machine-parseable JSON
sbkube --format json apply
# Environment variable support (recommended for LLM agents)
export SBKUBE_OUTPUT_FORMAT=llm
sbkube applySee: LLM-Friendly Output Guide
prepare → build → template → deploy
Or unified execution: sbkube apply (runs all 4 stages automatically)
Stage descriptions:
prepare: Download Helm charts and clone Git repositoriesbuild: Build Docker images (if needed)template: Render Kubernetes manifests from Helm chartsdeploy: Apply manifests to Kubernetes cluster
SBKube supports various deployment sources:
| Type | Description | Example | |------|-------------|---------| | helm | Helm charts (remote/local) |
chart: grafana/grafana | | yaml | Raw YAML manifests | chart: ./manifests/ | | git | Git repositories |
git_url: https://github.com/... | | http | HTTP file downloads | url: https://example.com/manifest.yaml | |
action | Custom actions (apply/delete) | action: apply | | exec | Custom command execution |
exec: ./scripts/deploy.sh |
SBKube uses declarative YAML files for all configurations:
- config.yaml - Application definitions and deployment specs
- sources.yaml - External sources (Helm repos, Git repos)
- values/ - Helm values files directory
Advanced chart customization without forking:
- overrides - Replace files in chart templates
- removes - Remove files from chart templates
Simple Helm Deployment:
namespace: my-namespace
apps:
grafana:
type: helm
chart: grafana/grafana
version: 6.50.0
values:
- grafana.yamlChart Customization:
apps:
cnpg:
type: helm
chart: cloudnative-pg/cloudnative-pg
overrides:
templates/secret.yaml: my-custom-secret.yaml # Replace chart file
removes:
- templates/serviceaccount.yaml # Remove chart fileDependency Management:
apps:
database:
type: helm
chart: cloudnative-pg/cloudnative-pg
backend:
type: helm
chart: ./charts/backend
depends_on:
- database # Deploy backend after databaseMore examples: examples/ directory
SBKube는 배포 상태 관리를 위한 직관적인 명령어를 제공합니다:
# 클러스터 상태 확인
sbkube status
# App-group별 그룹핑
sbkube status --by-group
# 특정 app-group 상세 조회
sbkube status app_000_infra_network
# 의존성 트리 시각화
sbkube status --deps
# Pod 헬스체크 상세 정보
sbkube status --health-check
# 배포 히스토리
sbkube history
# 두 배포 비교
sbkube history --diff dep_123,dep_456
# Helm values 비교
sbkube history --values-diff dep_123,dep_456
# 롤백
sbkube rollback dep_123애플리케이션을 논리적 그룹으로 관리할 수 있습니다:
apps:
- name: app_000_infra_network # 인프라 네트워크 그룹
type: helm
chart: cilium/cilium
- name: app_010_data_postgresql # 데이터 스토리지 그룹
type: helm
chart: cloudnative-pg/cloudnative-pg
deps:
- app_000_infra_network
- name: app_020_app_backend # 애플리케이션 그룹
type: helm
chart: ./charts/backend
deps:
- app_010_data_postgresqlApp-group 네이밍 컨벤션: app_{priority}_{category}_{name}
priority: 000-999 (배포 우선순위)category: infra, data, app 등name: 구체적인 애플리케이션 이름
v1.0.0에서 제거될 예정인 명령어:
# 이전 (deprecated) # 새로운 (권장)
sbkube cluster status → sbkube status
sbkube state list → sbkube history
sbkube state show <id> → sbkube history --show <id>
sbkube state rollback <id> → sbkube rollback <id>자세한 내용은 CHANGELOG.md를 참조하세요.
v0.2.x에서 현재 버전으로 업그레이드하는 경우, 자동 마이그레이션 도구를 사용하세요:
sbkube migrate old-config.yaml -o config.yaml자세한 내용은 CHANGELOG.md 및 Migration Guide를 참조하세요.
- 📋 이슈 트래커
- 📧 문의: [email protected]
MIT License - 자세한 내용은 LICENSE 파일을 참조하세요.
🇰🇷 한국 k3s 환경에 특화된 Kubernetes 배포 자동화 도구