Skip to content

About

Neki On-Premise K3S gitops repository

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Latest commit

 

History

400 Commits

Folders and files

Repository files navigation

gitops-k3s

k3s 클러스터의 Kubernetes 매니페스트를 GitOps 방식으로 관리하는 저장소입니다.

아키텍처 구조

Infrastructure Architecture

디렉토리 구조

gitops-k3s/
├── cluster/                        # 클러스터 전체(네임스페이스 무관) 인프라 리소스
│   ├── cert-manager/
│   │   └── cluster-issuer.yaml     # Let's Encrypt ClusterIssuer
│   ├── coredns/
│   │   └── coredns-hairpin-nat.yaml # Hairpin NAT용 CoreDNS 커스텀 설정
│   ├── k3s/
│   │   └── config.yaml             # 노드 /etc/rancher/k3s/config.yaml (NodePort localhost 전용)
│   └── traefik/
│       └── traefik-helmchart.yaml  # Traefik Ingress Controller HelmChart
└── overlays/                       # 환경별 Kustomize 오버레이
    ├── prod/                       # 프로덕션 환경 (namespace: prod)
    │   ├── kustomization.yaml
    │   ├── namespace.yaml
    │   ├── deployment.yaml         # neki-prod 애플리케이션
    │   ├── ingress.yaml            # HTTP (web entrypoint)
    │   ├── ingressroute-https.yaml # HTTPS (websecure entrypoint)
    │   ├── certificate.yaml        # cert-manager TLS 인증서 요청
    │   ├── monitoring/             # 별도 Application monitoring-prod (argocd/apps/monitoring-prod.yaml)
    │   │   ├── kustomization.yaml  # 대시보드 ConfigMap(grafana-dashboards) 생성 포함
    │   │   ├── monitoring.yaml     # Prometheus / Grafana / Loki / Promtail
    │   │   ├── monitoring-ingressroute.yaml # Grafana HTTPS IngressRoute
    │   │   ├── certificate.yaml    # yapp-monitoring-tls-cert
    │   │   └── dashboards/         # Grafana 대시보드 JSON
    │   ├── admin-web-deployment.yaml   # neki-admin-web (Deployment / Service / PVC) - admin-web-prod
    │   ├── admin-web-ingressroute-https.yaml # neki-admin-web HTTPS IngressRoute - admin-web-prod
    │   ├── admin-web-certificate.yaml  # admin-web-tls-cert - admin-web-prod
    │   ├── admin-web-secret.example.yaml # neki-admin-web 환경변수 예시
    │   ├── admin-web-secret.yaml       # ⚠️ gitignore - 직접 관리 필요
    │   └── secret.yaml             # ⚠️ gitignore - 직접 관리 필요
    └── staging/                    # 스테이징 환경 (namespace: staging)
        ├── kustomization.yaml
        ├── namespace.yaml
        ├── deployment.yaml         # yapp-dev 애플리케이션
        ├── ingress.yaml            # HTTP (web entrypoint)
        ├── ingressroute-https.yaml # HTTPS (websecure entrypoint)
        ├── certificate.yaml        # cert-manager TLS 인증서 요청
        └── secret.yaml             # ⚠️ gitignore - 직접 관리 필요
    └── prefect/                    # Prefect 워크플로 오케스트레이션 (namespace: prefect)
        ├── kustomization.yaml
        ├── namespace.yaml
        ├── server.yaml             # Prefect Server API/UI (NodePort 30420)
        ├── worker.yaml             # Kubernetes work pool 워커 + RBAC
        ├── worker-base-job-template.json # work pool base job template (flow run Job 스펙)
        ├── secret.example.yaml     # DB 비밀번호 Secret 예시
        └── secret.yaml             # ⚠️ gitignore - 직접 관리 필요

클러스터 인프라 (cluster/)

Traefik (cluster/traefik/traefik-helmchart.yaml)

