AWS CloudFormation StackSets のトラブルシューティング - AWS CloudFormation
スタックオペレーション失敗の一般的な原因失敗したスタック作成または更新オペレーションを再試行するスタックインスタンスの削除に失敗する場合スタックのインポートオペレーションが失敗するStackSets オペレーションのスタックインスタンスの失敗回数

AWS CloudFormation StackSets のトラブルシューティング

このトピックでは、AWS CloudFormation StackSets の一般的な問題と推奨される解決方法について説明します。

スタックオペレーション失敗の一般的な原因

問題: スタックオペレーション失敗。スタックインスタンスのステータスは OUTDATED です。

原因: スタックオペレーションが失敗する一般的な原因は複数あります。

  • テンプレートで指定されているリソースを作成するターゲットアカウントのアクセス権限が不十分。

  • AWS CloudFormation テンプレートでエラーが発生する場合があります。AWS CloudFormation のテンプレートを検証し、スタックセットを作成する前にエラーを修正します。

  • テンプレートで、グローバルリソースを作成しようとしています。S3 バケットのように一意である必要がありますが、このリソースは一意ではありません。

  • 指定されたターゲットアカウント番号は存在しません。ウィザードの [Set deployment options (デプロイオプションの設定)] ページで指定したターゲットアカウント番号を確認します。

  • この管理者アカウントには、ターゲットアカウントとの信頼関係はありません。

  • テンプレートで指定されているリソースの最大数が既にターゲットアカウントに存在しています。たとえば、ターゲットアカウントで許可されている IAM ロールの制限に達していますが、テンプレートを使用して、さらに IAM ロールを作成できます。

  • スタックセットで許可されているスタックの最大数に達しました。スタックセットあたりのスタックの最大数については、AWS CloudFormation の制限を参照してください。

ソリューション: スタックセットを作成する前にターゲットアカウントおよび管理者アカウントで必要とされるアクセス権限の詳細については、「管理者アカウントのすべてのユーザーに、すべてのターゲットアカウントのスタックを管理するための許可を付与します。」を参照してください。

失敗したスタック作成または更新オペレーションを再試行する

問題: スタック作成またはスタック更新の失敗。スタックインスタンスのステータスは OUTDATED です。スタックの作成または更新に失敗した場合にトラブルシューティングするには、AWS CloudFormation コンソールを開いてスタックのイベントを表示します。ステータスは、DELETED (作成オペレーションに失敗した場合)、または FAILED (更新オペレーションに失敗した場合) と表示されます。スタックイベントを参照し、[状況の理由] 列を検索します。[状況の理由] の値は、スタックオペレーションが失敗した理由を表します。

スタック作成失敗の根本的な原因を修正したら、スタック作成を再試行するために次の手順を行います。

ソリューション: スタックオペレーションを再試行するために、次のステップを行います。

  1. コンソールで、オペレーションが失敗したスタックを含むスタックセットを選択します。

  2. [アクション] メニューで [Edit StackSet details (StackSet の詳細を編集)] を選択して、スタックの作成または更新を再試行します。

  3. [Specify template (テンプレートの指定)] ページで、同一の AWS CloudFormation テンプレートを使用するために、デフォルトオプション [現在のテンプレートの使用] をそのまま使用します。テンプレートを変更せざるを得なかったことでスタックオペレーションに失敗したため、修正後のテンプレートをアップロードする場合は、[テンプレートを Amazon S3 にアップロード]、[参照] の順に選択して、アップデート後のテンプレートを選択します。修正後のテンプレートのアップロードが完了したら、[次へ] を選択します。

  4. [スタックの詳細を指定] ページで、テンプレート固有のパラメータを変更していない場合は、[次へ] を選択します。

  5. [Set deployment options (デプロイオプションの設定)] ページで、必要に応じて [Maximum concurrent accounts (同時アカウントの最大数)] および [Failure tolerance (障害耐性)] のデフォルトを変更します。これらの設定の詳細については、「スタックセットオペレーションのオプション」をご参照ください。

  6. [確認] ページで選択内容を確認し、チェックボックスをオンにして必要な IAM 機能を確認します。[送信] を選択します。

  7. スタックが正常に更新されたら、スタックの作成を妨げている根本的な問題が解決されるまで、この手順を繰り返します。

