Amazon ECS 블루/그린 배포 문제 해결

다음은 Amazon ECS와 함께 블루/그린 배포를 사용할 때 겪을 수 있는 일반적인 문제에 대한 해결책을 제공해요. 블루/그린 배포 오류는 다음 단계에서 발생할 수 있어요.

출처: 문서

본문

동기 경로 (Synchronous path) – CreateService 또는 UpdateService API 호출에 대한 응답으로 즉시 나타나는 오류.
비동기 경로 (Asynchronous path) – DescribeServiceDeployments의 statusReason 필드에 나타나고 배포 롤백을 일으키는 오류.

팁: Amazon ECS MCP 서버를 AI 어시스턴트와 함께 사용해 자연어로 배포를 모니터링하고 배포 문제를 해결할 수 있어요.

로드 밸런서 구성 문제 (Load balancer configuration issues)

로드 밸런서 구성은 Amazon ECS 블루/그린 배포의 핵심 구성 요소예요. 리스너 규칙, 대상 그룹, 로드 밸런서 유형을 올바르게 구성하는 것은 성공적인 배포에 필수적이에요. 이 섹션은 블루/그린 배포를 실패시킬 수 있는 일반적인 로드 밸런서 구성 문제를 다룹니다.

로드 밸런서 문제를 해결할 때 리스너 규칙과 대상 그룹의 관계를 이해하는 것이 중요해요. 블루/그린 배포에서:

프로덕션 리스너 규칙은 현재 활성(blue) 서비스 개정으로 트래픽을 보내요.
테스트 리스너 규칙은 프로덕션 트래픽을 이동하기 전에 새(green) 서비스 개정을 검증하는 데 사용할 수 있어요.
대상 그룹은 각 서비스 개정의 컨테이너 인스턴스를 등록하는 데 사용돼요.
배포 중에는 리스너 규칙의 대상 그룹 가중치를 조정해 트래픽이 blue 서비스 개정에서 green 서비스 개정으로 점진적으로 이동돼요.

리스너 규칙 구성 오류 (Listener rule configuration errors)

다음 문제는 블루/그린 배포의 잘못된 리스너 규칙 구성과 관련돼요.

Application Load Balancer 리스너 ARN 대신 리스너 규칙 ARN 사용

오류 메시지: productionListenerRule has an invalid ARN format. Must be RuleArn for ALB or ListenerArn for NLB. Got: arn:aws:elasticloadbalancing:us-west-2:123456789012:listener/app/my-alb/abc123/def456
해결책: Application Load Balancer를 사용할 때는 productionListenerRule과 testListenerRule에 리스너 ARN이 아닌 리스너 규칙 ARN을 지정해야 해요. Network Load Balancer의 경우 리스너 ARN을 사용해야 해요. 리스너 ARN을 찾는 방법은 Application Load Balancer User Guide의 Listeners for your Application Load Balancers를 참고하세요. 규칙의 ARN 형식은 arn:aws:elasticloadbalancing:region:account-id:listener-rule/app/...예요.

프로덕션 및 테스트 리스너에 같은 규칙 사용

오류 메시지: The following rules cannot be used as both production and test listener rules: arn:aws:elasticloadbalancing:us-west-2:123456789012:listener-rule/app/my-alb/abc123/def456/ghi789
해결책: 프로덕션 및 테스트 트래픽에 서로 다른 리스너 규칙을 사용해야 해요. 테스트 대상 그룹으로 라우팅하는 테스트 트래픽용 별도의 리스너 규칙을 만드세요.

리스너 규칙과 연결되지 않은 대상 그룹

오류 메시지: Service deployment rolled back because of invalid networking configuration: Target group arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/myAlternateTG/abc123 is not associated with either productionListenerRule or testListenerRule.
해결책: 기본 대상 그룹과 대체(alternate) 대상 그룹 모두 프로덕션 리스너 규칙 또는 테스트 리스너 규칙 중 하나와 연결되어야 해요. 두 대상 그룹이 리스너 규칙과 올바르게 연결되도록 로드 밸런서 구성을 업데이트하세요.

Application Load Balancer에서 테스트 리스너 규칙 누락

오류 메시지: For Application LoadBalancer, testListenerRule is required when productionListenerRule is not associated with both targetGroup and alternateTargetGroup
해결책: Application Load Balancer를 사용할 때 두 대상 그룹이 모두 프로덕션 리스너 규칙과 연결되지 않으면 테스트 리스너 규칙을 지정해야 해요. 구성에 testListenerRule을 추가하고 두 대상 그룹이 모두 프로덕션 또는 테스트 리스너 규칙 중 하나와 연결되도록 하세요. 자세한 내용은 Application Load Balancer User Guide의 Listeners for your Application Load Balancers를 참고하세요.

