<div align="center">
Argo Watcher
CI 파이프라인에서 Argo CD 배포를 기다리고, 방금 빌드한 이미지가 성공적으로 배포되었는지 여부를 확인하세요.
Argo Watcher는 CI/CD (지속적 통합/지속적 배포) 파이프라인을 위한 Argo CD 배포를 추적합니다. 파이프라인이 이미지를 빌드하고 푸시한 후, Argo Watcher 클라이언트는 해당 정확한 이미지가 배포될 때까지 기다린 다음, 성공 또는 실패 여부로 종료 코드를 반환하여 파이프라인이 그 결과에 따라 행동할 수 있게 합니다. 이는 선택적 내장형 GitOps 업데이트기를 갖춘, GitOps 워크플로우를 위한 피드백 루프입니다.
GitHub Actions
GitHub go.mod Go version
GitHub release (latest by date)
codecov
Documentation Status
GitHub
<img src="https://raw.githubusercontent.com/shini4i/assets/main/src/argo-watcher/demo.png" alt="Argo Watcher UI" height="441" width="680">
</div>
문제점 (The problem)
CI 파이프라인은 이미지를 빌드하고, 푸시하며, Git 저장소를 업데이트합니다. Argo CD가 이 변경 사항을 감지하여 배포하지만, 파이프라인은 그 결과를 알 수 없습니다. 롤아웃(rollout)에 성공했나요? 실패했나요? 어느 쪽이든 성공했다고만 보고합니다.
해결책 (The solution)
Argo Watcher는 파이프라인에서 방금 빌드한 이미지를 Argo CD 애플리케이션을 감시하고, 배포의 최종 상태를 파이프라인으로 다시 보고하여 비동기 프로세스를 파이프라인이 분기(branch)할 수 있는 결과로 변환합니다.
기능 (Features)
- 배포 추적 (Deployment tracking) — Argo CD 애플리케이션의 상태 및 동기화(sync) 상태를 모니터링합니다.
- CI 클라이언트 (CI client) — 배포를 기다리고 일치하는 상태 코드로 종료되는 작은 바이너리입니다.
- 실시간 웹 UI (Real-time Web UI) — WebSocket을 통해 배포 상태, 히스토리 및 작업별 상세 정보를 전송합니다.
- 내장형 GitOps 업데이트기 (Built-in GitOps updater) — 선택적으로 이미지 태그를 GitOps 저장소에 커밋하여 Argo CD Image Updater를 대체할 수 있습니다.
- 배포 잠금 (Deployment lock) — 일정 또는 필요 시 배포를 동결(freeze)합니다.
- 알림 (Notifications) — 배포 시작 및 결과에 대해 Webhook 또는 Mattermost로 알립니다.
- 인증 (Authentication) — 파이프라인을 위한 deploy token 또는 JWT, 웹 UI를 위한 모든 OIDC 제공자(Keycloak, Authentik 등)를 지원합니다.
왜 argocd app wait를 사용하지 않나요? (Why not argocd app wait?)
argocd app wait는 애플리케이션이 'Synced' 상태이고 'Healthy' 상태가 될 때까지 기다립니다. 이 명령어는 리비전(revision)이나 이미지 태그에 대한 인수가 없기 때문에, Argo CD가 아직 커밋을 가져오지 않은 경우 이전 리비전만으로도 조건을 만족하며 배포가 시작되지 않았음에도 불구하고 성공적으로 반환됩니다. 또한 모든 파이프라인에서 argocd CLI와 Argo CD 토큰이 필요합니다.
Argo Watcher는 사용자가 빌드한 이미지 태그가 'Synced' 상태이고 'Healthy' 상태인 애플리케이션에서 실행될 때까지 기다리며, 모든 배포 기록을 Web UI에 보관합니다. 파이프라인에서는 서버 URL과 선택적 배포 토큰만 필요합니다. API 폴링 및 kubectl rollout status를 포함한 전체 비교 내용은 CI에서 Argo CD 배포 대기하기를 참고하십시오.
아키텍처 (Architecture)
graph LR
subgraph CI["CI 파이프라인"]
Build["빌드 및 푸시"]
...
작동 방식 (How it works)
- 사용자의 파이프라인은 이미지를 빌드하고 푸시한 다음, 추적할 애플리케이션과 이미지로 Argo Watcher 클라이언트를 실행합니다.
- 태그는 Argo Watcher의 내장 업데이트기 또는 Argo CD Image Updater에 의해 GitOps 리포지토리에서 업데이트됩니다.
- Argo CD가 동기화(sync)를 수행하는 동안, 서버는 API를 폴링하고 작업 진행 상황을 Web UI로 스트리밍합니다.
- 최종 상태('deployed', 'failed' 등)는 클라이언트로 다시 전송되고, 클라이언트는 그에 따라 종료되며 파이프라인은 계속되거나 실패합니다.
시작하기 (Getting started)
Argo Watcher를 가장 빠르게 사용해 보는 방법은 번들된 Docker Compose 스택입니다. 이 스택은 서버, Postgres 데이터베이스, Web UI, 그리고 모의 Argo CD를 실행하므로 클러스터 없이도 로컬에서 전체 작업 수명 주기(task lifecycle)를 연습할 수 있습니다:
git clone https://github.com/shini4i/argo-watcher.git
cd argo-watcher
docker compose up
실행이 완료되면 Web UI는 http://localhost:3100에서 사용할 수 있습니다. 빠른 시작(Quick Start) 가 작업을 제출하고 배포를 관찰하는 방법을 안내합니다.
실제 Kubernetes 클러스터에 Helm을 사용하여 배포하고 클라이언트(ghcr.io/shini4i/argo-watcher-client)를 CI 파이프라인에 연결하려면, 설치 가이드를 따르세요.
문서(Documentation)
구성(Configuration), API, 그리고 모든 가이드: argo-watcher.readthedocs.io.
기여(Contributing)
기여는 환영합니다 — 코드 작성 전에 이슈를 여세요. 변경 사항이 충족해야 하는 내용은 CONTRIBUTING.md에 있으며, 로컬 설정은 개발 가이드에 있습니다.
라이선스(License)
본 프로젝트는 Apache License 2.0 하에 라이선스가 부여되었습니다.