k3s 내장 HelmChart CRD로 Traefik을 커스텀 설정으로 배포합니다.

EntryPoint 내부 포트 외부 노출 포트
web (HTTP) 5678 5678
websecure (HTTPS) 4641 4641

기존 nginx가 80/443 포트를 사용 중이므로 5678/4641 포트를 사용합니다. 공유기/방화벽에서 외부 5678→내부 5678, 외부 4641→내부 4641로 포트포워딩 설정이 필요합니다.

적용 방법:

kubectl apply -f cluster/traefik/traefik-helmchart.yaml

cert-manager (cluster/cert-manager/cluster-issuer.yaml)

Let's Encrypt ACME HTTP-01 챌린지를 통해 TLS 인증서를 자동 발급/갱신합니다.

  • Issuer: letsencrypt-prod (ClusterIssuer)
  • HTTP-01 챌린지 solver: Traefik IngressClass 사용

전제 조건: cert-manager가 클러스터에 먼저 설치되어 있어야 합니다.

# cert-manager 설치 (아직 안 된 경우)
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml

# ClusterIssuer 적용
kubectl apply -f cluster/cert-manager/cluster-issuer.yaml

CoreDNS Hairpin NAT (cluster/coredns/coredns-hairpin-nat.yaml)

클러스터 내부에서 외부 도메인(suitestudy.com)으로 요청 시 공유기를 거치지 않고 직접 노드 IP로 라우팅되도록 CoreDNS를 커스텀 설정합니다.

  • yapp.suitestudy.com → 192.168.219.106
  • dev-yapp.suitestudy.com → 192.168.219.106
  • yapp-monitoring.suitestudy.com → 192.168.219.106
kubectl apply -f cluster/coredns/coredns-hairpin-nat.yaml

k3s 설정 (cluster/k3s/config.yaml)

노드의 /etc/rancher/k3s/config.yaml 원본입니다. NodePort 를 노드 localhost 에서만 받도록(nodeport-addresses=127.0.0.1/32) 해서, ArgoCD·Prefect 같은 NodePort 서비스는 외부에서 열리지 않고 SSH 터널로만 접근됩니다. 이 설정이 없으면 NodePort 가 노드의 모든 인터페이스에서 열리고, 공유기가 포트를 넘기는 한 터널 없이도 인터넷에서 바로 접근됩니다. Traefik(4641/5678)은 servicelb 가 ClusterIP 로 넘기므로 영향이 없습니다.

서비스 터널 브라우저
ArgoCD ssh -L 8443:localhost:32693 -p <PORT> yapp@suitestudy.com https://localhost:8443
Prefect ssh -L 30420:localhost:30420 -p <PORT> yapp@suitestudy.com http://localhost:30420

ArgoCD 가 동기화하지 않으므로 바꾸면 노드에 직접 반영하고 k3s 를 재시작합니다. 재시작해도 파드는 계속 돌고, API 서버만 잠깐 끊깁니다.

scp -P <PORT> cluster/k3s/config.yaml yapp@suitestudy.com:/tmp/k3s-config.yaml
ssh -p <PORT> yapp@suitestudy.com
sudo cp /etc/rancher/k3s/config.yaml /etc/rancher/k3s/config.yaml.bak
sudo install -o root -g root -m 644 /tmp/k3s-config.yaml /etc/rancher/k3s/config.yaml
sudo systemctl restart k3s

환경별 오버레이 (overlays/)

도메인 구성

환경 도메인 네임스페이스
prod yapp.suitestudy.com prod
prod (모니터링) yapp-monitoring.suitestudy.com prod
prod (어드민) admin-web.suitestudy.com prod
staging dev-yapp.suitestudy.com staging

TLS 인증서

각 환경의 certificate.yaml이 cert-manager에게 인증서 발급을 요청합니다. cert-manager가 Let's Encrypt에서 인증서를 발급받아 Secret으로 자동 저장합니다.