대상 그룹 구성 오류 (Target group configuration errors)

다음 문제는 블루/그린 배포의 잘못된 대상 그룹 구성과 관련돼요.

리스너 규칙에 트래픽이 있는 여러 대상 그룹

오류 메시지: Service deployment rolled back because of invalid networking configuration. productionListenerRule arn:aws:elasticloadbalancing:us-west-2:123456789012:listener-rule/app/my-alb/abc123/def456/ghi789 should have exactly one target group serving traffic but found 2 target groups which are serving traffic
해결책: 블루/그린 배포를 시작하기 전에 리스너 규칙에서 하나의 대상 그룹만 트래픽을 받는지(0이 아닌 가중치) 확인하세요. 트래픽을 받지 않아야 하는 대상 그룹의 가중치를 0으로 설정하도록 리스너 규칙 구성을 업데이트하세요.

로드 밸런서 항목 간 중복 대상 그룹

오류 메시지: Duplicate targetGroupArn found: arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/myecs-targetgroup/abc123
해결책: 각 대상 그룹 ARN은 서비스 정의의 모든 로드 밸런서 항목에서 고유해야 해요. 구성을 검토하고 각 로드 밸런서 항목에 서로 다른 대상 그룹을 사용하는지 확인하세요.

프로덕션 리스너 규칙의 예상치 못한 대상 그룹

오류 메시지: Service deployment rolled back because of invalid networking configuration. Production listener rule is forwarding traffic to unexpected target group arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/random-nlb-tg/abc123. Expected traffic to be forwarded to either targetGroupArn: arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/nlb-targetgroup/def456 or alternateTargetGroupArn: arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/nlb-tg-alternate/ghi789
해결책: 프로덕션 리스너 규칙이 서비스 정의에 지정되지 않은 대상 그룹으로 트래픽을 보내고 있어요. 리스너 규칙이 서비스 정의에 지정된 대상 그룹으로만 트래픽을 보내도록 구성되어 있는지 확인하세요. 자세한 내용은 Application Load Balancer User Guide의 forward actions를 참고하세요.

로드 밸런서 유형 구성 오류 (Load balancer type configuration errors)

다음 문제는 블루/그린 배포의 잘못된 로드 밸런서 유형 구성과 관련돼요.

Classic Load Balancer와 Application Load Balancer 또는 Network Load Balancer 구성 혼합

오류 메시지: All loadBalancers must be strictly either ELBv1 (defining loadBalancerName) or ELBv2 (defining targetGroupArn)
참고: Classic Load Balancer는 Elastic Load Balancing의 이전 세대 로드 밸런서예요. 최신 세대 로드 밸런서로 마이그레이션하는 것을 권장해요. 자세한 내용은 Migrate your Classic Load Balancer를 참고하세요.
해결책: 모두 Classic Load Balancer를 사용하거나 모두 Application Load Balancer와 Network Load Balancer를 사용하세요. Application Load Balancer와 Network Load Balancer의 경우 targetGroupArn 필드만 지정하세요.

Classic Load Balancer와 함께 고급 구성 사용

오류 메시지: advancedConfiguration field is not allowed with ELBv1 loadBalancers
해결책: 블루/그린 배포의 고급 구성은 Application Load Balancer와 Network Load Balancer에서만 지원돼요. Classic Load Balancer(loadBalancerName으로 지정)를 사용한다면 advancedConfiguration 필드를 사용할 수 없어요. Application Load Balancer로 전환하거나 advancedConfiguration 필드를 제거하세요.

로드 밸런서 간 일관되지 않은 고급 구성

오류 메시지: Either all or none of the provided loadBalancers must have advancedConfiguration defined
해결책: 여러 로드 밸런서를 사용한다면 모든 로드 밸런서에 advancedConfiguration을 정의하거나 어느 것에도 정의하지 않아야 해요. 모든 로드 밸런서 항목에서 일관성을 유지하도록 구성을 업데이트하세요.

블루/그린 배포에서 고급 구성 누락

오류 메시지: advancedConfiguration field is required for all loadBalancers when using a non-ROLLING deployment strategy
해결책: Application Load Balancer와 함께 블루/그린 배포 전략을 사용할 때는 모든 로드 밸런서 항목에 대해 advancedConfiguration 필드를 지정해야 해요. 로드 밸런서 구성에 필수 advancedConfiguration을 추가하세요.

권한 문제 (Permission issues)

다음 문제는 블루/그린 배포의 권한 부족과 관련돼요.

인프라 역할의 신뢰 정책 누락

오류 메시지: Service deployment rolled back because of invalid networking configuration. ECS was unable to manage the ELB resources due to missing permissions on ECS Infrastructure Role 'arn:aws:iam::123456789012:role/Admin'.
해결책: 로드 밸런서 리소스 관리에 지정된 IAM 역할에 올바른 신뢰 정책이 없어요. 서비스가 역할을 수임할 수 있도록 역할의 신뢰 정책을 업데이트하세요. 신뢰 정책에는 다음이 포함되어야 해요.

