Feature/175: AWS CloudFront 연동

[syeongkim]

[FEATURE] AWS CloudFront (CDN) 연동 기능 구현

📋 개요

AWS CloudFront CDN 서비스를 AgenticCP 플랫폼에 연동하여 사용자가 CDN Distribution의 전체 생명주기를 관리하고, 캐시 무효화 기능을 사용할 수 있도록 구현했습니다.

CloudFront는 전 세계 사용자에게 빠르고 안정적인 콘텐츠 전송을 제공하는 CDN 서비스로, 본 기능을 통해 Distribution 생성, 조회, 수정, 삭제 및 캐시 무효화를 통합 관리할 수 있습니다.

🎯 목표

1. CloudFront Distribution 생명주기 관리

   • Distribution 생성, 조회, 수정, 삭제 기능 제공
   • 퍼블릭 S3 버킷 및 커스텀 Origin 지원
   • SSL/TLS 인증서 설정 지원
   • 캐시 동작(Cache Behavior) 설정 지원

2. 캐시 무효화 기능

   • 캐시 무효화 생성 및 상태 조회 기능 제공

3. 멀티 클라우드 아키텍처 준수

   • Hexagonal Architecture 패턴 적용
   • 향후 GCP, Azure CDN 연동을 위한 확장 가능한 구조
   • CSP-agnostic 입력 검증 로직

4. 플랫폼 통합

   • CloudResource 엔티티를 통한 통합 리소스 관리
   • 감사 로깅(Audit Logging) 적용
   • DB 동기화 및 보상 트랜잭션 구현

🏗️ 구현 내용

1. 아키텍처

Hexagonal Architecture 패턴을 따라 Port & Adapter 구조로 구현했습니다.

Outbound Ports (인터페이스)

• CDNManagementPort: Distribution 생명주기 관리 (생성, 수정, 삭제)
• CDNDiscoveryPort: Distribution 조회 (목록, 단건, 존재 여부)
• CDNInvalidationPort: 캐시 무효화 관리 (생성, 조회)

Adapters (구현체)

• AwsCloudFrontManagementAdapter: AWS CloudFront Distribution 관리
• AwsCloudFrontDiscoveryAdapter: AWS CloudFront Distribution 조회
• AwsCloudFrontInvalidationAdapter: AWS CloudFront 캐시 무효화
• AwsCloudFrontMapper: AWS SDK 모델 ↔ CloudResource 변환
• AwsCloudFrontErrorTranslator: AWS 예외 → 도메인 예외 변환

Services

• CDNPortRouter: ProviderType 기반 포트 라우팅
• CDNUseCaseService: 비즈니스 로직 오케스트레이션

Configuration

• AwsCloudFrontConfig: CloudFrontClient 빈 생성 및 ThreadLocal 자격증명 관리

2. 주요 기능 구현

2.1 Distribution 관리

• 생성: Origin 설정, Cache Behavior, SSL 인증서, 태그 지원
• 조회: 목록 조회(필터링, 정렬, 페이징), 단건 조회
• 수정: 설정 변경, 태그 업데이트
• 삭제: 활성화된 Distribution은 자동 비활성화 후 배포 완료 대기 후 삭제

2.2 캐시 무효화

• 생성: 경로 목록을 지정하여 캐시 무효화 생성
• 조회: 무효화 상태 조회 (InProgress, Completed)

2.3 DB 동기화

• CloudResource 엔티티에 Distribution 정보 저장
• metadata 필드(JSONB)에 Distribution 상세 정보 저장
• 보상 트랜잭션: DB 저장 실패 시 CSP 리소스 삭제

2.4 보안 및 감사

• @AuditRequired 어노테이션을 통한 감사 로깅
• 리소스 타입: CDN_DISTRIBUTION
• 심각도: CREATE/UPDATE (HIGH), DELETE (CRITICAL), LIST/GET (LOW)

3. 데이터 모델

Port Models (내부 도메인 모델)

• CreateDistributionCommand: Distribution 생성 명령
• UpdateDistributionCommand: Distribution 수정 명령
• DeleteDistributionCommand: Distribution 삭제 명령
• CreateInvalidationCommand: 캐시 무효화 생성 명령
• InvalidationResult: 캐시 무효화 결과 (내부 포트 모델)
• OriginConfig: Origin 설정 VO
• CacheBehaviorConfig: Cache Behavior 설정 VO

DTOs (외부 API 모델)

• CDNDistributionCreateRequest: Distribution 생성 요청
• CDNDistributionUpdateRequest: Distribution 수정 요청
• CDNDistributionQueryRequest: Distribution 조회 요청
• CDNInvalidationRequest: 캐시 무효화 생성 요청
• CDNInvalidationResponse: 캐시 무효화 응답
• CloudResource: Distribution 조회/생성/수정 응답 (다른 리소스와 일관성 유지)

