157 lines
5.7 KiB
Markdown
157 lines
5.7 KiB
Markdown
# Project Infra
|
|
|
|
K3s 기반 인증 플랫폼의 인프라 source-of-truth입니다. 범용
|
|
`k8s-template`의 lifecycle/ownership 스켈레톤을 적용하고, 기존 리소스를
|
|
IaC catalog와 Kubernetes desired-state catalog로 분리했습니다.
|
|
|
|
현재 실제 배포 환경은 폐기 가능한 단일 클러스터용 `lab`입니다. `dev`,
|
|
`staging`, `prod` IaC root는 확장 위치만 예약되어 있으며 아직 실행 가능한
|
|
Terraform/OpenTofu 구성이 아닙니다.
|
|
|
|
## Lifecycle
|
|
|
|
```text
|
|
bootstrap/foundation
|
|
|
|
|
v
|
|
infrastructure/live
|
|
|
|
|
v
|
|
bootstrap/gitops
|
|
|
|
|
v
|
|
gitops/clusters ──> platform / policies / tenants / apps
|
|
```
|
|
|
|
- `bootstrap/foundation`: remote state와 초기 identity 같은 선행 조건
|
|
- `infrastructure/live`: 네트워크, IAM, DNS, load balancer와 클러스터 생성 root
|
|
- `bootstrap/gitops`: 선택한 GitOps controller와 cluster root 연결
|
|
- `gitops/clusters`: Kubernetes desired state의 실제 배포 entrypoint
|
|
|
|
현재는 Argo CD/Flux가 설치되어 있지 않으므로 `bootstrap/gitops`는 확장
|
|
계약만 제공합니다. 실제 `lab` 배포는 readiness 경계를 보존하는
|
|
`scripts/bin/bootstrap.sh`가 ordered stage를 server-side apply합니다.
|
|
|
|
## Repository layout
|
|
|
|
| Path | Responsibility |
|
|
| --- | --- |
|
|
| `bootstrap/` | foundation 및 GitOps controller bootstrap |
|
|
| `infrastructure/components/` | 재사용 가능한 compute/database/networking/storage IaC 단위 |
|
|
| `infrastructure/stacks/` | 반복되는 component 조합 |
|
|
| `infrastructure/live/<env>/<leaf>/` | 실제 IaC plan/apply와 state 경계 |
|
|
| `gitops/apps/` | auth-server, PostgreSQL, migration 같은 app 소유 배포 정의 |
|
|
| `gitops/platform/` | Traefik, Vault, VSO, Keycloak, MinIO, registry와 operator |
|
|
| `gitops/policies/` | 공통 보안·거버넌스 정책 |
|
|
| `gitops/tenants/` | namespace, RBAC, quota 같은 tenant 경계 |
|
|
| `gitops/clusters/lab/main/namespaces`, `stages/` | 현재 실제 배포 entrypoint |
|
|
| `gitops/clusters/lab/main/all/` | 전체 render/schema/policy 감사 전용; apply 금지 |
|
|
| `scripts/` | staged bootstrap, teardown와 검증 도구 |
|
|
| `tests/kustomize-entrypoints.txt` | 검증할 Kustomize entrypoint inventory |
|
|
|
|
`_template` 디렉터리는 새 component/root를 만들 때 복제하는 뼈대입니다.
|
|
이 저장소는 이미 실제 `lab` 구성이 조립된 프로젝트이므로 루트에 별도
|
|
`examples/`를 유지하지 않습니다. 현재 구현을 참고하고 새 단위는 각 책임
|
|
폴더의 `_template`에서 시작합니다.
|
|
|
|
예를 들어 새 환경과 app을 시작할 때 다음처럼 복제합니다.
|
|
|
|
```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/apps/_template gitops/apps/example-api
|
|
```
|
|
|
|
복제 후 `__REPLACE_ME_*__` 값을 교체하고, 실제 cluster root에서 필요한
|
|
catalog만 참조합니다.
|
|
|
|
## Current architecture
|
|
|
|
```text
|
|
Traefik -> oauth2-proxy -> auth-server -> PostgreSQL
|
|
\-> Keycloak
|
|
docker-registry -> MinIO
|
|
|
|
Vault KV-v2 -> Vault Secrets Operator -> Kubernetes Secret -> workload
|
|
```
|
|
|
|
- Namespace `mnt`에는 PSS Restricted와 default-deny NetworkPolicy를 적용합니다.
|
|
- K3s packaged Traefik manifest는 수정하지 않고 `HelmChartConfig`만 관리합니다.
|
|
- Flyway와 Keycloak realm import는 versioned one-shot operation입니다.
|
|
- `lab`의 PostgreSQL, Vault와 MinIO는 운영 HA/backup 설계가 아닙니다.
|
|
|
|
## Deploy
|
|
|
|
```bash
|
|
export KUBE_CONTEXT_LAB='<expected-context>'
|
|
bash scripts/bin/bootstrap.sh lab
|
|
```
|
|
|
|
배포 순서는 다음과 같습니다.
|
|
|
|
```text
|
|
namespaces
|
|
00-platform
|
|
10-vault
|
|
20-secrets
|
|
30-data
|
|
35-registry
|
|
40-operations
|
|
50-apps
|
|
```
|
|
|
|
`gitops/clusters/lab/main/all`은 직접 apply하지 않습니다. CRD establishment,
|
|
Vault 초기화, Secret materialization과 migration 완료는 한 번의 Kustomize
|
|
apply로 표현할 수 없습니다.
|
|
|
|
## Validate
|
|
|
|
```bash
|
|
make doctor
|
|
make check
|
|
|
|
# CI와 같은 pinned toolchain을 사용한 full gate
|
|
mise install
|
|
VALIDATION_PROFILE=full make check
|
|
```
|
|
|
|
`make check`는 템플릿 구조/민감 파일/IaC 계약 검증과 프로젝트별
|
|
Kustomize/schema/policy/shell/docs 검증을 모두 실행합니다.
|
|
|
|
## Extension rules
|
|
|
|
- 외부 load balancer, VPC와 DNS는 `infrastructure/components`에서 구현하고
|
|
`infrastructure/live` root가 조립합니다.
|
|
- in-cluster ingress/LB controller, Istio 같은 service mesh는
|
|
`gitops/platform/<unit>`에 두고 cluster stage가 선택합니다.
|
|
- sidecar는 workload 기본 계약이면 app `base`, 환경별 선택이면 해당
|
|
`overlays/<env>`에 patch/component로 구성합니다.
|
|
- VSO와 secret delivery controller는 `gitops/platform/secret-delivery`,
|
|
실제 비밀값은 Vault에 둡니다.
|
|
- 규모가 커지면 `live/<provider>/<account>/<region>/<env>/<stack>`과
|
|
`clusters/<env>/<region>/<cluster>`로 깊이만 확장하고 ownership 경계는
|
|
유지합니다.
|
|
|
|
## Secret incident boundary
|
|
|
|
`vault-init-keys.json`은 Git에서 제외되며 로컬 권한은 `0600`이어야 합니다.
|
|
과거 Git 이력에 포함된 값은 이미 노출된 것으로 간주해야 하므로 실제 Vault
|
|
root token과 unseal/recovery material을 회전한 뒤, 협업자와 조율하여 원격
|
|
이력을 별도로 정리해야 합니다.
|
|
|
|
## Documentation
|
|
|
|
- [실행 가이드](guide.md)
|
|
- [프로젝트 아키텍처](docs/architecture.md)
|
|
- [스켈레톤 구조 계약](docs/architecture/repository-structure.md)
|
|
- [운영과 검증](docs/operations.md)
|
|
- [Vault와 VSO](docs/vault-vso.md)
|
|
- [Ingress와 Traefik](docs/ingress-traefik.md)
|
|
- [보안 강화](docs/security-hardening.md)
|
|
- [장애 기록](docs/troubleshooting.md)
|
|
- [템플릿 사용 가이드](docs/guides/getting-started.md)
|