Admin SPA GitOps 배포 노트 — ArgoCD·Kustomize
NFT 런치패드 어드민 SPA 를 ArgoCD·Kustomize 로 배포할 때의 구조와 함정을 정리한 문서
개요
NFT 런치패드 운영자용 어드민 SPA 를 k8s 위에 GitOps 방식으로 배포하는 패턴을 정리한 문서 레포지토리다. 정적 SPA 가 nginx 컨테이너로 서빙되는 런타임 구조와, dev/qa/prod overlay + Jenkins + ArgoCD 로 이어지는 빌드-배포 흐름을 다룬다. 특히 SPA 특유의 '환경 변수는 런타임이 아닌 빌드타임에 결정된다'는 함정과, admin 화면이므로 필요한 VPN/OAuth 기반 접근 제어, SPA 라우팅을 위한 nginx fallback 설정, index.html 과 정적 자산의 캐시 정책 분리 등 운영 관점의 교훈을 코드 없이 문서로만 정리했다. 실제 소스코드 대신 관찰자 시점에서 정리한 아키텍처/교훈/스택 노트로 구성되어 있다.
담당 역할
NFT 런치패드 어드민 프론트엔드의 k8s GitOps 배포 구조를 관찰·분석하고, SPA 배포 특유의 함정과 권장 패턴을 문서로 정리했다.
아키텍처 다이어그램
레포지토리 분석 결과를 바탕으로 자동 생성된 구조도입니다.
SPA 빌드-배포 흐름
코드 변경부터 CI 빌드, ArgoCD reconcile, 어드민 운영자 접근까지의 전체 GitOps 흐름을 보여준다.
정적 파일 서빙 컨테이너 구조
빌드 단계와 런타임 Pod 내부에서 SPA 정적 파일이 어떻게 서빙되는지를 보여준다.
기술스택
각 기술을 이 프로젝트에서 어떤 용도로 썼는지 정리했습니다.
핵심 포인트
- SPA 는 런타임 env 주입이 불가함을 명시하고, 환경별 이미지 분리 빌드 전략을 채택
- 새로고침 404 방지를 위한 nginx SPA fallback(try_files) 설정 정리
- index.html 은 no-store, 해시 자산은 immutable 캐시로 분리하는 캐시 전략 정리
- VPN 화이트리스트만으로는 부족해 OAuth·그룹 권한과 결합해야 함을 명시
- 이미지 태그 고정(latest) 시 ArgoCD sync 가 무효화되는 함정과 SHA/semver 태깅 필요성 기록
문제와 해결
문제SPA 는 브라우저에서 .env 를 읽을 수 없어 k8s Deployment 의 환경 변수만으로는 환경별 API URL 을 다르게 줄 수 없음
해결환경별로 별도 이미지를 빌드(app:dev/qa/prod)하거나, index.html 에 window.__CONFIG__ placeholder 를 두고 nginx 시작 시 ConfigMap 값을 sed 로 주입하는 런타임 inject 패턴 중 하나를 선택
문제SPA 는 client-side 라우팅을 쓰므로 특정 경로에서 새로고침하면 nginx 가 해당 path 파일을 못 찾아 404 발생
해결nginx location 설정에 try_files $uri $uri/ /index.html 을 적용해 모든 요청을 index.html 로 fallback
문제같은 이미지 태그(latest)로 재배포하면 manifest 변경이 없어 ArgoCD 가 변경으로 인식하지 못함
해결이미지 태그를 항상 커밋 SHA 또는 semver 로 고정해 배포마다 manifest 가 변경되도록 함
레포지토리 정보
- 생성
- 2026년 5월 14일
- 최근 커밋
- 2026년 5월 14일
- 크기
- 5 KB
- 라이선스
- 없음
이 문서는 2026년 7월 26일 에 자동 분석으로 생성되었습니다.