4. 에러 처리

• AwsCloudFrontErrorTranslator: AWS SDK 예외를 도메인 예외로 변환
• BusinessException: 비즈니스 로직 예외
• ResourceNotFoundException: 리소스 미발견 예외

🧪 테스트

단위 테스트

Adapter 테스트

• AwsCloudFrontManagementAdapterTest: Distribution 생성, 수정, 삭제 테스트
  • 활성화된 Distribution 삭제 시 비활성화 및 배포 대기 로직 검증
  • ETag 기반 동시성 제어 검증
  • 태그 관리 검증
• AwsCloudFrontDiscoveryAdapterTest: Distribution 조회 테스트
  • 목록 조회 (필터링, 정렬, 페이징)
  • 단건 조회
  • 존재 여부 확인
• AwsCloudFrontInvalidationAdapterTest: 캐시 무효화 테스트
  • 무효화 생성 (CallerReference 제공/미제공)
  • 무효화 상태 조회

Service 테스트

• CDNUseCaseServiceTest: 비즈니스 로직 테스트
  • Capability 검증
  • 세션 획득
  • 보상 트랜잭션
• CDNUseCaseServiceDbSyncTest: DB 동기화 테스트
  • Distribution 생성 시 DB 저장
  • Metadata 저장 검증
  • DB 저장 실패 시 보상 트랜잭션

🚀 API 엔드포인트

Distribution 관리

• POST /api/v1/clouds/{cloudAccountId}/cloudfront/distributions - Distribution 생성
• GET /api/v1/clouds/{cloudAccountId}/cloudfront/distributions - Distribution 목록 조회
• GET /api/v1/clouds/{cloudAccountId}/cloudfront/distributions/{distributionId} - Distribution 상세 조회
• PUT /api/v1/clouds/{cloudAccountId}/cloudfront/distributions/{distributionId} - Distribution 수정
• DELETE /api/v1/clouds/{cloudAccountId}/cloudfront/distributions/{distributionId} - Distribution 삭제

캐시 무효화

• POST /api/v1/clouds/{cloudAccountId}/cloudfront/distributions/{distributionId}/invalidations - 캐시 무효화 생성
• GET /api/v1/clouds/{cloudAccountId}/cloudfront/distributions/{distributionId}/invalidations/{invalidationId} - 캐시 무효화 상태 조회

📝 사용 예시

Distribution 생성

POST /api/v1/clouds/{cloudAccountId}/cloudfront/distributions
{
  "providerType": "AWS",
  "accountScope": "123456789012",
  "distributionName": "my-cdn-distribution",
  "comment": "My CDN Distribution",
  "enabled": true,
  "origin": {
    "id": "origin-1",
    "domainName": "example.com",
    "type": "CUSTOM",
    "httpPort": 80,
    "httpsPort": 443
  },
  "cacheBehaviors": [
    {
      "pathPattern": "/api/*",
      "ttl": 3600,
      "allowedMethods": ["GET", "HEAD", "OPTIONS"]
    }
  ],
  "tags": {
    "Environment": "production",
    "Project": "my-project"
  }
}

캐시 무효화 생성

POST /api/v1/clouds/{cloudAccountId}/cloudfront/distributions/{distributionId}/invalidations
{
  "paths": ["/path/to/invalidate/*", "/another/path/*"]
}

⚠️ 주의사항

1. IAM 권한: CloudFront 작업을 수행하려면 적절한 IAM 권한이 필요합니다.

2. Distribution 삭제: 활성화된 Distribution을 삭제하려면 먼저 비활성화되어야 하며, 배포가 완료될 때까지 대기해야 합니다. 본 구현에서는 자동으로 처리됩니다.

3. 배포 대기 시간: Distribution 비활성화 후 배포 완료까지 최대 10분까지 대기할 수 있습니다.

4. ETag 동시성 제어: Distribution 수정 및 삭제 시 ETag를 사용하여 동시성 제어를 수행합니다.

🔄 향후 개선 사항

• Private S3 Origin 지원 (OAI/OAC)
• GCP Cloud CDN 연동
• Azure CDN 연동
• Distribution 모니터링 메트릭 수집
• 배포 상태 폴링 최적화 (Webhook 또는 이벤트 기반)

✅ 체크리스트

• Hexagonal Architecture 패턴 적용
• Port & Adapter 구현
• AWS SDK v2 통합
• DB 저장 로직 (metadata 포함)
• 보상 트랜잭션 구현
• 입력 검증 (CSP-agnostic)
• 에러 처리 및 변환
• 감사 로깅 적용
• 단위 테스트 작성
• DB 동기화 테스트