Move directory

2026-03-06 17:08:31 +09:00
parent 4d99258344
commit 21addb6e88
73 changed files with 0 additions and 0 deletions
@@ -0,0 +1,145 @@
+# 전체 아키텍처 개요
+
+## 1. 목적
+
+Helm Chart 신규 버전을 카탈로그에 자동으로 추가하고, 해당 버전으로 배포/업그레이드 시 참고할 주의사항을 문서화한다.
+
+> **카탈로그 역할**: 신규 배포를 위한 Helm 차트 버전 보관소. 운영 클러스터 직접 변경과 무관.
+
+자동화 항목:
+- 신규 버전 차트 pull 및 카탈로그 디렉토리 추가
+- Structured Diff JSON 기반 변경 분석
+- `custom-values.yaml` 수정 필요 여부(Breaking) 판단
+- 업그레이드 주의사항 문서 자동 생성 (`CUSTOM-README.md`에 추가)
+- Git PR 자동 생성
+
+---
+
+## 2. 설계 원칙
+
+| # | 원칙 |
+|---|------|
+| 1 | LLM은 Helm CLI를 직접 구성하거나 실행하지 않는다. helm 실행은 결정론적 Skill이 전담하며, Agent/LLM은 Skill을 언제 호출할지만 결정한다 |
+| 2 | Diff 생성은 100% deterministic 해야 한다 |
+| 3 | LLM 입력은 반드시 Structured JSON 형식이다 |
+| 4 | Breaking Change 판단은 코드 기반 Rule Engine이 먼저 수행한다 |
+| 5 | LLM은 설명 및 Markdown 생성만 담당한다 |
+| 6 | 각 컴포넌트는 Agent Skill로 노출한다 (Agent가 직접 호출) |
+| 7 | 카탈로그 업데이트는 Git PR로 관리한다 (운영 환경 직접 변경 아님) |
+| 8 | 외부 입력(PR comment, webhook 등)은 신뢰 경계 밖으로 취급하며, 프롬프트 주입 방어를 기본 전제로 한다 |
+
+## 2.1 운영 기준 (Non-Functional)
+
+- **성능**: Diff 생성 + 요약 전체 파이프라인 5분 내 완료를 목표로 한다 (대형 차트는 예외).
+- **신뢰성**: 실패 시 재시도 3회, 재시도 후 실패는 알림 전송 + 중단.
+- **검토 정책**: `breaking=true` PR에는 `needs-review` 레이블을 부착한다. 담당자가 `custom-values.yaml` 수정 후 merge 여부를 판단한다. (`breaking=false` PR은 자동 merge 가능)
+
+---
+
+## 3. 전체 시스템 아키텍처
+
+### Step 1: Skills (에이전트 내부에서 호출되는 개별 기능)
+
+```
+[Chart Version Detector]
+      │  chart명, current/new version
+      ▼
+[chart_updater Skill]
+      │  helm pull → manifests/helm/<chart>/<to_version>/ 생성
+      │  CUSTOM-README.md carry-over from previous version
+      ▼
+[helm_diff Skill]
+      │  values/template/CRD 비교
+      ▼
+[Structured Diff JSON]
+      │  { values, templates, crd, dependencies }
+      ▼
+[breaking_change_check Skill]
+      │  custom-values.yaml 기준 판단 (LLM 없음)
+      │  breaking=true: custom-values.yaml 수정 필요
+      │  breaking=false: 수정 불필요 (주의사항만)
+      ▼
+[generate_upgrade_doc Skill]   ← 항상 실행
+      │  breaking=true  → LLM 상세 가이드 (custom-values.yaml 수정 방법 포함)
+      │  breaking=false → 템플릿 기반 간단 요약
+      ▼
+[update_docs_file Skill]
+      │  CUSTOM-README.md에 업그레이드 주의사항 섹션 추가
+      ▼
+[create_pr Skill]
+      │  branch 생성 → PR 생성 (항상)
+      │  breaking=true  → label: needs-review
+      │  breaking=false → label: auto-update
+```
+
+> 각 Skill은 독립적으로 호출 가능. 호출 순서는 Agent(Step 2~3)가 담당.
+
+> `deploy_validate` Skill은 Phase 2에서 구현 예정 (현재 스코프 밖).
+
+### Step 2~3: On-Cluster AI Agent
+
+```
+[OpenClaw / Nanobot on K8s]
+      │
+      ├── Skill: chart_version_detector → 신규 버전 감지
+      ├── Skill: chart_updater          → 신규 버전 차트 pull
+      ├── Skill: helm_diff              → Structured Diff JSON 생성
+      ├── Skill: breaking_check         → custom-values.yaml 수정 필요 여부 판단
+      ├── Skill: generate_doc           → 업그레이드 주의사항 문서 생성 (항상)
+      ├── Skill: update_docs            → CUSTOM-README.md 업데이트
+      ├── Skill: create_pr              → GitHub PR 생성
+      └── Channel: Discord              → 알림 발송 (추후 Slack으로 변경 가능)
+
+트리거: Cron 스케줄 또는 K8s 이벤트
+```
+
+---
+
+## 4. 컴포넌트 책임 분리
+
+| 컴포넌트 | 역할 | 결정성 | LLM 사용 |
+|---------|------|--------|---------|
+| Chart Version Detector | 신규 버전 감지 | ✅ | ❌ |
+| Chart Updater | 신규 버전 차트 pull → 버전 디렉토리 생성 | ✅ | ❌ |
+| Helm Diff Engine | Structured Diff JSON 생성 | ✅ | ❌ |
+| Breaking Change Rule Engine | custom-values.yaml 수정 필요 여부 판단 | ✅ | ❌ |
+| LLM Summarizer | 업그레이드 주의사항 문서 생성 | ❌ | ✅ (breaking=true 시만) |
+| Docs Updater | CUSTOM-README.md 업그레이드 주의사항 섹션 추가 | ✅ | ❌ |
+| Git PR Bot | branch / commit / PR 생성 | ✅ | ❌ |
+
+---
+
+## 5. 기술 스택
+
+| 영역 | 선택 | 비고 |
+|------|------|------|
+| Helm CLI | helm 3.x | pull, template, diff |
+| 버전 감지 | ArtifactHub API / GitHub Release Webhook | |
+| Diff 처리 | Python (deepdiff 또는 직접 구현) | |
+| Rule Engine | Python | 코드 기반, custom-values.yaml 기준 |
+| LLM | Claude (Anthropic) | via Skill or API, breaking=true 시만 호출 |
+| 문서 저장 | `manifests/helm/<chart>/<version>/CUSTOM-README.md` | 업그레이드 주의사항 섹션 추가 |
+| PR 생성 | GitHub API (PyGithub / gh CLI) | |
+| 스케줄링 | Agent 내장 스케줄러 (Cron) | Step 2~3 |
+| On-Cluster Agent | OpenClaw / Nanobot | Step 2~3 |
+| Skill Contract | JSON 스키마 (Skill I/O) | Step 1 계약 (Agent-Skill 인터페이스) |
+
+---
+
+## 6. 데이터 흐름 요약
+
+```
+입력:  chart명 + current_version + new_version (레포 내 디렉토리 기준)
+중간:  Structured Diff JSON (values/templates/crd/breaking) + CUSTOM-README.md (docs_context)
+출력:  CUSTOM-README.md 업그레이드 주의사항 섹션 + GitHub PR
+```
+
+---
+
+## 7. 관련 설계 문서
+
+- [01-helm-diff-engine.md](01-helm-diff-engine.md) — Diff Engine 상세 설계
+- [02-breaking-change-rules.md](02-breaking-change-rules.md) — Rule Engine 판단 로직
+- [03-llm-summarizer.md](03-llm-summarizer.md) — LLM Summarizer + Docs Updater
+- [04-skill-interface.md](04-skill-interface.md) — Skill 인터페이스 정의
+- [05-on-cluster-agent.md](05-on-cluster-agent.md) — On-Cluster Agent 설계 (Step 2~3)