5. CodeDeploy

1. Overview

 

개요 및 배경

• 애플리케이션 배포(v1 -> v2)를 자동화하고 실패 시 자동 롤백을 지원하는 강력한 배포 서비스임
• 배포 속도 제어 및 appspec.yml 파일을 활용한 세밀한 배포 수명 주기(Lifecycle) 관리가 가능함
• 주요 배포 대상 리소스: EC2 인스턴스, 온프레미스 서버, AWS Lambda, Amazon ECS

주요 리소스 및 기능

1. EC2 / 온프레미스 (On-premises) 플랫폼 배포
   • 대상 서버에 반드시 CodeDeploy 에이전트(Agent)가 설치되어 있어야 작동하며, AWS Systems Manager(SSM)를 통해 설치 자동화 가능
   • 에이전트가 Amazon S3에서 애플리케이션 리비전(Revision)을 다운로드해야 하므로, 대상 EC2에 적절한 IAM 권한(인스턴스 프로파일) 부여 필수
   • 인플레이스(In-place) 배포: 기존 인스턴스에서 애플리케이션 구동을 잠시 멈추고 새 버전으로 업데이트함 (AllAtOnce, HalfAtATime, OneAtATime 등 속도 조절 가능)
   • 블루/그린(Blue/Green) 배포: 기존(Blue)과 동일한 규모의 새 Auto Scaling 그룹(Green)을 프로비저닝한 뒤, 로드 밸런서 트래픽을 일괄 전환함
2. AWS Lambda 플랫폼 배포
   • 특정 Lambda 별칭(Alias)(예: PROD)이 가리키는 버전을 v1에서 v2로 점진적 전환(Traffic Shifting)하며, AWS SAM 프레임워크와 네이티브 통합됨
   • Linear (선형): 지정된 시간(N분)마다 일정한 비율로 트래픽을 점진적 증가시킴 (예: Linear10PercentEvery3Minutes)
   • Canary (카나리): 지정된 시간 동안 소규모 트래픽만 새 버전으로 보내 안전성을 테스트한 후, 100% 전환함 (예: Canary10Percent5Minutes)
   • AllAtOnce (일괄): 즉시 100%의 트래픽을 새 버전으로 전환함
3. Amazon ECS 플랫폼 배포
   • 새로운 ECS 작업 정의(Task Definition)를 기반으로 컨테이너 애플리케이션을 배포함
   • ALB(Application Load Balancer)를 통해 기존 대상 그룹(Target Group)에서 신규 대상 그룹으로 트래픽을 전환함 (Lambda와 동일하게 Linear, Canary, AllAtOnce 전략 사용)

헷갈리는 포인트 (Tips)

• EC2나 온프레미스 배포 시, 배포가 S3 다운로드 단계에서 실패한다면 EC2 인스턴스 프로파일(IAM Role)에 S3 읽기 권한이 올바르게 할당되었는지 가장 먼저 확인해야 함
• ECS 플랫폼을 대상으로 하는 배포는 인플레이스(In-place) 방식을 지원하지 않으며, 오직 블루/그린(Blue/Green) 배포 방식만 사용할 수 있음
• 트래픽 전환 전략 중, Canary는 최초 소규모 오픈 후 나머지 전체를 '한 번에' 전환하는 방식이고, Linear는 여러 단계에 걸쳐 '일정한 비율로 여러 번' 트래픽을 늘려가는 방식임을 명확히 구분해야 함

---

2. EC2 Deep Dive

 

개요 및 배경

• EC2/온프레미스 환경에 대한 CodeDeploy 배포의 세부 동작 방식, 배포 수명 주기(Lifecycle) 훅, 블루/그린 배포 구성, 배포 속도 제어 및 이벤트 알림(SNS) 구조를 깊이 있게 이해해야 함
• 무중단 배포를 위해 로드 밸런서(ALB) 연동 시 트래픽 제어 단계와 애플리케이션 설치 단계의 실행 순서 파악이 중요함

주요 리소스 및 기능

