argocd

gitops/argocd/

Deck의 repo-internal ArgoCD SSOT다.

현재 1차 범위는 linkpie만 대상으로 하고, 운영 패턴은 lingo, duplo-config와 같이 ArgoCD + Kustomize + ExternalSecret + ALB ingress를 따른다.

구조

경로	설명
projects/	env별 AppProject
root-apps/	env별 App of Apps root application
apps/dev/	dev child applications
apps/stage/	stage child applications
apps/prod/	prod child applications
manifests/linkpie/	linkpie workload base/overlay
manifests/linkpie-postgres/	stage PostgreSQL 18 statefulset
manifests/ingress/	ALB ingress
manifests/secretstore/	External Secrets SecretStore

운영 기준

• dev, prod: 외부 Amazon RDS for PostgreSQL 18를 사용한다.
• stage: deck-postgres PostgreSQL 18 이미지를 별도 app으로 배포한다.
• 앱 런타임은 env별로 SPRING_PROFILES_ACTIVE=dev|stage|prod를 사용한다.
• datasource 공통 계약은 application.yaml의 DATABASE_URL이며, GitOps secret은 DATABASE_URL, APP_CRYPTO_PROVIDERS_ENV_KEK 두 키만 주입한다.
• APP_BASE_URL은 secret이 아니라 env별 overlay ConfigMap에서 관리한다.
• 앱 런타임 Pod는 SPRING_FLYWAY_ENABLED=false로 두고 schema migration을 수행하지 않는다.
• 현재 linkpie migration은 별도 ArgoCD Application이 아니라, 같은 linkpie Application 안의 Sync hook Job 단계로 실행한다.
• linkpie-config ConfigMap은 sync-wave -15, linkpie-secrets ExternalSecret은 sync-wave -10, linkpie-secrets-ready wait hook은 sync-wave -8, migration Job은 sync-wave -5, runtime Deployment는 기본 wave로 배치한다.
• wait hook은 target Secret의 존재만이 아니라 runtime/migration에 필요한 key set(DATABASE_URL, APP_CRYPTO_PROVIDERS_ENV_KEK)이 채워질 때까지 대기한다.
• stage의 linkpie-postgres는 linkpie-postgres-secrets ExternalSecret 뒤에 linkpie-postgres-secrets-ready wait hook을 두고, Secret 생성 완료 후 StatefulSet을 올린다.
• migration job은 동일 linkpie 이미지를 재사용하되 runtime profile을 그대로 쓰고 SPRING_PROFILES_INCLUDE=migration만 추가한다. SPRING_FLYWAY_LOCATIONS=classpath:db/migration/app,classpath:db/migration/linkpie로 app base와 linkpie layer만 실행한다.
• migration 작성 규칙은 Expand-Contract (Parallel Change) 패턴을 따른다.
• image source는 Harbor + ECR dual-push를 유지하되, EKS 런타임은 ECR 경로를 기준으로 둔다.

최소 운영 계약

• Secret: DATABASE_URL, APP_CRYPTO_PROVIDERS_ENV_KEK
• ConfigMap: APP_BASE_URL

앱 런타임은 split datasource env를 읽지 않는다. local script, Tencent compose, single-host bundle도 앱에는 DATABASE_URL만 주입한다. plain local 실행은 공통 fallback URL을 그대로 쓰고, suffix/외부 DB가 필요할 때만 DATABASE_URL을 명시한다.

DATABASE_URL은 아래 형식을 기준으로 관리한다.

jdbc:postgresql://<host>:5432/<db>?user=<username>&password=<password>&sslmode=require

user, password에 &, =, %, ?, # 같은 reserved character가 있으면 percent-encoding해서 넣는다.

사전 조건

• ArgoCD에는 git@github.com:chequer-io/deck.git를 읽을 수 있는 repo credential이 먼저 등록돼 있어야 한다.
• cluster에는 External Secrets Operator와 AWS Load Balancer Controller가 먼저 설치돼 있어야 한다.
• external-secrets-sa는 SecretStore가 가정하는 Pod Identity 또는 IRSA에 먼저 연결돼 있어야 한다.
• ECR 저장소 aip/app/deck-linkpie, aip/app/deck-postgres와 GitHub OIDC push 권한이 먼저 준비돼 있어야 한다.
• GitHub publish 경로에는 아래 설정이 필요하다.
  • repo variable: AIP_AWS_CI_ROLE_ARN
  • repo variable: AIP_AWS_REGION=ap-northeast-2
  • repo variable: AIP_ECR_REGISTRY=536697260860.dkr.ecr.ap-northeast-2.amazonaws.com
  • repo variable: IREG_QUERYPIE_IO_USERNAME — 값: service_ci+deck (Robot 계정, 1Password item "ireg.querypie.io - deck")
  • repo secret: IREG_QUERYPIE_IO_PASSWORD — 1Password item "ireg.querypie.io - deck"

Bootstrap 순서

1. repo credential, External Secrets Operator, Pod Identity/IRSA, ECR, RDS endpoint 같은 사전 조건을 먼저 준비한다.
2. projects/*.yaml을 적용한다.
3. env별 root-apps/*-application.yaml을 적용한다.

이미지/롤아웃 계약

• CI는 immutable tag와 convenience tag를 함께 발행한다.
  • develop: dev-<image-sha>, dev-latest
  • release: <image-sha>, latest
• GitOps overlay는 항상 immutable tag를 commit으로 고정한다.
• 현재 기본 overlay 값은 origin/develop, origin/release 기준으로 이미 발행됐을 가능성이 높은 immutable tag를 가리킨다.
• deterministic rollout은 overlay의 images.newTag를 immutable tag로 갱신하는 PR로 수행한다.
• dev-latest, latest는 로컬/수동 검증용 convenience tag로만 취급하고 GitOps manifest 기본값으로는 사용하지 않는다.

참고 운영 패턴

• duplo-config: config repo 기반 ArgoCD + Kustomize
• lingo: app repo 내부 argocd/ 기반 GitOps