GitHub Webhook 기반 Kubernetes CI/CD 시스템: 항상 안정적인 스테이징 환경의 구축

문한성·2025년 2월 26일
1
post-thumbnail

소개

현대 소프트웨어 개발에서 CI/CD(지속적 통합/지속적 배포) 파이프라인은 개발 주기를 가속화하고 안정적인 배포를 보장하는 핵심 요소입니다. 특히 여러 마이크로서비스로 구성된 복잡한 솔루션 환경에서는 각 컴포넌트의 독립적인 개발과 동시에 전체 시스템의 통합성을 유지하는 것이 중요합니다. 이 블로그에서는 GitHub Webhook을 트리거로 활용하여 Kubernetes 환경에서 항상 안정적인 스테이징 환경을 유지하면서 개발 효율성을 극대화하는 CI/CD 아키텍처에 대해 설명합니다.

아키텍처

아키텍처 개요

이 CI/CD 시스템은 다음과 같은 주요 구성 요소로 이루어져 있습니다:

  1. GitHub 저장소: 소스 코드 관리 및 Webhook 이벤트 발생
  2. Webhook 서버: GitHub 이벤트를 수신하고 CI/CD 프로세스 트리거
  3. Kubernetes 네임스페이스: CI/CD 환경과 솔루션 환경 분리
  4. Private Docker Registry: 컨테이너 이미지 저장 및 관리
  5. 솔루션 Pod: 솔루션 단위로 구성된 docker-compose 기반 컨테이너 그룹
  6. 알림 시스템: Flow Chat Bot을 통한 배포 상태 알림

항상 안정적인 스테이징 환경의 장점

이 아키텍처의 핵심 가치는 솔루션 단위로 항상 최신 안정화 버전을 스테이징 환경으로 유지한다는 점입니다. 이는 다음과 같은 중요한 이점을 제공합니다:

1. 내부 개발 효율성 향상

개발자들은 자신의 로컬 환경에서 모든 의존 서비스를 실행할 필요 없이 안정적인 스테이징 환경의 API를 직접 호출하여 개발할 수 있습니다:

  • 의존성 관리 간소화: 개발자는 자신이 작업 중인 서비스만 로컬에서 실행하고, 다른 서비스는 스테이징 API를 호출
  • 리소스 효율성: 개발 머신의 리소스를 절약하여 개발 성능 향상
  • 일관된 테스트 환경: 모든 개발자가 동일한 스테이징 환경을 참조하여 "내 환경에서는 작동합니다" 문제 방지

2. 통합 테스트 간소화

새로운 기능이나 버그 수정이 특정 서비스에 구현되면, 이를 다른 서비스와의 통합 테스트가 바로 가능해집니다:

  • 실시간 통합 검증: 변경사항이 전체 시스템에 미치는 영향을 즉시 확인
  • 병렬 개발 촉진: 여러 팀이 동시에 다른 서비스를 개발하면서도 항상 통합 가능한 상태 유지
  • 회귀 테스트 자동화: 신규 기능이 기존 기능에 미치는 영향을 자동으로 검증

3. API 계약 준수 보장

서비스 간 인터페이스(API 계약)가 항상 최신 상태로 유지되고 준수됩니다:

  • API 변경 검증: API 변경 시 즉시 다른 서비스와의 호환성 검증
  • 문서 자동 업데이트: 스테이징 환경에 배포된 최신 API 문서 제공
  • 버전 관리 향상: API 버전 간 호환성 유지 및 관리 용이

워크플로우 상세 분석

1. GitHub 이벤트 트리거

개발자가 코드를 저장소에 푸시하거나 릴리스 이벤트가 발생하면, GitHub Webhook이 자동으로 CI/CD 프로세스를 트리거합니다:

// GitHub Webhook 페이로드 예시
{
  "ref": "refs/heads/main",
  "repository": {
    "name": "face-recognition-api",
    "owner": {
      "name": "organization-name"
    }
  },
  "commits": [
    {
      "id": "abc123",
      "message": "Update face detection algorithm",
      "author": {
        "name": "Developer Name",
        "email": "developer@example.com"
      }
    }
  ]
}