환경 Certificate 이름 생성되는 Secret
prod neki-tls-cert neki-tls-cert
prod yapp-monitoring-tls-cert yapp-monitoring-tls-cert
prod admin-web-tls-cert admin-web-tls-cert
staging dev-yapp-tls-cert dev-yapp-tls-cert

IngressRoute에서 tls.secretName으로 이 Secret을 참조합니다.

적용 방법

# prod 전체 적용
kubectl apply -k overlays/prod/

# staging 전체 적용
kubectl apply -k overlays/staging/

Neki Admin (overlays/prod/admin-web-*.yaml)

Team-Neki-Admin 의 운영자 관리 페이지(Next.js standalone) 입니다. 별도 ArgoCD Application admin-web-prod(argocd/apps/admin-web-prod.yaml)가 overlays/prod 의 admin-web-*.yaml 만 골라(directory.include) 동기화합니다. neki-prod 의 kustomization.yaml 에는 넣지 않습니다. 매니페스트 파일을 추가하면 include 목록에도 넣어야 합니다.

구성요소 리소스 비고
neki-admin-web Deployment (replicas 1) / Service (ClusterIP 80→3000) ghcr.io/team-neki/neki-admin-web
(미사용) PersistentVolumeClaim 1Gi (local-path) /app/.data 마운트. 현재 앱이 쓰지 않음
환경변수 Secret neki-admin-web-secret ConfigMap 없이 전부 여기. ⚠️ gitignore - 직접 관리

접속: https://admin-web.suitestudy.com:4641 (Traefik websecure 는 4641 포트)

이미지

태그는 overlays/prod/admin-web-deployment.yaml 의 image: 줄에 직접 적습니다. neki-prod / sprint / notification 과 같은 방식이고, Team-Neki-Admin 의 빌드 워크플로가 그 줄을 갱신하면 ArgoCD 가 롤링합니다.

이미지는 한 곳에서만 참조합니다. sprint-deployment.yaml 처럼 같은 이미지를 여러 줄에 적으면 갱신에서 하나를 놓쳤을 때 컨테이너마다 버전이 갈리는데, 파드는 정상 기동하므로 드러나지 않습니다. 워크플로는 갱신 전후의 참조 개수를 비교해 이 경우를 막습니다.

GHCR 패키지는 team-neki-workflow 처럼 공개(public) 여야 합니다. 비공개로 두면 파드가 ImagePullBackOff 로 멈추므로, 그 경우에는 dockerconfigjson 타입 Secret 을 만들고 admin-web-deployment.yaml 에 imagePullSecrets 를 추가해야 합니다.

PVC 와 replicas: 1 / Recreate

원래는 Amplitude 일별 집계를 SQLite 파일 하나에 캐시했기 때문에 replicas: 1 고정, strategy: Recreate 였습니다. local-path PVC 는 ReadWriteOnce 이고 노드 로컬이라 RollingUpdate 로 두면 새 파드와 기존 파드가 겹치는 순간 같은 볼륨을 동시에 붙잡기 때문입니다.

Team-Neki-Admin 이 75cf4f7 에서 로컬 저장소를 걷어내고 관리자 API 프록시로 바뀌었습니다. 그래서 SQLite 의존성은 없습니다. 하지만 2026-10-10 에 확인해 보니 /app/.data/amplitude/ (daily, metrics-ranges, dashboard-ranges) 아래에 파일 59개(276K)가 있었습니다. 파드 기동(09-18) 이후인 10-06 에 수정된 파일도 있어, 실행 중인 앱은 아직 이 경로에 캐시를 씁니다. 따라서 PVC 는 그대로 두고, ArgoCD 가 지우지 않도록 Prune=false,Delete=false 를 붙였습니다. fsGroup·Recreate 를 걷어낼지는 앱이 이 경로를 정말 안 쓰게 된 뒤에 정합니다.

Secret

