dip/service-catalog
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Move directory

Browse Source
This commit is contained in:
wbsong111
2026-03-06 17:08:31 +09:00
parent 4d99258344
commit 21addb6e88
73 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
agent/update_catalog/docs/README.md
+91
View File
@@ -0,0 +1,91 @@
# Helm Chart Upgrade 자동화 시스템
## 개요
Helm Chart 업그레이드 시 기존 버전과 신규 버전 간의 변경점을 **정형 데이터(Structured Diff JSON)**로 생성하고, LLM이 이를 해석하여 변경 요약·Breaking Change 분석·업그레이드 문서를 자동으로 생성하는 시스템이다.
> 핵심 원칙: LLM은 Diff 생성자가 아니라 **Diff 해석자(Summarizer)** 역할만 수행한다.
---
## 로드맵
| Step | 설명 | 상태 |
|------|------|------|
| **Step 1** | Skills 구현 (helm_diff · breaking_check · generate_doc · create_pr · deploy_validate) | 🔨 구현 중 |
| **Step 2** | Agent 프레임워크 POC (OpenClaw vs Nanobot — 클러스터 배포 후 결정) | 📋 계획 |
| **Step 3** | Agent 워크플로 정의 (Skills를 에이전트에 등록 + 스케줄/트리거 설정) | 💡 구상 |
| **Step 4** | 보안 정책 수립 후 운영 (RBAC · NetworkPolicy · Skill allowlist) | 💡 구상 |
> **결정**: 파이프라인 오케스트레이션 코드는 구현하지 않는다.
> Skills(핵심 로직)만 구현하고, 순서 제어는 Agent가 담당한다.
> → [결정 배경](decisions/001-agentic-first.md)
---
## 전체 아키텍처 흐름
```
[Step 1] Skills (독립 실행 가능한 개별 도구)
helm_diff → breaking_change_check → generate_upgrade_doc → update_docs_file → deploy_validate → create_pr
[Step 2~3] On-Cluster Agent (OpenClaw / Nanobot)
Agent가 위 Skills를 등록하여 워크플로로 오케스트레이션
트리거: Cron 스케줄 또는 K8s 이벤트
```
---
## 문서 구조
- [status.md](status.md) — 구현 진행 현황
### 설계 문서 (`design/`)
아키텍처 결정 사항과 컴포넌트 상세 설계를 담는다.
구현과 독립적으로 유지되며, 결정이 바뀔 때만 업데이트한다.
| 파일 | 설명 |
|------|------|
| [00-architecture-overview.md](design/00-architecture-overview.md) | 전체 아키텍처 + 설계 원칙 + 기술 스택 |
| [01-helm-diff-engine.md](design/01-helm-diff-engine.md) | Chart Version Detector · Helm Diff Engine · Values/Template/CRD Diff 설계 |
| [02-breaking-change-rules.md](design/02-breaking-change-rules.md) | Breaking Change Rule Engine 판단 로직 + 조건 정의 |
| [03-llm-summarizer.md](design/03-llm-summarizer.md) | LLM Summarizer · Prompt 설계 · BUILD-README 갱신 설계 |
| [04-skill-interface.md](design/04-skill-interface.md) | Skill 인터페이스 정의 (Agent-Skill 계약) |
| [05-on-cluster-agent.md](design/05-on-cluster-agent.md) | On-Cluster Agent 설계 (Step 2~3) + 보안 고려사항 |
### 구현 계획 (`implementation/`)
각 Step의 작업 목록과 실행 순서를 담는다.
작업이 진행되면서 자주 업데이트되며, 완료 후에는 참고용으로만 유지된다.
| 파일 | 설명 |
|------|------|
| [01-skills.md](implementation/01-skills.md) | Step 1 Skills 구현 태스크 목록 + 우선순위 + 완료 기준 |
| [02-agent.md](implementation/02-agent.md) | Step 2~4 Agent 구현 계획 (POC → 워크플로 → 보안) |
### 의사결정 기록 (`decisions/`)
중요한 아키텍처 결정 사항과 배경을 ADR(Architecture Decision Record) 형식으로 유지한다.
| 파일 | 설명 |
|------|------|
| [001-agentic-first.md](decisions/001-agentic-first.md) | 파이프라인 오케스트레이션 건너뛰고 Agent 직접 구현 결정 |
---
## 설계 원칙
1. **LLM은 Helm CLI를 직접 실행하지 않는다.**
2. **Diff 생성은 100% deterministic 해야 한다.**
3. **LLM 입력은 반드시 Structured JSON 형식이다.**
4. **Breaking Change 판단은 코드 기반 Rule Engine이 먼저 수행한다.**
5. **LLM은 설명 및 Markdown 생성만 담당한다.**
6. **각 컴포넌트는 독립적인 Skill로 노출한다.** (Agent가 호출하는 계약)
7. **운영 환경은 Git PR을 통해서만 변경한다.**
---
## 관련 문서
- [1.구조 설계(structure tool+llm summarizer).md](../1.구조%20설계(structure%20tool+llm%20summarizer).md) — 초기 설계 원본
agent/update_catalog/docs/architecture-local-vs-k8s.md
+87
View File
@@ -0,0 +1,87 @@
# OpenClaw 기반 MCP Tool 아키텍처 (로컬 vs K8s)
아래는 동일한 MCP Tool 세트를 **로컬 환경**과 **K8s 환경**에서 실행할 때의 아키텍처 비교다.
---
## 1) 로컬 환경 아키텍처
```mermaid
flowchart LR
subgraph LocalHost[Local Host]
OC[OpenClaw Agent]
Skills[Skills Registry]
Tools["MCP Tools<br/>(helm_diff, breaking_check,<br/>generate_doc, update_docs, create_pr, deploy_validate)"]
Repo["dip-catalog Repo<br/>(manifests/helm/...)"]
Files["Docs/Outputs
(upgrade.md, PR metadata)]
Secrets[Local Secrets
(.env / keychain)"]
end
OC -->|Skill 호출| Tools
OC --> Skills
Tools --> Repo
Tools --> Files
Tools --> Secrets
OC -->|GitHub API| GH[GitHub]
OC -->|LLM API| LLM[LLM Provider]
```
**특징**
- OpenClaw와 MCP Tools가 같은 머신에서 실행
- `chart_path`는 로컬 디렉토리 기준으로 바로 접근
- Secrets는 로컬 파일/.env/키체인으로 관리
- 배포 검증이 필요하면 로컬 K8s(kind/k3d) 사용
---
## 2) K8s 환경 아키텍처
```mermaid
flowchart LR
subgraph K8s["Kubernetes Cluster"]
OC["OpenClaw Agent Pod"]
Skills["Skills Registry"]
Tools["MCP Tools<br/>(helm_diff, breaking_check,<br/>generate_doc, update_docs, create_pr, deploy_validate)"]
Repo["Git Repo Volume
(dip-catalog)"]
NS[Test Namespace]
end
OC -->|Skill 호출| Tools
OC --> Skills
Tools --> Repo
Tools --> NS
OC -->|GitHub API| GH[GitHub]
OC -->|LLM API| LLM[LLM Provider]
Secrets[Secrets/ConfigMap] --> OC
Secrets --> Tools
NP[NetworkPolicy] --- OC
```
**특징**
- OpenClaw가 Pod로 실행되고 Tools는 같은 Pod 또는 별도 Service로 동작
- repo는 볼륨으로 마운트하거나 git clone으로 동기화
- secrets는 K8s Secret/ConfigMap으로 주입
- deploy_validate는 테스트 네임스페이스에 실제 배포
- NetworkPolicy/RBAC로 최소 권한 운영
---
## 차이 요약
| 구분 | 로컬 환경 | K8s 환경 |
|------|-----------|----------|
| 실행 위치 | 로컬 머신 | K8s Pod/Service |
| repo 접근 | 로컬 파일 시스템 | 볼륨 마운트/클론 |
| secrets | .env/키체인 | Secret/ConfigMap |
| 배포 검증 | kind/k3d | 테스트 네임스페이스 |
| 보안 통제 | OS 권한 | RBAC/NetworkPolicy |
---
필요하면 이 문서를 `design/`에 이동하거나, 시스템 설계 문서에 통합해도 돼.
agent/update_catalog/docs/decisions/001-agentic-first.md
+99
View File
@@ -0,0 +1,99 @@
# ADR 001: 파이프라인 오케스트레이션 건너뛰고 Agent 직접 구현
**상태**: 채택 (2026-03-03)
---
## 배경
초기 설계는 다음 3단계 로드맵이었다:
```
Phase 1: 정적 분석 파이프라인
(MCP Tools + Python 오케스트레이션 코드)
↓
Phase 2A: GitHub Actions로 배포 검증 추가
↓
Phase 2B: On-Cluster AI Agent (OpenClaw/Nanobot)
```
이 구조에서 Phase 1은 두 가지를 포함하고 있었다:
1. **MCP Tools** — `helm_diff`, `breaking_check` 등 핵심 로직
2. **파이프라인 오케스트레이션 코드** — Tools를 순서대로 호출하는 Python 코드
---
## 결정
**파이프라인 오케스트레이션 코드는 구현하지 않는다.**
MCP Tools(핵심 로직)만 구현하고, 순서 제어는 처음부터 Agent(OpenClaw/Nanobot)가 담당하도록 한다.
수정된 로드맵:
```
Step 1: MCP Tools 구현 (오케스트레이션 없이)
↓
Step 2: Agent 프레임워크 POC (OpenClaw vs Nanobot)
↓
Step 3: Agent 워크플로에 MCP Tools를 Skills로 연결
↓
Step 4: 보안 정책 수립 후 운영
```
---
## 이유
### 낭비가 되는 코드
파이프라인 오케스트레이션 코드는 Phase 2B에서 Agent 워크플로 정의로 대체된다.
```python
# 이 코드는 Phase 2B에서 쓸모없어진다
diff = helm_diff(...)
breaking = breaking_check(diff)
doc = generate_doc(diff, breaking)
pr = create_pr(doc)
```
처음부터 Agent를 목표로 한다면 이 코드를 작성하고 나중에 버리는 것은 낭비다.
### MCP Tools는 낭비가 아니다
반면 MCP Tools 자체(helm_diff, breaking_check 등의 구현 로직)는 Agent에서도 그대로 사용된다.
버려지는 코드가 없다.
### K8s 클러스터 보유
Staging K8s 클러스터가 이미 있으므로 On-Cluster Agent를 바로 구성할 수 있다.
"클러스터 없이 로컬 파이프라인으로 먼저 검증"이라는 이유가 성립하지 않는다.
### 테스트 용이성
개별 MCP Tool은 파이프라인 없이도 독립적으로 단위 테스트 가능하다.
---
## 결과
- 구현 시간 단축: 파이프라인 오케스트레이션 코드 작성 + 나중에 Agent로 재작성하는 이중 작업 제거
- Agent 프레임워크 선택이 중요해짐: Step 2 POC로 검증 후 결정 필요
- 중간 산출물 없음: 파이프라인이 없으므로 MCP Tools 완성 전까지는 E2E 동작 확인 불가
→ POC 단계에서 단일 Tool 호출부터 점진적으로 검증
---
## 대안으로 고려했던 것
### 파이프라인 먼저 구현 후 Agent로 전환
- 장점: 중간 단계에서 E2E 동작 확인 가능, 디버깅 용이
- 단점: 파이프라인 오케스트레이션 코드가 버려짐 (낭비), 구현 기간 길어짐
- **기각 이유**: K8s 클러스터가 이미 있어 이 중간 단계가 불필요
### GitHub Actions Phase 2A 추가
- 장점: 배포 검증을 클러스터 없이 CI에서 먼저 구현 가능
- 단점: Agent에서 동일 기능을 다시 구현해야 함 (이중 작업)
- **기각 이유**: `deploy_validate` MCP Tool로 직접 구현, Agent가 조건부 호출
agent/update_catalog/docs/decisions/002-dip-catalog-structure.md
+50
View File
@@ -0,0 +1,50 @@
# ADR 002: dip-catalog 디렉토리 기반 Helm Chart 구조를 기준으로 설계
**상태**: 채택 (2026-03-03)
---
## 배경
대상 카탈로그는 GitHub 레포 내 `manifests/helm/<chart>/<version>/` 구조로 관리된다.
각 버전 디렉토리는 완전한 Helm chart 구조를 포함하며, 추가 문서와 기본 배포 values가 존재한다.
- `README.md`, `BUILD-README.md`, `CUSTOM-README.md` (버전 디렉토리 내)
- `custom-values.yaml` (배포 시 기본 values)
이 구조는 일반 Helm repo/index 기반 감지 방식과 다르므로, 감지/입력/문서 생성 방식을 조정해야 한다.
---
## 결정
1. **버전 감지는 디렉토리 기반**으로 수행한다.
- `manifests/helm/<chart>/` 하위 버전 디렉토리 변화 또는 git diff로 신규 버전 감지
2. **helm_diff 입력에 `chart_path`를 추가**하고 dip-catalog에서는 이를 우선 사용한다.
3. **`custom-values.yaml`을 기본 values_override로 적용**한다.
4. **README/BUILD/CUSTOM 문서를 요약하여 LLM 입력 컨텍스트(`docs_context`)로 제공**한다.
- 단, 컨텍스트는 “참고용”으로만 사용하고 diff에 없는 변경을 생성하지 않는다.
---
## 이유
- 레포 구조가 Helm repo/index.yaml 방식이 아니므로 기존 감지 방법이 부정확하다.
- 동일 chart라도 버전 디렉토리마다 커스텀 문서 및 기본 values가 존재해,
업그레이드 문서 생성에 중요한 맥락이 된다.
---
## 결과
- MCP Tool 인터페이스 및 설계 문서에 `chart_path`, `docs_context` 반영
- LLM Summarizer는 문서 컨텍스트를 참고하되, Structured Diff JSON을 우선한다
---
## 대안으로 고려했던 것
### Helm repo/index 기반 감지 유지
- 장점: 기존 설계 재사용 가능
- 단점: dip-catalog 구조에는 적용 불가
- **기각 이유**: 실제 운영 구조와 불일치
agent/update_catalog/docs/design/00-architecture-overview.md
+145
View File
@@ -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)
agent/update_catalog/docs/design/01-helm-diff-engine.md
+281
View File
@@ -0,0 +1,281 @@
# Helm Diff Engine 설계
## 1. 개요
두 버전의 Helm Chart를 비교하여 **Structured Diff JSON**을 생성하는 컴포넌트.
모든 출력은 deterministic하며 LLM을 사용하지 않는다.
---
## 2. Chart Version Detector
### 역할
새로운 Helm Chart 버전 출시를 감지한다.
### 감지 방법
| 방법 | 설명 | 적합 대상 |
|------|------|---------|
| **Repo 디렉토리 스캔** | `manifests/helm/<chart>/` 하위 버전 디렉토리 변화를 감지 | dip-catalog 구조 |
| Git diff 기반 감지 | 최신 커밋에서 추가된 `<version>/` 디렉토리 파악 | dip-catalog 구조 |
| Helm repo `index.yaml` 주기 스캔 | 등록된 repo의 index 파일 직접 파싱 | 외부/사내 Helm repo |
| ArtifactHub API 조회 | `https://artifacthub.io/api/v1/packages/helm/{org}/{chart}` | 공개 chart |
| GitHub Release Webhook | 차트 소스 저장소의 release 이벤트 구독 | GitHub 기반 차트 |
| Cron 기반 스케줄링 | 위 방법들을 주기적으로 실행 | 공통 |
### 출력
```json
{
"chart": "airflow",
"repo": "apache",
"current_version": "1.2.3",
"latest_version": "1.3.0",
"detected_at": "2025-01-01T00:00:00Z"
}
```
### dip-catalog 차트 업데이트 흐름 (버전 디렉토리 유지)
신규 버전이 감지되면 dip-catalog 구조에 맞춰 **버전 디렉토리를 추가**한다.
기존 버전 디렉토리는 유지한다.
```
1) helm pull <repo>/<chart> --version <new> # 최신 차트 다운로드
2) tar xzf <chart>-<new>.tgz # 압축 해제
3) manifests/helm/<chart>/<new>/ 로 이동 # 버전 디렉토리 생성
4) chart_updater: 이전 버전 디렉토리에서 파일 복사
- custom-values.yaml → 그대로 복사
- CUSTOM-README.md → 그대로 복사 (배포 관련 내용 유지)
- BUILD-README.md → 복사 + 버전 번호 치환 (from_version → to_version)
5) generate_upgrade_doc → CUSTOM-README.md에 업그레이드 주의사항 섹션 추가 (항상 실행)
```
---
## 3. Helm Diff Engine
### 입력
```json
{
"chart": "airflow",
"from_version": "1.2.3",
"to_version": "1.3.0",
"values_override": {},
"chart_path": "manifests/helm/airflow/1.3.0"
}
```
> dip-catalog 구조에서는 `chart_path`를 우선 사용한다.
### 처리 단계
```
1. (repo 구조) helm pull <repo>/<chart> --version <from> → chart_old/
2. (repo 구조) helm pull <repo>/<chart> --version <to> → chart_new/
1'. (dip-catalog) manifests/helm/<chart>/<from>/ 복사 → chart_old/
2'. (dip-catalog) manifests/helm/<chart>/<to>/ 복사 → chart_new/
3. values.yaml 비교 → Values Diff
4. helm template 결과 비교 → Template Diff
5. CRD schema 비교 → CRD Diff
6. Chart.yaml 비교 → Dependency Diff
7. 결과 병합 → Structured Diff JSON
```
### helm template 표준 옵션
재현성을 위해 아래 옵션을 고정한다.
```
helm template <chart> \
--values values_override.yaml \
--include-crds \
--kube-version <target_k8s_version> \
--api-versions <explicit_api_versions>
```
> `target_k8s_version`과 `api-versions`는 환경별 설정값으로 관리한다.
> dip-catalog의 경우 `custom-values.yaml`이 존재하면 `values_override` 기본값으로 적용한다.
### 에러 처리
| 상황 | 대응 |
|------|------|
| helm pull 실패 | 재시도 3회 → 실패 시 알림 후 중단 |
| chart 미존재 | 로그 기록 + 스킵 |
| helm template 렌더링 오류 | 오류 내용 JSON에 포함, partial diff 생성 |
| 네트워크 타임아웃 | 60s timeout 설정, 재시도 |
---
## 4. Values Diff 설계
### 비교 항목
- `added`: 신규 버전에서 추가된 key
- `removed`: 신규 버전에서 삭제된 key
- `changed`: default 값이 변경된 key
- `type_changed`: 값의 타입이 변경된 key (string → int 등)
### 처리 방식
values.yaml을 **flat key** 형태로 변환 후 비교한다.
- dip-catalog에서는 `custom-values.yaml`을 기본 values_override로 사용한다.
```yaml
# 중첩 구조 예시
image:
tag: 1.2.3
pullPolicy: IfNotPresent
# flat key 변환 결과
image.tag: 1.2.3
image.pullPolicy: IfNotPresent
```
> **주의**: key 이동(rename)은 `removed` + `added`로 표현된다. 의미적 rename 감지는 기본 비활성화하며, 필요한 경우 heuristic(유사도 기반) 옵션으로 제공한다.
### 출력
```json
{
"values": {
"added": ["resources.limits.cpu", "resources.limits.memory"],
"removed": ["ingress.enabled"],
"changed": {
"image.tag": { "old": "1.2.3", "new": "1.3.0" },
"replicaCount": { "old": 1, "new": 2 }
},
"type_changed": [
{ "key": "workers.replicas", "old_type": "string", "new_type": "integer" }
]
}
}
```
---
## 5. Template Diff 설계
### 처리 방식
```bash
helm template <chart_old> --values values_override.yaml > old.yaml
helm template <chart_new> --values values_override.yaml > new.yaml
```
YAML을 **리소스 단위**로 분리 후 비교한다 (`kind` + `metadata.name` 기준).
- `generateName`만 존재하는 리소스는 템플릿 파일명 + 순번으로 안정적 ID를 생성한다.
- Cluster-scoped 리소스는 namespace를 무시한다.
### 비교 리소스 타입
| 리소스 | 분석 항목 |
|--------|---------|
| Deployment / StatefulSet | container image, env, resource limits, replicas |
| Service | port, targetPort, type |
| Ingress | rules, TLS, annotations |
| ConfigMap | data key 추가/삭제/변경 |
| CRD | 별도 CRD Diff로 처리 |
| ServiceAccount | annotations |
### 출력
```json
{
"templates": {
"Deployment/airflow-scheduler": {
"image_changed": true,
"image": { "old": "apache/airflow:1.2.3", "new": "apache/airflow:1.3.0" },
"env_added": ["AIRFLOW__CORE__NEW_SETTING"],
"env_removed": [],
"resource_limits_changed": true
},
"Service/airflow-webserver": {
"port_changed": false
}
}
}
```
---
## 6. CRD Diff 설계
### 비교 항목
| 항목 | 설명 |
|------|------|
| schema 변경 | OpenAPI v3 schema 필드 변경 |
| required 필드 추가 | 기존 CR에 영향 |
| field 제거 | 기존 CR의 해당 필드 무시됨 |
| version 변경 | storage version 변경 시 migration 필요 |
| webhook 변경 | conversion webhook 추가/제거 |
### 출력
```json
{
"crd": {
"AirflowCluster": {
"changed": true,
"breaking": true,
"breaking_reasons": ["required field added: spec.executor"],
"schema_changed": true,
"version_changed": false,
"fields_removed": [],
"fields_added": ["spec.executor"],
"required_fields_added": ["spec.executor"]
}
}
}
```
---
## 7. Dependency Diff 설계
Chart.yaml의 `dependencies` 블록 비교.
```json
{
"dependencies": {
"added": ["redis"],
"removed": [],
"version_changed": {
"postgresql": { "old": "12.1.0", "new": "13.0.0" }
}
}
}
```
---
## 8. 최종 Structured Diff JSON
LLM Summarizer에 전달되는 통합 출력:
```json
{
"chart": "airflow",
"from_version": "1.2.3",
"to_version": "1.3.0",
"generated_at": "2025-01-01T00:00:00Z",
"values": { ... },
"templates": { ... },
"crd": { ... },
"dependencies": { ... },
"errors": []
}
```
`errors` 필드에는 렌더링 실패 등의 부분적 오류를 포함한다. LLM은 이를 참고하여 분석 범위를 명시해야 한다.
---
## 9. 관련 문서
- [02-breaking-change-rules.md](02-breaking-change-rules.md) — Breaking Change 판단 로직
- [04-skill-interface.md](04-skill-interface.md) — `helm_diff` Skill 인터페이스
agent/update_catalog/docs/design/02-breaking-change-rules.md
+158
View File
@@ -0,0 +1,158 @@
# Breaking Change Rule Engine 설계
## 1. 개요
Structured Diff JSON을 입력받아 **코드 기반**으로 Breaking Change 여부를 판단한다.
LLM을 사용하지 않으며, 결과는 완전히 deterministic하다.
> **카탈로그 맥락에서의 Breaking 정의**: `custom-values.yaml`을 수정해야 하는 상황.
> 카탈로그는 신규 배포를 위한 차트 보관소이며, 운영 클러스터 직접 변경과 무관하다.
> Breaking 판단의 기준은 "기존 `custom-values.yaml`이 새 차트 버전에서 유효한가?"이다.
> 설계 의도: LLM이 "이건 Breaking인 것 같아"라고 추론하는 대신, 코드가 명확한 기준으로 판단한다.
---
## 2. Breaking Change 판단 기준
### 2.0 공통 원칙
모든 values 관련 규칙에서 **`custom-values.yaml`에 해당 key가 존재하는지 여부**가 breaking 판단의 핵심 조건이다.
- `custom-values.yaml`이 없거나 해당 key를 사용하지 않는 경우 → `warning`으로 처리 (실제 수정 불필요)
- `custom-values.yaml`에 해당 key가 존재하는 경우 → `breaking`으로 처리 (수정 필요)
### 2.1 Values 관련
| 조건 | 판정 | 조건 상세 |
|------|------|---------|
| values key 삭제 | ✅ Breaking | 해당 key가 `custom-values.yaml`에 **있을** 때 — 기존 override가 무시됨 |
| values key 삭제 | ⚠️ Warning | 해당 key가 `custom-values.yaml`에 **없을** 때 (또는 custom-values.yaml 없음) |
| values type 변경 | ✅ Breaking | 해당 key가 `custom-values.yaml`에 **있을** 때 — 파싱 오류 또는 예상치 못한 동작 |
| values type 변경 | ⚠️ Warning | 해당 key가 `custom-values.yaml`에 **없을** 때 |
| values key 추가 | ℹ️ Info | 항상 — 신규 기능, 필요 시 custom-values.yaml에 추가 검토 |
| default 값 변경 | ⚠️ Warning | custom-values.yaml에서 명시적으로 override하지 않는 경우 동작 변경 가능 |
> **`custom-values.yaml` 없는 차트**: 해당 차트에 custom override가 없으므로 values 삭제는 모두 `warning`으로 처리.
### 2.2 Template / 리소스 관련
카탈로그 맥락에서 Template 변경은 `custom-values.yaml` 수정 요인이 아니므로 **Warning**으로 처리한다.
담당자가 신규 배포 시 참고할 수 있도록 업그레이드 주의사항 문서에 기록한다.
| 조건 | 판정 | 이유 |
|------|------|------|
| Service port 변경 | ⚠️ Warning | 카탈로그 신규 배포 시 주의사항. custom-values.yaml에서 port override 가능 |
| Service type 변경 (ClusterIP → NodePort 등) | ⚠️ Warning | 네트워크 구성 변경 필요, 주의사항으로 기록 |
| Deployment selector 변경 | ⚠️ Warning | 재배포 시 주의사항. custom-values.yaml 수정 요인 아님 |
| StatefulSet selector 변경 | ⚠️ Warning | 동일 |
| StatefulSet volumeClaimTemplate 변경 | ⚠️ Warning | 동일 |
| container 이름 변경 | ⚠️ Warning | 참조 변경 필요, 주의사항 기록 |
| 리소스 삭제 | ⚠️ Warning | 의존 서비스 변경 필요, 주의사항 기록 |
| resource limits 변경 | ℹ️ Info | 참고 사항 |
| replicas 기본값 변경 | ℹ️ Info | custom-values.yaml에서 명시적 설정 시 영향 없음 |
### 2.3 CRD 관련
CRD 변경은 기존 Custom Resource의 유효성에 영향을 미치므로 Breaking으로 처리한다.
| 조건 | 판정 | 이유 |
|------|------|------|
| CRD field 삭제 | ✅ Breaking | 기존 CR의 해당 필드 손실 |
| required field 추가 | ✅ Breaking | 기존 CR validation 실패 |
| storage version 변경 | ✅ Breaking | migration 없이 롤백 불가 |
| conversion webhook 제거 | ✅ Breaking | 구버전 API 호출 실패 |
| field 추가 (optional) | ❌ Not Breaking | 하위 호환 |
| schema 제약 완화 | ❌ Not Breaking | 기존 CR은 계속 유효 |
### 2.4 Dependency 관련
서브차트의 values를 `custom-values.yaml`에서 override하는 경우에만 breaking이다.
| 조건 | 판정 | 조건 상세 |
|------|------|---------|
| 하위 chart major version 변경 | ✅ Breaking | `custom-values.yaml`에 해당 subchart prefix key가 **있을** 때 (예: `postgresql.*`) |
| 하위 chart major version 변경 | ⚠️ Warning | `custom-values.yaml`에 해당 subchart 관련 key가 **없을** 때 |
| 하위 chart 제거 | ⚠️ Warning | 항상 — 주의사항으로 기록 |
| 하위 chart 추가 | ℹ️ Info | 항상 — 신규 리소스 생성만 발생 |
### 2.5 Deprecated K8s API 감지
| 조건 | 판정 | 이유 |
|------|------|------|
| Deprecated API 사용 (extensions/v1beta1 등) | ⚠️ Warning | K8s 버전에 따라 영향 있을 수 있음 |
감지 방법: `helm template` 결과의 `apiVersion` 필드를 K8s deprecated API 목록과 대조.
---
## 3. Rule Engine 출력
## 2.6 Rule 우선순위 및 충돌 처리
- 동일 리소스에 여러 Rule이 매칭되면 **가장 높은 severity**를 최종 severity로 채택한다.
- reasons는 모두 남기되, `severity`는 max 기준으로 집계한다.
- `breaking=true`는 `reasons`에 항목이 하나라도 있을 때만 설정된다.
### 3.1 기본 출력
```json
{
"breaking": true,
"severity": "high",
"reasons": [
{
"type": "values_key_removed",
"key": "ingress.enabled",
"detail": "custom-values.yaml에서 사용 중인 key가 삭제됨 — custom-values.yaml 수정 필요"
}
],
"warnings": [
{
"type": "service_port_changed",
"resource": "Service/airflow-webserver",
"detail": "port changed from 8080 to 8081 — 신규 배포 시 참고"
},
{
"type": "values_key_removed",
"key": "old_setting",
"detail": "custom-values.yaml에서 사용하지 않는 key 삭제 — 수정 불필요"
}
]
}
```
### 3.2 severity 정의
| severity | 조건 |
|----------|------|
| `critical` | CRD storage version 변경 |
| `high` | custom-values.yaml에서 사용 중인 values key 삭제/타입 변경, CRD required field 추가 |
| `medium` | custom-values.yaml에서 사용 중인 subchart dependency major version 변경 |
| `warning` | Deprecated API 사용, 미사용 values key 삭제, template 변경 (port, resource 등) |
---
## 4. 확장 방법
새로운 Breaking 조건을 추가하려면 Rule 정의 파일에 항목을 추가한다.
각 Rule은 다음 인터페이스를 구현한다:
```python
class BreakingRule:
name: str
severity: str # critical / high / medium / warning
def check(self, diff: StructuredDiffJSON, custom_keys: set[str]) -> list[BreakingReason]:
...
```
Rule 목록은 설정 파일(`rules.yaml`)로 활성화/비활성화 가능하도록 설계한다.
---
## 5. 관련 문서
- [01-helm-diff-engine.md](01-helm-diff-engine.md) — Structured Diff JSON 생성
- [03-llm-summarizer.md](03-llm-summarizer.md) — Breaking Change 결과를 LLM에 전달
- [04-skill-interface.md](04-skill-interface.md) — `breaking_change_check` Skill 인터페이스
agent/update_catalog/docs/design/03-llm-summarizer.md
+243
View File
@@ -0,0 +1,243 @@
# LLM Summarizer + Docs Updater 설계
## 1. 개요
Structured Diff JSON과 Breaking Change 판단 결과를 입력받아 자연어 업그레이드 주의사항 문서를 생성하고,
해당 차트 버전의 `CUSTOM-README.md`에 반영한다.
> LLM의 유일한 역할: Structured JSON → Markdown 문서 변환. Diff 생성이나 Breaking 판단은 수행하지 않는다.
---
## 2. LLM Summarizer
### 2.0 실행 조건
- `generate_upgrade_doc`은 **항상 실행**한다 (breaking 여부 무관).
- `breaking=true` → LLM을 사용하여 `custom-values.yaml` 수정 방법을 포함한 상세 가이드 생성.
- `breaking=false` → 템플릿 기반 간단 요약 생성 (LLM 미호출).
> 카탈로그는 신규 배포를 위한 차트 보관소이므로, breaking 여부와 무관하게 모든 업그레이드에 주의사항 기록이 필요하다.
### 2.1 입력
```json
{
"chart": "airflow",
"from_version": "1.2.3",
"to_version": "1.3.0",
"values": { ... },
"templates": { ... },
"crd": { ... },
"dependencies": { ... },
"breaking": true,
"severity": "high",
"breaking_reasons": [
{
"type": "values_key_removed",
"key": "ingress.enabled",
"detail": "custom-values.yaml에서 사용 중인 key가 삭제됨 — 수정 필요"
}
],
"warnings": [
{
"type": "service_port_changed",
"resource": "Service/airflow-webserver",
"detail": "port changed from 8080 to 8081"
}
],
"docs_context": {
"CUSTOM-README.md": "..."
}
}
```
> dip-catalog 구조에서는 버전 디렉토리 내 `CUSTOM-README.md` 내용을 `docs_context`로 제공한다.
### 2.2 Prompt 설계
```
당신은 Kubernetes Helm 업그레이드 주의사항 문서를 작성하는 전문가입니다.
두 Helm 차트 버전 간 변경점을 담은 Structured Diff JSON이 제공됩니다.
이 카탈로그는 신규 배포를 위한 것이며, custom-values.yaml 수정 필요 여부가 핵심입니다.
## 작업
1. 핵심 변경 사항을 평문으로 요약합니다.
2. custom-values.yaml 수정이 필요한 항목(breaking_reasons)을 상세히 설명합니다.
3. 신규 배포 시 참고할 주의사항(warnings)을 기록합니다.
4. 아래 형식의 간결한 Markdown 문서를 생성합니다.
## 규칙
- 입력 JSON에 없는 내용은 절대 추가하지 마세요.
- 추측하지 마세요.
- docs_context는 보조 설명에만 사용하고, diff에 없는 변경을 추가하지 마세요.
- errors가 있으면 분석이 불완전할 수 있음을 명시하세요.
- 배포 담당자가 바로 참고할 수 있도록 명확하게 작성하세요.
## 출력 형식
아래 Markdown 구조를 정확히 지키세요 (`## {to_version}` 헤더는 포함하지 마세요 — `update_docs_file`이 관리):
### 변경 요약
- from_version: <from_version>
- to_version: <to_version>
- <핵심 변경 사항 bullet points>
### custom-values.yaml 수정 필요 항목
<breaking=true면 항목별 수정 방법>
<breaking=false면 "없음">
### 배포 시 주의사항
<warnings가 있으면 나열>
<없으면 섹션 생략>
### 참고
- severity: <severity>
- breaking: <true/false>
---
Input:
<Structured Diff JSON>
```
### 2.3 토큰 예산 관리
대형 chart(airflow, kafka 등)는 Structured Diff JSON이 매우 클 수 있다.
| 전략 | 설명 |
|------|------|
| 중요도 기반 필터링 | breaking_reasons와 changed 항목만 포함, unchanged는 제외 |
| template diff 요약 | 리소스별 상세 diff 대신 `변경된 리소스 목록`만 전달 |
| 청크 분할 | values / templates / crd를 각각 별도 LLM 호출 후 결과 합산 |
| 토큰 상한 설정 | 입력 JSON 최대 크기 제한 (예: 50,000 tokens), 초과 시 요약 버전 사용 |
### 2.4 출력 검증
- **금지 규칙**: 입력 JSON에 없는 버전/리소스를 언급하면 실패 처리.
- **서식 검증**: Markdown 구조가 규정과 다르면 1회 재생성, 실패 시 fallback 템플릿으로 대체.
- **요약 품질 기준**: breaking_reasons 누락/허위 서술은 오류로 간주.
### 2.5 예상 출력 (breaking=true)
> `update_docs_file`이 `## {to_version}` 헤더를 추가하므로, LLM 출력은 `###` 수준부터 시작한다.
```markdown
### 변경 요약
- from_version: 1.2.3
- to_version: 1.3.0
- Image tag 1.2.3 → 1.3.0 업데이트
- CPU limit 기본값 추가 (all containers)
- 새 환경변수 `AIRFLOW__CORE__NEW_SETTING` 추가 (scheduler)
### custom-values.yaml 수정 필요 항목
- **`ingress.enabled` 키 삭제**: 차트에서 해당 key가 제거되었습니다.
현재 custom-values.yaml에서 `ingress.enabled: true`로 설정하고 있는 경우,
신규 방식(`ingress.create: true` 등)으로 수정이 필요합니다.
### 배포 시 주의사항
- **Service port 변경**: `airflow-webserver` port 8080 → 8081.
Ingress, load balancer 설정 확인 필요.
### 참고
- severity: high
- breaking: true
```
### 2.6 예상 출력 (breaking=false)
> 템플릿 기반 fallback 출력 (LLM 미호출).
```markdown
### 변경 요약
- from_version: 1.2.3
- to_version: 1.3.0
- Chart airflow 1.2.3 → 1.3.0 업데이트
- Values: +2 추가 / -0 삭제 / ~3 변경
- Templates: +0 추가 / -0 삭제
### custom-values.yaml 수정 필요 항목
없음
### 참고
- severity: warning
- breaking: false
```
---
## 3. Docs Updater 설계
### 3.1 역할
생성한 업그레이드 주의사항 Markdown을 해당 차트 버전의 `CUSTOM-README.md`에 반영한다.
(`CUSTOM-README.md`는 배포에 관한 내용을 포함하는 문서로, 업그레이드 주의사항의 적합한 위치다.)
### 3.2 처리 방식
```
1. diff/breaking 결과로 업그레이드 주의사항 생성 (breaking=true면 LLM, 아니면 템플릿)
2. manifests/helm/<chart>/<to_version>/CUSTOM-README.md에 반영
- "# Upgrade History" 섹션이 없으면 파일 끝에 추가
- 해당 버전 항목이 이미 있으면 skip (idempotent)
3. 파일 저장
```
### 3.3 파일 구조 규칙
- 각 차트 버전 디렉토리의 `CUSTOM-README.md`에 업그레이드 주의사항을 추가한다.
- `CUSTOM-README.md`는 `chart_updater`가 이전 버전에서 carry-over하므로 기존 배포 내용은 유지된다.
- `BUILD-README.md`는 차트 메타 정보(repo, 설치 명령어 등)를 유지한다.
- 별도의 `docs/upgrade.md`는 생성하지 않는다.
### 3.4 중복 방지
이미 해당 버전 업그레이드 섹션이 존재하면 덮어쓰기 또는 스킵한다 (설정으로 제어).
---
## 4. Git PR Bot 설계
### 4.1 자동화 단계
```
1. 새 branch 생성: update-{chart}/{to_version}
2. 카탈로그 신규 버전 디렉토리 커밋 (manifests/helm/<chart>/<to_version>/)
3. CUSTOM-README.md 업그레이드 주의사항 섹션 포함
4. git commit
5. PR 생성
```
### 4.2 PR 메타데이터
**PR 제목**:
```
update {chart}: {from_version} → {to_version}
```
**PR labels**:
- `needs-review` (breaking=true 시) — 담당자 확인 권장
- `auto-update` (breaking=false 시) — 자동 업데이트, 검토 선택적
**PR description**:
```markdown
## Helm Chart Update: {chart} `{from_version}` → `{to_version}`
**Severity**: `high`
**Breaking**: ✅ custom-values.yaml 수정 필요 (담당자 확인 권장)
### Breaking Changes
- `[values_key_removed]` ingress.enabled — custom-values.yaml에서 사용 중인 key 삭제
### Warnings
- `[service_port_changed]` Service/airflow-webserver — port 8080 → 8081
---
*Generated by update-catalog automation*
```
---
## 5. 관련 문서
- [02-breaking-change-rules.md](02-breaking-change-rules.md) — Breaking Change 입력 생성
- [04-skill-interface.md](04-skill-interface.md) — `generate_upgrade_doc`, `create_pr` Skill
agent/update_catalog/docs/design/04-skill-interface.md
+242
View File
@@ -0,0 +1,242 @@
# Skill 인터페이스 정의
## 1. 개요
각 컴포넌트를 **OpenClaw Skill**로 노출한다.
이 인터페이스는 Skills(Step 1)와 On-Cluster Agent(Step 2~3) 간의 **계약(contract)**이다.
> Agent(OpenClaw/Nanobot)가 이 Skill들을 워크플로로 호출한다.
---
## 2. Skill 목록
| Skill 이름 | 역할 | 해당 컴포넌트 |
|-----------|------|-------------|
| `helm_diff` | 두 버전 간 Structured Diff JSON 생성 | Helm Diff Engine |
| `breaking_change_check` | Diff JSON에서 Breaking Change 판단 | Breaking Change Rule Engine |
| `generate_upgrade_doc` | 업그레이드 주의사항 Markdown 문서 생성 (항상 실행) | LLM Summarizer |
| `update_docs_file` | CUSTOM-README.md에 업그레이드 주의사항 섹션 추가 | Docs Updater |
| `create_pr` | GitHub PR 생성 | Git PR Bot |
| `deploy_validate` | test namespace에 배포 후 health 검증 **(Phase 2, 미구현)** | Deploy Validator |
---
## 3. Skill 상세 정의
## 2.1 공통 에러 스키마
모든 Skill은 실패 시 아래 형식으로 에러를 반환한다.
```json
{
"error": {
"code": "ERR_HELM_PULL" ,
"message": "helm pull failed",
"retryable": true,
"details": { "exit_code": 1 }
}
}
```
- `retryable=true`인 경우에만 자동 재시도를 수행한다.
## 2.2 Idempotency / Retry 정책
- **read-only Skill**(helm_diff, breaking_change_check, generate_upgrade_doc)는 안전 재시도 가능.
- **side-effect Skill**(update_docs_file, create_pr, deploy_validate)은 idempotency key를 사용한다.
- `create_pr`는 동일 key 요청 시 기존 PR URL을 반환해야 한다.
## 2.3 Auth/Secret 전달
- 토큰/시크릿은 **env var 또는 K8s Secret**으로 주입한다.
- 입력 payload에 직접 포함하지 않는다.
### 3.1 `helm_diff`
```yaml
name: helm_diff
description: >
두 버전의 Helm Chart를 비교하여 Structured Diff JSON을 생성한다.
values, templates, CRD, dependencies 변경사항을 포함한다.
input:
chart: string # 차트 이름 (예: "airflow")
repo: string # Helm repo 이름 또는 URL (repo 기반일 때만)
chart_path: string # 로컬 차트 경로 (dip-catalog 구조)
from_version: string # 기존 버전 (예: "1.2.3")
to_version: string # 신규 버전 (예: "1.3.0")
values_override: object # 사용자 정의 values (선택, dip-catalog은 custom-values.yaml 기본)
output:
chart: string
from_version: string
to_version: string
generated_at: string # ISO 8601 timestamp
values: object # Values Diff
templates: object # Template Diff
crd: object # CRD Diff
dependencies: object # Dependency Diff
errors: array # 부분 실패 정보
```
### 3.2 `breaking_change_check`
```yaml
name: breaking_change_check
description: >
Structured Diff JSON을 입력받아 Breaking Change 여부를 코드 기반으로 판단한다.
LLM을 사용하지 않으며 결과는 완전히 deterministic하다.
input:
diff_json: object # helm_diff 출력 (Structured Diff JSON)
output:
breaking: boolean
severity: string # critical / high / medium / warning
reasons: array # Breaking 사유 목록
warnings: array # 비중단 경고 목록
```
### 3.3 `generate_upgrade_doc`
```yaml
name: generate_upgrade_doc
description: >
Structured Diff JSON과 Breaking Change 결과를 기반으로 업그레이드 주의사항 Markdown을 생성한다.
항상 실행된다. breaking=true면 LLM 상세 가이드, breaking=false면 템플릿 기반 간단 요약.
input:
diff_json: object # helm_diff 출력
breaking_result: object # breaking_change_check 출력
docs_context: object # CUSTOM-README.md 내용 (dip-catalog)
max_tokens: integer # LLM 입력 최대 토큰 수 (기본: 50000)
output:
markdown: string # 생성된 Markdown 문서
truncated: boolean # 토큰 제한으로 입력이 잘렸는지 여부
```
### 3.4 `update_docs_file`
```yaml
name: update_docs_file
description: >
CUSTOM-README.md에 업그레이드 주의사항 섹션을 추가한다.
CUSTOM-README.md는 배포 관련 정보를 담는 문서로, 업그레이드 주의사항의 적합한 위치다.
BUILD-README.md는 chart_updater의 carry-over로만 관리된다.
input:
repo_path: string # 로컬 Git 저장소 경로
docs_file: string # 문서 파일 경로 (예: "manifests/helm/<chart>/<version>/CUSTOM-README.md")
version: string # 삽입할 버전 표기 (예: "1.2.3 → 1.3.0")
content: string # 삽입할 Markdown 내용
overwrite: boolean # 기존 버전 섹션 덮어쓰기 여부 (기본: false)
output:
success: boolean
file_path: string
already_existed: boolean
```
### 3.5 `create_pr`
```yaml
name: create_pr
description: >
Helm Chart 업그레이드를 위한 GitHub PR을 생성한다.
branch 생성, commit, PR 생성을 포함한다.
input:
chart: string # 차트 이름
from_version: string
to_version: string
repo_path: string # 로컬 Git 저장소 경로
doc_content: string # upgrade.md에 삽입할 내용
breaking: boolean # PR label 결정에 사용
severity: string # PR label 결정에 사용
output:
pr_url: string
branch_name: string
labels: array
```
### 3.6 `deploy_validate` (Phase 2A+)
```yaml
name: deploy_validate
description: >
Ephemeral test namespace에 Helm Chart를 배포하고 health를 검증한다.
성공/실패 결과와 Pod 상태를 반환한다.
input:
chart: string
repo: string
version: string
values_override: object
namespace: string # test namespace (예: "helm-test-airflow")
timeout: integer # 초 단위, 기본 300
output:
success: boolean
dry_run_passed: boolean
pod_status: object # { running: int, pending: int, failed: int }
events: array # 비정상 K8s events
logs: string # 실패 시 관련 Pod 로그
```
---
## 4. Agent 워크플로 호출 순서
Agent(OpenClaw/Nanobot)가 Skill들을 등록하고, 아래 순서를 워크플로로 정의한다.
```yaml
# 개념적 호출 순서 (실제 워크플로 정의는 implementation/02-agent.md 참고)
1. helm_diff(chart, repo, from_version, to_version)
↓
2. breaking_change_check(diff_json, custom_values) # custom-values.yaml 기준 판단
↓
3. generate_upgrade_doc(diff_json, breaking_result) # 항상 실행
│ breaking=true → LLM 상세 가이드 생성
│ breaking=false → 템플릿 기반 간단 요약
↓
4. update_docs_file(
repo_path,
docs_file="manifests/helm/<chart>/<to_version>/CUSTOM-README.md", # to_version으로 경로 결정
version="<from_version> → <to_version>",
content=<markdown>
) # 항상 실행
↓
5. create_pr(chart, from_version, to_version, ...) # 항상 실행
│ breaking=true → label: needs-review
│ breaking=false → label: auto-update
↓ exit 0 (항상)
# Phase 2 (미구현):
6. deploy_validate(chart, repo, to_version, namespace)
```
---
## 5. 버전 관리
이 인터페이스는 **명시적 버전**을 관리한다.
```yaml
skill_interface_version: "1.0"
```
Skill 입출력 변경 시:
- **하위 호환 변경** (필드 추가): 마이너 버전 증가
- **Breaking 변경** (필드 삭제/타입 변경): 메이저 버전 증가 + 마이그레이션 가이드 작성
---
## 6. 관련 문서
- [01-helm-diff-engine.md](01-helm-diff-engine.md) — `helm_diff` 구현 설계
- [02-breaking-change-rules.md](02-breaking-change-rules.md) — `breaking_change_check` 구현 설계
- [03-llm-summarizer.md](03-llm-summarizer.md) — `generate_upgrade_doc`, `create_pr` 구현 설계
- [05-on-cluster-agent.md](05-on-cluster-agent.md) — Agent가 이 인터페이스를 Skills로 사용하는 방법
agent/update_catalog/docs/design/05-on-cluster-agent.md
+189
View File
@@ -0,0 +1,189 @@
# On-Cluster AI Agent 설계 (Step 2~3)
## 1. 개요
Skills(Step 1)를 **클러스터 위에서 상시 동작하는 자율 에이전트**로 오케스트레이션한다.
OpenClaw 또는 Nanobot을 오케스트레이터로 삼아, Step 1에서 구현한 Skill들을 등록하여 Helm 업그레이드 자동화 전체를 수행한다.
> **전제**: Skills(Step 1) 구현 완료 + 인터페이스 버전 `1.0` 확정 이후 진행.
---
## 2. 아키텍처
```
[OpenClaw / Nanobot on K8s]
│
├── Skill: helm_diff → Structured Diff JSON 생성
├── Skill: breaking_check → Breaking Change 판단
├── Skill: generate_doc → 업그레이드 주의사항 문서 생성 (항상 실행)
├── Skill: update_docs → CUSTOM-README.md 업그레이드 주의사항 섹션 추가
├── Skill: create_pr → GitHub PR 생성
# deploy_validate: Phase 2 예정
├── Skill: k8s_event_watch → 클러스터 이벤트 감지
└── Channel: Slack / Telegram → 알림 발송
```
트리거:
- Cron 스케줄 (신규 chart 버전 주기 감지)
- K8s Event Watch (ArgoCD App 상태 변화 등)
---
## 3. OpenClaw vs Nanobot
| 항목 | OpenClaw | Nanobot |
|------|---------|---------|
| 코드 규모 | 430K+ lines | ~4,000 lines |
| 성숙도 | 높음 (100K+ GitHub stars) | 낮음 (신생) |
| Skills 생태계 | 풍부 (ClawHub) | 기본 지원 |
| K8s 배포 | 공식 Helm chart + K8s Operator | 직접 구성 필요 |
| 수평 확장 | 불가 (Recreate 전략) | 미정 |
| LLM 지원 | Claude, OpenAI, 로컬 모델 | Claude, OpenAI, Qwen 등 |
| 커스터마이징 | TypeScript / YAML 워크플로 | 코드 직접 수정 용이 |
| 보안 이슈 | 커뮤니티 이슈 있음 (Cisco, Palo Alto 조사) | 미검증 |
**권장**:
- 운영 안정성 우선 → **OpenClaw** (K8s Operator, 성숙한 생태계)
- 경량 커스터마이징 우선 → **Nanobot** (코드 소규모, 직접 수정)
---
## 4. Skills → Agent 연결 전략
Step 1에서 Skill 인터페이스를 표준으로 구현해두면 Agent 연결이 매끄럽다.
```
Step 1 (Skills) Step 2~3 (Agent)
───────────────────────────── ─────────────────────────────
helm_diff, breaking_check 등 OpenClaw/Nanobot Agent가
Skill로 구현 완료 → 동일한 Skill들을 등록 후
워크플로로 오케스트레이션
```
Agent 연결 시 추가되는 부분:
- 실행 환경: K8s Pod (Agent)
- 오케스트레이션: Agent 워크플로 정의 (Cron 스케줄 + 조건 분기)
- 스케줄링: Agent 내장 스케줄러
변경되지 않는 부분:
- Skill 구현체 (helm_diff, breaking_check 등)
- Structured Diff JSON 포맷
- Breaking Change 규칙
---
## 5. 보안 고려사항
## 4.1 운영 정책
- `breaking=true` PR에는 `needs-review` 레이블을 부착한다. 담당자가 `custom-values.yaml` 수정 후 merge 여부를 판단한다.
- `breaking=false` PR은 `auto-update` 레이블을 부착하며, 자동 merge가 가능하다.
- Agent는 PR 생성까지만 수행한다. merge 책임은 담당자에게 있다.
## 4.2 실패 처리
- Skill 실패 시: 알림 전송 + 자동 중단. 재시도는 최대 3회.
- `deploy_validate`는 Phase 2에서 구현 예정 (현재 스코프 밖).
## 4.3 관찰성
- 모든 Skill 호출은 audit log에 남긴다 (input hash + output status).
- Prometheus metrics: 성공/실패 카운트, 평균 처리 시간, 재시도 횟수.
- LLM 호출은 request_id를 부여하여 추적 가능해야 한다.
On-Cluster AI Agent는 구조적 위험이 있다.
| 위험 | 내용 | 대응 |
|------|------|------|
| 과도한 K8s 권한 | helm upgrade 권한 남용 | RBAC: test namespace만 허용, ServiceAccount 최소 권한 |
| Skill 취약점 | 3rd-party Skill의 26%가 취약 (Cisco 조사) | 허용 Skill allowlist 관리, ClawHub Skill 검토 필수 |
| Prompt Injection | PR comment, webhook 등 외부 콘텐츠로 에이전트 조작 | 입력 sanitization, 신뢰 범위(trust boundary) 명확화 |
| 외부 통신 데이터 유출 | GitHub API, Slack 등 외부 전송 | NetworkPolicy: 허용 egress 목록 명시, 민감 데이터 마스킹 |
| Shell 접근 | RCE 가능성 | shell skill 비활성화, read-only root filesystem, UID 1000 |
> Palo Alto Networks 평가: "Shell 접근 + 개인 데이터 + 외부 통신" = **"lethal trifecta"**
### 최소 보안 요구사항 (운영 투입 전 필수)
```yaml
# RBAC 예시: test namespace만 허용
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
namespace: helm-test
rules:
- apiGroups: ["apps"]
resources: ["deployments", "statefulsets"]
verbs: ["get", "list", "create", "update", "delete"]
- apiGroups: [""]
resources: ["pods", "services", "configmaps"]
verbs: ["get", "list", "create", "update", "delete"]
```
```yaml
# NetworkPolicy: 허용 egress만 통과
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: agent-egress-policy
spec:
podSelector:
matchLabels:
app: helm-upgrade-agent
policyTypes: ["Egress"]
egress:
- to: # GitHub API
- ipBlock:
cidr: 140.82.112.0/20
- to: # Slack API
- ipBlock:
cidr: 35.190.0.0/16
- ports:
- port: 443
```
---
## 6. K8s 배포 구성
```yaml
# OpenClaw Helm values 예시
image:
tag: latest
skills:
allowlist:
- helm_diff
- breaking_change_check
- generate_upgrade_doc
- update_docs_file
- create_pr
# deploy_validate: Phase 2에서 추가 예정
securityContext:
runAsNonRoot: true
runAsUser: 1000
readOnlyRootFilesystem: true
resources:
limits:
memory: "1Gi"
cpu: "500m"
```
---
## 7. 도입 순서 권장
1. Staging 클러스터에서 먼저 검증
2. 보안 정책 확립 (RBAC, NetworkPolicy, Skill allowlist)
3. Skill을 하나씩 추가하며 동작 확인
4. 운영 클러스터 투입 시 `breaking=true` PR은 사람이 직접 머지 승인 유지
---
## 8. 관련 문서
- [04-skill-interface.md](04-skill-interface.md) — Agent가 호출하는 Skill 인터페이스
- [../implementation/02-agent.md](../implementation/02-agent.md) — Agent 구현 계획 (Step 2~4)
agent/update_catalog/docs/implementation/01-skills.md
+157
View File
@@ -0,0 +1,157 @@
# Skills 구현 태스크 (Step 1)
## 목표
Agent(OpenClaw/Nanobot)가 직접 호출할 수 있는 Skill들을 구현한다.
파이프라인 오케스트레이션 코드는 구현하지 않는다. 순서 제어는 Agent가 담당한다.
> **범위**: 각 Skill이 독립적으로 호출 가능한 상태. Skill 간 호출 순서 코드는 제외.
---
## 태스크 목록
### 🔴 높음 (핵심 기능)
#### T1. Helm Diff Engine 구현 (`helm_diff` Skill)
- [ ] **dip-catalog 경로 지원**: `chart_path` 입력으로 `manifests/helm/<chart>/<version>/` 직접 사용
- [ ] 신규 버전 감지 시 `manifests/helm/<chart>/<new>/` 디렉토리 생성 (기존 유지)
- [ ] 최신 차트 pull + 압축 해제 후 신규 버전 디렉토리에 반영
- [ ] (repo 구조) `helm pull`로 두 버전 다운로드
- [ ] (dip-catalog) 로컬 디렉토리 복사로 `chart_old/chart_new` 구성
- [ ] values.yaml flat key 비교 (added / removed / changed / type_changed)
- [ ] **`custom-values.yaml` 기본 적용** (values_override 기본값)
- [ ] `helm template` 렌더링 후 리소스 단위 비교
- [ ] CRD schema 비교 (schema / required / version / webhook)
- [ ] dependency (Chart.yaml) 비교
- [ ] Structured Diff JSON 스키마 확정 및 출력
**완료 기준**: 임의의 두 chart 버전에 대해 Structured Diff JSON이 정상 생성됨
#### T2. Breaking Change Rule Engine 구현 (`breaking_change_check` Skill)
- **Breaking 정의**: `custom-values.yaml`을 수정해야 하는 상황 (카탈로그 맥락)
- [ ] Values key 삭제 감지 — custom-values.yaml에 해당 key 있을 때만 breaking, 없으면 warning
- [ ] Values type 변경 감지 — 동일 기준 (custom-values.yaml에 있을 때만 breaking)
- [ ] Service port / type 변경 감지 — ⚠️ warning (custom-values.yaml 수정 불필요)
- [ ] resource 삭제 감지 — ⚠️ warning (custom-values.yaml 수정 불필요)
- [ ] Dependency major version 변경 — custom-values.yaml에 해당 subchart prefix key 있을 때만 breaking
- [ ] CRD required field 추가 / field 삭제 / storage version 변경 감지
- [ ] severity 분류 (critical / high / medium / warning)
**완료 기준**: custom-values.yaml 기준으로 올바르게 breaking/warning 분류, False Positive 최소화
#### T3. LLM Summarizer 구현 (`generate_upgrade_doc` Skill)
- [ ] Structured Diff JSON + Breaking 결과를 LLM API에 전달
- [ ] **docs_context 반영**: README/BUILD/CUSTOM 요약을 참고 컨텍스트로 포함
- [ ] Prompt 구현 (설계 문서 기반)
- [ ] 토큰 예산 관리 (50,000 token 상한, 초과 시 중요도 기반 필터링)
- [ ] Markdown 출력 검증 (형식 일치 여부)
**완료 기준**: 생성된 Markdown이 설계 문서의 Output Format을 준수하고, 없는 내용을 만들어내지 않음
- breaking=true → LLM 상세 가이드 (USE_CLAUDE_CLI=1 필요)
- breaking=false → 템플릿 기반 간단 요약
- 항상 실행 (breaking 여부와 무관)
#### T3-1. CUSTOM-README.md 업그레이드 주의사항 추가
- [ ] generate_upgrade_doc 결과를 `CUSTOM-README.md`의 `# Upgrade History` 섹션에 추가
- [ ] `update_docs_file` Skill 호출: `docs_file="manifests/helm/<chart>/<to_version>/CUSTOM-README.md"`
#### T4. Skill 인터페이스 구현
- [ ] `helm_diff` Skill 구현 및 노출
- [ ] `breaking_change_check` Skill 구현 및 노출
- [ ] `generate_upgrade_doc` Skill 구현 및 노출
- [ ] `update_docs_file` Skill 구현 및 노출
- [ ] `create_pr` Skill 구현 및 노출
- [ ] `deploy_validate` Skill 구현 및 노출
- [ ] 인터페이스 버전 `1.0` 확정
**완료 기준**: 각 Skill이 독립적으로 호출 가능하고 입출력 스키마가 문서와 일치
---
### 🟡 중간 (안정성)
#### T5. 에러 처리 및 Fallback
- [ ] `helm pull` 실패 시 재시도 (3회) + 알림
- [ ] `helm template` 렌더링 실패 시 partial diff 생성
- [ ] chart 미존재 시 스킵 + 로그
- [ ] 네트워크 타임아웃 (60s) 처리
- [ ] 각 Skill의 오류 시 에러 응답 포맷 일관화
#### T6. Chart Version Detector 구현
- [ ] **dip-catalog 디렉토리 스캔** (`manifests/helm/<chart>/` 하위 버전 변화 감지)
- [ ] **git diff 기반 신규 버전 탐지**
- [ ] ArtifactHub API 연동
- [ ] Helm repo `index.yaml` 스캔
- [ ] GitHub Release Webhook 수신
- [ ] Cron 스케줄 설정
#### T7. Docs Updater 구현 (`update_docs_file` Skill)
- [ ] `CUSTOM-README.md`에 `# Upgrade History` 섹션 추가 (기존 내용 유지)
- [ ] 대상 경로: `manifests/helm/<chart>/<to_version>/CUSTOM-README.md`
- [ ] 중복 버전 처리 (overwrite 옵션)
- [ ] `BUILD-README.md`는 `chart_updater`가 carry-over + 버전 번호 치환으로 관리 (update_docs_file 대상 아님)
#### T8. Git PR Bot 구현 (`create_pr` Skill)
- [ ] branch 생성 (`helm-upgrade/{chart}/{version}`)
- [ ] commit (chart version 업데이트 + docs 수정)
- [ ] PR 생성 (제목, labels, machine-readable metadata 블록 포함)
#### T9. Deploy Validator 구현 (`deploy_validate` Skill)
- [ ] `helm upgrade --dry-run` 실행
- [ ] test namespace에 `helm upgrade` 배포
- [ ] Pod Running + Ready 상태 확인 (타임아웃: 5분)
- [ ] 비정상 K8s events 수집
- [ ] 실패 시 Pod 로그 수집
- [ ] namespace teardown
---
### 🟢 낮음 (개선)
#### T10. 사용자 정의 values 오버라이드 지원
- [ ] `values_override` 파일 경로 또는 inline YAML 지원
- [ ] Diff 생성 시 오버라이드 values 적용
- [ ] **dip-catalog 기본값**: `custom-values.yaml` 존재 시 자동 적용
---
## 구현 진행 현황
- 현황 표는 [docs/status.md](../status.md)에서 관리
---
## 우선순위 요약
```
T4 (Skill 인터페이스 스키마 확정) ← 가장 먼저 (다른 모든 태스크의 계약)
↓
T1 (Helm Diff) + T2 (Rule Engine) ← 병렬 구현 가능
↓
T3 (LLM Summarizer) → T3-1 (CUSTOM-README.md 업그레이드 주의사항 추가)
↓
T7 (Docs Updater) + T8 (PR Bot) + T9 (Deploy Validator) ← 병렬 구현 가능
↓
T5 (에러 처리) + T6 (Version Detector) + T10 (values 오버라이드)
```
---
## 완료 기준 (Step 1 전체)
- [ ] 각 Skill이 독립적으로 호출 가능
- [ ] airflow chart 임의 두 버전에 대해 각 Skill 단독 동작 확인
- [ ] Breaking Change가 있는 버전과 없는 버전 모두 올바르게 처리
- [ ] 생성된 PR에 machine-readable metadata 블록 포함
- [ ] 에러 발생 시 해당 Skill만 실패하고 에러 응답 반환 (전체 중단 없음)
- [ ] Skill 인터페이스 버전 `1.0` 확정
---
## 관련 설계 문서
- [design/01-helm-diff-engine.md](../design/01-helm-diff-engine.md)
- [design/02-breaking-change-rules.md](../design/02-breaking-change-rules.md)
- [design/03-llm-summarizer.md](../design/03-llm-summarizer.md)
- [design/04-skill-interface.md](../design/04-skill-interface.md)
agent/update_catalog/docs/implementation/02-agent.md
+139
View File
@@ -0,0 +1,139 @@
# Agent 구현 태스크 (Step 2~4)
## 전제 조건
- [ ] Step 1 Skills 구현 완료 (인터페이스 버전 `1.0` 확정)
- [ ] Staging K8s 클러스터 접근 가능
---
## Step 2: Agent 프레임워크 POC
**목표**: OpenClaw와 Nanobot 중 하나를 실제 클러스터에서 검증하여 프레임워크를 확정한다.
### POC 범위 (최소)
- [ ] 각 프레임워크를 Staging 클러스터에 배포
- [ ] `helm_diff` Skill 하나를 등록
- [ ] Agent가 Skill을 호출하여 실제 결과 반환 확인
- [ ] 두 프레임워크 비교 후 결정
### 비교 기준
| 항목 | OpenClaw | Nanobot | 결과 |
|------|---------|---------|------|
| K8s 배포 난이도 | 공식 Helm chart | 직접 구성 | - |
| Skill 연결 방식 | - | - | - |
| 로그/디버깅 편의성 | - | - | - |
| 보안 설정 가능 여부 | - | - | - |
> POC 완료 후 이 표를 채운다.
**완료 기준**: 두 프레임워크 중 하나 선택, 선택 이유를 [decisions/](../decisions/) 에 기록
---
## Step 3: Agent 워크플로 정의
**목표**: 선택한 프레임워크에서 모든 Skill을 등록하고 워크플로를 정의한다.
### 태스크
- [ ] 모든 Skill 등록
- `helm_diff`, `breaking_change_check`, `generate_upgrade_doc`
- `update_docs_file`, `create_pr`, `deploy_validate`
- [ ] 워크플로 정의 (Cron 스케줄 기반)
```yaml
workflow: helm-upgrade-automation
schedule: "0 8 * * *"
steps:
- name: detect-versions
skill: chart_version_detector
output: new_versions[] # current_version + latest_version
- name: generate-diffs
skill: helm_diff
for_each: new_versions
output: diff_json[]
# 내부에서 최신 차트 pull + 버전 디렉토리 생성 수행
- name: check-breaking
skill: breaking_change_check
for_each: diff_json
output: breaking_results[]
- name: generate-docs
skill: generate_upgrade_doc
# Skill 내부에서 severity 분기: breaking=true or severity≥high → LLM 심층 요약, 그 외 → 간이 템플릿
for_each: [diff_json, breaking_results]
output: docs[]
- name: update-docs
skill: update_docs_file
for_each: docs
output: updated[]
- name: validate-deployments
skill: deploy_validate
condition: breaking=false and severity<high # breaking=true or severity>=high이면 스킵 → 사람 승인 필요
for_each: updated
output: validation_results[]
- name: create-prs
skill: create_pr
for_each: updated
output: pr_urls[]
- name: notify
channel: slack
message: "Helm upgrade PRs created: {pr_urls}"
```
- [ ] K8s 이벤트 기반 트리거 설정 (선택: ArgoCD App 상태 변화 등)
- [ ] Staging 클러스터에서 E2E 동작 확인
**완료 기준**: Staging에서 airflow chart 신규 버전 감지 → PR 생성까지 E2E 자동 실행
---
## Step 4: 보안 정책 수립 후 운영
**목표**: 운영 클러스터 투입 전 보안 정책을 확립한다.
### 태스크
- [ ] RBAC 설정 (test namespace만 허용)
```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
namespace: helm-test
rules:
- apiGroups: ["apps"]
resources: ["deployments", "statefulsets"]
verbs: ["get", "list", "create", "update", "delete"]
- apiGroups: [""]
resources: ["pods", "services", "configmaps"]
verbs: ["get", "list", "create", "update", "delete"]
```
- [ ] NetworkPolicy 설정 (허용 egress만 통과)
- GitHub API (`api.github.com`)
- LLM API (`api.anthropic.com` 또는 `api.openai.com`)
- Slack API (알림용)
- [ ] Skill allowlist 관리 (shell skill 비활성화 필수)
- [ ] 입력 sanitization (Prompt Injection 방지)
- [ ] `breaking=true` PR은 사람이 직접 머지 승인 유지
**완료 기준**: 보안 체크리스트 전항목 충족, 운영 클러스터 투입
---
## 관련 문서
- [design/05-on-cluster-agent.md](../design/05-on-cluster-agent.md) — Agent 배포 설계 + 보안 고려사항
- [design/04-skill-interface.md](../design/04-skill-interface.md) — Agent가 호출할 Skill 인터페이스
- [decisions/001-agentic-first.md](../decisions/001-agentic-first.md) — 파이프라인 건너뛰기 결정 배경
agent/update_catalog/docs/skill-test-guide.md
+35
View File
@@ -0,0 +1,35 @@
# OpenClaw Skill 테스트 가이드
이 문서는 update_catalog 로컬 구현을 OpenClaw Skill로 테스트하는 방법을 정리한다.
## 1) 사전 조건
- OpenClaw 워크스페이스에 스킬 폴더가 있어야 함
- `~/.openclaw/workspace/skills/update-catalog-helm-diff/`
- `~/.openclaw/workspace/skills/update-catalog-breaking-check/`
- Python/Helm 설치
## 2) helm_diff 실행
```bash
/skill update-catalog-helm-diff --chart airflow --repo apache-airflow \
--chart-path /Users/songwonbin/openclaw-workspace/dip-catalog/manifests/helm/airflow/1.16.0 \
--from-version 1.16.0 --to-version 1.19.0
```
## 3) breaking_change_check 실행
1) helm_diff 결과를 파일로 저장
```bash
python3 ~/.openclaw/workspace/skills/update-catalog-helm-diff/scripts/run.py \
--chart airflow --repo apache-airflow \
--chart-path /Users/songwonbin/openclaw-workspace/dip-catalog/manifests/helm/airflow/1.16.0 \
--from-version 1.16.0 --to-version 1.19.0 \
> /tmp/helm_diff.json
```
2) breaking_check 실행
```bash
/skill update-catalog-breaking-check --diff-file /tmp/helm_diff.json
```
## 4) 참고
- repo 경로 변경 시 `UPDATE_CATALOG_ROOT` 환경변수로 수정 가능 (외부 repo override)
- 기본적으로 스킬은 **내부 포함 소스**를 사용 (독립형)
agent/update_catalog/docs/status.md
+16
View File
@@ -0,0 +1,16 @@
# 구현 진행 현황
## 워크플로 단계별 구현 현황(로컬 환경)
| 단계 | 기능/스킬 | 구현 상태 | 비고 |
|---|---|---|---|
| B | current_version 결정 | ✅ 구현 | chart_version_detector |
| C | BUILD-README repo 파싱 | ✅ 구현 | chart_version_detector |
| D | latest_version 감지 | ✅ 구현 | chart_version_detector |
| E | 최신 차트 pull + 버전 디렉토리 생성 | ✅ 구현 | chart_updater |
| F | Diff 생성 | ✅ 구현 | helm_diff |
| G | Breaking 판단 | ✅ 구현 | breaking_change_check |
| H | 업그레이드 문서 생성 | ✅ 구현 | generate_upgrade_doc (항상 실행; breaking=true → LLM, breaking=false → 템플릿) |
| I | CUSTOM-README.md 업그레이드 주의사항 추가 | ✅ 구현 | update_docs_file (manifests/helm/<chart>/<to_version>/CUSTOM-README.md) |
| J | deploy_validate | ❌ 미구현 | Phase 2 예정 |
| K | create_pr | ✅ 구현 (미테스트) | create_pr |
agent/update_catalog/docs/test/README.md
+6
View File
@@ -0,0 +1,6 @@
# 테스트 문서 구조
- env.md: 테스트 환경 정리
- unit.md: 단위 테스트 케이스
- integration.md: 통합 테스트 시나리오
- logs/: 테스트 실행 기록
agent/update_catalog/docs/test/env.md
+17
View File
@@ -0,0 +1,17 @@
# 테스트 환경 (env)
## 로컬 환경
- OS: Darwin 24.6.0 (arm64) / Darwin Kernel Version 24.6.0
- Python: 3.12.8
- Helm: v3.18.3+g6838ebc
- kubectl: v1.33.2 (Kustomize v5.6.0)
- 기타 의존성: 미기록
## 네트워크
- Helm repo 접근: 미확인
- GitHub API 접근: 미확인
- LLM API 접근: 미확인
## 실행 경로
- 작업 디렉토리: ~/openclaw-workspace/ai_agent_test/update_catalog
- 로그/결과 저장 위치: docs/test/logs/
agent/update_catalog/docs/test/integration.md
+14
View File
@@ -0,0 +1,14 @@
# 통합 테스트 (integration)
## 목적
- helm_diff → breaking_change_check → generate_upgrade_doc 흐름 검증
## 시나리오
### I1. 기본 업그레이드
- 입력: chart, from/to 버전
- 기대: diff 생성 → breaking 판단 → 문서 생성
### I2. breaking 발생 시나리오
- 입력: Service port 변경 포함 chart
- 기대: breaking=true, migration 단계 포함 문서
agent/update_catalog/docs/test/unit.md
+14
View File
@@ -0,0 +1,14 @@
# 단위 테스트 (unit)
## 목적
- 핵심 함수별 동작 검증 (helm_diff, breaking_change_check 등)
## 테스트 케이스
### U1. helm_diff 기본 동작
- 입력: chart, from/to 버전
- 기대: values/templates/dependencies 구조 출력
### U2. breaking_change_check 기본 규칙
- 입력: values removed / type_changed 포함 diff
- 기대: breaking=true, severity>=high
agent/update_catalog/docs/working-memory.md
+70
View File
@@ -0,0 +1,70 @@
# 업데이트 카탈로그 문서 메모리 (요약)
이 문서는 docs/design 및 docs/implementation 내용의 요점을 요약 저장한다.
변경 시 이 파일을 업데이트한다.
## design 요약
### 00-architecture-overview
- **목적**: Helm chart 신규 버전을 카탈로그(신규 배포용)에 추가하고, 업그레이드 주의사항을 CUSTOM-README.md에 자동 문서화.
- **카탈로그 역할**: 운영 클러스터 직접 변경 아님. 신규 배포를 위한 차트 보관소.
- **파이프라인**: chart_version_detector → helm_diff → breaking_change_check → generate_upgrade_doc(항상) → update_docs_file(CUSTOM-README.md) → create_pr.
- **검토 정책**: breaking=true → needs-review 레이블(담당자 판단), breaking=false → auto-update 레이블. deploy_validate는 Phase 2.
- 구성요소 책임 분리 및 스택(helm3, Python diff/rule, LLM, Git PR, OpenClaw/Nanobot).
### 01-helm-diff-engine
- 차트 버전 감지 방식: repo 디렉토리 스캔, git diff, index.yaml, ArtifactHub API, GitHub Release, cron.
- dip-catalog 흐름: 최신 chart pull/untar → manifests/helm/<chart>/<version>/ 디렉토리 생성(기존 유지).
- 이전 버전 파일 복사: custom-values.yaml(그대로), CUSTOM-README.md(그대로), BUILD-README.md(버전 번호 치환).
- generate_upgrade_doc → CUSTOM-README.md에 업그레이드 주의사항 섹션 추가 (항상 실행).
- helm_diff 처리: values, template, CRD, dependencies 비교 → Structured Diff JSON.
- values diff: flat key 비교(added/removed/changed/type_changed), rename은 removed+added.
- template diff: 리소스 단위(kind+name) 비교, generateName 처리.
- CRD diff: schema/required/version/webhook 변화 감지.
- errors 포함하여 부분 실패 기록.
### 02-breaking-change-rules
- **Breaking 정의**: custom-values.yaml을 수정해야 하는 상황.
- values_key_removed: custom-values.yaml에 해당 key가 있을 때만 breaking. 없으면 warning.
- values_type_changed: 동일 기준.
- service_port_changed, resource_removed: 카탈로그 맥락에서 warning (custom-values.yaml 수정 불필요).
- dependency_major_changed: custom-values.yaml에 해당 subchart prefix key 있으면 breaking, 없으면 warning.
- CRD 변경(field 삭제, required 추가, storage version 변경): breaking.
- deprecated API는 warning.
- severity: critical/high/medium/warning, 우선순위 규칙.
### 03-llm-summarizer
- **실행 조건**: generate_upgrade_doc 항상 실행. breaking=true → LLM 상세 가이드, breaking=false → 템플릿 요약.
- LLM 입력: diff + breaking 결과 + docs_context(CUSTOM-README.md).
- 규칙: 입력 JSON 외 내용 금지, 정해진 Markdown 포맷.
- 토큰 관리: 필터링/요약/청크.
- 출력 검증(포맷/허위 서술 금지).
- **대상 파일**: CUSTOM-README.md (배포 관련 문서). BUILD-README.md는 차트 메타 정보 유지.
### 04-skill-interface
- Skill 계약: helm_diff, breaking_change_check, generate_upgrade_doc, update_docs_file, create_pr.
- deploy_validate: Phase 2 예정 (현재 인터페이스만 정의, 구현 안 됨).
- update_docs_file: CUSTOM-README.md에 업그레이드 주의사항 추가. docs_file 경로에 to_version 포함.
- 워크플로: helm_diff → breaking_check → generate_doc(항상) → update_docs(CUSTOM-README.md, to_version 경로) → create_pr.
- 공통 에러 스키마, idempotency, secret 전달 방식.
- 인터페이스 버전 관리(1.0).
### 05-on-cluster-agent
- OpenClaw/Nanobot로 K8s 상시 에이전트 오케스트레이션.
- 보안 고려: RBAC 최소권한, NetworkPolicy, skill allowlist, prompt injection 방지.
- 운영 정책: breaking=true → needs-review 레이블(담당자 판단). breaking=false → auto-update.
- skills allowlist: helm_diff, breaking_change_check, generate_upgrade_doc, update_docs_file, create_pr (deploy_validate는 Phase 2).
## implementation 요약
### 01-skills
- Step 1 Skills 구현 태스크(T1~T10) + dip-catalog 최신 차트 pull/untar 반영.
- 핵심: helm_diff, breaking_check, generate_upgrade_doc(항상 실행), 인터페이스 노출.
- 문서 갱신은 CUSTOM-README.md 대상.
- 안정성: 에러 처리, version detector, docs updater, PR bot.
- 우선순위 로드맵 및 완료 기준.
### 02-agent
- Step 2~4: 프레임워크 POC(OpenClaw vs Nanobot), 워크플로 정의, 보안 정책 후 운영.
- 워크플로: generate_upgrade_doc 항상 실행, deploy_validate는 Phase 2.
- 결정사항은 decisions/에 기록.