본문으로 건너뛰기

PLT-NFR-007 무중단 배포 구현 가이드

🎯 개요​

PLT-NFR-007 요구사항​

"시스템은 무중단 배포를 지원해야 한다"

구현 전략​

기존 CD 체계를 완전히 유지하면서 무중단 배포 기능을 강화

현재 운영 중인 GitHub Actions + Atlantis + cloudrun-deploy/ 구조를 그대로 활용하여 PLT-NFR-007 무중단 배포 요구사항을 안전하고 효율적으로 구현합니다.

🏗️ 아키텍처 설계​

환경별 무중단 배포 전략​

환경배포 전략트래픽 전환롤백 정책검증 시간특징
DevFast Deploy즉시 100%수동 롤백1분빠른 개발, Warm-up 적용
StageCanary Deploy10% → 50% → 100%5% 에러율시 자동 롤백5분/단계Beta 테스터 안전성 검증
ProdBlue-Green Deploy완전 검증 후 전환1% 에러율시 즉시 롤백10분99.9% 가용성 보장

구현 접근법​

✅ 기존 인프라 완전 활용

  • gops-terraform-module.git//modules//serverless 모듈 그대로 사용
  • cloudrun-deploy/dta-wide-api/cloudrun/{dev,stage,prod}/terragrunt.hcl 설정 개선
  • GitHub Actions + Atlantis CD 파이프라인 100% 유지

✅ 무중단 배포 기능 강화

  • 환경별 배포 전략 환경변수 추가
  • Cloud Run annotations에 무중단 배포 메타데이터
  • 자동 롤백 조건 설정 (환경별 차등 적용)
  • 배포 검증 자동화 스크립트

📁 수정된 파일들​

Dev 환경​

# cloudrun-deploy/dta-wide-api/cloudrun/dev/terragrunt.hcl

locals {
  # PLT-NFR-007 무중단 배포 설정
  deployment_strategy = "fast"  # Dev: Fast Deploy
}

# 환경변수 추가
env = [
  # ... 기존 설정 ...
  {
    name  = "DEPLOYMENT_STRATEGY"
    value = local.deployment_strategy
  },
  {
    name  = "AUTO_ROLLBACK_ENABLED"
    value = "false"  # Dev: 수동 롤백
  },
  {
    name  = "WARM_UP_ENABLED"
    value = "true"   # Dev: Cold start 완화
  }
]

# 어노테이션 추가
annotations = {
  # ... 기존 설정 ...
  "dta.weltcorp.com/deployment-strategy" = local.deployment_strategy
  "dta.weltcorp.com/auto-rollback" = "false"
  "dta.weltcorp.com/warm-up-enabled" = "true"
}

Stage 환경​

# cloudrun-deploy/dta-wide-api/cloudrun/stage/terragrunt.hcl

locals {
  # PLT-NFR-007 무중단 배포 설정
  deployment_strategy = "canary"  # Stage: Canary Deploy
}

# 환경변수 추가
env = [
  # ... 기존 설정 ...
  {
    name  = "DEPLOYMENT_STRATEGY"
    value = local.deployment_strategy
  },
  {
    name  = "AUTO_ROLLBACK_ENABLED"
    value = "true"   # Stage: 자동 롤백
  },
  {
    name  = "ERROR_RATE_THRESHOLD"
    value = "5.0"    # Stage: 5% 에러율 초과시 롤백
  },
  {
    name  = "CANARY_TRAFFIC_PERCENT"
    value = "10"     # Stage: 초기 10% Canary 트래픽
  }
]

Prod 환경​

# cloudrun-deploy/dta-wide-api/cloudrun/prod/terragrunt.hcl

locals {
  # PLT-NFR-007 무중단 배포 설정
  deployment_strategy = "blue_green"  # Prod: Blue-Green Deploy
}

# 환경변수 추가
env = [
  # ... 기존 설정 ...
  {
    name  = "DEPLOYMENT_STRATEGY"
    value = local.deployment_strategy
  },
  {
    name  = "AUTO_ROLLBACK_ENABLED"
    value = "true"   # Prod: 자동 롤백 필수
  },
  {
    name  = "ERROR_RATE_THRESHOLD"
    value = "1.0"    # Prod: 1% 에러율 초과시 즉시 롤백
  },
  {
    name  = "VALIDATION_TIME_SECONDS"
    value = "600"    # Prod: 10분 완전 검증
  }
]