admin-web-secret.example.yaml 을 admin-web-secret.yaml 로 복사해 값을 채우고 직접 apply 합니다.

kubectl apply -f overlays/prod/admin-web-secret.yaml

ConfigMap 은 두지 않습니다. 비민감 값(TZ 등)까지 이 Secret 하나에 모으고, deployment 의 envFrom 도 secretRef 하나뿐입니다.

현재 넣어 둔 이름과 앱이 실제로 읽는 이름이 다릅니다. 관리자 백엔드와 오픈뱅킹 OAuth 가 붙는 것을 전제로 미리 맞춰 둔 이름이라, 아래 표의 "앱이 읽나" 가 ✗ 인 값들은 지금은 아무 효과가 없습니다. 값을 추가할 때는 코드가 그 이름을 읽는지 먼저 확인하세요. 읽지 않는 이름은 파드를 정상 기동시킨 채 화면만 비게 만듭니다.

현재 Secret 에 들어 있는 값

환경변수 앱이 읽나 값
TZ (Node 런타임) Asia/Seoul
AMPLITUDE_API_KEY ✗ 설정됨
AMPLITUDE_SECRET_KEY ✗ 설정됨
AMPLITUDE_REGION ✗ us
GROUP_ACCOUNT_DATA_MODE ✓ app/api/group-account/group-account-server.ts live
OPENBANKING_BASE_URL ✓ 〃 설정됨
OPENBANKING_CLIENT_ID ✗ 설정됨
OPENBANKING_CLIENT_SECRET ✗ 설정됨
OPENBANKING_REDIRECT_URI ✗ 설정됨
OPENBANKING_SCOPE ✗ login inquiry
OPENBANKING_AUTH_TYPE ✗ 0
OPENBANKING_CLIENT_USE_CODE ✗ 빈 값

앱이 읽지만 아직 넣지 않은 값

환경변수 읽는 곳 없을 때 동작
NEKI_ADMIN_DASHBOARD_API_URL app/api/amplitude/dashboard/route.ts 503 admin_api_not_configured
NEKI_ADMIN_ANALYTICS_API_URL app/api/amplitude/metrics/route.ts 503 admin_api_not_configured
OPENBANKING_ACCESS_TOKEN group-account-server.ts 모임통장 "연결 전" 표시
OPENBANKING_FINTECH_USE_NUM 〃 〃
OPENBANKING_BANK_TRAN_ID 〃 〃

그래서 지금 배포하면 대시보드는 빈 채로, 모임통장은 "계좌 연결 정보가 없습니다" 로 뜹니다. 파드 자체는 정상입니다. 관리자 백엔드가 뜨면 URL 두 개를 Secret 에 넣고 kubectl apply 후 kubectl -n prod rollout restart deploy/neki-admin-web 하면 됩니다.

남은 작업

  • 앱 인증 없음. 현재 어드민에는 자체 로그인이 없어 도메인을 아는 누구나 접근할 수 있습니다. 앱에 로그인을 붙이거나, Traefik basicAuth / ipAllowList 미들웨어를 admin-web-ingressroute-https.yaml 에 추가해야 합니다.
  • health 엔드포인트 없음. /api/health 가 없어 readiness 가 / 를 SSR 합니다. 주기를 30s 로 늘려 부담을 줄였지만, 앱에 /api/health 가 추가되면 probe 를 그쪽으로 옮기는 편이 낫습니다.

Prefect (overlays/prefect/, overlays/prefect-stg/)

Prefect 3 서버와 메타데이터 DB 는 공통으로 쓰고, prod/stg worker 와 flow run Job 은 각각 prefect/prefect-stg 네임스페이스에서 실행합니다. ArgoCD Application 은 prefect 와 prefect-stg 입니다. 메타데이터 DB 는 클러스터 안에 두지 않고 노드(호스트)의 PostgreSQL 14 를 사용합니다.

