CI/CD 파이프라인 통합 대시보드

개요

GitLab, AWS CodePipeline/CodeBuild/CodeDeploy, 온프레미스 서버 상태를 한 화면에서 모니터링하는 CI/CD 운영 대시보드입니다. 배포 상태를 확인하려면 여러 콘솔과 서버 상태를 따로 봐야 했고, 장애가 나면 어느 단계에서 막혔는지 확인하는 데 시간이 걸렸습니다.

이 대시보드는 파이프라인, 빌드, 서버, 알림, 승인 상태를 한곳에 모아 운영자가 배포 흐름을 빠르게 파악할 수 있도록 만든 프로젝트입니다.

기능	내용
파이프라인 모니터링	CodePipeline/CodeDeploy 단계별 상태 조회
서버 모니터링	SSM Agent, CodeDeploy Agent, 온프레미스 등록 상태 확인
빌드 모니터링	CodeBuild 프로젝트와 빌드 이력 조회
알림	Webex Bot API, Microsoft Teams 웹훅
승인 워크플로	운영/검증 환경 배포 승인 관리

기술 스택

영역	기술
프론트엔드	React 18, TypeScript, Vite
백엔드	FastAPI, SQLAlchemy async, boto3
데이터베이스	PostgreSQL 16
인증	Keycloak OIDC
인프라	K3s, Istio, ArgoCD, Harbor
알림	Webex Bot API, Microsoft Teams Webhook

아키텍처

graph LR
  U[User] --> G[Istio Gateway]
  G -->|/*.api/*| B[FastAPI Backend]
  G -->|/*| F[React Frontend]
  B --> DB[(PostgreSQL)]
  B --> KC[Keycloak]
  B --> AWS[AWS APIs]
  B --> Notify[Webhook Adapters]

상태 수집은 여러 collector가 각자 다른 주기로 실행합니다. 비용이 들거나 호출량이 많은 작업은 주기를 길게 두고, 파이프라인처럼 즉시성이 필요한 데이터는 짧은 주기로 가져오도록 분리했습니다. 백그라운드에서는 6개 collector가 asyncio.gather()로 병렬 실행되고, boto3 동기 호출은 asyncio.to_thread()로 분리해 FastAPI 이벤트 루프를 막지 않도록 했습니다.

Collector	주기	비용	설명
pipeline	15초	무료	CodePipeline/CodeDeploy 상태
ssm	5분	무료	SSM ping 확인
agent	15분	유료	Run Command로 CodeDeploy Agent 확인
builds	5분	무료	CodeBuild 프로젝트 상태
executions	5분	무료	파이프라인 실행 이력
tags	24시간	무료	태그 정보 수집

주요 구현 포인트

파이프라인 상태 통합

AWS 콘솔에서 분산되어 보이는 CodePipeline, CodeDeploy, CodeBuild 상태를 하나의 모델로 정규화했습니다. 파이프라인 단계별 성공/실패/진행 상태와 에러 메시지, CloudWatch 로그 링크를 함께 보여줍니다.

파이프라인과 서버 이름에서는 환경을 자동으로 추론합니다. dev, test/stg, prd/prod 같은 접두사나 하이픈 구분 규칙을 기준으로 개발/검증/운영 환경을 나눠 대시보드 필터와 알림에 사용합니다.

CodeBuild 실패는 단순히 “실패”로만 보여주지 않고, 실패 phase와 CloudWatch 로그 일부를 함께 가져옵니다. 컴파일 오류나 빌드 스크립트 실패처럼 운영자가 바로 봐야 하는 로그 주변 라인을 추려서 파이프라인 오류 메시지에 붙였습니다.

서버 상태 점검

배포 실패 원인이 애플리케이션 빌드가 아니라 서버 측 Agent 문제인 경우가 많습니다. SSM ping 상태, CodeDeploy Agent 설치/동작 여부, 온프레미스 인스턴스 등록 여부를 함께 수집해 배포 가능 상태를 확인할 수 있게 했습니다.

수집 항목	확인 내용
SSM Agent	ping 상태
CodeDeploy Agent	정상/비정상/미설치
On-Premises 등록	CodeDeploy 인스턴스 등록 여부

중복 알림 방지

장애 상태가 유지되는 동안 같은 알림이 반복 발송되지 않도록 alert_state 테이블에 발송 이력을 저장합니다. 파이프라인 실패는 executionId, 라이브러리 빌드 실패는 buildId를 기준으로 중복 여부를 판단합니다. 같은 실패는 다시 보내지 않고, 새 실행이나 새 빌드에서 다시 실패하면 별도 이벤트로 남깁니다.

배포 승인 워크플로

운영/검증 환경은 승인 없이 바로 배포되지 않도록 승인 요청 흐름을 두었습니다. 개발 환경은 즉시 실행 가능하고, 운영/검증 환경은 admin 승인을 거친 뒤 파이프라인 실행으로 이어집니다.

수동 재실행과 실패 스테이지 재시도도 승인 이력 테이블에 남깁니다. 실제 실행 버튼을 누른 사람, 대상 파이프라인, 환경, 브랜치, 승인/거절 상태를 남겨 나중에 배포 흐름을 되짚어볼 수 있게 했습니다.

요청자 -> 승인 요청 생성 -> admin 승인/거절 -> 파이프라인 실행

화면 구성

페이지	내용
Overview	전체 파이프라인과 서버 상태 요약
Pipelines	파이프라인 실행 상태와 재실행
Servers	SSM/CodeDeploy Agent 상태
Builds	CodeBuild 프로젝트와 빌드 이력
Alerts	장애 알림과 발송 상태

프로젝트 구조

├── frontend/
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── hooks/
│   │   └── services/
│   └── nginx.conf
└── backend/
    ├── app/
    │   ├── core/
    │   ├── models/
    │   ├── routers/
    │   └── services/
    └── entrypoint.sh

실행

# Backend
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

# Frontend
cd frontend
npm install
npm run dev

향후 개선점

GitOps 배포 현황 연동
다중 AWS 계정 지원
모바일 화면 대응
승인 이력과 장애 이력 리포트 개선