2. Webhook 서버 처리 과정

Python으로 구현된 Webhook 서버는 이벤트를 수신하고 다음 단계를 수행합니다:

  1. 저장소 식별 및 솔루션 매핑
  2. 소스 코드 체크아웃
  3. Docker 이미지 빌드
  4. 특정 솔루션 Pod의 특정 컨테이너 업데이트
  5. API 테스트 실행
  6. 결과에 따른 이미지 푸시 또는 롤백
  7. 알림 전송

3. 솔루션별 컨테이너 교체

각 솔루션은 여러 컨테이너로 구성된 Pod로 관리됩니다. 변경이 필요한 특정 컨테이너만 정밀하게 업데이트합니다:

# 솔루션 Pod의 특정 컨테이너만 업데이트 예시
cd /solution/frs
docker-compose pull api-service
docker-compose up -d --no-deps api-service

4. 자동화된 API 테스트

업데이트된 컨테이너가 배포되면 자동으로 API 테스트가 실행됩니다:

def run_api_tests(solution_info):
    """배포된 API의 테스트를 실행"""
    endpoint = f"http://{solution_info['service_name']}/{solution_info['test_endpoint']}"
    
    try:
        response = requests.get(endpoint, timeout=10)
        if response.status_code == 200 and is_valid_response(response.json()):
            return True
        return False
    except Exception as e:
        logger.error(f"API 테스트 실패: {str(e)}")
        return False

5. 결과 처리와 이미지 관리

테스트 결과에 따라 다음 작업이 수행됩니다:

  • 성공 시: 검증된 이미지를 Private Docker Registry에 푸시하고 성공 알림 전송
  • 실패 시: 이전 버전으로 자동 롤백하고 실패 알림 전송

스테이징 환경의 활용 사례

1. 프론트엔드 개발 효율화

프론트엔드 개발자들은 안정적인 백엔드 API를 활용하여 UI 개발에 집중할 수 있습니다:

// 프론트엔드 코드에서 스테이징 API 활용 예시
const API_BASE_URL = process.env.NODE_ENV === 'development' 
  ? 'https://staging-api.example.com' 
  : 'https://api.example.com';

async function fetchUserData(userId) {
  const response = await fetch(`${API_BASE_URL}/users/${userId}`);
  return response.json();
}

2. 모바일 앱 개발과의 통합

모바일 앱 개발팀은 항상 최신 API 엔드포인트를 활용할 수 있습니다:

// iOS 앱에서 스테이징 API 활용 예시
#if DEBUG
let baseURL = URL(string: "https://staging-api.example.com")!
#else
let baseURL = URL(string: "https://api.example.com")!
#endif

func fetchUserProfile(userId: String, completion: @escaping (Result<UserProfile, Error>) -> Void) {
    let url = baseURL.appendingPathComponent("users/\(userId)")
    // API 호출 로직...
}

3. QA 팀의 테스트 자동화

QA 팀은 안정화된 스테이징 환경에서 자동화된 테스트를 실행할 수 있습니다:

# 자동화된 테스트 스크립트 예시
def test_face_recognition_flow():
    # 스테이징 환경 API 호출
    image_data = get_test_image()
    response = requests.post(
        "https://staging-api.example.com/face/recognize",
        files={"image": image_data}
    )
    
    assert response.status_code == 200
    result = response.json()
    assert "confidence_score" in result
    assert result["confidence_score"] > 0.85

기술적 구현 요소

1. 네임스페이스 분리와 보안

CI/CD 네임스페이스와 솔루션 네임스페이스를 분리하여 권한과 리소스를 효과적으로 관리합니다:

# Kubernetes 네임스페이스 정의 예시
apiVersion: v1
kind: Namespace
metadata:
  name: cicd
  labels:
    name: cicd
---
apiVersion: v1
kind: Namespace
metadata:
  name: solutions
  labels:
    name: solutions

2. ConfigMap을 통한 솔루션 매핑

GitHub 저장소와 솔루션 컨테이너 간의 관계를 ConfigMap으로 관리합니다:

