# 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)를 참고합니다.