이벤트 리스너 워커 GitOps 배포 노트
블록체인/webhook 이벤트 리스너 워커를 ArgoCD+Kustomize로 배포할 때의 패턴과 함정을 정리한 기술 문서
개요
블록체인 이벤트나 외부 webhook을 수신·처리하는 listener 백엔드 워커를 Kubernetes에 GitOps 방식으로 배포하는 패턴을 정리한 문서 레포지토리다. dev/qa/prod 세 환경을 Kustomize overlay로 분리하고, Jenkins가 이미지 태그를 갱신하면 ArgoCD가 reconcile 하는 파이프라인을 관찰자 시점에서 기록했다. stateless처럼 보이지만 실제로는 처리한 이벤트의 offset/cursor 관리가 핵심이라는 점, 중복 처리를 막기 위한 replicas 및 배포 전략, graceful shutdown과 offset commit 타이밍의 관계 등 listener 워크로드 특유의 이슈를 다룬다. 공통 GitOps/Kustomize 패턴은 sibling 레포인 postgres-listen-notify-argocd-deploy-docs를 참조하도록 구성해, 이 문서는 listener 워크로드에 특화된 내용에 집중한다.
담당 역할
listener 워크로드의 GitOps k8s 배포 운영을 관찰하고, 아키텍처/함정/스택을 문서로 정리
아키텍처 다이어그램
레포지토리 분석 결과를 바탕으로 자동 생성된 구조도입니다.
Listener 워커 GitOps 배포 아키텍처
외부 이벤트 소스부터 listener Pod, offset 저장소, 그리고 Jenkins-ArgoCD GitOps 파이프라인까지의 전체 흐름을 보여준다.
이벤트 처리 및 offset commit 타이밍
이벤트 처리와 offset commit 순서에 따라 at-least-once/at-most-once가 갈리는 흐름을 나타낸다.
기술스택
각 기술을 이 프로젝트에서 어떤 용도로 썼는지 정리했습니다.
인프라
- Kuberneteslistener 워커 Pod 배포 및 오케스트레이션
DevOps
- ArgoCDGitOps 방식으로 이미지 태그 변경을 reconcile하여 배포
- Kustomizedev/qa/prod 환경별 base/overlay 구성 분리
- Jenkins이미지 빌드 후 태그를 갱신해 git push하는 CI 역할
- Prometheusevent_lag_seconds 등 listener 운영 지표 모니터링
데이터베이스
- PostgreSQL이벤트 처리 offset/cursor 영속 저장소 옵션
- Redis빠른 offset 저장 및 Redlock 기반 leader election 옵션
핵심 포인트
- listener는 stateless처럼 보이지만 offset/cursor lifecycle 관리가 신뢰성의 핵심임을 정리
- RollingUpdate가 중복 이벤트 처리를 유발할 수 있어 Recreate 또는 leader election을 권장
- at-least-once 처리 전제 하에 idempotency key 기반 중복 방지 패턴을 문서화
- ingress 유무를 webhook 수신 여부에 따라 환경별로 분기하는 패턴 정리
- event_lag_seconds를 핵심 지표로 삼는 모니터링 및 alert 설계 가이드 제공
문제와 해결
문제ArgoCD sync 시 SIGTERM으로 인해 offset 커밋 전에 pod가 종료되면 다음 pod에서 이벤트가 재처리됨
해결terminationGracePeriodSeconds를 120초 수준으로 늘려 graceful shutdown 시간을 확보
문제RollingUpdate 전략에서 신규 pod와 기존 pod가 동시에 같은 이벤트를 처리해 중복 부작용 발생
해결strategy.type을 Recreate로 설정하거나 k8s Lease 기반 leader election 도입
레포지토리 정보
- 생성
- 2026년 5월 14일
- 최근 커밋
- 2026년 5월 14일
- 크기
- 5 KB
- 라이선스
- 없음
이 문서는 2026년 7월 26일 에 자동 분석으로 생성되었습니다.