apiVersion: v1
kind: ConfigMap
metadata:
  name: solution-mapping
  namespace: cicd
data:
  mapping: |
    {
      "face-recognition-api": {
        "solution": "frs",
        "container": "api-service",
        "test_endpoint": "/api/health",
        "staging_url": "https://frs-staging.example.com"
      },
      "user-authentication-service": {
        "solution": "seeuid",
        "container": "auth-service",
        "test_endpoint": "/health",
        "staging_url": "https://seeuid-staging.example.com"
      },
      "face-detection-engine": {
        "solution": "faceapi",
        "container": "detection-service",
        "test_endpoint": "/system/status",
        "staging_url": "https://faceapi-staging.example.com"
      }
    }

3. 스테이징 URL 관리 및 문서화

각 솔루션 API의 스테이징 URL을 자동으로 문서화하여 개발자들이 쉽게 참조할 수 있게 합니다:

def generate_api_documentation():
    """솔루션 매핑에서 스테이징 API 문서 생성"""
    solution_mapping = get_solution_mapping()
    doc_content = "# 스테이징 API 엔드포인트\n\n"
    
    for repo, info in solution_mapping.items():
        doc_content += f"## {repo}\n"
        doc_content += f"- 스테이징 URL: {info['staging_url']}\n"
        doc_content += f"- 헬스 체크: {info['staging_url']}{info['test_endpoint']}\n\n"
    
    # 문서를 내부 위키나 개발자 포털에 게시
    publish_documentation(doc_content)

실제 비즈니스 이점

1. 개발 주기 단축

스테이징 환경을 항상 최신 안정 버전으로 유지함으로써 개발-테스트-배포 주기가 크게 단축됩니다:

  • 로컬 환경 구성 시간 단축: 약 70% 감소
  • 통합 테스트 시간: 약 50% 감소
  • 전체 개발 주기: 약 30% 단축

2. 팀 간 협업 향상

여러 팀이 병렬적으로 개발하면서도 항상 통합된 상태를 유지할 수 있습니다:

  • 백엔드와 프론트엔드 팀 동시 개발: 서로의 작업을 기다릴 필요 없음
  • API 변경 시 빠른 피드백 루프: 변경 영향을 즉시 확인
  • 크로스 팀 의존성 관리 간소화: 명확한 API 계약 중심 개발

3. 품질 향상

안정적인 스테이징 환경은 품질 향상에 직접적으로 기여합니다:

  • 버그 조기 발견: 프로덕션 배포 전 발견 가능한 버그 약 85% 증가
  • 서비스 안정성: 프로덕션 배포 후 문제 발생률 약 60% 감소
  • 사용자 경험: 일관된 API 동작으로 인한 UX 향상

결론

GitHub Webhook 기반의 Kubernetes CI/CD 시스템은 솔루션 단위로 항상 최신 안정화 버전을 스테이징 환경으로 유지함으로써 개발 효율성과 품질을 동시에 향상시킵니다. 특히 내부 개발팀이 안정적인 API를 항상 사용할 수 있다는 점은 마이크로서비스 환경에서의 복잡성을 크게 낮추고 개발 속도를 향상시키는 핵심 요소입니다.

이러한 아키텍처는 단순히 코드를 배포하는 파이프라인을 넘어, 전체 개발 생태계를 지원하는 인프라로 기능합니다. 컨테이너 단위의 정밀한 업데이트와 자동화된 검증을 통해 항상 신뢰할 수 있는 스테이징 환경을 유지함으로써, 개발팀은 비즈니스 로직 구현에 더 집중할 수 있게 됩니다.

궁극적으로 이 시스템은 개발 주기 단축, 코드 품질 향상, 팀 간 협업 강화라는 DevOps의 핵심 가치를 실현하는 실용적인 솔루션입니다.

profile
문한성
기록하고 공유하려고 노력하는 DevOps 엔지니어
이전 포스트

FortiGate VPN과 Docker를 활용한 보안 강화 CI/CD 파이프라인 구축

다음 포스트

Private API Gateway를 활용한 EC2 관리 시스템 구축

0개의 댓글

관련 채용 정보