スタックインスタンスの削除に失敗する場合

問題: スタックの削除に失敗した。

原因: 削除保護が有効になっているスタックでは、スタックを削除できない。

解決策: スタックの削除保護が有効になっているかどうかを確認する。有効になっている場合は、削除保護を無効にし、スタックインスタンスの実行を再度行います。

スタックのインポートオペレーションが失敗する

問題: スタックのインポートオペレーションで、既存のスタックを新規または既存のスタックセットにインポートできません。スタックインスタンスは INOPERABLE ステータスです。

解決策: 次のタスクを完了して、スタックのインポートオペレーションを元に戻します。

  1. [スタックセットからスタックを削除] オプションを使用し、設定中に [RetainStacks] を有効にしてから、続行してスタックセットからスタックインスタンスを削除します。詳細については、「AWS Management Consoleまたは AWS CLI を使用してスタックインスタンスを削除する」を参照してください。

  2. INOPERABLE スタックインスタンスを削除するために Stackset のスタックインスタンスが更新されていることがわかります。

  3. インポート失敗エラーに従ってスタックインスタンスを修正し、スタックインポートオペレーションを再試行します。

StackSets オペレーションのスタックインスタンスの失敗回数

スタックインスタンスの失敗回数は、スタックインスタンスのプロビジョニングまたは更新に失敗した場合に警告を発します。これらのスタックインスタンスは、次のいずれかの理由でデプロイされませんでした。

  • 類似した設定を持つ既存のリソース

  • AWS Identity and Access Management (IAM) ロールなどの依存関係の欠落

  • その他の相反要因

最大同時実行数でデプロイする場合、最大同時実行数は最大で失敗許容回数より 1 つ多くなります。例えば、失敗許容回数が 9 である場合、最大同時実行数は 10 を超えることはできません。これにより、一部のスタックインスタンスが更新に失敗した場合でも、オペレーションは SUCCEEDED を返します。新しいスタックインスタンスの失敗回数により、失敗許容回数がすべての失敗を許容するように設定されているため、オペレーションが条件付きでのみ成功したかどうかを判断できます。

AWS Management Console、AWS SDK、または AWS CLI を使用して失敗回数を取得し、スタックインスタンスをフィルタリングして、再デプロイが必要なインスタンスを判断できます。

コンソールを使用する場合

失敗したスタックインスタンスの数を表示するには:

  1. AWS CloudFormation コンソールを開き、[StackSets] を選択します。

  2. StackSet を選択し、[Operations] (オペレーション) タブを選択します。

  3. [Status] (ステータス) 列でステータスを選択すると、ステータスの詳細が表示されます。特定のオペレーションで失敗したスタックインスタンスの数は、ステータスの詳細で確認できます。

オペレーションのスタックインスタンスのステータス、リージョン、アカウントを表示するには:

  1. ステータスの詳細で、失敗したスタックインスタンスの回数を選択します。例: [Stack instances: <number of failed stack instances>] (スタックインスタンス: )。

  2. パネルヘッダーを選択してサイドパネルを拡張します。サイドパネルの結果は、選択したオペレーションが完了した後のスタックインスタンスのステータスです。

オペレーションの現在のスタックインスタンスの詳細を表示するには:

  1. [Stack Instances] (スタックインスタンス) タブを選択します。

  2. [Last operation ID] (最終オペレーション ID) でフィルタリングします。結果には、インスタンスを変更した最後のオペレーションからの現在のステータスとステータス理由が表示されます。このフィルターを [AWS アカウント]、[AWS リージョン]、[詳細ステータス]、[ドリフトステータス] と組み合わせて使用すると、検索結果をさらに絞り込むことができます。

AWS CLI の使用

