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,33 @@
+# GitOps Desired State
+
+Kubernetes API 안에서 지속적으로 reconcile할 desired state를 관리합니다.
+GitOps controller를 사용하지 않는 초기 단계에도 `kubectl kustomize`로 같은
+entrypoint를 렌더할 수 있습니다.
+
+```text
+platform ─┐
+policies ─┼──▶ clusters/<...>  ◀── GitOps controller root
+tenants  ─┤
+apps     ─┘
+```
+
+- `clusters`: 클러스터별 최종 조립점
+- `platform`: cluster-wide addon과 controller
+- `policies`: cluster-wide admission과 거버넌스 규칙
+- `tenants`: 구체적인 namespace/RBAC/quota/NetworkPolicy
+- `apps`: application 배포 정의
+
+Catalog 디렉터리를 controller root로 직접 지정하지 않습니다. cluster entrypoint가
+필요한 base/overlay를 선택하고 의존 순서를 명시합니다.
+
+## 기본 규칙
+
+- `base`는 환경을 모르며 재사용 가능한 기본값만 가집니다.
+- `overlays`는 차이만 patch하고 전체 manifest를 복사하지 않습니다.
+- CRD/controller가 필요한 리소스는 controller 이후에 reconcile합니다.
+- resource namespace, ownership label과 버전을 명시합니다.
+- raw `Secret` 또는 실제 비밀값을 커밋하지 않습니다.
+- 원격 base/chart를 참조할 때 immutable version 또는 digest를 사용합니다.
+
+Flux/Argo CD 고유 리소스와 sync ordering은 선택한 controller를 기록한 ADR에
+문서화합니다.
@@ -0,0 +1,18 @@
+# Application Deployment Catalog
+
+애플리케이션의 source code가 아니라 Kubernetes 배포 정의를 둡니다. app 팀이
+별도 source/deploy 저장소를 소유하면 이곳에는 immutable artifact를 참조하는
+GitOps 리소스만 둘 수 있습니다.
+
+```text
+apps/
+└── example-api/
+    ├── base/
+    └── overlays/
+        ├── dev/
+        └── prod/
+```
+
+base는 환경을 모르고, overlay에는 replica/resource/config처럼 필요한 차이만
+둡니다. image는 mutable tag 대신 조직 정책에 따른 고정 tag 또는 digest를
+사용합니다.
@@ -0,0 +1,22 @@
+# __REPLACE_ME_APPLICATION_NAME__
+
+## 소유자
+
+Team: __REPLACE_ME_OWNER__
+
+repository와 on-call 정보를 적습니다.
+
+## 배포 계약
+
+- Namespace:
+- Image/artifact source:
+- Ports/protocol:
+- Dependency:
+- SLO/alerts:
+
+## 구성
+
+- `base`: 공통 Kubernetes 배포 정의
+- `overlays`: 환경별 replica, resource, config 차이
+
+비밀은 ExternalSecret 같은 참조 또는 승인된 암호화 형식으로만 추가합니다.
@@ -0,0 +1,4 @@
+# Base
+
+환경을 모르는 application의 공통 manifest를 둡니다. namespace 자체의 소유권이
+tenant catalog에 있다면 이곳에서 중복 생성하지 않습니다.
@@ -0,0 +1,4 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources: []
@@ -0,0 +1,6 @@
+# Overlays
+
+필요한 환경에만 overlay를 추가합니다. 각 overlay는 `../../base`를 참조하고
+환경별 patch만 포함합니다.
+
+비밀값, 임시 debug 설정과 수동 hotfix 결과를 overlay에 커밋하지 않습니다.
@@ -0,0 +1,30 @@
+# Cluster Entrypoints
+
+클러스터별 최종 desired state 진입점입니다. GitOps controller의 root는 이
+디렉터리 아래 **하나의 실제 cluster leaf**만 가리킵니다.
+
+소규모:
+
+```text
+clusters/
+└── dev/
+    └── main/
+        └── kustomization.yaml
+```
+
+다중 환경·리전:
+
+```text
+clusters/
+├── dev/ap-northeast-2/dev-a/
+├── staging/ap-northeast-2/staging-a/
+└── prod/
+    ├── ap-northeast-2/prod-a/
+    └── ap-southeast-1/prod-b/
+```
+
+cluster leaf에는 catalog 구현을 복사하지 않고 선택 목록과 cluster 고유 patch만
+둡니다. 계정 또는 조직 경계가 필요하면 경로 segment를 추가할 수 있지만 자동화가
+고정 depth에 의존하지 않도록 합니다.
+
+`_template`을 실제 경로로 복사해 시작합니다.
@@ -0,0 +1,31 @@
+# __REPLACE_ME_CLUSTER_NAME__
+
+## 대상
+
+- Environment: __REPLACE_ME_ENVIRONMENT__
+- Region: __REPLACE_ME_REGION__
+- Cluster: __REPLACE_ME_CLUSTER_NAME__
+- Owner: __REPLACE_ME_OWNER__
+
+## 구성
+
+`kustomization.yaml`의 `resources`에 필요한 platform, policy, tenant와 app의
+base 또는 overlay를 추가합니다. 예:
+
+```yaml
+resources:
+  - ../../../platform/core/base
+  - ../../../policies/baseline/base
+  - ../../../apps/example-api/overlays/prod
+```
+
+위 예시는 `clusters/dev/main` 경로를 기준으로 합니다. 실제 상대 경로는 cluster
+leaf 깊이에 맞게 조정합니다.
+
+## 규칙
+
+- 이 디렉터리가 해당 클러스터의 유일한 root입니다.
+- 공통 manifest를 복사하지 않습니다.
+- 클러스터 고유 차이만 local patch로 둡니다.
+- dependency/sync 순서와 장애 시 reconcile 중지 절차를 문서화합니다.
+- `_template` 자체를 GitOps controller에 연결하지 않습니다.
@@ -0,0 +1,5 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+# Add reusable platform, policy, tenant and app paths after copying this template.
+resources: []
@@ -0,0 +1,23 @@
+# Platform Catalog
+
+클러스터 전체에서 사용하는 addon과 controller의 재사용 구성을 둡니다.
+
+예:
+
+```text
+platform/
+├── ingress/
+├── certificates/
+├── external-dns/
+├── external-secrets/
+├── storage/
+├── autoscaling/
+└── observability/
+```
+
+실제로 사용하는 항목만 만듭니다. 각 component는 자신의 CRD, controller,
+configuration과 values/patch를 응집해서 관리합니다. component 간 숨은 의존을
+만들지 말고 cluster root 또는 선택한 GitOps controller의 ordering 기능으로
+순서를 표현합니다.
+
+새 component는 `_template`을 복사해 시작합니다.
@@ -0,0 +1,21 @@
+# __REPLACE_ME_PLATFORM_COMPONENT_NAME__
+
+## 책임
+
+이 component가 소유하는 CRD, controller와 configuration을 적습니다.
+
+## 의존성
+
+선행 component, namespace, identity와 최소 Kubernetes version을 적습니다.
+
+## 구성
+
+- `base`: 모든 대상에서 공유하는 기본값
+- `overlays`: 환경/규모별 차이가 실제로 있을 때만 추가
+
+Helm을 사용하면 chart source/version, values와 release 리소스를 이 component
+안에 함께 둡니다. 원격 version은 고정합니다.
+
+## 운영
+
+upgrade 순서, health check, rollback과 uninstall 영향을 runbook으로 연결합니다.
@@ -0,0 +1,7 @@
+# Base
+
+환경과 클러스터를 모르는 재사용 가능한 기본 manifest만 둡니다.
+
+- 실제 domain, account ID, credential을 하드코딩하지 않습니다.
+- resource request/limit와 security context의 안전한 기본값을 둡니다.
+- 환경 차이는 `overlays`에서 patch합니다.
@@ -0,0 +1,4 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources: []
@@ -0,0 +1,7 @@
+# Overlays
+
+공통 base와 다른 값이 있을 때만 `<environment-or-profile>/` overlay를 만듭니다.
+overlay는 base를 참조하고 patch만 포함해야 합니다.
+
+`dev`, `prod` 전체 manifest 복사보다 replica, resource, retention처럼 실제로
+달라지는 항목만 표현합니다.
@@ -0,0 +1,18 @@
+# Policy Catalog
+
+cluster-wide admission 규칙과 거버넌스 정책을 둡니다. Kyverno, Gatekeeper 등
+정책 엔진은 하나를 선택하고 ADR로 기록합니다. 구체적인 Namespace,
+Role/RoleBinding, ResourceQuota와 NetworkPolicy 인스턴스는 `tenants`가
+소유하며 이곳에서 중복 생성하지 않습니다.
+
+권장 분류:
+
+- baseline workload security
+- allowed registries와 image 검증
+- resource request/limit
+- namespace/RBAC 생성 규칙 검증
+- network isolation 적용 여부 검증
+- 정책 예외와 만료 조건
+
+처음에는 audit 모드와 테스트로 영향 범위를 확인한 뒤 enforcement를 적용합니다.
+예외에는 owner, 사유와 만료일을 반드시 기록합니다.
@@ -0,0 +1,17 @@
+# __REPLACE_ME_POLICY_SET_NAME__
+
+## 목적과 범위
+
+보호하는 대상, 위협과 제외 범위를 적습니다.
+
+## 적용 단계
+
+audit 결과, enforcement 전환 조건과 rollback을 적습니다.
+
+## 예외
+
+예외 schema, 승인자와 만료 정책을 적습니다.
+
+## 테스트
+
+허용/거부 fixture와 선택한 policy engine의 test 명령을 추가합니다.
@@ -0,0 +1,4 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources: []
@@ -0,0 +1,16 @@
+# Tenant Catalog
+
+여러 팀 또는 workload 경계를 운영할 때 사용하는 선택 영역입니다.
+
+가능한 리소스:
+
+- Namespace와 ownership label
+- Role/RoleBinding
+- ResourceQuota와 LimitRange
+- 기본 NetworkPolicy
+- secret manager/service account 연결
+
+작은 단일 팀 구성에서는 이 계층을 생략하고 platform 또는 app 소유권에 맞게
+namespace를 관리할 수 있습니다. tenant와 app이 같은 namespace를 중복 생성하지
+않도록 한쪽만 소유합니다. `policies`는 이런 namespace-scoped 리소스 자체가
+아니라 조직 규칙을 검증하는 admission 정책만 소유합니다.
@@ -0,0 +1,19 @@
+# __REPLACE_ME_TENANT_NAME__
+
+## 소유자와 범위
+
+Team: __REPLACE_ME_OWNER__
+
+namespace, cluster 범위와 연락처를 적습니다.
+
+## 권한
+
+최소 RBAC와 workload identity contract를 적습니다.
+
+## Guardrail
+
+quota, limit, network와 승인된 policy exception ID/문서 참조를 적습니다.
+
+## 온보딩/오프보딩
+
+생성, 권한 회수, 데이터 보존과 namespace 삭제 절차를 적습니다.
@@ -0,0 +1,4 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources: []