# Project GitOps

Project Auth의 `dev-k3s` 배포 상태를 관리하는 GitOps configuration
저장소입니다. 배포 기준 저장소는 내부 Gitea 한 곳입니다.

```text
https://git.learn.hyeonworks.com/donghyeon.kang/project-gitops
```

애플리케이션 소스 저장소는 이미지를 빌드해 GHCR에 올리고, 이 저장소에는
배포할 immutable digest를 변경하는 PR만 생성합니다. Kubernetes 리소스는
Argo CD만 반영하며, Terraform은 Vault API만 관리합니다.

## 지원 범위

| 대상 | 상태 |
|---|---|
| `dev-k3s` | 지원하는 단일 노드 개발 환경 |
| production | 설계되지 않았으며 manifest/Application이 존재하지 않음 |
| Istio | 보류; 향후 ambient mode 후보 |

현재 dev Vault와 PostgreSQL, ingress는 TLS가 적용되지 않은 개발 프로파일입니다.
production 용도로 사용할 수 없습니다.

## 제어 흐름

```text
app CI -> GHCR digest -> GitOps PR -> validation -> main
                                                   |
                                                   v
                                              Argo CD
                                                   |
                                                   v
                                               Kubernetes

IaC PR -> Terraform plan -> approval -> Terraform apply -> Vault API
```

Argo CD 최초 설치와 root Application seed만 클러스터에 직접 적용합니다.
그 이후 routine deployment는 Git 변경으로만 수행합니다.

## 저장소 구조

```text
bootstrap/argocd/       최초 Argo CD 설치 버전과 단일 root Application
clusters/dev-k3s/
  projects/             AppProject 권한 경계
  applications/         foundation, platform, workload child Applications
  manifests/            dev-k3s가 실제 소비하는 최종 Kustomize 구성
platform/               Vault와 auth platform의 환경 중립 base
workloads/              auth-server와 api-server의 환경 중립 base
iac/terraform/
  modules/              재사용 Vault 모듈
  live/dev-k3s/         vault-core, vault-database state
  backend/dev-k3s/      secret을 포함하지 않는 backend 예시
policies/               Terraform이 소비하는 Vault ACL
hack/                   bootstrap, validation, 조건부 Vault init entrypoint
docs/                   architecture, ADR, recovery/operation runbook
```

cluster-specific namespace, host, image, secret reference는
`clusters/dev-k3s/manifests/`에서 완결합니다. `platform/`과 `workloads/`의
base는 클러스터를 알지 못합니다.

## Terraform state

| Root | 소유 범위 | 실행 권한 |
|---|---|---|
| `vault-core` | mounts, auth backends, policies, Kubernetes/JWT roles, app Transit key | 제한된 관리자 |
| `vault-database` | PostgreSQL connection과 dynamic database roles | `vault-database-automation-dev` |

Vault API 객체 하나는 정확히 한 state만 소유합니다. KV secret payload,
Vault init JSON, token, PostgreSQL password는 Git이나 Terraform state에
저장하지 않습니다. backend는 암호화, versioning, access control,
locking을 제공해야 합니다.

## 주요 명령

```bash
make validate
make bootstrap KUBE_CONTEXT=<expected-context>

make terraform-plan \
  TF_ROOT=vault-core \
  BACKEND_CONFIG=.local/terraform-backend/dev-k3s/vault-core.s3.hcl
```

`terraform-apply`는 동일한 입력과
`APPROVE_APPLY=dev-k3s/<root>`가 모두 있어야 실행되며 `auto-approve`를
사용하지 않습니다.

## 문서

- [빈 dev 클러스터 bootstrap](docs/runbooks/dev-bootstrap.md)
- [배포 구조](docs/architecture/deployment.md)
- [secret trust boundary](docs/architecture/secret-trust.md)
- [Terraform v2 state 이관](docs/runbooks/terraform-state-migration.md)
- [Vault backup/recovery](docs/runbooks/vault-backup-restore.md)
- [Sealed Secrets recovery](docs/runbooks/sealed-secrets-recovery.md)
- [입문 가이드](INTERN_GUIDE.md)