diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md new file mode 100644 index 0000000..3d5e548 --- /dev/null +++ b/.claude/CLAUDE.md @@ -0,0 +1,145 @@ +# Project Overview + +Modusign Helm chart repository - Kubernetes 애플리케이션 배포를 위한 재사용 가능한 Helm 템플릿 차트 모음 + +# Architecture & Structure (IMPORTANT) + +## Project Architecture + +**아키텍처 패턴**: Helm Chart Repository (Multi-Chart) + +**핵심 차트 관계**: +- `application-template`: 마이크로서비스 배포용 (Server/Worker/Scheduler 컴포넌트) +- `cronjob-template`: 스케줄 기반 배치 작업용 +- `custom-resource-template`: 커스텀 Kubernetes 리소스 배포용 + +## Directory Structure + +``` +modusign-helm/ +├── charts/ # Helm 차트 디렉토리 +│ ├── application-template/ # 메인 애플리케이션 차트 +│ │ ├── templates/ +│ │ │ ├── hooks/ # Helm lifecycle hooks (Job) +│ │ │ ├── server/ # Server 컴포넌트 리소스 +│ │ │ ├── worker/ # Worker 컴포넌트 리소스 +│ │ │ └── scheduler/ # Scheduler 컴포넌트 리소스 +│ │ ├── Chart.yaml # 차트 메타데이터 +│ │ ├── values.yaml # 기본 설정값 +│ │ └── CONVENTION.md # 라벨링 컨벤션 +│ ├── cronjob-template/ # CronJob 차트 +│ └── custom-resource-template/ # 커스텀 리소스 차트 +├── .github/ +│ ├── workflows/release.yml # 차트 릴리즈 자동화 +│ └── configs/cr.yaml # chart-releaser 설정 +└── .pre-commit-config.yaml # Pre-commit hooks 설정 +``` + +**주요 컴포넌트 구조 (application-template):** +- `server/`: HTTP 서버 워크로드 (Deployment/Rollout, Service, HPA, Istio 리소스) +- `worker/`: 백그라운드 워커 워크로드 +- `scheduler/`: 스케줄러 워크로드 +- `hooks/`: Helm lifecycle hooks (pre-install, post-install 등) + +# Conventions + +## Code Conventions + +**Formatting 도구**: EditorConfig +**설정 파일**: `.editorconfig` + +- 들여쓰기: 2 spaces (YAML, JSON, Shell) +- Line endings: LF +- 파일 끝: newline 추가 +- Trailing whitespace: 제거 (Markdown 제외) + +## Commit Conventions + +**Convention**: Conventional Commits +- 형식: `type(scope): message` +- 타입: `feat`, `fix`, `chore`, `docs`, `refactor`, `test` +- commitlint: `@commitlint/config-conventional` 사용 + +## Pre-commit Hooks + +**Hook 도구**: pre-commit + +커밋 전 자동 실행되는 검사: +- `check-yaml`: YAML 문법 검증 (chart 템플릿 제외) +- `end-of-file-fixer`: 파일 끝 newline 확인 +- `trailing-whitespace`: 불필요한 공백 제거 +- `check-merge-conflict`: 머지 충돌 마커 확인 +- `check-added-large-files`: 5MB 이상 파일 차단 +- `shfmt`: Shell 스크립트 포맷팅 +- `helmlint`: Helm 차트 린트 +- `helm-docs`: README 자동 생성 + +**IMPORTANT**: 커밋 메시지 검증은 `commit-msg` 스테이지에서 실행됨 + +# Commands + +## Development + +- Lint: `helm lint charts/` +- Template: `helm template charts/ -f values.yaml` +- Dry-run: `helm install --dry-run --debug charts/` + +## Testing + +- Helm lint all: `for d in charts/*/; do helm lint "$d"; done` + +## Pre-commit + +- Install hooks: `pre-commit install && pre-commit install --hook-type commit-msg` +- Run all hooks: `pre-commit run --all-files` +- Run specific hook: `pre-commit run ` + +## Helm Docs + +- Generate README: `helm-docs --template-files=README.md.gotmpl` + +# CI/CD Pipeline + +## Workflows + +**CI 도구**: GitHub Actions + +| Workflow | 트리거 | 주요 단계 | +| -------------- | ------------ | ---------------------------- | +| Release Charts | push to main | checkout, helm, chart-releaser | + +## Release Strategy + +**자동 릴리즈 조건**: +- `main` 브랜치에 push 시 자동 트리거 +- `Chart.yaml`의 `version` 변경 시에만 실제 릴리즈 수행 +- `helm/chart-releaser-action` 사용 + +**배포 방식**: +- GitHub Pages (`gh-pages` 브랜치)로 Helm repository 호스팅 +- `skip_existing: true`로 중복 릴리즈 방지 + +# Workflow + +## Chart 추가/수정 + +1. `charts/` 하위에 차트 추가 또는 수정 +2. `Chart.yaml`에서 `version` 업데이트 +3. `main` 브랜치로 squash merge +4. 릴리즈 workflow 자동 실행 + +## Chart 사용 + +```bash +helm repo add modusign-helm https://modusign.github.io/modusign-helm/ +helm repo update +helm search repo modusign-helm +``` + +# Common Gotchas + +- **IMPORTANT**: `Chart.yaml`의 `version`을 변경해야만 릴리즈가 수행됨 +- Kubernetes 버전 요구사항: `>=1.23` +- 기본 이미지 레지스트리: `harbor.modusign.co.kr/modusign` +- Istio 리소스는 `server.istio.enabled: true`일 때만 생성됨 +- ArgoCD Vault Plugin 사용 시 `vault.enabled: true` 설정 필요 diff --git a/.claude/rules/git-workflow.md b/.claude/rules/git-workflow.md new file mode 100644 index 0000000..2f34a8a --- /dev/null +++ b/.claude/rules/git-workflow.md @@ -0,0 +1,49 @@ +--- +paths: + - "**/Chart.yaml" + - ".github/**/*" +--- + +# Git Workflow Rules + +## Branch Strategy + +- `main`: 릴리즈 브랜치 (보호됨) +- Feature/Fix 브랜치에서 작업 후 `main`으로 squash merge + +## Commit Message + +Conventional Commits 형식 필수: + +``` +type(scope): subject + +[optional body] +``` + +**타입:** +- `feat`: 새로운 기능 +- `fix`: 버그 수정 +- `refactor`: 코드 리팩토링 +- `docs`: 문서 수정 +- `chore`: 빌드, CI 등 기타 작업 +- `test`: 테스트 추가/수정 + +**예시:** +``` +feat(application-template): add HPA external metrics support +fix(cronjob-template): correct indentation in values.yaml +refactor(charts): upgrade chart version to 1.8.6 +``` + +## Release Trigger + +- `main` 브랜치 push 시 자동 릴리즈 +- **IMPORTANT**: `Chart.yaml`의 `version` 변경 필수 +- 동일 버전은 `skip_existing: true`로 무시됨 + +## PR Guidelines + +- 단일 차트 변경 권장 +- 여러 차트 동시 변경 시 각각 별도 PR +- 릴리즈 노트 자동 생성됨 (`generate-release-notes: true`) diff --git a/.claude/rules/helm-chart.md b/.claude/rules/helm-chart.md new file mode 100644 index 0000000..6e2d764 --- /dev/null +++ b/.claude/rules/helm-chart.md @@ -0,0 +1,47 @@ +--- +paths: + - "charts/**/*.yaml" + - "charts/**/*.tpl" +--- + +# Helm Chart Rules + +## Chart Structure + +- 각 차트는 `charts/` 디렉토리 하위에 위치 +- 필수 파일: `Chart.yaml`, `values.yaml`, `templates/_helpers.tpl` +- README는 `helm-docs`로 자동 생성 (수동 수정 금지) + +## Version Management + +- **IMPORTANT**: 차트 수정 시 반드시 `Chart.yaml`의 `version` 업데이트 +- Semantic Versioning 사용: `MAJOR.MINOR.PATCH` + +## Labels Convention + +application-template 차트는 다음 라벨 규칙을 따름: + +**필수 라벨:** +- `app.kubernetes.io/name`: 워크로드 이름 (e.g., `document-server`) +- `app.kubernetes.io/instance`: Release 이름 +- `app.kubernetes.io/version`: 애플리케이션 버전 +- `app.kubernetes.io/component`: `server`, `worker`, `scheduler` +- `app.kubernetes.io/part-of`: 최상위 애플리케이션 이름 +- `helm.sh/chart`: 차트 정보 +- `app.kubernetes.io/managed-by`: `Helm` + +**Modusign 커스텀 라벨:** +- `app.modusign.co.kr/zone`: 네임스페이스 기반 zone +- `app.kubernetes.io/env`: 런타임 환경 (`prod`, `stage`, `dev`) + +## Template Patterns + +- Helper 함수는 `_helpers.tpl`에 정의 +- 조건부 리소스 생성: `{{- if .Values.xxx.enabled }}` +- 컴포넌트별 templates: `server/`, `worker/`, `scheduler/` 디렉토리로 분리 + +## Values Structure + +- `global.*`: 모든 컴포넌트 공통 설정 +- `server.*`, `worker.*`, `scheduler.*`: 컴포넌트별 설정 +- 컴포넌트 설정이 없으면 global 값 사용