# 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)