🦀 KubeClaw

🏗️ 아키텍처

┌─────────────────────────────────────────────────┐
│ Kubernetes Cluster │
│ Namespace: kubeclaw │
│ │
│ ┌──────────────┐ ┌──────────────────────┐ │
│ │ Flask App │───▶│ PostgreSQL 16 │ │
│ │ Deployment │ │ (StatefulSet + PVC) │ │
│ │ (2 replicas)│ │ + pgvector │ │
│ └──────┬───────┘ │ + PostGIS │ │
│ │ └──────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ ┌──────────────────────┐ │
│ │ Redis │ │ Backup CronJob │ │
│ │ (캐시/세션) │ │ (pg_dump 매일 02:00) │ │
│ └──────────────┘ └──────────────────────┘ │
└─────────────────────────────────────────────────┘

📦 기술 스택

🗂️ 디렉토리 구조

KubeClaw/
├── README.md
├── pyproject.toml # uv 프로젝트 메타데이터
├── .github/
│ └── copilot-instructions.md # AI 어시스턴트 시스템 프롬프트 (전역 적용)
├── docs/
│ └── implementation_plan.md # 구현 계획서
├── docker/ # 검증된 컨테이너 이미지 정의
│ ├── Dockerfile # 커스텀 PostgreSQL (pgvector + PostGIS)
│ ├── Dockerfile.app # Flask 앱 (multi-stage, uv 빌드)
│ ├── docker-compose.yml # 로컬 개발 환경
│ └── init.sql # DB 스키마 초기화
├── helm/
│ └── kubeclaw/ # 전체 스택 Helm Chart
│ ├── Chart.yaml
│ ├── values.yaml # 설정 중앙화 (이미지, 리소스, 비번 등)
│ └── templates/ # K8s 리소스 템플릿
├── k8s/
│ ├── namespace.yaml # kubeclaw 네임스페이스
│ └── storage-class.yaml # 고성능 StorageClass
└── scripts/
 ├── push-image.sh # 이미지 빌드 → 레지스트리 푸시
 └── deploy.sh # Helm 배포 자동화

🚀 빠른 시작

1. 사전 요구사항

kubectl version --client # >= 1.28
helm version # >= 3.14
uv --version # 최신

2. 커스텀 DB 이미지 빌드 & 푸시

# 레지스트리 설정 후 실행
export REGISTRY=your-repo # 예: docker.io/yourname
bash scripts/push-image.sh

3. 네임스페이스 및 스토리지 설정

kubectl apply -f k8s/namespace.yaml
kubectl apply -f k8s/storage-class.yaml

4. Helm 배포

# values.yaml 에서 이미지/비밀번호 설정 후
bash scripts/deploy.sh
# 또는 직접 실행
helm upgrade --install kubeclaw helm/kubeclaw \
 --namespace kubeclaw \
 --values helm/kubeclaw/values.yaml

5. 상태 확인

kubectl get pods -n kubeclaw
kubectl get pvc -n kubeclaw
kubectl logs -n kubeclaw -l app=kubeclaw-db

⚙️ 주요 설정 (values.yaml)

# 이미지 설정
db:
 image: your-repo/custom-pg
 tag: "16-latest"
app:
 image: your-repo/kubeclaw-app
 tag: "1.0.0"
 replicas: 2
# 리소스 제한 (OOM 방지 필수)
resources:
 db:
 limits:
 cpu: "2"
 memory: "2Gi"
 app:
 limits:
 cpu: "500m"
 memory: "512Mi"
# 영구 저장소
persistence:
 size: "20Gi"
 storageClass: "fast-ssd"

🔒 보안

💾 백업

# 수동 백업 트리거
kubectl create job --from=cronjob/kubeclaw-db-backup manual-backup -n kubeclaw

🗄️ 로컬 개발 (Docker Compose)

cd docker
cp ../.env.example ../.env # 환경변수 설정
docker compose up -d

📚 참고