GitOps 개요

목적

Lumie의 인프라 저장소는 Argo CD의 App-of-Apps 패턴을 사용해 lumie-infra로부터 클러스터를 조정합니다. Ansible은 Argo CD의 첫 설치와 소수의 부트스트랩 시크릿만 수행하고, 그 이후에는 선언된 상태가 Git에서 Argo CD Application을 거쳐 네임스페이스 워크로드로 흘러가야 합니다.

이 페이지는 lumie-infra, 부트스트랩 자동화, GitOps 전달 경로를 변경하는 개발자를 위한 개요 문서입니다. 컨트롤러별 상세 내용은 Argo CD, CI/CD, Gitea, Tekton, Zot를 참고하세요.

소스 경로

경로	역할
lumie-infra/provision/ansible/roles/argocd-bootstrap/tasks/main.yml	Argo CD, 부트스트랩 네임스페이스, 정적 MinIO 또는 Vault 시크릿의 첫 설치 경로
lumie-infra/provision/ansible/roles/argocd-bootstrap/defaults/main.yml	Argo CD 준비 후 Ansible이 적용하는 루트 앱 목록
lumie-infra/bootstrap/application.yaml	동기화 wave -1로 적용되는 부트스트랩 서브트리용 루트 Application
lumie-infra/bootstrap/kustomization.yaml	부트스트랩 하위 순서: MinIO, Zot, Vault, 그다음 Gitea
lumie-infra/{platform,storage,security,observability,applications}/application.yaml	나머지 GitOps 계층의 루트 Application
lumie-infra/applications/kustomization.yaml	Argo CD 자체 관리, 이미지 태그 자동화, Lumie 서비스, 비활성 Tekton 항목을 포함한 application 서브트리 등록
lumie-infra/applications/cluster-bootstrap/**	ClusterIssuer, 기본 StorageClass 같은 클러스터 범위 one-shot 리소스

소유권 경계

계층	단일 출처	비고
첫 설치	provision/ansible/roles/argocd-bootstrap/**	최소 Helm 릴리스로 Argo CD를 설치하고 루트 Application 매니페스트를 적용
루트 GitOps 트리	bootstrap/, platform/, storage/, security/, observability/, applications/	각 디렉터리가 하나의 루트 Application CR과 그 하위 트리를 소유
하위 애플리케이션	applications/**, platform/** 및 동급 디렉터리	개별 앱이 네임스페이스 범위 워크로드 매니페스트와 Helm values를 소유
빌드 출력	저장소 .github/workflows/ci.yml 및 applications/argocd-image-updater/**	GitHub Actions가 이미지를 빌드하고, Zot이 이미지를 저장하며, argocd-image-updater가 태그를 lumie-infra에 다시 기록하고, 실제 롤아웃은 Argo CD가 수행

클러스터는 부트스트랩 이후 수동 구성 대상이 아닙니다. 어떤 컨트롤러, 시크릿, 큐, ingress가 장기적으로 필요하다면 라이브 클러스터에만 존재해서는 안 되며 lumie-infra에 선언된 상태로 남아 있어야 합니다.

런타임 흐름

코드에서 보이는 동기화 순서는 다음과 같습니다.

단계	근거
나머지보다 먼저 부트스트랩 루트 서브트리	bootstrap/application.yaml이 argocd.argoproj.io/sync-wave: "-1" 설정
일반 애플리케이션보다 먼저 cluster-scoped 부트스트랩	applications/cluster-bootstrap/argocd.yaml이 동기화 wave -2 설정
부트스트랩 내부 순서	bootstrap/kustomization.yaml이 minio -> zot -> vault -> gitea 순서를 지정

운영 메모

• 모든 루트 Application은 prune: true와 selfHeal: true가 켜진 자동 동기화를 사용합니다.
• applications/argocd/argocd.yaml은 초기 Ansible 설치 후 Argo CD를 자체 관리 상태로 전환합니다.
• GitOps 접근 경로의 활성 흐름은 GitHub를 중심으로 합니다. Argo CD 루트 Application은 https://github.com/Lumie-Edu/lumie-infra.git에서 lumie-infra를 가져오고, argocd-image-updater도 이미지 태그 갱신을 같은 저장소에 다시 기록합니다. 비활성 Tekton 경로에는 여전히 Gitea 기반 values 갱신 매니페스트가 남아 있습니다. 자세한 내용은 CI/CD와 Gitea를 참고하세요.

계약 드리프트

검사한 소스는 현재 GitOps 경계에 대해 완전히 일치하지 않습니다.

소스	주장
provision/ansible/roles/argocd-bootstrap/defaults/main.yml	bootstrap에 여전히 web-apps/application.yaml이 app_of_apps_paths로 포함됨
lumie-infra 저장소 트리	검사한 저장소에는 web-apps/application.yaml 경로가 없음
2026년 6월 14일 라이브 클러스터	루트 Application은 여섯 개뿐이며 web-apps 루트 Application은 없음

부트스트랩 기본값이 정리되기 전까지 활성 계약은 여섯 루트 모델로 문서화하세요.

가시성을 유지해야 할 Git 호스트 분리도 하나 더 있습니다.

소스	주장
활성 루트 Argo CD Application, Ansible 부트스트랩, argocd-image-updater	GitHub lumie-infra에서 가져오거나 같은 저장소에 다시 기록
비활성 applications/tekton/ci-cd/manifests/tasks/git-update-values.yaml	Tekton을 재활성화하면 배포 values 변경을 http://gitea-http.gitea.svc.cluster.local:3000/Lumie-Edu/lumie-infra.git로 푸시

Tekton을 재활성화하기 전에는 이 Git 호스트 분리를 먼저 해소해야 합니다.

검증

GitOps 영역을 변경할 때는 저장소와 클러스터를 함께 확인하세요.

cd lumie-infra
rg -n "sync-wave|app_of_apps_paths|repoURL: https://github.com/Lumie-Edu/lumie-infra.git|argocd-image-updater|tekton" \
  bootstrap applications platform storage security observability provision/ansible

kubectl get applications -n argocd
kubectl get applications bootstrap platform storage security observability applications -n argocd -o wide

성공 신호:

• 저장소 점검에서 체크인된 여섯 개 루트 Application 경로, applications/ 아래의 cluster-bootstrap 하위 애플리케이션, 활성 argocd-image-updater 등록이 계속 보입니다.
• 라이브 클러스터에는 bootstrap, platform, storage, security, observability, applications 여섯 개의 활성 루트 애플리케이션이 보입니다.
• 오래된 Ansible 기본값을 실제 저장소 경로와 함께 다시 도입하지 않는 한, web-apps라는 이름의 루트 Application은 존재하지 않습니다.