구성요소 리소스 비고
prefect-server Deployment / Service(NodePort 30420) prefecthq/prefect:3.8.5-python3.11
prefect-worker Deployment / Role / RoleBinding work pool neki-pool 자동 생성, flow run 은 prefect 네임스페이스에 Job 으로 실행
(DB) 호스트 PostgreSQL 14 (192.168.219.106:5432, DB/role prefect) 클러스터 리소스 없음. 파드 → 노드 IP 로 직접 접속
prefect-stg-worker prefect-stg 네임스페이스의 Deployment / Role / RoleBinding neki-stg-pool, flow run Job 도 prefect-stg 에 실행

접속

외부(DNS/nginx/TLS) 노출 없이 SSH 터널로만 접근합니다. NodePort 30420 은 노드 localhost 에서만 열립니다(k3s 설정). UI 가 API 를 http://localhost:30420/api 로 호출하도록 설정되어 있으므로 로컬 포트도 30420 으로 맞춰야 합니다.

ssh -L 30420:localhost:30420 -p <PORT> yapp@suitestudy.com
# 브라우저: http://localhost:30420

flow 코드에서 접속할 때(클러스터 내부): PREFECT_API_URL=http://prefect-server.prefect.svc.cluster.local:4200/api

Secret

overlays/prefect/secret.yaml (gitignore) 에 호스트 DB prefect role 의 비밀번호가 있습니다(Secret prefect-db). secret.example.yaml 을 복사해 만들고 직접 apply 합니다. 호스트 DB 에 role/database 를 만드는 방법은 secret.example.yaml 주석을 참고하세요.

flow 가 바깥(Kakao, 앱 DB, S3)에 붙을 때 쓰는 값은 각 네임스페이스의 prefect-workflow Secret 입니다. 각 overlay 의 workflow-secret.example.yaml 을 복사해 실제 Secret 을 직접 적용합니다. worker 가 아니라 flow run Job 파드가 읽습니다. Secret 이 없으면 flow run Job 파드가 CreateContainerConfigError 로 뜨지 않습니다. prod Secret 은 운영 앱 DB/버킷, stg Secret 은 dev_yapp/staging-team-neki-workflow 를 가리켜야 합니다. 기존 prefect Secret 의 실제 값을 확인하지 않고 prod 라고 가정해 배포하면 안 됩니다.

키 쓰는 flow 없으면
KAKAO_API_KEY 지점 수집 (picdot 등 Kakao 수집원 브랜드, 좌표 보정) Kakao 수집원 브랜드는 실패, 나머지는 좌표 보정 건너뜀
DATABASE_URL legal-dong (법정동 코드), subway-station (지하철 역). 앱 DB 에 직접 적재 flow 가 시작 직후 RuntimeError 로 실패
S3_BUCKET 지점 수집 (stores-collect, 브랜드별 *-stores). 수집 결과를 S3 raw/ collect/ runs/ 에 적재. 환경 접두를 붙인 staging-team-neki-workflow 또는 prod-team-neki-workflow 적재 시점에 RuntimeError 로 실패
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION 지점 수집. boto3 기본 자격증명 체인이 집어감. IAM role 없음 S3 PUT 에서 NoCredentialsError 로 실패

k3s 에서는 LocalStack 을 쓰지 않고 기존 staging-team-neki-workflow, prod-team-neki-workflow 버킷을 각각 사용합니다. 각 Secret 의 S3_BUCKET 과 DATABASE_URL 은 같은 환경이어야 합니다. 두 work pool 은 공통 Prefect API 를 쓰지만 deployment 이름은 stg 에만 -stg 접미사를 붙여 구분합니다. 검색 색인 Batch Job 은 flow run 파드의 service account namespace 에 생성됩니다.

S3 자격증명은 환경별 버킷만 접근하도록 나누고 s3:PutObject, s3:GetObject, s3:ListBucket 을 허용합니다. 최신 파티션을 목록 조회로 찾고 실패한 브랜드를 이전 파티션으로 대신하므로 쓰기만으로는 부족합니다. AWS_PROFILE, AWS_ENDPOINT_URL 은 로컬 LocalStack 용이므로 넣지 않습니다.

