Amazon ECS ブルー/グリーンデプロイのトラブルシューティング - Amazon Elastic Container Service
ロードバランサー設定の問題アクセス許可の問題ライフサイクルフックの問題

Amazon ECS ブルー/グリーンデプロイのトラブルシューティング

以下は、Amazon ECS でブルー/グリーンデプロイを使用する際に発生する可能性がある一般的な問題の解決策です。ブルー/グリーンデプロイエラーは、次のフェーズで発生する可能性があります。

  • 同期パス: CreateService または UpdateService API コールに応答してすぐに表示されるエラー。

  • 非同期パス: DescribeServiceDeployments の statusReason フィールドに表示され、デプロイのロールバックを引き起こすエラー

ロードバランサー設定の問題

ロードバランサーの設定は、Amazon ECS でのブルー/グリーンデプロイの重要なコンポーネントです。リスナールール、ターゲットグループ、ロードバランサータイプの適切な設定は、デプロイを成功させるために不可欠です。このセクションでは、ブルー/グリーンデプロイが失敗する原因となる一般的なロードバランサー設定の問題について説明します。

ロードバランサーの問題をトラブルシューティングするときは、リスナールールとターゲットグループの関係を理解することが重要です。ブルー/グリーンデプロイでは:

  • 本番リスナールールは、現在アクティブな (ブルー) サービスリビジョンにトラフィックをルーティングします

  • テストリスナールールを使用して、本番トラフィックに移行する前に新しい (グリーン) サービスリビジョンを検証できます

  • ターゲットグループを使用して、各サービスリビジョンからのコンテナインスタンスが登録されます

  • デプロイ中、リスナールールでターゲットグループの重みを調整することで、トラフィックはブルーサービスリビジョンからグリーンサービスリビジョンに徐々に移行されます

リスナールール設定エラー

以下の問題は、ブルー/グリーンデプロイのリスナールールの誤った設定に関連しています。

リスナールール ARN の代わりに Application Load Balancer リスナー 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 を使用する場合は、リスナー ARN ではなく、productionListenerRule と testListenerRule のリスナールール ARN を指定する必要があります。Network Load Balancer の場合は、リスナー ARN を使用する必要があります。

リスナー ARN を確認する方法については、「Application Load Balancer ユーザーガイド」の「Application Load Balancer のリスナー」を参照してください。ルールの 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

解決策: 本番トラフィックとテストトラフィックには異なるリスナールールを使用する必要があります。テストターゲットグループにルーティングするテストトラフィック用に別のリスナールールを作成します。

Network Load Balancer のテストリスナールールがない

エラーメッセージ: TestListenerRule is required for NLB with arn:aws:elasticloadbalancing:us-west-2:123456789012:targetgroup/nlb-targetgroup/abc123

解決策: Network Load Balancer を使用する場合は、productionListenerRule と testListenerRule の両方を指定する必要があります。有効なリスナー ARN を持つ testListenerRule を設定に追加します。詳細については、「Network Load Balancer ユーザーガイド」の「Network Load Balancer のリスナーを作成する」を参照してください。

ターゲットグループがリスナールールに関連付けられていない

エラーメッセージ: 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.

解決策: プライマリターゲットグループと代替ターゲットグループの両方を、本番リスナールールまたはテストリスナールールに関連付ける必要があります。ロードバランサー設定を更新して、両方のターゲットグループがリスナールールに適切に関連付けられるようにします。

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 ユーザーガイド」の「Application Load Balancer のリスナー」を参照してください。

ターゲットグループ設定のエラー

以下の問題は、ブルー/グリーンデプロイのターゲットグループ設定が正しくないことに関連しています。

リスナールールに、トラフィックがある複数のターゲットグループがある

エラーメッセージ: 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

解決策: ブルー/グリーンデプロイを開始する前に、リスナールールでトラフィックを受信している (重みがゼロ以外の) ターゲットグループが 1 つだけであることを確認します。リスナールール設定を更新して、トラフィックを受信すべきでないターゲットグループの重みをゼロに設定します。

ロードバランサーエントリ間でターゲットグループが重複している

エラーメッセージ: 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 のユーザーガイド」の「転送アクション」を参照してください。

ロードバランサータイプの設定エラー

以下の問題は、ブルー/グリーンデプロイのロードバランサータイプの設定が正しくないことに関連しています。

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 の前世代のロードバランサーです。現行世代のロードバランサーに移行することをお勧めします。詳細については、「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 をロードバランサー設定に追加します。

アクセス許可の問題

以下の問題は、ブルー/グリーンデプロイのアクセス許可が不十分であることに関連しています。

インフラストラクチャロールに信頼ポリシーがない

エラーメッセージ: 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 インフラストラクチャの IAM ロール」を参照してください。

ロードバランサーロールに書き込みアクセス許可がない

エラーメッセージ: 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 インフラストラクチャの IAM ロール」を参照してください。

リスナールールを変更するアクセス許可がありません

エラーメッセージ: 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 インフラストラクチャの IAM ロール」を参照してください。

ブルー/グリーンデプロイでは、AmazonECS-ServiceLinkedRolePolicy マネージドポリシーをインフラストラクチャロールにアタッチすることをお勧めします。これには、ロードバランサーリソースを管理するために必要なすべてのアクセス許可が含まれます。

ライフサイクルフックの問題

以下の問題は、ブルー/グリーンデプロイのライフサイクルフックに関連しています。

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 Logs の 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 のアクセス許可の詳細については、「Amazon ECS ブルー/グリーンデプロイの Lambda 関数に必要となるアクセス許可」を参照してください。

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 関数がタイムアウトしたか、無効なレスポンスを返しました。hookStatus フィールドを SUCCEEDED または FAILED のいずれかに設定して、Lambda 関数が有効なレスポンスを返すようにします。また、Lambda 関数のタイムアウトが検証ロジックに対して適切に設定されていることも確認します。詳細については、「Amazon ECS サービスデプロイのライフサイクルフック」を参照してください。

有効な Lambda レスポンスの例:

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