dip/service-catalog
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
18ca8cd9790f0c7da93a76845580f55575318ebe
service-catalog/CLAUDE.md
T
wbsong111 6290322f1b Add VictoriaMetrics observability stack + sync catalog for monitoring test 
- VM stack 10 charts: victoria-metrics-cluster/auth, victoria-logs-cluster,
  victoria-metrics-agent/alert, opentelemetry-collector, kube-state-metrics,
  prometheus-node-exporter, alertmanager, perses (JWT/OIDC, Infisical-ready)
- ArgoCD ApplicationSet (syncWave) + per-chart dip-values overlays
- doc/victoria-metrics-architecture.md, define-chart-resources updates
- includes pending working-tree changes (mlflow, kubeflow, apisix, CLAUDE.md)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-25 11:10:51 +09:00

148 lines
7.2 KiB
Markdown
Raw Blame History

# DIP Catalog — 하네스 엔지니어링 가이드
## 프로젝트 개요
DIP Catalog는 두 개의 독립 서브시스템으로 구성된다.
| 서브시스템 | 설명 | 경로 |
|-----------|------|------|
| **정적 카탈로그** | 45+ 엔터프라이즈 Helm 차트 버전 보관소 (Kafka, Airflow, MLflow, KServe, OpenMetadata 등) | `manifests/helm/` |
| **자동화 에이전트** | Helm 차트 신규 버전 감지 → Diff 분석 → 문서 생성 → GitHub PR 자동화 | `agent/update_catalog/` |
카탈로그는 운영 클러스터 직접 변경과 무관하다. **모든 변경은 Git PR을 통해서만 이루어진다.**
---
## 디렉토리 구조
```
dip-catalog/
├── manifests/
│ ├── helm/<chart>/<version>/ # Helm 차트 정적 카탈로그 (각 버전 독립 디렉토리)
│ ├── applicationset/ # ArgoCD ApplicationSet 매니페스트
│ └── kustomize/ # Kustomize 오버레이 (Kubeflow, Model Registry)
├── agent/
│ └── update_catalog/
│ ├── skills/ # 자동화 Skills (Python, 각 Skill 독립 실행 가능)
│ ├── scripts/run_flow.sh # 전체 파이프라인 로컬 실행 스크립트
│ └── docs/ # 아키텍처·설계 문서 (한국어)
│ ├── design/ # 컴포넌트별 상세 설계 (00~05)
│ ├── decisions/ # ADR (아키텍처 결정 기록)
│ └── status.md # 구현 현황
└── doc/ # 차트 리소스 프로파일 (CPU/Memory/Storage 정의)
```
---
## 정적 카탈로그 작업
### 차트 디렉토리 구조
각 `manifests/helm/<chart>/<version>/`에 다음 파일이 있어야 한다.
| 파일 | 역할 |
|------|------|
| `Chart.yaml` | Helm 차트 메타데이터 |
| `values.yaml` | 업스트림 기본값 |
| `custom-values.yaml` | PaaSup 전용 오버라이드 (Breaking Change 판단 기준) |
| `CUSTOM-README.md` | 업그레이드 주의사항 (자동 생성 + 수동 추가 가능) |
| `BUILD-README.md` | 업스트림 README (버전 정보 파싱에 사용됨, 변경 금지) |
### 신규 차트 추가
`manifests/helm/<chart>/<version>/` 디렉토리를 생성하고 위 5개 파일을 포함시킨다.
`custom-values.yaml`은 PaaSup 환경에 필요한 오버라이드만 작성한다. 기본값 전체를 복사하지 않는다.
### 리소스 프로파일
차트별 CPU/Memory/Storage 요구사항은 `doc/define-chart-resources.md`에 Small/Medium/Large 티어로 정의되어 있다. 신규 차트 추가 시 이 파일에도 리소스 정의를 추가한다.
---
## 자동화 Skills 작업
### 파이프라인 순서
```
chart_version_detector → chart_updater → helm_diff →
breaking_change_check → generate_upgrade_doc → update_docs_file → create_pr
```
각 Skill은 독립 실행 가능하다. JSON을 stdout으로 출력하며, 다음 Skill의 입력으로 전달된다.
### 로컬 실행
```bash
# 전체 파이프라인 실행 (필수 환경변수 오버라이드)
CATALOG_ROOT=/path/to/dip-catalog CHART=airflow \
bash agent/update_catalog/scripts/run_flow.sh
# 개별 Skill 실행 예시
python3 agent/update_catalog/skills/chart_version_detector/scripts/run.py \
--catalog-root /path/to/dip-catalog --chart airflow
python3 agent/update_catalog/skills/helm_diff/scripts/run.py \
--chart airflow --repo bitnami \
--chart-path /path/to/dip-catalog/manifests/helm/airflow/1.15.0 \
--from-version 1.15.0 --to-version 1.16.0
```
### 주요 환경변수
| 변수 | 설명 | 기본값 |
|------|------|--------|
| `CATALOG_ROOT` | dip-catalog 레포 절대 경로 | **하드코딩된 로컬 경로** (반드시 오버라이드) |
| `CHART` | 대상 차트명 | `airflow` |
| `USE_CLAUDE_CLI=1` | LLM 호출 활성화 (breaking=true 시 상세 가이드 생성) | 미설정 시 템플릿 기반 생성 |
> `run_flow.sh`의 `CATALOG_ROOT` 기본값은 songwonbin의 로컬 경로로 하드코딩되어 있다. 다른 환경에서 실행할 때 반드시 환경변수로 오버라이드한다.
### Skill 인터페이스 확인
각 Skill의 입출력 스키마는 `agent/update_catalog/skills/<skill>/SKILL.md`에 정의되어 있다.
---
## 설계 원칙
아래 원칙을 위반하는 코드를 제안하거나 작성하지 않는다.
1. **LLM은 Helm CLI를 직접 실행하지 않는다.** helm 실행은 결정론적 Skill(Python)이 전담한다.
2. **Diff 생성은 100% deterministic이다.** Structured Diff JSON 형식을 사용하며 LLM이 직접 diff를 생성하지 않는다.
3. **LLM 입력은 반드시 Structured JSON이다.** 자유 텍스트나 raw helm output을 LLM에 직접 전달하지 않는다.
4. **Breaking Change 판단은 Rule Engine이 먼저 수행한다.** `custom-values.yaml`의 실제 사용 키 기준으로 코드가 판단하며 LLM은 후순위다.
5. **LLM은 Markdown 설명 생성만 담당한다.** `breaking=true` 시에만 호출되며, `breaking=false`이면 템플릿 기반으로 생성한다.
6. **운영 환경은 Git PR로만 변경한다.** 클러스터 직접 변경이나 kubectl apply를 자동화 흐름에 포함하지 않는다.
7. **보안 경계**: 외부 입력(PR comment, webhook 등)은 신뢰 경계 밖으로 취급한다. 프롬프트 주입 방어를 기본 전제로 한다.
---
## 현재 구현 상태
| Step | 내용 | 상태 |
|------|------|------|
| **Step 1** | Skills 구현 (로컬 실행) | ✅ 거의 완료 |
| **Step 2** | Agent 프레임워크 POC (OpenClaw vs Nanobot) | 📋 계획 |
| **Step 3** | On-Cluster Agent 워크플로 정의 | 💡 구상 |
| **Step 4** | 보안 정책 수립 후 운영 | 💡 구상 |
**Step 1 세부 현황:**
- `chart_version_detector`, `chart_updater`, `helm_diff`, `breaking_change_check`, `generate_upgrade_doc`, `update_docs_file`: ✅ 구현 완료
- `create_pr`: ✅ 구현 (실제 GitHub 연동 테스트 미완료)
- `deploy_validate`: ❌ Phase 2 예정
---
## 주요 설계 문서
| 문서 | 설명 |
|------|------|
| [agent/update_catalog/docs/design/00-architecture-overview.md](agent/update_catalog/docs/design/00-architecture-overview.md) | 전체 아키텍처 + 설계 원칙 + 기술 스택 |
| [agent/update_catalog/docs/design/01-helm-diff-engine.md](agent/update_catalog/docs/design/01-helm-diff-engine.md) | Helm Diff Engine 상세 설계 |
| [agent/update_catalog/docs/design/02-breaking-change-rules.md](agent/update_catalog/docs/design/02-breaking-change-rules.md) | Breaking Change Rule Engine 판단 로직 |
| [agent/update_catalog/docs/design/03-llm-summarizer.md](agent/update_catalog/docs/design/03-llm-summarizer.md) | LLM Summarizer + Prompt 설계 |
| [agent/update_catalog/docs/design/04-skill-interface.md](agent/update_catalog/docs/design/04-skill-interface.md) | Skill 인터페이스 계약 (Agent-Skill) |
| [agent/update_catalog/docs/design/05-on-cluster-agent.md](agent/update_catalog/docs/design/05-on-cluster-agent.md) | On-Cluster Agent 설계 (Step 2~3) |
| [agent/update_catalog/docs/decisions/001-agentic-first.md](agent/update_catalog/docs/decisions/001-agentic-first.md) | 파이프라인 오케스트레이션 건너뛰기 결정 배경 |
| [agent/update_catalog/docs/status.md](agent/update_catalog/docs/status.md) | 구현 현황 상세 |
Reference in New Issue View Git Blame Copy Permalink