失敗したスタックインスタンスの数を取得するには、describe-stack-set-operation または list-stack-set-operations を呼び出して、StatusDetails を参照してください。

$ aws cloudformation describe-stack-set-operation --stack-set-name ss1 \
    --operation-id 5550e62f-c822-4331-88fa-21c1d7bafc60
{
    "StackSetOperation": {
        "OperationId": "5550e62f-c822-4331-88fa-21c1d7bafc60",
        "StackSetId": "ss1:9101ca57-49fc-4a61-a5a6-4c97b8adb08f",
        "Action": "CREATE",
        "Status": "SUCCEEDED",
        "OperationPreferences": {
            "RegionOrder": [],
            "FailureToleranceCount": 10,
            "MaxConcurrentCount": 10
        },
        "AdministrationRoleARN": "arn:aws:iam::123456789012:role/AWSCloudFormationStackSetAdministrationRole",
        "ExecutionRoleName": "AWSCloudFormationStackSetExecutionRole",
        "CreationTimestamp": "2022-10-26T17:18:53.947000+00:00",
        "EndTimestamp": "2022-10-26T17:19:35.304000+00:00",
        "StatusDetails": {
            "FailedStackInstancesCount": 3
        }
    }
}
aws cloudformation list-stack-set-operations --stack-set-name ss1
{
    "Summaries": [
        {
            "OperationId": "5550e62f-c822-4331-88fa-21c1d7bafc60",
            "Action": "CREATE",
            "Status": "SUCCEEDED",
            "CreationTimestamp": "2022-10-26T17:18:53.947000+00:00",
            "EndTimestamp": "2022-10-26T17:19:35.304000+00:00",
            "StatusDetails": {
                "FailedStackInstancesCount": 3
            },
            "OperationPreferences": {
                "RegionOrder": [],
                "FailureToleranceCount": 10,
                "MaxConcurrentCount": 10
            }
        }
    ]
}

特定のオペレーションの履歴概要を把握するには、list-stack-set-operation-results を使用して、オペレーションが完了した後の各スタックインスタンスのステータスとステータスの理由を表示します。Status と StatusReason を見つけるには、次の例を参照してください。

aws cloudformation list-stack-set-operation-results --stack-set-name ss1 --operation-id 5550e62f-c822-4331-88fa-21c1d7bafc60 --filters Name=OPERATION_RESULT_STATUS,Values=FAILED
{
    "Summaries": [
        {
            "Account": "123456789012",
            "Region": "us-west-2",
            "Status": "FAILED",
            "StatusReason": "Account 123456789012 should have 'AWSCloudFormationStackSetExecutionRole' role with trust relationship to Role 'AWSCloudFormationStackSetAdministrationRole'.",
            "AccountGateResult": {
                "Status": "SKIPPED",
                "StatusReason": "Account 123456789012 should have 'AWSCloudFormationStackSetExecutionRole' role with trust relationship to Role 'AWSCloudFormationStackSetAdministrationRole'."
            },
            "OrganizationalUnitId": ""
        },
        {
            "Account": "123456789012",
            "Region": "us-west-1",
            "Status": "FAILED",
            "StatusReason": "Account 123456789012 should have 'AWSCloudFormationStackSetExecutionRole' role with trust relationship to Role 'AWSCloudFormationStackSetAdministrationRole'.",
            "AccountGateResult": {
                "Status": "SKIPPED",
                "StatusReason": "Account 123456789012 should have 'AWSCloudFormationStackSetExecutionRole' role with trust relationship to Role 'AWSCloudFormationStackSetAdministrationRole'."
            },
            "OrganizationalUnitId": ""
        },
        {
            "Account": "123456789012",
            "Region": "us-east-1",
            "Status": "FAILED",
            "StatusReason": "Account 123456789012 should have 'AWSCloudFormationStackSetExecutionRole' role with trust relationship to Role 'AWSCloudFormationStackSetAdministrationRole'.",
            "AccountGateResult": {
                "Status": "SKIPPED",
                "StatusReason": "Account 123456789012 should have 'AWSCloudFormationStackSetExecutionRole' role with trust relationship to Role 'AWSCloudFormationStackSetAdministrationRole'."
            },
            "OrganizationalUnitId": ""
        }
    ]
}