1. 배포 대상 식별 방법
   • EC2 태그(Tags): 특정 태그(예: Project=FinanceApp)가 부여된 인스턴스들을 식별하여 업데이트함
   • Auto Scaling 그룹 연동: 특정 ASG를 대상으로 지정하면, 향후 해당 그룹에서 새로 스케일 아웃(Scale-out)되는 인스턴스에도 CodeDeploy가 자동으로 최신 버전을 배포함
2. appspec.yml 및 배포 수명 주기 훅 (Lifecycle Hooks)
   • CodeDeploy 에이전트가 실행할 스크립트와 실행 시점을 정의하는 핵심 파일임
   • 로드 밸런서 환경에서 인플레이스(In-place) 배포 시 훅 실행 순서:
     1. BlockTraffic (로드 밸런서 트래픽 차단): BeforeBlockTraffic -> BlockTraffic (예약됨) -> AfterBlockTraffic
     2. Application Installation (애플리케이션 설치): ApplicationStop -> DownloadBundle (예약됨) -> BeforeInstall -> Install (예약됨) -> AfterInstall -> ApplicationStart -> ValidateService
     3. AllowTraffic (로드 밸런서 트래픽 허용): BeforeAllowTraffic -> AllowTraffic (예약됨) -> AfterAllowTraffic
3. 블루/그린(Blue/Green) 배포 모드
   • 수동(Manual) 모드: Blue와 Green 인스턴스 그룹을 사용자가 사전에 각각 태그로 지정하여 직접 프로비저닝해야 함
   • 자동(Automatic) 모드: 기존 ASG를 복제하여 CodeDeploy가 Green ASG를 자동 생성 및 프로비저닝함
   • 배포 완료 후 기존(Blue) 인스턴스는 지정된 시간(기본 1시간, 최대 2일) 대기 후 자동 종료(Terminate)되거나, 롤백을 위해 수동으로 유지(Keep alive)할 수 있음
4. 블루/그린 배포 시 훅(Hook) 실행 차이
   • 신규(v2/Green) 인스턴스: 트래픽이 없는 상태이므로 ApplicationStop부터 시작하여 Install -> ValidateService 후 AllowTraffic 관련 훅이 실행됨
   • 기존(v1/Blue) 인스턴스: 트래픽이 제거되는 과정이므로 BeforeBlockTraffic -> BlockTraffic -> AfterBlockTraffic까지만 실행되고 이후 종료됨

헷갈리는 포인트 (Tips)

• BlockTraffic, DownloadBundle, Install, AllowTraffic 단계는 CodeDeploy 서비스가 자체적으로 수행하는 예약된(Reserved) 단계이므로 사용자가 이 시점에 사용자 지정 스크립트를 실행할 수 없음
• EC2 인스턴스 내에서 훅 스크립트 실행 시, CodeDeploy 에이전트가 DEPLOYMENT_GROUP_NAME과 같은 환경 변수를 주입해주므로 스크립트 내부에서 동적인 로직 처리가 가능함
• 블루/그린 배포를 구성하려면 인프라 아키텍처 상에 로드 밸런서(ALB, CLB, NLB 등)가 반드시 존재해야 트래픽 전환(Traffic Shifting)이 가능함

---

3. ECS Deep Dive

 

개요 및 배경

• Amazon ECS 서비스에 새로운 작업 정의(Task Definition)를 배포하고 로드 밸런서 트래픽을 안전하게 전환하는 프로세스를 자동화함
• ECS 플랫폼 배포는 오직 블루/그린(Blue/Green) 배포 방식만 지원하며, 로드 밸런서(ALB/NLB) 연동이 필수적임
• EC2나 온프레미스 서버와 달리 대상 컨테이너에 CodeDeploy 에이전트(Agent)를 설치할 필요가 없음

주요 리소스 및 기능

1. 배포 사전 요구사항 및 파이프라인 자동화
   • 새로운 컨테이너 이미지를 빌드하여 Amazon ECR에 푸시해야 함
   • 해당 이미지를 참조하는 새로운 ECS 작업 정의(Task Definition) 리비전을 생성 및 등록함
   • 새 작업 정의의 ARN과 로드 밸런서 정보(컨테이너 이름, 포트 등)가 명시된 appspec.yml 파일을 생성함
   • CodePipeline 연동 시, CodeBuild 단계에서 위 3가지 작업을 모두 수행한 뒤 동적으로 생성된 appspec.yml을 CodeDeploy의 입력 아티팩트로 전달하는 아키텍처를 구성함
