191 lines
7.9 KiB
Markdown
191 lines
7.9 KiB
Markdown
# 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)를 참고합니다.
|