list-stack-instances を DETAILED_STATUS フィルターおよび LAST_OPERATION_ID フィルターと一緒に使用すると、スタックインスタンスをデプロイしようとした最後のオペレーションで失敗したスタックインスタンスのリストを取得できます。DETAILED_STATUS と LAST_OPERATION_ID を含む例の --filters フラグを参照してください。

aws cloudformation list-stack-instances --stack-set-name ss1 --filters Name=DETAILED_STATUS,Values=FAILED Name=LAST_OPERATION_ID,Values=5550e62f-c822-4331-88fa-21c1d7bafc60
{
    "Summaries": [
        {
            "StackSetId": "ss1:9101ca57-49fc-4a61-a5a6-4c97b8adb08f",
            "Region": "us-east-1",
            "Account": "123456789012",
            "Status": "OUTDATED",
            "StatusReason": "Account 123456789012 should have 'AWSCloudFormationStackSetExecutionRole' role with trust relationship to Role 'AWSCloudFormationStackSetAdministrationRole'.",
            "StackInstanceStatus": {
                "DetailedStatus": "FAILED"
            },
            "OrganizationalUnitId": "",
            "DriftStatus": "NOT_CHECKED",
            "LastOperationId": "5550e62f-c822-4331-88fa-21c1d7bafc60"
        },
        {
            "StackSetId": "ss1:9101ca57-49fc-4a61-a5a6-4c97b8adb08f",
            "Region": "us-west-1",
            "Account": "123456789012",
            "Status": "OUTDATED",
            "StatusReason": "Account 123456789012 should have 'AWSCloudFormationStackSetExecutionRole' role with trust relationship to Role 'AWSCloudFormationStackSetAdministrationRole'.",
            "StackInstanceStatus": {
                "DetailedStatus": "FAILED"
            },
            "OrganizationalUnitId": "",
            "DriftStatus": "NOT_CHECKED",
            "LastOperationId": "5550e62f-c822-4331-88fa-21c1d7bafc60"
        },
        {
            "StackSetId": "ss1:9101ca57-49fc-4a61-a5a6-4c97b8adb08f",
            "Region": "us-west-2",
            "Account": "123456789012",
            "Status": "OUTDATED",
            "StatusReason": "Account 123456789012 should have 'AWSCloudFormationStackSetExecutionRole' role with trust relationship to Role 'AWSCloudFormationStackSetAdministrationRole'.",
            "StackInstanceStatus": {
                "DetailedStatus": "FAILED"
            },
            "OrganizationalUnitId": "",
            "DriftStatus": "NOT_CHECKED",
            "LastOperationId": "5550e62f-c822-4331-88fa-21c1d7bafc60"
        }
    ]
}

スタックインスタンスを変更する最後のオペレーション ID を見つけるには、list-stack-instances または describe-stack-instance を使用して LastOperationId を取得します。

aws cloudformation describe-stack-instance --stack-set-name ss1 --stack-instance-account 123456789012 --stack-instance-region us-east-2
{
    "StackInstance": {
        "StackSetId": "ss1:9101ca57-49fc-4a61-a5a6-4c97b8adb08f",
        "Region": "us-west-2",
        "Account": "123456789012",
        "ParameterOverrides": [],
        "Status": "OUTDATED",
        "StackInstanceStatus": {
            "DetailedStatus": "FAILED"
        },
        "StatusReason": "Account 123456789012 should have 'AWSCloudFormationStackSetExecutionRole' role with trust relationship to Role 'AWSCloudFormationStackSetAdministrationRole'.",
        "OrganizationalUnitId": "",
        "DriftStatus": "NOT_CHECKED",
        "LastOperationId": "5550e62f-c822-4331-88fa-21c1d7bafc60"
    }
}