{
  "Version":"2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "ecs.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

로드 밸런서 역할의 읽기 권한 누락

오류 메시지: service myService failed to describe target health on target-group myTargetGroup with (error User: arn:aws:sts::123456789012:assumed-role/myELBRole/ecs-service-scheduler is not authorized to perform: elasticloadbalancing:DescribeTargetHealth because no identity-based policy allows the elasticloadbalancing:DescribeTargetHealth action)
해결책: 로드 밸런서 리소스 관리에 사용되는 IAM 역할에 대상 상태 정보를 읽을 권한이 없어요. 역할 정책에 elasticloadbalancing:DescribeTargetHealth 권한을 추가하세요. Elastic Load Balancing 권한에 대한 정보는 Amazon ECS infrastructure IAM role for load balancers를 참고하세요.

로드 밸런서 역할의 쓰기 권한 누락

오류 메시지: service myService failed to register targets in target-group myTargetGroup with (error User: arn:aws:sts::123456789012:assumed-role/myELBRole/ecs-service-scheduler is not authorized to perform: elasticloadbalancing:RegisterTargets on resource: arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/myTargetGroup/abc123 because no identity-based policy allows the elasticloadbalancing:RegisterTargets action)
해결책: 로드 밸런서 리소스 관리에 사용되는 IAM 역할에 대상을 등록할 권한이 없어요. 역할 정책에 elasticloadbalancing:RegisterTargets 권한을 추가하세요. Elastic Load Balancing 권한에 대한 정보는 Amazon ECS infrastructure IAM role for load balancers를 참고하세요.

리스너 규칙 수정 권한 누락

오류 메시지: Service deployment rolled back because TEST_TRAFFIC_SHIFT lifecycle hook(s) failed. User: arn:aws:sts::123456789012:assumed-role/myELBRole/ECSNetworkingWithELB is not authorized to perform: elasticloadbalancing:ModifyListener on resource: arn:aws:elasticloadbalancing:us-west-2:123456789012:listener/app/my-alb/abc123/def456 because no identity-based policy allows the elasticloadbalancing:ModifyListener action
해결책: 로드 밸런서 리소스 관리에 사용되는 IAM 역할에 리스너를 수정할 권한이 없어요. 역할 정책에 elasticloadbalancing:ModifyListener 권한을 추가하세요. Elastic Load Balancing 권한에 대한 정보는 Amazon ECS infrastructure IAM role for load balancers를 참고하세요.

블루/그린 배포의 경우 인프라 역할에 AmazonECS-ServiceLinkedRolePolicy 관리형 정책을 연결하는 것을 권장해요. 이 정책에는 로드 밸런서 리소스 관리에 필요한 모든 권한이 포함돼요.

수명 주기 훅 문제 (Lifecycle hook issues)

다음 문제는 블루/그린 배포의 수명 주기 훅과 관련돼요.

Lambda 훅 역할의 잘못된 신뢰 정책

오류 메시지: Service deployment rolled back because TEST_TRAFFIC_SHIFT lifecycle hook(s) failed. ECS was unable to assume role arn:aws:iam::123456789012:role/Admin
해결책: Lambda 수명 주기 훅에 지정된 IAM 역할에 올바른 신뢰 정책이 없어요. 서비스가 역할을 수임할 수 있도록 역할의 신뢰 정책을 업데이트하세요. 신뢰 정책에는 다음이 포함되어야 해요.

{
  "Version":"2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "ecs.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Lambda 훅이 FAILED 상태 반환

오류 메시지: Service deployment rolled back because TEST_TRAFFIC_SHIFT lifecycle hook(s) failed. Lifecycle hook target arn:aws:lambda:us-west-2:123456789012:function:myHook returned FAILED status.
해결책: 수명 주기 훅으로 지정된 Lambda 함수가 FAILED 상태를 반환했어요. Amazon CloudWatch 로그에서 Lambda 함수 로그를 확인해 실패 이유를 확인하고 배포 이벤트를 올바르게 처리하도록 함수를 업데이트하세요.

Lambda 함수 호출 권한 누락

오류 메시지: Service deployment rolled back because TEST_TRAFFIC_SHIFT lifecycle hook(s) failed. ECS was unable to invoke hook target arn:aws:lambda:us-west-2:123456789012:function:myHook due to User: arn:aws:sts::123456789012:assumed-role/myLambdaRole/ECS-Lambda-Execution is not authorized to perform: lambda:InvokeFunction on resource: arn:aws:lambda:us-west-2:123456789012:function:myHook because no identity-based policy allows the lambda:InvokeFunction action
해결책: Lambda 수명 주기 훅에 사용되는 IAM 역할에 Lambda 함수를 호출할 권한이 없어요. 특정 Lambda 함수 ARN에 대해 역할 정책에 lambda:InvokeFunction 권한을 추가하세요. Lambda 권한에 대한 정보는 Permissions required for Lambda functions in Amazon ECS blue/green deployments를 참고하세요.

Lambda 함수 시간 초과 또는 잘못된 응답

오류 메시지: Service deployment rolled back because TEST_TRAFFIC_SHIFT lifecycle hook(s) failed. ECS was unable to parse the response from arn:aws:lambda:us-west-2:123456789012:function:myHook due to HookStatus must not be null
해결책: Lambda 함수가 시간 초과되거나 잘못된 응답을 반환했어요. Lambda 함수가 hookStatus 필드를 SUCCEEDED 또는 FAILED 중 하나로 설정한 유효한 응답을 반환하는지 확인하세요. 또한 검증 로직에 적절한 Lambda 함수 시간 초과가 설정되어 있는지 확인하세요. 자세한 내용은 Lifecycle hooks for Amazon ECS service deployments를 참고하세요.
유효한 Lambda 응답의 예:

{
  "hookStatus": "SUCCEEDED",
  "reason": "Validation passed"
}

수명 주기 훅의 잘못된 targetType

오류 메시지: Invalid targetType. Valid values are: AWS_LAMBDA, PAUSE
해결책: 수명 주기 훅 구성에서 targetType 필드를 확인하세요. 유효한 값은 AWS_LAMBDA와 PAUSE예요.

일시 중지 훅의 잘못된 수명 주기 단계

오류 메시지: Invalid lifecycle stage provided for Pause Hook
해결책: 일시 중지 훅은 PRE_SCALE_UP, POST_SCALE_UP, POST_TEST_TRAFFIC_SHIFT, PRE_PRODUCTION_TRAFFIC_SHIFT 또는 POST_PRODUCTION_TRAFFIC_SHIFT에서만 구성할 수 있어요. 일시 중지 훅에는 TEST_TRAFFIC_SHIFT 또는 PRODUCTION_TRAFFIC_SHIFT를 사용할 수 없어요.

일시 중지 훅 시간 초과

오류 메시지: Service deployment rolled back because POST_TEST_TRAFFIC_SHIFT pause hook timed out.
해결책: 일시 중지 훅이 ContinueServiceDeployment 호출을 받기 전에 시간 초과됐어요. 자동화 또는 승인 워크플로가 구성된 시간 초과가 만료되기 전에 ContinueServiceDeployment를 호출하는지 확인하세요. 훅이 만료되도록 설정된 시점을 보려면 DescribeServiceDeployments의 expiresAt 필드를 확인하세요. 더 많은 시간이 필요하면 일시 중지 훅 구성에서 timeoutInMinutes 값을 늘리세요(최대 20,160분 / 14일). 시간 초과 시 롤백 대신 배포를 자동으로 계속하길 원하면 timeoutConfiguration.action을 CONTINUE로 설정하세요.

잘못된 hookId 형식

오류 메시지: Invalid hookId: hookId must follow the format: ecs-{hookType}-{id}
해결책: ContinueServiceDeployment에 제공된 hookId가 예상 형식과 일치하지 않아요. DescribeServiceDeployments를 호출하고 lifecycleHookDetails 배열을 확인해 올바른 hookId를 검색하세요. hookId를 수동으로 구성하지 마세요.

hookId를 찾을 수 없거나 만료됨

오류 메시지: Provided hookId is either completed, unavailable, or not associated with the given Resource ARN
해결책: hookId가 더 이상 유효하지 않아요. 훅이 이미 시간 초과됐거나, 이미 계속되었거나 롤백되었거나, 새 배포가 트리거되어(이전 hookId가 무효화됨) 또는 hookId가 다른 서비스 배포 ARN에 속할 때 발생할 수 있어요. 활성 배포에서 DescribeServiceDeployments를 호출해 현재 hookId를 검색하세요.

터미널 상태의 배포

오류 메시지: Continuing a service deployment is not allowed for service deployment in terminal states.
해결책: 배포가 이미 완료, 롤백 또는 중지되었어요. ContinueServiceDeployment는 AWAITING_ACTION 상태의 일시 중지 훅이 있는 IN_PROGRESS 배포에서만 호출할 수 있어요. DescribeServiceDeployments를 사용해 현재 배포 상태를 확인하세요.

서비스 배포를 찾을 수 없음

오류 메시지: The service deployment does not exist.
해결책: 제공된 serviceDeploymentArn이 기존 서비스 배포와 일치하지 않아요. ListServiceDeployments를 사용해 올바른 ARN을 찾으세요.