如何快速有效地调试 CloudFormation 模板？答案

【问题标题】：How can I quickly and effectively debug CloudFormation templates?如何快速有效地调试 CloudFormation 模板？
【发布时间】：2012-08-04 23:42:25
【问题描述】：

CloudFormation 是一种强大的 AWS 产品，允许通过单个 API 调用以编程方式创建 AWS 资源堆栈，例如 web tier of an application,、high performance computing cluster, 或 an entire application stack,。它非常强大。使用它肯定被认为是一种好的 AWS 实践，尤其是当它与 Chef, Puppet, 或 cloud-init. 结合使用时，调试它会让我陷入困境。

以生产为例：股票mongodb cluster templates 不适合我。我特别不知道为什么。我确信这很简单，因为它几乎总是如此。我的问题不在于我无法弄清楚出了什么问题。假设它完全正确地删除了资源，堆栈需要 20 到 30 分钟才能失败，然后再删除 3 到 4 分钟。

我错过了什么？我知道--disable-rollback 标志并将其用作氧气。我很久以前就学会了用cfn-signal 包装退出消息并将它们像压舱物一样扔下沉船。我怎样才能使模板调试过程更快，或者我是否会在制作半小时后发现我的错误？

【问题讨论】：

即使是 JSON 中的拼写错误，有时也要等到构建过程的 10 多分钟后才会被捕获，因为它不会注意到特定资源类型没有特定属性名称，直到它尝试启动该资源。
我的最爱，无特定顺序：当您switch resource contexts and encounter almost-but-not-quite-identical attributes, 忘记在用户脚本声明中添加转义引号时，以及与 VolumeAttachments 相关的任何事情，因为它们偶尔会无缘无故地失败。
+1 提到“禁用自动回滚”——这对于获得更好的子堆栈错误消息非常棒
我发现策略段中的错误会导致像 BucketPolicy 这样的东西永远卡在 CREATE 阶段——如果卡在 CREATE 阶段就从那里开始。

标签： amazon-web-services amazon-cloudformation

【解决方案1】：

在 AWS CLI 工具中使用 aws cloudformation validate-template 命令。它仅验证您的模板是有效的 JSON 还是 YAML，而不是您的键和值是否正确（例如不检查键中的拼写错误）

【讨论】：

这个在统一的cli里也可以docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/…
顺便说一下，这是新 AWS CLI 工具中的aws cloudformation validate-template。
对于 2017 年及以上遇到此问题的任何人，现在是 aws cloudformation validate-template，它仅验证您的模板是有效的 JSON 还是 YAML，而不是您的键和值是否正确（例如'不检查键中的拼写错误）。
由于某种原因，它似乎忽略了行长，例如Property validation failure: [Length of value {XYZ} for property {/RepositoryDescription} is greater than maximum allowed length {100}]。根据validate-template 命令，这不是问题，但 UI 会返回此错误。
如果这个工具只做文件格式验证不是； jsonlint 或 yamllint 够不够？此外，此工具的文件大小限制为 51,200 字节。

【解决方案2】：

一年后，另一种选择是将这些模板抽象到第三方库，例如troposphere。该库为您构建 JSON 有效负载，并在此过程中进行大量验证。这也解决了“哇，管理一个 1000 行的 JSON 文件真是令人难过” 的问题。

【讨论】：

“哇，管理一个 1000 行的 JSON 文件真是令人难过”——这就是为什么要创建嵌套堆栈的原因吗？ ;-) 虽然我同意 - 对流层太棒了！

【解决方案3】：

我怎样才能使模板调试过程更快，或者我是否会在我犯错半小时后一直发现自己的错误？

以下是一些最佳实践建议，专门针对提高复杂 CloudFormation 模板开发的迭代速度：

使用 CloudFormation 工具验证模板和堆栈更新

AWS 已经在其自己的 Best Practices 文档中概述了这些内容，因此我不再赘述：

此步骤的重点是在实际执行堆栈创建/更新之前捕获明显的语法或逻辑错误。

单独测试资源

在复杂堆栈中使用任何单个 CloudFormation 资源之前，请确保您彻底了解该资源的创建/更新/删除行为的全部范围，包括对使用的任何限制和典型的启动/拆卸时间，方法是在较小的范围内测试它们的行为, 独立堆栈优先。

如果您正在开发或使用任何第三方自定义资源，请使用适合语言平台的库编写单元测试，以确保应用程序逻辑在所有用例中都按预期运行。
请注意，单个资源创建/更新/删除的时间量可能因资源类型而异，具体取决于底层 API 调用的行为。例如，复杂的 AWS::CloudFront::Distribution 资源有时可能需要 30-60 分钟 来创建/更新/删除，而 AWS::EC2::SecurityGroup 会在几秒钟内更新。
个别资源在其实现中可能存在错误/问题/限制，当单独测试时，这些资源更容易调试和开发解决方法，而不是在更大的堆栈中进行测试。请注意限制，例如 AWS Service Limits 取决于您的个人 AWS 账户设置，或 Region Availability of services 取决于您创建堆栈的区域。

以小增量构建复杂的堆栈

