wbsong111
6.2 KiB
6.2 KiB
전체 아키텍처 개요
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=truePR에는needs-review레이블을 부착한다. 담당자가custom-values.yaml수정 후 merge 여부를 판단한다. (breaking=falsePR은 자동 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_validateSkill은 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 — Diff Engine 상세 설계
- 02-breaking-change-rules.md — Rule Engine 판단 로직
- 03-llm-summarizer.md — LLM Summarizer + Docs Updater
- 04-skill-interface.md — Skill 인터페이스 정의
- 05-on-cluster-agent.md — On-Cluster Agent 설계 (Step 2~3)