service-catalog/agent/update_catalog/docs/design/02-breaking-change-rules.md

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 기본 출력

{
  "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은 다음 인터페이스를 구현한다:

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 — Structured Diff JSON 생성
• 03-llm-summarizer.md — Breaking Change 결과를 LLM에 전달
• 04-skill-interface.md — breaking_change_check Skill 인터페이스