DATABASE_URL 은 파드에서 붙으므로 호스트를 localhost 로 적으면 안 됩니다. 노드 IP 또는 클러스터 Service 주소를 씁니다. 대상은 Prefect 메타DB(prefect-db)가 아니라 Team-Neki-Server 가 쓰는 앱 DB 입니다.

기존 prod 설치 명령입니다. staging 최초 설치는 아래 절차로 분리합니다.

kubectl apply -f overlays/prefect/secret.yaml
kubectl apply -f overlays/prefect/workflow-secret.yaml
kubectl apply -k overlays/prefect/

staging 최초 설치

staging worker 는 최초 설치 시 replicas: 0 입니다. Application 이 먼저 동기화돼도 지원하지 않는 초기 이미지로 worker 를 시작하지 않습니다. 준비 후 GitOps 에서 replicas: 1 로 변경해야 합니다. kubectl scale 만 사용하면 ArgoCD selfHeal 이 다시 0으로 되돌립니다.

  1. GitOps staging overlay 를 먼저 병합합니다.

  2. Workflow PR #34를 병합하거나 해당 브랜치의 build 액션을 environment=stg로 실행합니다. build가 성공하고 GitOps main의 staging worker 이미지 두 곳이 --environment stg 지원 이미지로 갱신됐는지 확인합니다. 초기 태그 0.1.1-a593d55 상태로는 worker 를 활성화하지 않습니다.

  3. 최신 GitOps main을 받은 뒤 namespace를 먼저 만들고 staging Secret을 적용합니다. 실제 Secret은 workflow-secret.example.yaml을 복사해 staging 값으로 작성합니다.

    git pull --ff-only
    kubectl apply -f overlays/prefect-stg/namespace.yaml
    kubectl apply -f overlays/prefect-stg/workflow-secret.yaml
  4. overlays/prefect-stg/worker.yaml의 replicas를 1로 바꾸는 커밋을 main에 반영한 뒤 Application을 적용합니다. 이미 적용된 Application은 그 커밋을 자동 동기화합니다.

    kubectl apply -f argocd/apps/prefect-stg.yaml
    kubectl -n prefect-stg rollout status deployment/prefect-worker
  5. 첫 initContainer가 neki-stg-pool을 staging template과 함께 생성하거나 갱신합니다. Prefect UI에서 pool의 namespace가 prefect-stg이고 Secret/ConfigMap 참조가 있는지 확인합니다. 새 -stg deployment는 pause 상태입니다. 수동 실행으로 DB/S3 대상과 검색 Batch Job을 확인한 뒤 필요한 스케줄만 켭니다.

ArgoCD를 사용하지 않고 overlay를 직접 적용할 때도 위 이미지·Secret 준비와 replicas: 1 변경을 마친 뒤 kubectl apply -k overlays/prefect-stg/를 실행합니다.

업그레이드

server.yaml / worker.yaml 의 이미지 태그를 같은 Prefect 버전으로 올립니다(워커는 -kubernetes 접미사 이미지). DB 마이그레이션은 서버 기동 시 자동 수행됩니다. work pool 의 base job template 을 바꾸려면 worker-base-job-template.json 을 수정하면 워커 재기동 시 initContainer 가 work pool 에 동기화합니다.

gitignore 처리 대상

다음 파일들은 민감 정보를 포함하므로 Git에 올리지 않고 직접 관리합니다.

파일 내용 관리 방법
overlays/prod/secret.yaml jasypt 암호화 키 서버에서 직접 kubectl apply
overlays/staging/secret.yaml jasypt 암호화 키 서버에서 직접 kubectl apply
overlays/prefect/secret.yaml Prefect DB 비밀번호 서버에서 직접 kubectl apply
overlays/prod/admin-web-secret.yaml neki-admin-web 환경변수 전체 서버에서 직접 kubectl apply

