dip/service-catalog
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
main
service-catalog/agent/update_catalog/docs/design/04-skill-interface.md
T
wbsong111 21addb6e88 Move directory
2026-03-06 17:08:31 +09:00

8.0 KiB
Raw Permalink Blame History

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은 실패 시 아래 형식으로 에러를 반환한다.

{
  "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

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

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

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

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

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+)

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들을 등록하고, 아래 순서를 워크플로로 정의한다.

# 개념적 호출 순서 (실제 워크플로 정의는 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. 버전 관리

이 인터페이스는 명시적 버전을 관리한다.

skill_interface_version: "1.0"

Skill 입출력 변경 시:

  • 하위 호환 변경 (필드 추가): 마이너 버전 증가
  • Breaking 변경 (필드 삭제/타입 변경): 메이저 버전 증가 + 마이그레이션 가이드 작성

6. 관련 문서

Reference in New Issue View Git Blame Copy Permalink