AWS CodeDeploy에서 배포 시 발생한 INTERNAL_ERROR 오류를 트러블슈팅할 수 있는 방법

일반적으로 CodeDeploy에서 EC2 인스턴스에 Blue/Green 배포가 수행되는 경우 아래와 같은 수명 주기를 거치게 됩니다. [1]

배포 실패가 발생하는 경우 어떤 수명 주기 단계에서 배포가 실패했는지 CodeDeploy 콘솔 상에서 오류 메시지를 통해 확인하고 트러블슈팅이 가능하지만, “The deployment failed because an internal system error occurred. Wait a few minutes and then try again. If the problem continues, contact your AWS administrator or AWS Support.” 오류 메시지와 함께 인스턴스에서 수명 주기가 Skipped 상태인 채로 실행되지 않는 경우 무엇이 문제인지 파악하기 어려울 것입니다.

위의 오류로 실패한 배포 ID를 AWS CLI로 확인해 보았을 때 "INTERNAL_ERROR"라는 오류 코드와 콘솔에서 확인되는 것과 동일한 메시지를 확인할 수 있습니다.

$ aws deploy get-deployment --deployment-id <배포 ID>
 <생략>
 "errorInformation": {
       "code": "INTERNAL_ERROR",
       "message": "The deployment failed because an internal system error occurred. Wait a few minutes and then try again. If the problem continues, contact your AWS administrator or AWS Support."
 },

이러한 경우 오류 메시지에서 나와 있는 것처럼 AWS CodeDeploy 일시적인 내부 오류에 의한 것일 수 있고, AWS Support 케이스를 통해 문의하여 해결하실 수 있습니다. 하지만 AWS Support 플랜에 가입되어 있지 않거나 서비스 임팩트 상황인 경우, 배포 유형이 Blue/Green, 배포 그룹으로 Auto Scaling 그룹으로 구성된 환경에서 사용자 측에서 확인할 수 있는 방법 중 하나를 소개하려고 합니다.

Blue/Green 배포

배포 그룹이 Auto Scaling 그룹으로 설정되었을 때 CodeDeploy에서는 배포 수명 주기가 실행되기 이전에 먼저 현재 Auto Scaling 그룹(Blue)과 동일하게 구성된 Auto Scaling 그룹(Green)을 자동으로 새로 생성하고 모든 Auto Scaling 그룹 설정을 동일하게 복사합니다.[2] 이 때의 Auto Scaling 그룹 설정이란 조정 정책(Scaling policy), 예약된 작업(Scheduled Action) 등을 의미하여 새로 생성된 Auto Scaling 그룹에 기존 설정들을 모두 동일하게 적용할 수 있도록 CodeDeploy 관리형 정책에 관련 권한들이 정의되어 있습니다. [3]

이렇게 “CodeDeploy_deployment_group_name_deployment_id" 형태의 이름을 가진 대체(Green) 환경이 CodeDeploy에 의해 프로비저닝되면, 각 인스턴스가 InService 상태가 된 이후 인스턴스 내부에서 CodeDeploy 수명주기가 실행됩니다.

문제 및 해결 방법

하지만 인스턴스 내부의 모든 CodeDeploy 수명주기가 Skipped 되고 배포 오류 메시지로 “The deployment failed because an internal system error occurred. Wait a few minutes and then try again. If the problem continues, contact your AWS administrator or AWS Support.”가 확인된다면, 수명 주기 이전 단계인 Auto Scaling 그룹 생성 및 설정 복사 단계가 정상적으로 수행되었는지 우선적으로 확인이 필요합니다.

가장 쉽게 확인하는 방법은 CloudTrail 콘솔에서 CreateAutoScalingGroup, PutScalingPolicy, PutScheduledUpdateGroupAction 와 같은 Auto Scaling 그룹 관련 API들이 오류 없이 잘 실행되었는지 확인하는 것입니다. INTERNAL_ERROR 오류와 관련하여 주로 확인할 수 있는 부분은 Green이 되는 Auto Scaling 그룹으로 예약된 작업(Scheduled Action)을 Blue와 동일하게 적용하는 PutScheduledUpdateGroupAction API가 호출되었을 때 아래와 같이 예약된 작업이 이미 존재하는 경우입니다.

"eventSource": "autoscaling.amazonaws.com", 
"eventName": "PutScheduledUpdateGroupAction", 
"awsRegion": "ap-northeast-2", 
"sourceIPAddress": "codedeploy.amazonaws.com", 
"userAgent": "codedeploy.amazonaws.com", 
"errorCode": "AlreadyExistsFault", 
"errorMessage": "Scheduled action with this scheduled start time already exists", 
"requestParameters": { 
   <생략>
},

Auto Scaling 그룹 문서 [4]를 확인해 보면 아래와 같은 제약 사항을 확인할 수 있습니다.

예약된 작업은 고유한 시간 값을 가져야 합니다. 다른 크기 조정 활동이 이미 예약된 경우 한 번에 하나의 활동을 예약하려고 시도하면 호출이 거부되고 예약된 시작 시간에 예약된 작업이 이미 있음을 알리는 오류가 반환됩니다.

이러한 제약 사항에 의해 CodeDeploy에서는 정상적으로 대체(Green) 환경이 생성되지 못했다고 판단하여 내부적으로 오류가 발생하게 된 것입니다.

따라서 해당 이슈를 해결하는 방법은 Blue가 되는 기존 Auto Scaling 그룹의 예약된 작업 목록을 모두 확인하여 서로 시작 시간이 겹치지 않도록 수정해 준 이후 다시 CodeDeploy 배포를 시도하면 정상적으로 오류 없이 수행될 것입니다.

그렇다면 Blue가 되는 기존 Auto Scaling 그룹에서는 어떻게 동일한 시작 시간을 가진 예약된 작업이 등록되었는지 의문이 들 수 있을 것입니다. 예약된 작업을 반복되는 일정(Recurring schedule)으로 등록하는 경우 설정한 시작 시간에 작업을 수행한 다음 지정된 반복에 따라 시작 시간을 업데이트하고 작업을 수행합니다. 따라서 기존 Auto Scaling 그룹이 생성되었던 시점에서는 등록된 예약된 작업들이 시작 시간이 겹치지 않았더라도 지정된 반복에 따라 시작 시간이 업데이트되면서 CodeDeploy Blue/Green 배포가 이루어질 시점에 시작 시간이 겹치는 시간 동안 오류가 발생할 수 있습니다.

---

참고:
[1] https://docs.aws.amazon.com/ko_kr/codedeploy/latest/userguide/reference-appspec-file-structure-hooks.html#appspec-hooks-server
[2] https://docs.aws.amazon.com/ko_kr/codedeploy/latest/userguide/deployment-groups-create-blue-green.html
[3] https://docs.aws.amazon.com/ko_kr/codedeploy/latest/userguide/managed-policies.html
[4] https://docs.aws.amazon.com/ko_kr/autoscaling/ec2/userguide/ec2-auto-scaling-scheduled-scaling.html