Kubernetes Infrastructure Skeleton

Kubernetes 인프라 저장소를 새로 시작할 때 복제해서 사용하는 기본 골격입니다. 작은 단일 클러스터부터 여러 계정·리전·클러스터를 운영하는 구성까지 같은 수명주기 경계를 유지하도록 설계했습니다.

이 스켈레톤이 고정하는 것은 폴더의 책임, 배포 경계, 소유권 규칙입니다. 클라우드 공급자, IaC 엔진(Terraform/OpenTofu/Pulumi 등), GitOps 컨트롤러, 비밀 관리 도구와 정책 엔진은 프로젝트 요구에 맞춰 선택합니다.

Kubernetes manifest 조립의 최소 기본값은 kubectl에 내장된 Kustomize입니다. Helm이 필요한 컴포넌트는 해당 컴포넌트 내부에 Chart 또는 values를 함께 둡니다.

수명주기

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에서도 다시 선언하지 않습니다.

폴더 구조

.
├── 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/는 복사 원본이 아니라 설계 참고 자료입니다.

examples/minimal  ──▶ 소규모의 canonical 경로와 조립 방식 확인
examples/scaled   ──▶ 계정·리전·환경·클러스터 확장 경로 결정
        │
        ▼
각 영역의 _template 복사
        │
        ▼
infrastructure/live 및 gitops/clusters에 실제 구성 작성

examples/minimal에서 live, catalog base, cluster root의 관계를 확인하고 Kustomize 결과를 렌더합니다.
계정·리전·클러스터가 여러 개인 경우 examples/scaled의 계층을 참고해 실제 경로 깊이를 정합니다.
예제 파일이나 값을 운영 경로로 복사하지 않고, 위 표의 _template에서 실제 component와 entrypoint를 생성합니다.
예제와 실제 구성이 같은 소유권·배포 경계를 따르는지 비교한 뒤 검증합니다.

kubectl kustomize examples/minimal/gitops/clusters/dev/main
make check

시작하기

먼저 프로젝트의 공급자, IaC 엔진, GitOps 컨트롤러, 비밀 관리 방식을 ADR로 기록합니다. 이후 필요한 템플릿만 복사합니다.

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

먼저 도구를 확인합니다.

make doctor

복사 직후에는 미치환 token과 빈 cluster root가 있으므로 make check 실패가 정상입니다. 실제 메타데이터를 채우고 component 리소스와 cluster 참조를 추가한 뒤 검증합니다.

kubectl kustomize gitops/clusters/dev/main
make check

구체적인 완료 순서는 docs/guides/getting-started.md를 참고합니다. 이 저장소는 안전을 위해 기본 apply/destroy 명령을 제공하지 않습니다.

규모에 따른 사용법

소규모

infrastructure/live/dev/cluster
gitops/clusters/dev/main

live가 component를 직접 호출하고, stacks, policies, tenants는 필요할 때까지 사용하지 않아도 됩니다.

중·대규모

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에 정리되어 있습니다.

기본 규칙

디렉터리와 리소스 이름은 소문자 kebab-case를 사용합니다.
평문 Secret, kubeconfig, private key, state와 plan 파일은 커밋하지 않습니다.
.terraform.lock.hcl, Chart.lock, 암호화된 SOPS 파일은 커밋합니다.
예제는 examples/에만 두며 실제 reconcile 경로에서 참조하지 않습니다.
배포 변경은 렌더와 검증을 통과한 뒤 리뷰를 거칩니다.
프로젝트별 도구 버전과 소유자는 복제 직후 명시적으로 고정합니다.

보안 기준은 SECURITY.md, 기여 규칙은 CONTRIBUTING.md를 참고합니다.

7.9 KiB Raw Blame History