wbsong111
159 lines
6.9 KiB
Markdown
159 lines
6.9 KiB
Markdown
# 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 인터페이스
|