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

Add catalog update agent

Browse Source
This commit is contained in:
wbsong111
2026-03-06 17:06:07 +09:00
parent d4fecb4ae5
commit ca64890bb6
73 changed files with 4718 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
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)
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) — 파이프라인 건너뛰기 결정 배경