Project Infra 실행 가이드

1. 준비

필수:

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

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

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

2. 사전 렌더

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

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

3. Bootstrap

대화형:

bash scripts/bin/bootstrap.sh lab

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

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

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

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

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

4. Stage별 확인

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 결과:

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합니다.

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를 만들 때:

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

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

7. Teardown

앱과 operation만:

bash scripts/bin/teardown.sh lab

데이터와 namespace 포함:

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

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

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 강제 제거

3.4 KiB Raw Blame History