# Amazon CloudFormation StackSets 故障排除
<a name="stacksets-troubleshooting"></a>

本主题包含一些常见的 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)

## 堆栈操作失败的常见原因
<a name="common-reasons-for-stack-operation-failure"></a>

**问题：**堆栈操作失败，并且堆栈实例状态为 `OUTDATED`。

**原因：**有几个导致堆栈操作失败的常见原因。
+ 目标账户中的权限不足，无法创建模板中指定的资源。
+ CloudFormation 模板可能存在错误。验证 CloudFormation 中的模板并修复错误，然后再尝试创建 StackSet。
+ 模板可能尝试创建必须唯一但不唯一的全球资源 (如 S3 存储桶)。
+ 指定的目标账号不存在。检查您在向导的 **Set deployment options** 页面上指定的目标账号。
+ 管理员账户与目标账户没有信任关系。
+ 目标账户中已存在模板中指定的资源的最大数量。例如，您可能已达到目标账户中允许的 IAM 角色数限制，但模板创建更多 IAM 角色。
+ 您已达到 StackSet 中允许的最大堆栈数量。有关每个 StackSet 的最大堆栈数，请参阅 [了解 CloudFormation 配额](cloudformation-limits.md)。

**解决方案：**有关创建 StackSet 之前目标和管理员账户所需权限的更多信息，请参阅[授予管理员账户的所有用户管理所有目标账户中堆栈的权限](stacksets-prereqs-self-managed.md#stacksets-prereqs-accountsetup)。

## 重试失败的堆栈创建或更新操作
<a name="retrying-failed-stack-creation-or-update-operations"></a>

**问题：**堆栈创建或更新失败，并且堆栈实例状态为 `OUTDATED`。要查找堆栈创建或更新失败的原因，请打开 CloudFormation 控制台，查看堆栈的事件，这些事件的状态为 `DELETED`（创建操作失败时）或 `FAILED`（更新操作失败时）。浏览堆栈事件，然后查找 **Status reason** 列。**Status reason** 的值解释了堆栈操作失败的原因。

在确定堆栈创建失败的根本原因并准备好重试堆栈创建后，请执行下列步骤。

**解决方案：**执行下列步骤以重试堆栈操作。

1. 在控制台中，选择包含操作失败的堆栈的 StackSet。

1. 在**操作**菜单上，选择 **Edit StackSet details (编辑堆栈集详细信息)** 以重试创建或更新堆栈。

1. 在**指定模板**页面上，要使用相同的 CloudFormation 模板，请保留默认选项**使用当前模板**。如果您的堆栈操作因模板需要更改而失败，并且您想上传修订后的模板，请改为选择 **Upload a template to Amazon S3**，然后选择 ** Browse** 以选择更新的模板。上传完修订后的模板后，选择 **Next**。

1. 在**指定堆栈详细信息**页面上，如果您不更改特定于模板的任何参数，请选择**下一步**。

1. 在 **Set deployment options** 页上，更改 **Maximum concurrent accounts** 和 **Failure tolerance** 的默认值 (如果需要)。有关这些设置的更多信息，请参阅 [StackSet 操作选项](stacksets-concepts.md#stackset-ops-options)。

1. 在**审核**页面上，检查所选的内容，然后选中相应的复选框以确认所需的 IAM 功能。选择**提交**。

1. 如果您的堆栈未成功更新，请在解决任何阻止堆栈创建的基本问题后重复此过程。

## 堆栈实例删除操作失败
<a name="stack-instance-delete-fails"></a>

**问题：**堆栈删除操作失败。

**原因：**对于任何已启用终止保护的堆栈，堆栈删除操作将失败。

**解决方案：**确定该堆栈是否已启用终止保护。如果已启用，则禁用终止保护，然后再重新执行堆栈实例删除操作。

## 堆栈导入操作失败
<a name="stack-import-fails"></a>

**问题：**堆栈导入操作无法将现有堆栈导入新的或现有的 StackSet。堆栈实例处于 `INOPERABLE` 状态。

**解决方案：**通过完成以下任务恢复堆栈导入操作。

1. 使用**从 StackSet 删除堆栈**选项，并在配置过程中启用 **RetainStacks**，然后继续从 StackSet 中删除堆栈实例。有关更多信息，请参阅 [从 Amazon CloudFormation StackSet 中删除堆栈](stackinstances-delete.md)。

1. 您将看到 StackSet 的堆栈实例会更新，删除 `INOPERABLE` 堆栈实例。

1. 根据导入失败错误修复堆栈实例，然后重试堆栈导入操作。

## StackSets 操作的堆栈实例失败计数
<a name="stack-instance-failure-count-for-stackset-operations"></a>

如果堆栈实例无法预置或更新，堆栈实例失败计数会发出警报。由于以下一个或多个原因，这些堆栈实例未部署：
+ 现有资源具有类似配置
+ 缺少依赖项，例如 Amazon Identity and Access Management（IAM）角色
+ 其他冲突因素

如果您想以最大并发进行部署，则最大并发计数最多比容错计数多一。例如，如果容错计数为 9，则最大并发计数不能超过 10。即使某些堆栈实例无法更新，这也会导致操作返回 `SUCCEEDED`。新的堆栈实例失败计数让您能够确定，操作是否仅在符合条件的情况下成功，因为容错计数设置为允许所有失败。

您可以使用 Amazon Web Services 管理控制台、Amazon SDK 或 Amazon CLI 获取失败计数并筛选堆栈实例，以确定需要重新部署哪些实例。

### 使用控制台
<a name="stack-instance-failure-count-for-stackset-operations-console-examples"></a>

**若要查看失败堆栈实例的数量，请执行以下操作：**

1. 打开 [CloudFormation 控制台](https://console.amazonaws.cn/cloudformation)，然后选择 **StackSet**。

1. 选择您的 StackSet，然后选择 **Operations**（操作）选项卡。

1. 在 **Status**（状态）列中选择状态以查看状态详细信息。您将在状态详细信息中找到特定操作的失败堆栈实例的数量。

**若要查看操作的堆栈实例的账户、区域和状态，请执行以下操作：**

1. 在状态详细信息中，选择失败的堆栈实例计数。*示例：***Stack instances: `<number of failed stack instances>`**（堆栈实例：）。

1. 通过选择面板标头来展开侧面板。侧面板中的结果是所选操作完成后堆栈实例的状态。

**若要查看操作的当前堆栈实例详细信息，请执行以下操作：**

1. 选择 **Stack Instances**（堆栈实例）选项卡。

1. 按 **Last operation ID**（上次操作 ID）筛选。结果为上次修改实例的操作的当前状态和状态原因。您可以将此筛选条件与 **Amazon 账户**、**Amazon 区域**、**详细状态**和 **偏差状态**结合使用，以进一步优化搜索结果。

### 使用 Amazon CLI
<a name="stack-instance-failure-count-for-stackset-operations-cli-examples"></a>

若要获取失败的堆栈实例数量，请调用 `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"
    }
}
```