本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 疑難排解 CloudFormation StackSets
本主題涵蓋部分常見的 StackSets 問題，以及這些問題的建議解決方案。
**Topics**
+ [堆疊操作失敗的常見原因](#common-reasons-for-stack-operation-failure)
+ [重試失敗的堆疊建立或更新操作](#retrying-failed-stack-creation-or-update-operations)
+ [堆疊執行個體刪除失敗](#stack-instance-delete-fails)
+ [堆疊匯入操作失敗](#stack-import-fails)
+ [StackSets 操作的堆疊執行個體失敗計數](#stack-instance-failure-count-for-stackset-operations)
## 堆疊操作失敗的常見原因
**問題：**堆疊操作失敗，且堆疊執行個體的狀態為 `OUTDATED`。
**原因：**堆疊操作失敗可能有幾種常見原因。
+ 目標帳戶沒有足夠的許可，無法建立範本中指定的資源。
+ CloudFormation 範本可能有錯誤。在建立 StackSet 之前，請驗證 CloudFormation 中的範本並修正錯誤。
+ 範本正在嘗試建立的全域資源 (如 S3 儲存貯體) 必須獨一無二，但該資源已存在。
+ 指定的目標帳戶號碼並不存在；請檢查您在精靈的 **Set deployment options (設定部署選項)** 頁面中所指定之目標帳戶號碼。
+ 管理員帳戶與目標帳戶沒有信任關係。
+ 目標帳戶中的資源已達範本所指定的最大數量。舉例來說，目標帳戶可能已達到 IAM 角色數量的上限，但範本仍持續建立更多 IAM 角色。
+ StackSet 中允許的堆疊數已達到上限，如需每個 StackSet 的堆疊數目上限，請參閱 [了解 CloudFormation 配額](cloudformation-limits.md)。
**解決方案：** 如需詳細資訊，以了解建立 StackSets 前目標與管理員帳戶要具備的許可，請參閱 [為管理員帳戶的所有使用者提供可以在所有目標帳戶中管理堆疊的許可](stacksets-prereqs-self-managed.md#stacksets-prereqs-accountsetup) 小節。
## 重試失敗的堆疊建立或更新操作
**問題：**堆疊建立或更新失敗，且堆疊執行個體的狀態為 `OUTDATED`。若要對堆疊建立或更新失敗的原因進行故障診斷，請開啟 CloudFormation 主控台以檢視堆疊事件；在建立操作失敗的情況下，這些事件的狀態將為 `DELETED`，而在更新操作失敗的情況下，則會顯示 `FAILED` 狀態。請瀏覽堆疊事件，並找到 **Status reason (狀態原因)** 欄。透過 **Status reason (狀態原因)** 的數值，即可掌握堆疊操作失敗的原因。
若您將堆疊建立失敗的潛在原因修正完成，且準備好重試堆疊建立操作，則請執行下列步驟。
**解決方案：**執行下列步驟，進而重試堆疊操作。
1. 在主控台中，選取包含操作失敗堆疊的 StackSet。
1. 在 **Actions (動作)** 選單中，選擇 **Edit StackSet details (編輯 StackSet 詳細資訊)** 重試建立或更新堆疊。
1. 若要在**指定範本**頁面上使用相同的 CloudFormation 範本，請保留預設選項**使用目前的範本**。如果是因範本需要變更而導致堆疊操作失敗，且您想上傳修訂的範本，則請改為選擇 **Upload a template to Amazon S3 (將範本上傳到 Amazon S3)**，接著選擇 **Browse (瀏覽)** 並選取更新後的範本。完成修訂範本上傳作業時，選擇 **Next (下一步)**。
1. 若您沒有要在**指定堆疊詳細資訊** 頁面上變更任何範本特定的參數，請選擇**下一步**。
1. 在**設定部署選項**頁面上，您可以視需要變更**並行帳戶數目上限**和**容錯能力**的預設值。如需這些設定的詳細資訊，請參閱 [StackSet 操作選項](stacksets-concepts.md#stackset-ops-options)。
1. 在 **Review (檢閱)** 頁面上，檢視您的選項並勾選核取方塊，藉此確認所需的 IAM 功能。選擇**提交**。
1. 如果無法成功更新堆疊，請先解決任何阻礙堆疊建立的潛在原因，然後重複此程序。
## 堆疊執行個體刪除失敗
**問題：**無法刪除堆疊。
**原因：**如果任何堆疊啟用終止保護，將無法刪除該堆疊。
**解決方案：**請判斷堆疊是否啟用終止保護。如果堆疊已啟用終止保護，請先停用該功能，然後再次刪除堆疊執行個體。
## 堆疊匯入操作失敗
**問題：**堆疊匯入操作無法將現有堆疊匯入新的或現有的 StackSets。堆疊執行個體處於 `INOPERABLE` 狀態。
**解決方案：**完成下列任務，還原堆疊匯入操作。
1. 在設定期間使用**從 StackSets 刪除堆疊**選項並啟用 **RetaInstacks**，然後繼續刪除 StackSet 中的堆疊執行個體。如需詳細資訊，請參閱 [從 CloudFormation StackSets 刪除堆疊](stackinstances-delete.md)。
1. 您將看到 Stackset 的堆疊執行個體已更新，以便刪除 `INOPERABLE` 堆疊執行個體。
1. 根據匯入失敗錯誤修正堆疊執行個體，然後重試堆疊匯入操作。
## StackSets 操作的堆疊執行個體失敗計數
堆疊執行個體失敗計數會在堆疊執行個體無法佈建或更新時提醒您。由於以下一個或多個原因，導致這些堆疊執行個體並未部署：
+ 現有資源具備類似組態
+ 缺少相依性，例如 AWS Identity and Access Management (IAM) 角色
+ 其他衝突因素
如果您要使用並行數目上限進行部署，並行計數上限最多會比故障容錯計數多一。例如，如果容錯計數為 9，則最大並行計數不能超過 10。這樣一來，即使某些堆疊執行個體無法更新，操作仍會傳回 `SUCCEEDED`。新的堆疊執行個體失敗計數可讓您判斷操作是否僅因容錯計數設定為允許所有失敗而有條件地成功。
您可以使用 AWS 管理主控台、 AWS SDK 或 AWS CLI 取得故障計數並篩選堆疊執行個體，以判斷需要重新部署哪些執行個體。
### 使用主控台
**檢視失敗的堆疊執行個體數：**
1. 開啟 [CloudFormation 主控台](https://console.aws.amazon.com/cloudformation)，然後選擇 **StackSet**。
1. 選擇您的 StackSet，然後選擇 **Operations** (操作) 索引標籤。
1. 選擇 **Status** (狀態) 資料欄中的狀態，以檢視狀態的詳細資訊。您可以在狀態詳細資訊中找到特定操作的失敗堆疊執行個體數目。
**檢視操作的堆疊執行個體的帳戶、區域和狀態：**
1. 在狀態詳細資訊中，選擇失敗的堆疊執行個體計數。*範例：***Stack instances (堆疊執行個體)：``**。
1. 選擇面板標頭，展開側邊面板。側邊面板中的結果是選取的操作完成後堆疊執行個體的狀態。
**檢視操作的目前堆疊執行個體詳細資訊：**
1. 選擇 **Stack Instances** (堆疊執行個體) 索引標籤。
1. 依 **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"
}
}
```