在执行 Stack 创建/更新时，任何单个 Resource 中的失败都会导致 Stack 回滚整个 Resource 更改集，这可能会不必要地破坏其他成功创建的 Resources，并且在构建复杂的 Stack 时会花费很长时间具有相关资源的长依赖关系图。

解决方案是在较小的更新批次中逐步构建您的堆栈，一次添加一个（或几个）资源。这样，如果/当资源创建/更新发生故障时，回滚不会导致整个 Stack 的资源被销毁，只会导致最近更新中更改的资源集。

监控堆栈更新进度

在执行创建/更新时，请务必通过查看堆栈事件来Monitor the Progress of your Stack Update。这将是调试单个资源的进一步问题的起点。

【讨论】：

关于 CloudFront 以及需要多长时间，您是否知道无论如何让堆栈处于完成状态，无需等待，我想获得输出，但不需要等待分发完成部署在我的案例中

【解决方案4】：

您是否查看过 AWS Toolkit for Eclipse 中包含的 AWS CloudFormation 模板编辑器？它具有语法突出显示、语句完成和部署到 AWS CloudFormation。

【讨论】：

“AWS Toolkit for Visual Studio”对我来说是不可或缺的。

【解决方案5】：

AWS CloudFormation linter 提供了超越aws cloudformation validate-template 的额外静态分析

它将通知您哪些资源类型和实例类型在某些区域不可用，根据允许值验证属性值，捕获循环资源依赖关系、语法错误、模板限制等等

除了 CLI，要记住运行 linter 的最流行的机制之一是安装一个编辑器插件，如 Visual Studio Code extension，它在每个文件保存时运行

pre-commit Git hooks are described here等其他机制

【讨论】：

【解决方案6】：

聚会迟到了，但我还要补充一点，花点时间配置和学习您的编辑器是值得的。我知道这听起来很简单，但请尝试一下。

在我的情况下，使用 vim，一旦我花一些时间安装 json 语法插件，并且（最终）了解折叠技术以轻松导航大型 CF 文件，我的表现要好得多。我现在建议拼写错误（不应该出现的逗号等），颜色突出显示可以节省大量时间，提供清晰的视觉线索。

这可能有助于减轻语法错误，但其他工具可以更好地修复模板内的逻辑错误。希望有一天 CF 会有“预览”模式。

【讨论】：

根本不是一个可笑的建议。我不确定我是否可以在没有语法高亮的情况下进行编码。
有一个 CFN 预览，显示您将要创建的所有资源，它还会告诉您堆栈的成本。我正在使用 Java API，所以我不确定它在 CLI 上是否可用，但试试这个：link

【解决方案7】：

对于 JetBrains IDE（IntelliJ IDEA PhpStorm WebStorm PyCharm RubyMine AppCode CLion Gogland DataGrip Rider Android Studio )，AWS CloudFormation 插件支持深度检查 JSON 和 YAML CFN 模板

【讨论】：

【解决方案8】：

如果您正在处理 EC2 机器，那么我建议您登录到 EC2 机器并跟踪 boot.log 文件（RHEL6/Centos 中的 /var/log/boot.log）。此文件会随您的所有 shell 活动（如安装、下载文件、复制文件等活动）进行更新。

另外，使用 http://www.jsoneditoronline.org/ 之类的编辑器来获取 JSON 的树形表示。这有助于您检查 JSON 元素的顺序。

当您更新文件时，请始终使用 http://www.git-tower.com/blog/diff-tools-mac/ 之类的工具或实际的版本控制系统，以确保您不会意外更改可能会破坏脚本的内容。

【讨论】：

【解决方案9】：

除了 AWS CLI aws cloudformation validate-template 命令之外，还有一个基于节点的 cfn-check 工具可以进行更深入的验证。

【讨论】：

【解决方案10】：

去年 12 月添加到 Cloudformation 的最近新功能是添加了 additional Parameter Types。这些新类型允许您的模板执行更强大的数据检查，并且在创建资源和嵌套 Cloudformation 堆栈时也可以“快速失败”。当使用新的ConstraintDescription attribute 传入无效值时，您还可以提供更好的人类可读的自定义错误消息。

新类型在处理各种 VPC 资源时特别有用。您可以确保模板的参数是正确的类型，并且明确表示期望单个值与列表。

例如：

"Parameters" : {
  "SingleGroup": { "Type": "AWS::EC2::SecurityGroup::Id", ...},
  "GroupList": {"Type": "List<AWS::EC2::SecurityGroup::Id>", ...}
}

【讨论】：

【解决方案11】：

请在https://pypi.org/project/cloudformation-validator/查看我的 cloudformation 验证器

这将验证架构，然后再次验证规则列表，并允许自定义规则。我还允许与部署工具轻松集成。

【讨论】：

【解决方案12】：

您还可以在此处使用亚马逊提供的 CloudFormation Designer：https://console.aws.amazon.com/cloudformation/designer/home?region=us-east-1

只需将您的模板 (JSON) 粘贴到“模板”窗格中，然后单击对勾符号即可验证您的模板。任何错误都会显示在“错误”窗格中。

希望这会有所帮助。

【讨论】：