refactor: 폴더 구조 변경

2026-08-02 00:22:19 +09:00
parent f9c463f87a
commit be2f8e4863
1869 changed files with 4565 additions and 295591 deletions
@@ -57,10 +57,10 @@ Kustomize는 Kubernetes 리소스를 **template-free**로 조합하고 환경별

 overlay 한 디렉터리의 `kustomization.yaml`은 짧아야 한다. diff가 몇 백 줄을 넘으면 base 설계 실패 신호.

-권장 구조:
+권장 unit overlay 구조:

 ```
-overlays/prod/
+gitops/apps/auth-server/overlays/prod/
  kustomization.yaml
  patches/
    auth-replicas.yaml
@@ -70,21 +70,26 @@ overlays/prod/
    postgres-storage.yaml
 ```

-### 4. 디렉터리 구조는 base / components / overlays 3축
+### 4. catalog unit과 cluster entrypoint를 분리

 ```
-k8s/
-  base/
-    app/units/<domain>/<service>/
-    managing/<job>/
-    plugins/<platform>/
-  components/
-    <reusable-cross-cutting>/
-  overlays/
-    <env>/[region/]
+gitops/
+  apps/<unit>/
+    base/
+    components/
+    overlays/<env>/
+  platform/<unit>/
+    base/
+    components/
+    overlays/<env>/
+  policies/<unit>/
+  tenants/<unit>/
+  clusters/<env>/<region-or-cluster>/
 ```

-`components/`는 "Kustomize Components"로, 여러 overlay에서 재사용.
+`components/`는 소유 unit 내부의 Kustomize Component입니다. 여러 catalog를
+조립하는 최종 경계는 `clusters/`이며 catalog 디렉터리를 controller root로
+직접 사용하지 않습니다.

 ### 5. `commonLabels` 금지, `labels:` 사용

@@ -108,15 +113,14 @@ labels:

 기존 `commonLabels` 사용 코드는 migration plan을 세워 교체. selector에 이미 들어간 label이 있다면 해당 리소스를 **재배포** (delete + recreate) 없이는 변경 불가.

-### 6. selector에는 불변 3종만
+### 6. selector에는 불변 2종만

 overlay에서 selector를 건드리지 않는다. selector에 허용되는 label은:

 - `app.kubernetes.io/name`
 - `app.kubernetes.io/instance`
- `app.kubernetes.io/component`

-이 3종은 base에서 고정. overlay가 `labels:`로 추가하는 label은 반드시 `includeSelectors: false`.
+이 2종은 base에서 고정. overlay가 `labels:`로 추가하는 label은 반드시 `includeSelectors: false`.

 ### 7. `patches:` (v5 스타일) 사용, `patchesStrategicMerge` / `patchesJson6902` 금지

@@ -146,7 +150,7 @@ patches:
 multiple overlay에서 공통으로 끼워야 하는 변경(예: mTLS 활성화, sidecar 주입, monitoring label 추가)은 component로.

 ```
-components/
+gitops/apps/auth-server/components/
  with-istio-sidecar/
    kustomization.yaml        # kind: Component
    patches/
@@ -215,11 +219,15 @@ field manager 이름을 환경별로 통일해야 `managedFields` 충돌이 예
 CI가 아래를 순서대로 실행:

 ```bash
-kubectl kustomize overlays/prod > /tmp/rendered.yaml
+kubectl kustomize gitops/clusters/prod/kr-main/all > /tmp/rendered.yaml
 kubeconform -strict -summary -schema-location default -schema-location 'https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json' /tmp/rendered.yaml
-kubectl diff --server-side --field-manager=ci -k overlays/prod
+kubectl diff --server-side --field-manager=ci -k gitops/clusters/prod/kr-main/stages/50-apps
 ```

+`all`은 schema/policy 감사용이고 diff/apply는 의존성이 준비된 개별 stage를
+대상으로 합니다. 여러 stage 변경은 승인된 orchestrator/controller가 순서와
+health gate를 보장해야 합니다.
+
 - kubeconform / kubeval: schema validation
 - kyverno / OPA Gatekeeper: policy validation (post-render)
 - conftest: opa policy bundle 실행
@@ -254,62 +262,41 @@ v2.1에서 `bases:`가 `resources:`로 통합됨. 신규 파일에서 `bases:`
 ## 추천 폴더 구조

 ```text
-k8s/
-  base/
-    app/
-      kustomization.yaml
-      units/
-        identity/
-          auth/
-            kustomization.yaml
-            deployment.yaml
-            service.yaml
-            servicemonitor.yaml
-            pdb.yaml
-            hpa.yaml
-          keycloak/
-            kustomization.yaml
-        data/
-          postgres-identity/
-            kustomization.yaml
-            statefulset.yaml
-            service-headless.yaml
-            service.yaml
-    managing/
-      flyway-migrate-identity/
+gitops/
+  apps/
+    auth/
+      base/
        kustomization.yaml
-        job.yaml
-      backup-postgres/
-        kustomization.yaml
-        cronjob.yaml
-    plugins/
-      ingress-nginx/
-      cert-manager/
-      external-secrets/
-      kube-prometheus-stack/
-      fluent-bit/
-  components/
-    with-service-monitor/
-    with-pdb-tier1/
-    with-topology-spread-zone/
-    with-network-policy-deny-default/
-  overlays/
-    dev/
-      kustomization.yaml
-    staging/
-      kustomization.yaml
-    prod/
-      kr-main/
-        kustomization.yaml
-        patches/
-      kr-dr/
-        kustomization.yaml
-        patches/
-  scripts/
-    render.sh
-    diff.sh
-    apply.sh
-    validate.sh
+        deployment.yaml
+        service.yaml
+        servicemonitor.yaml
+        pdb.yaml
+        hpa.yaml
+      components/
+        with-service-monitor/
+        with-pdb-tier1/
+        with-topology-spread-zone/
+      overlays/{lab,staging,prod}/
+    postgres-identity/
+      base/
+      overlays/{lab,staging,prod}/
+    flyway-migrate-identity/
+      base/
+      overlays/{lab,staging,prod}/
+  platform/
+    ingress-nginx/
+    cert-manager/
+    secret-delivery/
+  policies/
+    network-policy-deny-default/
+  clusters/
+    lab/main/stages/
+    staging/main/stages/
+    prod/kr-main/stages/
+    prod/kr-dr/stages/
+scripts/
+  bin/
+  ci/
 ```

 ## 프로젝트 기준 요약
@@ -317,9 +304,10 @@ k8s/
 - Kustomize v5 문법 기준, `commonLabels` 금지, `labels:` 사용
 - `patches:` 단일 키, `target:` + `path:` 또는 `patch:` inline
 - `components:`로 cross-cutting 재사용
- selector에는 불변 3종만 (name / instance / component)
+- selector에는 불변 2종만 (name / instance)
 - generator는 configMap만 기본, secret은 External Secrets
 - `kubectl apply --server-side --field-manager=<id>` 전제
 - render + schema + policy 검증을 CI에서 강제
- base / components / overlays 3축 디렉터리
+- catalog unit의 base/components/overlays와 cluster entrypoint를 분리
+- `stages/`만 apply하고 `all/`은 render/schema/policy audit에만 사용
 - overlay diff는 짧아야 한다 (base 재작성 금지)