2. 트래픽 전환 전략 (Traffic Shifting)
   • Linear (선형): 설정된 시간 간격(N분)마다 트래픽을 일정 비율(%)씩 점진적으로 새 대상 그룹(Green)으로 전환함 (예: Linear10PercentEvery1Minute)
   • Canary (카나리): 지정된 시간 동안 소규모 트래픽(예: 10%)만 새 대상 그룹으로 보내 안전성을 모니터링한 후, 남은 100%를 일괄 전환함 (예: Canary10Percent15Minutes)
   • All At Once (일괄): 즉시 100%의 트래픽을 새 대상 그룹으로 전환함
   • 테스트 리스너 (Test Listener): 메인 운영 리스너가 트래픽을 전환하기 전, 보조 리스너를 통해 새 대상 그룹에만 테스트 트래픽을 전송하여 사전 검증(Health Check 등)을 수행할 수 있음
3. 배포 수명 주기 훅 (Lifecycle Hooks)
   • ECS 배포에서 훅(Hook)은 쉘 스크립트가 아닌 AWS Lambda 함수로 실행되며, 배포당 한 번씩만 호출됨
   • 실행 흐름: BeforeInstall -> Install (예약됨, 새 ECS 태스크 생성) -> AfterInstall -> (Test Listener를 통한 테스트 트래픽 주입 및 검증) -> BeforeAllowTraffic -> AllowTraffic (예약됨, 운영 트래픽 전환) -> AfterAllowTraffic

헷갈리는 포인트 (Tips)

• EC2 배포 시 appspec.yml에는 쉘 스크립트(.sh) 경로를 지정하지만, ECS 배포 시에는 각 훅 단계에서 실행할 Lambda 함수의 ARN을 기재해야 함
• Install 및 AllowTraffic 단계는 CodeDeploy와 ECS 서비스가 통신하여 컨테이너를 프로비저닝하고 로드 밸런서 트래픽을 전환하는 예약된(Reserved) 단계이므로, 사용자 지정 Lambda 함수를 연결할 수 없음
• 전체 배포 과정을 롤백해야 하는 상황이 발생하면, CodeDeploy는 로드 밸런서 트래픽을 다시 기존 대상 그룹(Blue)으로 즉시 라우팅하여 가용성을 복구함

---

4. Lambda Deep Dive

 

개요 및 배경

• 특정 Lambda 별칭(Alias)이 가리키는 버전을 기존 버전(v1)에서 새로운 대상 버전(v2)으로 안전하고 점진적으로 전환(Traffic Shifting)함
• 컨테이너나 서버 배포와 달리, 대상 환경에 CodeDeploy 에이전트(Agent)를 설치할 필요가 없는 완전 관리형 서버리스 배포 방식임

주요 리소스 및 기능

1. appspec.yml 구성 및 파이프라인 자동화
   • 배포할 Lambda 함수 이름, 대상 별칭(Alias), 현재 버전(Current Version), 대상 버전(Target Version) 정보만을 포함하는 매우 단순한 구조를 가짐
   • 일반적인 CI/CD 파이프라인에서 CodeBuild가 새 Lambda 버전을 생성함과 동시에 appspec.yml을 동적으로 생성하여 아티팩트로 전달하고, CodeDeploy가 이를 바탕으로 배포를 수행함
2. 트래픽 전환 전략 (Traffic Shifting Strategies)
   • Linear (선형): 설정된 시간(분) 간격마다 일정 비율(%)로 트래픽을 점진적으로 증가시킴 (예: Linear10PercentEvery3Minutes)
   • Canary (카나리): 지정된 시간 동안 소규모 트래픽만 대상 버전으로 전송하여 안전성을 검증한 후, 남은 트래픽을 일괄 전환함 (예: Canary10Percent10Minutes)
   • All At Once (일괄): 즉시 100%의 트래픽을 새로운 버전으로 전환함