🚀 배포 프로세스​

1. 개발자 작업 (변경 없음)​

# 기존 워크플로 그대로 사용
git checkout -b feature/new-feature
git add .
git commit -m "feat: implement new feature"
git push origin feature/new-feature

# GitHub Actions가 자동으로 빌드 및 이미지 푸시 실행

2. Atlantis를 통한 배포 (변경 없음)​

# Pull Request 생성 후 Atlantis가 자동으로:
# 1. terragrunt plan 실행
# 2. 승인 후 terragrunt apply 실행
# 3. Cloud Run 서비스 업데이트

# 무중단 배포 환경변수가 자동으로 적용됨:
# - DEPLOYMENT_STRATEGY (fast/canary/blue_green)
# - AUTO_ROLLBACK_ENABLED (true/false)
# - ERROR_RATE_THRESHOLD (1.0~10.0)

3. 배포 검증 (새로 추가)​

# 환경별 배포 검증 실행
./scripts/validate-zero-downtime-deployment.sh -e dev
./scripts/validate-zero-downtime-deployment.sh -e stage  
./scripts/validate-zero-downtime-deployment.sh -e prod

# 특정 배포 전략으로 검증
./scripts/validate-zero-downtime-deployment.sh -e stage --strategy canary --validation-time 600

4. 실시간 모니터링​

# 배포 상태 실시간 확인
watch -n 5 "gcloud run services describe dta-wide-api \
  --region=europe-west3 \
  --format='value(spec.traffic[].percent,spec.traffic[].revisionName)'"

# Health check 연속 모니터링  
watch -n 10 "curl -s https://SERVICE_URL/health | jq"

🔍 배포 검증 도구​

자동 검증 스크립트​

# Dev 환경 검증
./scripts/validate-zero-downtime-deployment.sh -e dev

# Stage 환경 검증 (Canary 배포)
./scripts/validate-zero-downtime-deployment.sh -e stage --strategy canary

# Prod 환경 검증 (Blue-Green 배포)
./scripts/validate-zero-downtime-deployment.sh -e prod --strategy blue_green

수동 확인 명령어​

# 현재 revision 확인
gcloud run revisions describe REVISION_NAME \
  --region=europe-west3 \
  --format='value(metadata.name,status.conditions[0].status)'

# 트래픽 분산 확인
gcloud run services describe dta-wide-api \
  --region=europe-west3 \
  --format='value(spec.traffic[].percent,spec.traffic[].revisionName)'

# Health check
curl -f https://SERVICE_URL/health
curl -f https://SERVICE_URL/health/deep

🛡️ 응급상황 대응​

즉시 롤백​

# 이전 안정 버전으로 롤백
gcloud run services update-traffic dta-wide-api \
  --to-latest --region=europe-west3

# 또는 특정 revision으로 롤백
gcloud run services update-traffic dta-wide-api \
  --to-revisions=PREVIOUS_REVISION=100 \
  --region=europe-west3

응급 스케일 다운 (Dev/Stage만)​

gcloud run services update dta-wide-api \
  --min-instances=0 --region=europe-west3

📊 모니터링​

Cloud Run 메트릭 확인​

커스텀 메트릭 (환경변수 기반)​

애플리케이션에서 다음 환경변수를 활용하여 배포 관련 메트릭 수집:

  • DEPLOYMENT_STRATEGY: 배포 전략 식별
  • AUTO_ROLLBACK_ENABLED: 자동 롤백 여부
  • ERROR_RATE_THRESHOLD: 에러율 임계값
  • REVISION_NAME: 현재 revision 추적

🎯 환경별 특징​

|------|-----------|-----------|-------------|-----------|------| | Dev | Fast Deploy | ❌ 수동 | 10% | 1분 | 빠른 개발, Warm-up | | Stage | Canary Deploy | ✅ 자동 | 5% | 5분 | Beta 안전성 검증 | | Prod | Blue-Green Deploy | ✅ 자동 | 1% | 10분 | 최대 안전성 보장 |

🔧 애플리케이션 코드 통합​

Health Check 엔드포인트 구현​

// apps/dta-wide-api/src/health/health.controller.ts

@Controller('health')
export class HealthController {
  @Get()
  async getHealth(): Promise<HealthCheckResult> {
    return {
      status: 'ok',
      timestamp: new Date().toISOString(),
      deployment: {
        strategy: process.env.DEPLOYMENT_STRATEGY,
        revision: process.env.REVISION_NAME,
        autoRollback: process.env.AUTO_ROLLBACK_ENABLED === 'true'
      }
    };
  }