TLS Secret(tls-secret.yaml)은 cert-manager의 Certificate로 대체되어 더 이상 사용하지 않습니다.

전체 초기 배포 순서

# 1. cert-manager 설치
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml
kubectl wait --for=condition=available deployment --all -n cert-manager --timeout=120s

# 2. 클러스터 인프라 적용
kubectl apply -f cluster/traefik/traefik-helmchart.yaml
kubectl apply -f cluster/coredns/coredns-hairpin-nat.yaml
kubectl apply -f cluster/cert-manager/cluster-issuer.yaml

# 3. App Secret 적용 (gitignore 파일 - 직접 관리)
kubectl apply -f overlays/prod/secret.yaml
kubectl apply -f overlays/staging/secret.yaml
kubectl apply -f overlays/prod/admin-web-secret.yaml

# 4. 환경별 리소스 적용
kubectl apply -k overlays/prod/
kubectl apply -k overlays/staging/

Spring Batch 이미지 배포

Server의 Deploy Batch (GHCR + GitOps)를 수동 실행하며 environment=stg 또는 prod 를 선택한다. 워크플로는 해당 overlay 의 images.env 에서 NEKI_BATCH_IMAGE를 GHCR의 버전-SHA 태그로 갱신한다. 각 네임스페이스의 고정 이름 ConfigMap neki-images를 Prefect flow Job이 envFrom으로 읽는다. 별도의 상주 batch Deployment를 만들지 않는다.

초기 :main 값은 첫 배포 전 자리표시자다. 최초 이미지 게시와 GitOps 태그 갱신을 완료한 뒤 배치를 호출한다. 배치 이미지는 pull secret을 사용하지 않으므로 GHCR 패키지를 public으로 제공해야 한다. API가 먼저 배포되어 배치 메타 테이블 마이그레이션이 적용되어 있어야 한다.

Job 템플릿 ConfigMap에는 내용 해시를 적용해 변경 시 worker의 볼륨 참조와 Pod가 갱신되고 initContainer가 work pool 템플릿을 다시 동기화한다. 이미지 태그 ConfigMap은 고정 이름을 유지하므로 이후 태그 변경만으로 worker를 재기동할 필요는 없다. 실행 중인 flow Job의 환경은 바뀌지 않으며 다음 Job부터 새 값을 읽는다.

Admin API (admin-api Application)

Server의 apps/admin을 독립 ArgoCD Application으로 배포합니다. argocd/apps/admin-api.yaml은 overlays/admin-api만 관리하며 기존 neki-prod와 리소스를 공유하지 않습니다. namespace는 prod, Deployment는 neki-admin-api, replicas: 1, RollingUpdate(maxSurge=1, maxUnavailable=0)입니다. 롤링 중에만 새 Pod와 기존 Pod가 겹칠 수 있으며, 세션은 PostgreSQL에 공유합니다.

Google OIDC와 Spring Session JDBC를 사용합니다. 운영자가 기존 TB_USERS.role에 ROLE_ADMIN을 부여·회수하며 Spring이 매 관리 요청에서 현재 DB 권한을 확인합니다. 세션은 마지막 접근 후 30분간 요청이 없으면 만료됩니다. 메모리 H2/local 프로파일은 배포하지 않습니다.

Service 주소는 http://neki-admin-api-service.prod.svc.cluster.local:8081입니다. 외부 Ingress/NodePort는 만들지 않으며 Next 서버 프록시가 이 주소로 요청합니다. Next 로그인·콜백·세션 쿠키 프록시는 별도 연결 작업입니다. Spring 직접 콜백 개발은 로컬 실행 또는 port-forward로 검증할 수 있습니다. 운영 쿠키는 Secure이므로 실제 브라우저 연결은 HTTPS를 사용하고, URI·호스트가 확정된 뒤 Google에 등록합니다.