3. 배포 수명 주기 훅 (Lifecycle Hooks)
   • EC2 배포와 달리 쉘 스크립트가 아닌 AWS Lambda 함수 자체를 훅으로 사용하여 검증 로직을 실행함
   • BeforeAllowTraffic: 트래픽이 새 버전으로 라우팅되기 전에 사전 상태 체크 및 유효성 검증을 수행함
   • AllowTraffic (예약됨): CodeDeploy가 실제 트래픽 전환을 수행하는 단계로 사용자 정의 훅을 연결할 수 없음
   • AfterAllowTraffic: 트래픽 전환이 완료된 후, 새 버전이 실제 트래픽을 정상적으로 처리하는지 최종 검증함

헷갈리는 포인트 (Tips)

• Lambda 플랫폼 배포의 수명 주기 훅은 EC2 배포에 비해 매우 단순하며, 오직 트래픽 허용(AllowTraffic) 전후 단계(BeforeAllowTraffic, AfterAllowTraffic)에만 훅을 배치할 수 있음
• appspec.yml의 훅 정의 부분에는 스크립트 파일(.sh) 경로가 아닌, 검증 로직을 수행할 Lambda 함수의 이름(또는 ARN)을 명시해야 함

---

5. Rollbacks & Troubleshooting

 

개요 및 배경

• 배포 실패 또는 비정상 동작 발생 시 이전의 안정적인 버전으로 되돌리는 롤백(Rollback) 메커니즘과 일반적인 오류 해결(Troubleshooting) 방법
• Auto Scaling Group(ASG) 확장(Scale-out) 및 로드 밸런서(ELB) 상태 검사(Health Checks)와 관련된 배포 트러블슈팅 개념 이해 필요

주요 리소스 및 기능

1. 롤백 (Rollbacks)
   • 새 EC2 인스턴스나 ECS 태스크 배포 실패, 혹은 연결된 CloudWatch 경보(Alarm) 트리거 시 자동으로 롤백을 수행함 (수동 실행 및 비활성화도 가능)
   • 시스템 상태를 단순히 복원(Restore)하는 것이 아니라, 마지막으로 성공했던 이전 버전을 완전히 '새로운 배포(New Deployment)'로 취급하여 다시 푸시(Push)하는 메커니즘임
2. 트러블슈팅: Invalid Signature Exception 및 권한 문제
   • Invalid Signature Exception: CodeDeploy 서비스와 EC2 인스턴스 간의 시간 불일치(Time mismatch)로 인해 서명이 만료되는 문제임. EC2의 시간을 NTP 등을 통해 동기화하여 해결함
   • 인스턴스 배포 실패/건너뜀 발생 시: CodeDeploy 에이전트 정상 실행 여부, IAM 인스턴스 프로파일/서비스 역할 권한, HTTP 프록시(proxy_uri) 구성, 시간 동기화 상태를 우선 점검해야 함
   • CodeDeploy의 모든 배포 실패 이벤트는 Amazon EventBridge를 통해 가로채어(Intercept) 알림 및 대응 자동화를 구현할 수 있음
3. 배포 진행 중 ASG 스케일 아웃 (Scale-out Event)
   • 배포가 아직 완료되지 않은 시점에 ASG가 확장(Scale-out)되면, 새로 생성된 인스턴스에는 이전 버전(v1)이 프로비저닝됨 (일시적으로 v1과 v2가 혼재됨)
   • 기본적으로 메인 배포가 성공적으로 완료된 후, CodeDeploy가 구버전 인스턴스들을 최신 버전(v2)으로 맞추기 위한 후속 배포(Follow-on deployment)를 자동으로 시작함

헷갈리는 포인트 (Tips)

• 블루/그린 배포 시 AllowTraffic 단계 실패 현상: 배포 로그 상에는 오류가 없고 애플리케이션 설치도 정상적으로 완료되었으나 트래픽 전환이 불가능한 경우, ELB(Elastic Load Balancer)의 상태 검사(Health checks)가 잘못 구성되어 인스턴스를 비정상으로 판별했을 확률이 매우 높음. ELB 헬스 체크 설정을 점검하고 수정해야 함