  @Get('ready')
  async getReadiness(): Promise<ReadinessCheckResult> {
    // 배포 관련 정보 포함한 상세 readiness 체크
    const isReady = await this.checkApplicationReadiness();
    
    return {
      status: isReady ? 'ready' : 'not_ready',
      deployment: {
        strategy: process.env.DEPLOYMENT_STRATEGY,
        warmUpEnabled: process.env.WARM_UP_ENABLED === 'true',
        errorThreshold: process.env.ERROR_RATE_THRESHOLD
      },
      timestamp: new Date().toISOString()
    };
  }

  @Get('deep')  
  async getDeepHealth(): Promise<DeepHealthCheckResult> {
    // 데이터베이스, Redis, 외부 서비스 연결 확인
    const checks = await Promise.allSettled([
      this.checkDatabase(),
      this.checkRedis(),
      this.checkExternalServices()
    ]);

    return {
      status: checks.every(c => c.status === 'fulfilled') ? 'ok' : 'error',
      checks: this.parseHealthChecks(checks),
      deployment: {
        strategy: process.env.DEPLOYMENT_STRATEGY,
        environment: process.env.ENVIRONMENT
      }
    };
  }
}

🎯 성공 기준 및 KPI​

배포 성공률 목표​

환경목표 성공률롤백 허용 빈도평균 배포 시간
Dev≥ 95%주 2회 이하≤ 5분
Stage≥ 99%월 2회 이하≤ 15분
Prod≥ 99.9%월 1회 이하≤ 30분

서비스 가용성 목표​

  • 배포 중 가용성: 99.9% 이상 유지
  • 최대 허용 다운타임: 0초 (무중단 배포)
  • 롤백 완료 시간: 2분 이내

🔄 개선 로드맵​

단기 (1-2개월)​

  1. ✅ 기본 무중단 배포 - 환경변수 기반 구현 완료
  2. 🔄 Health Check 강화 - Deep health check 구현
  3. 🔄 배포 메트릭 수집 - 성공률, 배포 시간 추적

중기 (3-6개월)​

  1. 📋 실제 Traffic Splitting - gops-terraform-module 지원시 적용
  2. 📋 자동 성능 테스트 - 배포 후 부하 테스트 자동화
  3. 📋 Slack 알림 통합 - 배포 상태 실시간 알림

장기 (6-12개월)​

  1. 📋 A/B 테스트 통합 - 배포와 연계된 기능 테스트
  2. 📋 AI 기반 롤백 - 과거 데이터 기반 자동 롤백 판단
  3. 📋 Multi-region 배포 - 규제 허용시 다중 지역 확장

✅ PLT-NFR-007 요구사항 달성​

"시스템은 무중단 배포를 지원해야 한다" ✅

구현 완료 항목​

  1. ✅ 환경별 차별화된 배포 전략 - Fast/Canary/Blue-Green 구현
  2. ✅ 자동 롤백 메커니즘 - 환경별 에러율 임계값 설정
  3. ✅ 배포 검증 도구 - 자동화된 Health Check 및 성능 테스트
  4. ✅ 기존 CD 체계 100% 유지 - GitHub Actions + Atlantis 그대로 활용
  5. ✅ 응급상황 대응 절차 - 즉시 롤백 및 문제 해결 가이드

즉시 사용 가능한 명령어​

# 배포 검증
./scripts/validate-zero-downtime-deployment.sh -e {dev|stage|prod}

# 즉시 롤백  
gcloud run services update-traffic dta-wide-api --to-latest --region=europe-west3

# 배포 상태 확인
gcloud run services describe dta-wide-api --region=europe-west3 \
  --format='value(spec.traffic[].percent,spec.traffic[].revisionName)'

핵심 환경변수 (자동 적용됨)​

  • DEPLOYMENT_STRATEGY: fast/canary/blue_green
  • AUTO_ROLLBACK_ENABLED: true/false
  • ERROR_RATE_THRESHOLD: 1.0~10.0%
  • WARM_UP_ENABLED: true/false (Dev만)

📞 지원 및 문의​

기술 문의: Platform 인프라 감사 보고서
관련 문서: 가용성 구현 가이드

변경 이력​

버전날짜작성자변경 내용
0.1.02025-08-13bok@weltcorp.com최초 작성