init: k8s 폴더 구조init

2026-07-26 17:11:25 +09:00
commit 0912b5030f
61 changed files with 2124 additions and 0 deletions
@@ -0,0 +1,190 @@
+# Kubernetes Infrastructure Skeleton
+
+Kubernetes 인프라 저장소를 새로 시작할 때 복제해서 사용하는 기본 골격입니다.
+작은 단일 클러스터부터 여러 계정·리전·클러스터를 운영하는 구성까지 같은
+수명주기 경계를 유지하도록 설계했습니다.
+
+이 스켈레톤이 고정하는 것은 **폴더의 책임, 배포 경계, 소유권 규칙**입니다.
+클라우드 공급자, IaC 엔진(Terraform/OpenTofu/Pulumi 등), GitOps 컨트롤러,
+비밀 관리 도구와 정책 엔진은 프로젝트 요구에 맞춰 선택합니다.
+
+Kubernetes manifest 조립의 최소 기본값은 `kubectl`에 내장된 Kustomize입니다.
+Helm이 필요한 컴포넌트는 해당 컴포넌트 내부에 Chart 또는 values를 함께 둡니다.
+
+## 수명주기
+
+```text
+bootstrap/foundation
+        │
+        ▼
+infrastructure/live
+        │
+        ▼
+bootstrap/gitops
+        │
+        ▼
+gitops/clusters ──▶ platform / policies / tenants / apps
+```
+
+- `bootstrap/foundation`: state backend, 초기 identity 등 선행 조건
+- `infrastructure/live`: 네트워크, IAM, DNS, Kubernetes 클러스터 프로비저닝
+- `bootstrap/gitops`: 선택한 GitOps 컨트롤러와 루트 연결만 설치
+- `gitops/clusters`: 플랫폼과 워크로드의 최종 desired state 조립
+
+동일한 리소스를 두 단계가 동시에 관리하지 않습니다. 예를 들어 GitOps가 관리하는
+Kubernetes 리소스를 IaC에서도 다시 선언하지 않습니다.
+
+## 폴더 구조
+
+```text
+.
+├── bootstrap/
+│   ├── foundation/            # state/identity 등 최초 선행 조건
+│   └── gitops/                # Flux 또는 Argo CD 최소 부트스트랩
+├── infrastructure/
+│   ├── components/            # 작고 재사용 가능한 IaC 단위
+│   ├── stacks/                # 여러 component의 재사용 조합(선택)
+│   ├── live/                  # 실제 plan/apply 및 state 경계
+│   └── tests/                 # IaC 단위·계약 테스트
+├── gitops/
+│   ├── clusters/              # 클러스터별 최종 조립·동기화 진입점
+│   ├── platform/              # ingress, external-dns controller, storage 등
+│   ├── policies/              # cluster-wide admission/guardrail 정책
+│   ├── tenants/               # namespace, RBAC, quota, NetworkPolicy(선택)
+│   └── apps/                  # 애플리케이션 배포 정의
+├── docs/
+│   ├── architecture/          # 구조·의존성·설계 문서
+│   ├── decisions/             # Architecture Decision Records
+│   ├── guides/                # 사용 절차
+│   └── runbooks/              # 장애·변경·복구 절차
+├── examples/
+│   ├── minimal/               # 렌더 가능한 최소 구성
+│   └── scaled/                # 확장 구조 예시
+├── scripts/                   # 로컬/CI 공통 검증 자동화
+└── tests/                     # 저장소 수준 렌더·정책·통합 테스트
+```
+
+## 템플릿 위치
+
+별도의 최상위 `template/` 폴더는 없습니다. 템플릿은 실제 결과물이 위치할
+책임 영역 가까이에 `_template/` 이름으로 배치되어 있습니다.
+
+| 만들 대상 | 복사 원본 | 용도 |
+|---|---|---|
+| IaC component | `infrastructure/components/_template` | network, identity, cluster 등 재사용 단위 |
+| IaC stack | `infrastructure/stacks/_template` | 여러 component의 반복 조합 |
+| 실제 IaC root | `infrastructure/live/_template` | environment별 state/plan/apply 경계 |
+| cluster root | `gitops/clusters/_template` | 클러스터 desired state 최종 조립점 |
+| platform component | `gitops/platform/_template` | ingress, storage, observability 등 |
+| application 배포 | `gitops/apps/_template` | application base/overlay |
+| policy set | `gitops/policies/_template` | cluster-wide admission/guardrail |
+| tenant | `gitops/tenants/_template` | namespace, RBAC, quota, NetworkPolicy |
+
+`_template`은 복사 원본이며 배포 대상이 아닙니다. 실제 이름으로 복사한 뒤
+`__REPLACE_ME_*__` 값을 모두 채우고 리소스를 추가합니다. 템플릿 밖의 미치환
+값과 아무 리소스도 렌더하지 않는 실제 cluster root는 검증에 실패합니다.
+
+## 예제를 활용해 설계하는 방법
+
+`examples/`는 복사 원본이 아니라 설계 참고 자료입니다.
+
+```text
+examples/minimal  ──▶ 소규모의 canonical 경로와 조립 방식 확인
+examples/scaled   ──▶ 계정·리전·환경·클러스터 확장 경로 결정
+        │
+        ▼
+각 영역의 _template 복사
+        │
+        ▼
+infrastructure/live 및 gitops/clusters에 실제 구성 작성
+```
+
+1. `examples/minimal`에서 `live`, catalog `base`, cluster root의 관계를 확인하고
+   Kustomize 결과를 렌더합니다.
+2. 계정·리전·클러스터가 여러 개인 경우 `examples/scaled`의 계층을 참고해
+   실제 경로 깊이를 정합니다.
+3. 예제 파일이나 값을 운영 경로로 복사하지 않고, 위 표의 `_template`에서
+   실제 component와 entrypoint를 생성합니다.
+4. 예제와 실제 구성이 같은 소유권·배포 경계를 따르는지 비교한 뒤 검증합니다.
+
+```bash
+kubectl kustomize examples/minimal/gitops/clusters/dev/main
+make check
+```
+
+## 시작하기
+
+먼저 프로젝트의 공급자, IaC 엔진, GitOps 컨트롤러, 비밀 관리 방식을
+ADR로 기록합니다. 이후 필요한 템플릿만 복사합니다.
+
+```bash
+mkdir -p infrastructure/live/dev
+cp -R infrastructure/live/_template infrastructure/live/dev/cluster
+
+mkdir -p gitops/clusters/dev
+cp -R gitops/clusters/_template gitops/clusters/dev/main
+
+cp -R gitops/platform/_template gitops/platform/ingress
+```
+
+먼저 도구를 확인합니다.
+
+```bash
+make doctor
+```
+
+복사 직후에는 미치환 token과 빈 cluster root가 있으므로 `make check` 실패가
+정상입니다. 실제 메타데이터를 채우고 component 리소스와 cluster 참조를 추가한
+뒤 검증합니다.
+
+```bash
+kubectl kustomize gitops/clusters/dev/main
+make check
+```
+
+구체적인 완료 순서는
+[`docs/guides/getting-started.md`](docs/guides/getting-started.md)를 참고합니다.
+이 저장소는 안전을 위해 기본 `apply`/`destroy` 명령을 제공하지 않습니다.
+
+## 규모에 따른 사용법
+
+### 소규모
+
+```text
+infrastructure/live/dev/cluster
+gitops/clusters/dev/main
+```
+
+`live`가 component를 직접 호출하고, `stacks`, `policies`, `tenants`는 필요할
+때까지 사용하지 않아도 됩니다.
+
+### 중·대규모
+
+```text
+infrastructure/live/<provider>/<account>/<region>/<environment>/<stack>
+gitops/clusters/<environment>/<region>/<cluster>
+```
+
+경로 깊이는 조직 상황에 맞추되 다음 계약은 유지합니다.
+
+- `infrastructure/live`의 실행 가능한 leaf 하나가 state/plan/apply 경계입니다.
+- `gitops/clusters`의 leaf 하나가 클러스터 동기화 진입점입니다.
+- 공통 구현은 `components`, `platform`, `policies`, `tenants`, `apps`에 한 번만
+  둡니다.
+- 환경·클러스터 경로에는 공통 구현을 복사하지 않고 조합과 차이만 둡니다.
+
+더 자세한 확장 기준은
+[`docs/architecture/repository-structure.md`](docs/architecture/repository-structure.md)에
+정리되어 있습니다.
+
+## 기본 규칙
+
+- 디렉터리와 리소스 이름은 소문자 `kebab-case`를 사용합니다.
+- 평문 Secret, kubeconfig, private key, state와 plan 파일은 커밋하지 않습니다.
+- `.terraform.lock.hcl`, `Chart.lock`, 암호화된 SOPS 파일은 커밋합니다.
+- 예제는 `examples/`에만 두며 실제 reconcile 경로에서 참조하지 않습니다.
+- 배포 변경은 렌더와 검증을 통과한 뒤 리뷰를 거칩니다.
+- 프로젝트별 도구 버전과 소유자는 복제 직후 명시적으로 고정합니다.
+
+보안 기준은 [`SECURITY.md`](SECURITY.md), 기여 규칙은
+[`CONTRIBUTING.md`](CONTRIBUTING.md)를 참고합니다.