# Project Infra 실행 가이드

## 1. 준비

필수:

- `kubectl`, `helm`, `jq`, `openssl`
- 대상 K3s cluster의 kubeconfig
- 환경과 정확히 매핑한 context 변수

```bash
export KUBE_CONTEXT_LAB='<expected-context>'
kubectl config current-context
```

전체 정적 도구는 `mise install`로 설치할 수 있습니다.

## 2. 사전 렌더

```bash
kubectl kustomize gitops/clusters/lab/main/all >/tmp/project-infra-lab.yaml
make check
```

`all`은 감사용입니다. 렌더 결과를 `kubectl apply -f`로 적용하지 마세요.

## 3. Bootstrap

대화형:

```bash
bash scripts/bin/bootstrap.sh lab
```

비대화 환경에서는 각 stage 확인을 명시적으로 승인합니다.

```bash
CONFIRM=yes AUTO_GENERATE=yes \
  bash scripts/bin/bootstrap.sh lab
```

`AUTO_GENERATE=yes`로 생성한 비밀번호는 출력하지 않습니다. Vault에서 권한을
가진 운영자가 별도로 확인합니다.

기본 Vault init 파일은 ignored 상태이지만 평문입니다. 가능하면 repo 밖 경로를
사용하세요.

```bash
VAULT_KEYS_FILE=/secure/path/lab-vault-init.json \
  bash scripts/bin/bootstrap.sh lab
```

## 4. Stage별 확인

```bash
kubectl -n mnt get pods
kubectl -n mnt get vaultconnection,vaultauth,vaultstaticsecret
kubectl -n mnt get jobs
kubectl -n mnt get keycloak,keycloakrealmimport
```

기대 one-shot 결과:

```bash
kubectl -n mnt wait --for=condition=Complete \
  job/auth-server-migrate-0-1-0 --timeout=1800s
kubectl -n mnt wait --for=condition=Done \
  keycloakrealmimport/platform-realm-v1 --timeout=600s
```

## 5. 개별 stage 진단

bootstrap이 실패하면 실패한 stage를 먼저 렌더하고 diff합니다.

```bash
stage='30-data'
kubectl kustomize "gitops/clusters/lab/main/stages/$stage" >/tmp/stage.yaml
kubectl apply -f /tmp/stage.yaml --dry-run=server --server-side
kubectl diff -f /tmp/stage.yaml --server-side
```

의존 stage가 준비되지 않은 상태에서 뒤 stage를 apply하지 마세요. 특히
`20-secrets`는 VSO CRD/controller와 Vault auth가, `30-data`는 선행
destination Secret이, `35-registry`는 MinIO bucket/access key와 Vault 경로가,
`40-operations`는 DB와 Keycloak이 준비되어야 합니다.

## 6. Migration과 realm 변경

Flyway SQL을 추가하거나 수정해 새 release를 만들 때:

1. SQL version을 추가합니다. 이미 적용된 migration을 수정하지 않습니다.
2. Job 이름과 instance label의 release suffix를 올립니다.
3. bootstrap의 completion target도 새 Job 이름으로 맞춥니다.
4. render/schema/diff 후 operation stage를 실행합니다.

Realm 변경도 기존 `platform-realm-v1` spec을 고쳐 재실행되는 것으로 가정하지
않습니다. 새 versioned KeycloakRealmImport operation을 만들고 완료 상태를
확인합니다.

## 7. Teardown

앱과 operation만:

```bash
bash scripts/bin/teardown.sh lab
```

데이터와 namespace 포함:

```bash
DELETE_DATA=yes bash scripts/bin/teardown.sh lab
```

전용 lab cluster에서 공유 operator까지:

```bash
DELETE_DATA=yes TEARDOWN_PLATFORM=yes \
  bash scripts/bin/teardown.sh lab
```

## 8. 금지 사항

- `gitops/clusters/lab/main/all` 직접 apply
- K3s packaged manifest 직접 수정
- `vault-init-keys.json` commit
- Secret 값을 shell argv나 문서 예시에 기록
- 완료된 Flyway Job을 이유 없이 삭제해 같은 release 재실행
- 데이터 삭제 flag 없이 finalizer 강제 제거