Secret

overlays/admin-api/secret.example.yaml을 secret.yaml로 복사해 실제 값으로 채웁니다. secret.yaml은 기존 gitignore 규칙으로 커밋되지 않습니다. Secret은 예시나 Kustomization에 포함하지 않고 운영자가 직접 적용합니다.

  • GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET: Google Web application 클라이언트 자격증명
  • ADMIN_OAUTH_REDIRECT_URI: 브라우저가 접근할 수 있는 외부 콜백. Google 등록값과 정확히 일치

Secret이 없으면 Pod는 시작하지 않으며, 설정 변경 후에는 Deployment를 재시작해야 합니다. DB 연결은 API와 같은 postgres 공통 설정을 사용합니다. 기존 neki-secrets의 jasypt-password를 JASYPT_PASSWORD로 주입해 암호화된 연결 정보를 읽습니다. 기존 DB Secret을 복제하거나 별도 admin DB·스키마를 만들지 않습니다.

최초 배포

  1. GitOps 구성을 main에 먼저 머지합니다. 아직 Application은 apply하지 않습니다. bootstrap은 자리표시자이며 실제 이미지가 아닙니다.

  2. Server의 세션 인증 #361을 main에 머지합니다. 공유 DB 마이그레이션 V41·V42·V43은 이 PR이 추가하며, main push로 실행되는 API prod 배포가 Flyway로 적용합니다. API 롤아웃 후 flyway_schema_history에 V43까지 성공으로 기록됐는지 확인합니다. admin은 Flyway validate만 수행하므로 세션 스키마·관리자 계정 전환·공동 관리 미디어 컬럼이 미적용이면 기동을 거부합니다.

  3. V43 적용을 확인한 뒤 Server Actions의 **Deploy Admin API (GHCR + GitOps)**를 수동 실행합니다. Server 저장소의 admin-production 보호 환경에 승인자와 ADMIN_GITOPS_PAT 환경 secret이 있어야 합니다. 워크플로가 deployment.yaml의 이미지 한 줄을 sha-<전체 커밋 SHA> 태그로 갱신합니다. 브랜드 #358(V44)과 포즈 #359는 #361을 기반으로 하며, 각 기능을 쓰기 전에 같은 방식으로 머지 → API 배포로 마이그레이션 적용 확인 → admin 재배포 순서를 따릅니다.

  4. GHCR neki-admin-api 패키지를 public으로 설정합니다. 이 구성은 imagePullSecret을 사용하지 않으므로 private 패키지는 가져올 수 없습니다.

  5. prod namespace의 기존 neki-secrets 준비를 확인하고 OAuth Secret을 적용한 뒤 Application을 등록합니다.

    kubectl apply -f overlays/admin-api/secret.yaml
    kubectl apply -f argocd/apps/admin-api.yaml
    kubectl rollout status deployment/neki-admin-api -n prod --timeout=180s
    kubectl port-forward -n prod svc/neki-admin-api-service 8081:8081

로그인하지 않은 /admin/v1/auth/me는 HTTP 401이어야 합니다. Google callback URI가 준비되면 로그인 → me에서 사용자/권한/CSRF 조회 → DB ADMIN 부여 → 같은 세션으로 관리 요청 허용 → ADMIN 회수 후 403 → CSRF를 포함한 로그아웃을 확인합니다. GitOps 커밋 완료는 실제 ArgoCD rollout 성공을 뜻하지 않습니다.

이후 배포는 동일 워크플로를 수동 실행하면 ArgoCD가 이미지 태그 변경을 반영합니다. 이전 SHA를 다시 빌드해 롤백할 수 있지만 DB 마이그레이션은 유지됩니다. 인증·PostgreSQL 지원 전의 H2 기반 이미지로 되돌리면 같은 운영 계약을 보장하지 못합니다.

About

Neki On-Premise K3S gitops repository

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors