疑難排 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 (針對失敗的更新作業)。請瀏覽堆疊事件，並找到 Status reason (狀態原因) 欄。透過 Status reason (狀態原因) 的數值，即可掌握堆疊操作失敗的原因。

若您將堆疊建立失敗的潛在原因修正完成，且準備好重試堆疊建立操作，則請執行下列步驟。

解決方案：執行下列步驟，進而重試堆疊操作。

  1. 在主控台中，選取包含操作失敗堆疊的堆疊集。

  2. 在「動作」選單中，選擇 「編輯 StackSet詳細資料」以重試建立或更新堆疊。

  3. 若要在 Specify template (指定範本) 頁面上使用相同的 AWS CloudFormation 範本，請保留預設選項 Use current template (使用目前的範本)。如果是因範本需要變更而導致堆疊操作失敗，且您想上傳修訂的範本，則請改為選擇 Upload a template to Amazon S3 (將範本上傳到 Amazon S3)，接著選擇 Browse (瀏覽) 並選取更新後的範本。完成修訂範本上傳作業時，選擇 Next (下一步)。

  4. 若您沒有要在 Specify details (指定詳細資訊) 頁面上變更任何範本特定的參數，請選擇 Next (下一步)。

  5. 在設定部署選項頁面上，您可以視需要變更並行帳戶數目上限和容錯能力的預設值。如需這些設定的詳細資訊，請參閱 堆疊集操作選項。

  6. 在 Review (檢閱) 頁面上，檢視您的選項並勾選核取方塊，藉此確認所需的 IAM 功能。選擇提交。

  7. 如果無法成功更新堆疊，請先解決任何阻礙堆疊建立的潛在原因，然後重複此程序。

堆疊執行個體刪除失敗

問題：無法刪除堆疊。

原因：如果任何堆疊啟用終止保護，將無法刪除該堆疊。

解決方案：請判斷堆疊是否啟用終止保護。如果堆疊已啟用終止保護，請先停用該功能，然後再次刪除堆疊執行個體。

堆疊匯入操作失敗

問題：堆疊匯入操作無法將現有堆疊匯入新的或現有的堆疊集。堆疊執行個體處於 INOPERABLE 狀態。

解決方案：完成下列任務，還原堆疊匯入操作。

  1. 使用 StackSets「從選項刪除堆疊」並在設定RetainStacks期間啟用，然後繼續從堆疊集中刪除堆疊執行個體。若要取得更多資訊，請參閱〈〉從堆疊集刪除堆疊執行個體。

  2. 您將看到 Stackset 的堆疊執行個體已更新，以便刪除 INOPERABLE 堆疊執行個體。

  3. 根據匯入失敗錯誤修正堆疊執行個體，然後重試堆疊匯入操作。

作業的堆疊執行個體失敗計 StackSets 數

堆疊執行個體失敗計數會在堆疊執行個體無法佈建或更新時提醒您。由於以下一個或多個原因，導致這些堆疊執行個體並未部署：

  • 現有資源具備類似組態

  • 缺少相依性，例如 AWS Identity and Access Management (IAM) 角色

  • 其他衝突因素

如果您要使用並行數目上限進行部署，並行計數上限最多會比故障容錯計數多一。例如，如果容錯計數為 9，則最大並行計數不能超過 10。這樣一來，即使某些堆疊執行個體無法更新，操作仍會傳回 SUCCEEDED。新的堆疊執行個體失敗計數可讓您判斷操作是否僅因容錯計數設定為允許所有失敗而有條件地成功。

您可以使用 AWS Management Console、 AWS SDK 或 AWS CLI 取得失敗計數和篩選堆疊執行個體，以判斷哪些執行個體需要重新部署。

使用主控台

檢視失敗的堆疊執行個體數：

  1. 開啟主AWS CloudFormation 控台並選擇StackSets。

  2. 選擇您的 StackSet，然後選擇 [作業] 索引標籤。

  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 篩選條件，取得上次嘗試部署堆疊執行個體的操作中失敗的堆疊執行個體清單。請見範例中的 --filters 標記具有 DETAILED_STATUS 和 LAST_OPERATION_ID：

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"
    }
}