init: 폴더구조 설계 및 인프라 설계

2026-07-24 14:31:53 +09:00
parent 34ad612281
commit f9c463f87a
1839 changed files with 323096 additions and 1 deletions
@@ -0,0 +1,147 @@
+# Architecture 상세
+
+README 의 Architecture / Key Components 를 보충하는 문서. 폴더 구조 전체와 워크로드, 이미지 정책을 모은다.
+
+## 폴더 구조
+
+```
+Project-Infra/
+├── .gitignore                                  # vault-init-keys.json 제외
+├── .kube-linter.yaml                           # kube-linter 규칙 (컨텍스트 오탐 4종 제외)
+├── README.md                                   # 본 프로젝트 진입 문서
+├── guide.md                                    # 운영 절차서
+├── docs/                                       # README 보조 분할 문서
+│
+├── k8s/
+│   ├── base/
+│   │   ├── managing/
+│   │   │   ├── namespace/                      # mnt namespace + PSS restricted 라벨
+│   │   │   └── migration-flyway/               # Flyway Job (공식 이미지)
+│   │   │
+│   │   ├── app/                                # 애플리케이션 워크로드 (소유권 = 개발팀)
+│   │   │   ├── identity/auth/
+│   │   │   │   ├── stateful/identity-postgres/
+│   │   │   │   └── stateless/auth-server/
+│   │   │   ├── storage/minio/stateful/minio/
+│   │   │   └── test/stateless/test-server-{1,2,3}/
+│   │   │
+│   │   └── plugins/                            # 플랫폼 플러그인 (다른 워크로드가 의존)
+│   │       ├── vault/                          # Vault StatefulSet (공식 이미지)
+│   │       ├── docker-registry/                # Registry Deployment (공식 이미지)
+│   │       ├── oauth2-proxy/                   # ForwardAuth 용 auth proxy
+│   │       └── vso/                            # VSO CRD 리소스 (VaultConnection / VaultAuth / VaultStaticSecret)
+│   │
+│   ├── components/
+│   │   └── forward-auth/                       # oauth2-proxy + Traefik ForwardAuth 재사용 component
+│   │
+│   ├── overlays/
+│   │   ├── dev/
+│   │   │   ├── kustomization.yaml              # dev 전체 집계 (namespace: mnt)
+│   │   │   ├── networkpolicy-baseline.yaml     # default-deny + DNS egress
+│   │   │   ├── platform/
+│   │   │   │   ├── traefik/                    # HelmChartConfig + Middleware + TLSOption
+│   │   │   │   ├── cert-manager/               # cert-manager v1.20.2
+│   │   │   │   ├── cert-manager-issuers/       # letsencrypt-staging/prod ClusterIssuer
+│   │   │   │   └── keycloak-operator/          # Keycloak Operator 26.6.1
+│   │   │   ├── tls/                            # cert-manager 적용 후 Certificate
+│   │   │   ├── vault/                          # Vault overlay + NetworkPolicy + storage patch
+│   │   │   ├── registry/                       # Registry overlay + NetworkPolicy + storage patch
+│   │   │   ├── vso/                            # VSO CRDs (Helm 설치 후 별도 apply)
+│   │   │   ├── database/                       # identity-postgres + VaultStaticSecret
+│   │   │   ├── auth/                           # auth-server + Ingress(project.com) + flyway
+│   │   │   ├── keycloak/                       # Keycloak CR + public Ingress
+│   │   │   ├── keycloak-realm/                 # KeycloakRealmImport (Git-managed realm/client)
+│   │   │   ├── storage/                        # minio + VaultStaticSecret + certConfig FQDN patch
+│   │   │   └── test/                           # test-server 1/2/3
+│   │   ├── components/forward-auth/            # dev overlay 에 포함되는 ForwardAuth component
+│   │   ├── staging/                            # 의도적으로 비어둠
+│   │   └── prod/                               # 의도적으로 비어둠
+│   │
+│   └── scripts/
+│       ├── bin/                                # 사용자 진입점 (bootstrap.sh / teardown.sh)
+│       ├── ci/validate.sh                      # kustomize + kubeconform + kube-linter
+│       ├── lib/                                # 공통 라이브러리 (common.sh / vault.sh)
+│       └── tasks/                              # 재사용 작업 (vault-init / vault-seed-apps / vso-install)
+│
+└── terraform/                                  # contracts 만 존재, 추후 구현
+```
+
+## 네임스페이스 전략
+
+`mnt` 단일 namespace. 학습 단계의 단순성 우선. 실무에서는 역할별 namespace(`auth`, `storage`, `security`, `registry`) 분리가 원칙이며, base 는 환경 중립이라 overlay 재구성으로 분리 가능하다.
+
+- Pod Security Standards: `pod-security.kubernetes.io/enforce=restricted` (audit + warn 동시).
+- 모든 리소스는 overlay 의 `namespace: mnt` 로 일괄 주입.
+
+## 워크로드 목록
+
+| 워크로드 | 종류 | 위치 | 참조 Secret |
+|---|---|---|---|
+| `identity-postgres` | StatefulSet | `base/app/identity/auth/stateful/` | `identity-postgres-superuser`, `keycloak-db`, `auth-server-db` |
+| [`auth-server`](https://github.com/donghyeon-ka/project-auth-server/tree/develop) | Deployment | `base/app/identity/auth/stateless/` | `auth-server-db` |
+| `keycloak` | Keycloak CR (Operator 생성 StatefulSet) | `overlays/dev/keycloak/` | `keycloak-db-operator`, `keycloak-bootstrap-admin-operator` |
+| `minio` | Tenant CRD | `base/app/storage/minio/stateful/` | `minio-tenant-env` |
+| `test-server-1/2/3` | Deployment | `base/app/test/stateless/` | — |
+| `migration-flyway` | Job (PreSync / sync-wave=-1) | `base/managing/migration-flyway/` | `auth-server-db` |
+| `vault` | StatefulSet | `base/plugins/vault/` | — |
+| `docker-registry` | Deployment | `base/plugins/docker-registry/` | `docker-registry-basic-auth`, `docker-registry-pull-credentials` |
+
+auth-server / keycloak 모두 `jdbc:postgresql://identity-postgres:5432/<db>` 로 short name 접속 (같은 namespace).
+
+### Flyway 실행 순서
+
+dev overlay 가 migration-flyway Job 에 ArgoCD annotation 을 patch:
+
+```
+argocd.argoproj.io/sync-wave: "-1"
+argocd.argoproj.io/hook: PreSync
+```
+
+ArgoCD 배포 시 Job 이 앱보다 먼저 돌고 스키마 마이그레이션을 마친 뒤 `auth-server` 가 뜬다.
+
+### Keycloak hostname patch
+
+dev overlay JSON patch 가 Keycloak ConfigMap 에 다음을 주입:
+
+- `KC_HOSTNAME=https://keycloak.dev.example.com`
+- `KC_HOSTNAME_ADMIN=https://keycloak-admin.dev.example.com`
+
+staging / prod 는 자체 hostname 을 overlay 에서 주입.
+
+### MinIO certConfig.dnsNames
+
+base 는 short name(`minio`, `minio-hl`) 만 둔다. dev overlay 에서 `minio.mnt.svc.cluster.local`, `*.minio-hl.mnt.svc.cluster.local` 을 patch — base 환경 중립성 원칙.
+
+## 이미지 정책
+
+| 구분 | 이미지 | 근거 |
+|---|---|---|
+| 공식 upstream | `hashicorp/vault:1.17.2` | HashiCorp 공식 |
+| | `registry:2.8.3` | Docker library 공식 |
+| | `postgres:16.4` | PostgreSQL 공식 |
+| | `quay.io/keycloak/keycloak:26.6.1` | Keycloak Operator 26.6.1 관리 |
+| | `minio/minio:RELEASE.2025-01-20T14-49-07Z` | MinIO 공식 |
+| | `flyway/flyway:10.20.1` | Flyway 공식 |
+| 사용자 개발 | `registry.example.com/auth-platform/auth-server:0.1.0` | 조직 개발 서비스 |
+| | `registry.example.com/test-platform/test-server-{1,2,3}:0.1.0` | 조직 개발 서비스 |
+
+prod 승격 시 공식 이미지도 digest pin(`@sha256:…`)으로 전환.
+
+## Docker Registry
+
+| 항목 | 값 |
+|---|---|
+| 이미지 | `registry:2.8.3` |
+| 내부 서비스 | `docker-registry.mnt.svc.cluster.local:5000` |
+| 외부 Ingress | `registry.project.com` (`/v2` only) |
+| 인증 | 내부 Service 무인증, 외부 Ingress + kubelet pull 만 credential 사용 |
+| 저장 | MinIO S3 bucket `docker-registry` |
+
+### 인증 경계
+
+Registry 자체 auth 는 켜지 않는다. 인증 경계는 두 곳:
+
+- 외부 Ingress: Traefik `Middleware/docker-registry-basic-auth` 가 VSO 로 생성된 `docker-registry-basic-auth` Secret 의 htpasswd 를 검증
+- 내부 pull: 앱 ServiceAccount 에 `docker-registry-pull-credentials` imagePullSecret
+
+따라서 `docker-registry-ingress-traefik` NetworkPolicy + BasicAuth Secret + imagePullSecret 이 함께 있어야 push/pull 양쪽이 안전하다.