View a markdown version of this page

CloudFormation 语言服务器 - Amazon CloudFormation
IDE 与 CloudFormation 语言服务器集成开始使用在 IDE 中初始化 CloudFormation 项目（仅限 VS Code）开源需要帮助？
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

CloudFormation 语言服务器

Amazon CloudFormation 语言服务器可帮助您在编辑器中编写 CloudFormation 模板。在您键入时，它会建议资源类型和属性、显示文档、查找错误、允许您跳转到定义，并针对某些问题提供修复建议。它使用语言服务器协议（LSP），使该服务器能够与不同的编辑器配合使用。启动和使用语言服务器来实现这些本地创作功能不需要 Amazon Web Services 账户 或 Amazon 凭证。

Amazon Toolkit 集成还使用语言服务器来处理调用 Amazon 服务的在线工作流。这些工作流可以浏览资源和堆栈。它们还可以运行服务端模板验证、部署模板、显示更改集差异以及监控堆栈事件。这些在线工作流是唯一需要活跃 Amazon Web Services 账户 和有效 Amazon 凭证的功能。

IDE 与 CloudFormation 语言服务器集成

Amazon 通过 Amazon 工具包为以下 IDE 提供与 CloudFormation 语言服务器的现成集成：

以下 IDE 还支持 CloudFormation 语言服务器：

  • Kiro：

  • Cursor

  • 大多数 VS Code 分叉和分配

对于 Visual Studio Code 和 JetBrains IDE，请安装 Amazon Toolkit。Toolkit 会包括并启动语言服务器，因此您无需单独下载该服务器。

对于支持 LSP 的其他编辑器，请从 GitHub 上的最新版本下载适用于您计算机的文件，将其解压缩，然后配置编辑器以运行下面的命令：

node /path/to/install-location/cfn-lsp-server-standalone.js --stdio

有关支持的 Node.js 版本、可用下载、文件验证和不同编辑器的设置示例，请参阅独立安装指南。

开始使用

下面的步骤展示了如何通过 Amazon Toolkit for Visual Studio Code 和 JetBrains IDE 使用语言服务器。对于其他编辑器，请按照独立安装指南中的设置示例进行操作。

先决条件

在您开始之前，请确保：

  • 您正在 macOS、Windows 或 Linux 上使用支持的 IDE。

  • 对于 Visual Studio Code 或 JetBrains IDE，请安装或更新 Amazon Toolkit。

  • 对于其他编辑器，请安装支持的 Node.js 版本，并下载适用于计算机的语言服务器文件。独立安装指南列出了支持的版本和文件。

无需 Amazon Web Services 账户 或 Amazon 凭证即可启动语言服务器或使用其本地创作和模板检查功能。只有当您使用浏览资源或堆栈、调用 CloudFormation 服务或部署模板的在线工作流时，才需要在 Toolkit 中配置有效的 Amazon 凭证。

第 1 步：安装或升级 Amazon 工具包

从 IDE 的扩展程序或插件管理器中安装或更新到最新版本的 Amazon 工具包，然后重新启动 IDE。

安装后，Amazon 工具包会自动启用 CloudFormation IDE 支持。首次安装或升级带有 CloudFormation 语言服务器的 Amazon Toolkit 时，系统会提示您授予 Amazon 收集匿名使用数据的权限。这些数据有助于 Amazon 改进 CloudFormation 语言服务器并增强撰写体验。不会收集任何敏感信息，Amazon 也不会记录或存储模板内容、资源配置或任何可识别身份的客户数据。您可以随时从 IDE 设置中更改遥测首选项。重新启动 IDE 以使更改生效。所收集的使用数据仅涵盖功能交互和性能指标。这些见解有助于 Amazon 识别并确定需要改进方面优先顺序，例如加快验证速度、增强自动补全功能以及改进错误诊断机制。

第 2 步：在 Amazon 工具包中访问 CloudFormation

安装 Amazon 工具包后，在 IDE 中打开 CloudFormation 面板。在 VS Code 中，从活动栏打开 Amazon 工具包面板，然后选择 CLOUDFORMATION。在 JetBrains IDE 中，从侧栏打开 Amazon 工具包工具窗口，然后选择 CloudFormation 选项卡。

CloudFormation 面板包含以下部分：

  • 区域：显示当前 Amazon Web Services 区域。在 VS Code 中，您可以通过选择区域名称或使用命令面板中的 Amazon CloudFormation: Select Region 命令来更改区域。在 JetBrains IDE 中，区域是通过 Amazon 工具包连接设置配置的。

  • 堆栈：显示您的账户中 CloudFormation 堆栈的分页列表。展开堆栈，以便查看其更改集节点，其中列出了与该堆栈关联的更改集。使用“查看堆栈详细信息”操作打开堆栈详细信息视图，该视图显示堆栈概述、事件、输出和资源。

  • 资源：添加资源类型后，面板将显示您账户中该类型的 Amazon 资源。您可以查看、刷新、复制或将它们导入到您的模板中。

在 JetBrains IDE 中，树上方的工具栏可快速访问常见操作，包括验证和部署、重新运行、验证和部署、添加资源类型和刷新。也可以通过右键单击树节点上的上下文菜单来执行操作。

第 3 步：验证、测试和优化您的模板

在您编写 CloudFormation 模板时，CloudFormation 语言服务器会在后台运行，并在无需 Amazon 凭证的情况下提供本地创作辅助：

  • 代码完成：根据 CloudFormation 架构来建议资源类型、参数和属性。

  • 提取到参数：当光标位于模板中的字面值（例如，类似 t2.micro 的字符串）上时，IDE 会提供重构操作，用于将该值提取到 Parameters 部分中，并将字面值替换为指向新参数的 !Ref。如果在多个位置出现相同的字面值，则可以选择一次提取所有出现的字面值。

Toolkit 还提供了一个在线工作流，用于向模板添加现有 Amazon 资源。此工作流需要有效的 Amazon 凭证，并使用 Amazon 云端控制 API（CCAPI）检索资源的实时配置和属性，从而帮助您在模板中克隆或重复使用现有基础设施。

要向模板添加资源

  • 添加资源类型：在 Amazon 工具包 CloudFormation 面板的资源下，添加要浏览的资源类型。在 VS Code 中，单击添加 + 图标或使用命令面板中的 Amazon CloudFormation: Add Resource Types 命令。在 JetBrains 中，单击工具栏中的添加资源类型按钮或右键单击资源节点。

  • 搜索资源类型：在搜索对话框中，键入要添加的 Amazon 资源类型。示例：

    • AWS::S3::Bucket

    • AWS::Lambda::Function

  • 浏览资源：在资源部分，将显示您的账户中检测到的 Amazon 资源的分页列表。如果您拥有大量资源，则只会显示第一页。使用导航控件来浏览其他页面并查看所有可用资源。

  • 选择要包含在您的模板中的资源。

  • 您可以通过两种方式将资源插入到您的模板中，具体方式取决于您的目标：

    • 克隆现有资源：使用现有 Amazon 资源的实时配置和属性在模板中创建新资源。

    • 导入现有资源：通过将资源的实时状态添加到模板中，将其插入到您的堆栈中。

提示

  • 您可以随时刷新资源部分，查看您的账户或区域中可用的最新资源列表。

  • 如果您正在导入资源，请不要在同一个账户中添加属于现有 CloudFormation 堆栈的已存在资源。

  • 要确认资源是否已由 CloudFormation 管理，请使用资源旁边的信息操作。在 VS Code 中，单击 i 图标。在 JetBrains IDE 中，右键单击资源并选择获取堆栈管理信息。

在 VS Code 中，从命令面板运行 Amazon CloudFormation：按类型添加相关资源命令。从模板中已定义的资源类型中选择一种。IDE 会列出所选类型可通过其属性引用的资源类型。例如，如果您选择 AWS::EC2::Instance，则 IDE 可能会建议 AWS::EC2::SecurityGroup 或 AWS::EC2::Subnet。选择一个或多个相关资源类型，然后选择是创建新的资源定义还是导入现有资源。此功能目前在 JetBrains IDE 中不受支持。

静态验证

CloudFormation 语言服务器提供由 CloudFormation Linter 和 CloudFormation Guard 提供支持的内置静态验证。这些检查在后台本地运行，不需要 Amazon 凭证。它们可帮助您在部署前识别语法错误、合规性差距以及最佳实践问题。

静态验证概述

您将在 IDE 中看到两种类型的实时静态验证：

  • CloudFormation Linter（cfn-lint）：根据 CloudFormation 资源规范和架构规则验证您的模板。

  • Guard（cfn-guard）：根据合规性规则和组织策略包验证您的模板。

CloudFormation Linter（cfn-lint）

CloudFormation Linter 已集成到 IDE 中，以在您键入时自动检查模板的语法和结构。

  • 架构验证：检测语法和架构错误，以确保您的模板符合 CloudFormation 资源架构。

  • 错误突出显示：在出现问题时，会显示内联标记，这些标记代表部署拦截器或警告信息。

  • 悬停获取帮助：将鼠标悬停在错误上方时，IDE 会显示与该问题相关的诊断消息。如果有快速修复方案可用，也会提供。

Guard 集成

Guard 会根据定义合规性和安全策略的规则集来验证您的模板。IDE 通过 CloudFormation 语言服务器实时运行 Guard 验证，以在您撰写模板时为您提供即时反馈。

  • 默认规则包：IDE 包含了一套预先注册好的 Guard 规则，这些规则侧重于资源安全和配置维护方面的基本最佳实践。要了解更多信息，请参见 guard 规则注册表。

  • 添加规则包：要添加或修改规则集，请打开“IDE 设置”，导航到“Guard 配置”部分，然后选择或上传其他 Guard 规则包。

提示：了解诊断指示器

  • 蓝色指示器：最佳实践提示或优化建议。

  • 黄色指示器：关于非拦截问题的警告（例如，缺少标签或参数）。

  • 红色指示器：部署拦截器，例如无效的属性名称、缺少必填字段或架构不匹配。

第 4 步：浏览模板

IDE 提供 CloudFormation 模板的结构化分层视图，该视图分为 Parameters、Resources、Outputs 和 Mappings 等部分，显示了每种资源类型和逻辑 ID。这使得在大型模板中能够轻松快速地定位并导航到特定的资源或参数。在 VS Code 中，探索器侧栏中的大纲面板显示此结构。在 JetBrains IDE 中，打开结构工具窗口，查看当前打开的文件的模板结构。

您可以将转到定义用于 GetAtt 和 Ref 之类的内置函数，从而使您可以直接跳转到模板中引用的资源或参数。这可以帮助您跟踪依赖项、了解资源关系并更高效地进行编辑。

第 5 步：验证和部署

验证和部署是一个在线工作流，它调用 CloudFormation 服务，并且需要有效的 Amazon 凭证。当您准备好部署模板时，请使用此功能来创建更改集。IDE 会验证您的模板，如果未发现任何拦截错误，则会继续创建偏差感知更改集。然后 IDE 会显示差异视图，以便您可以在执行更改集之前查看所有提议的更改。

在 VS Code 中，打开命令面板并运行 Amazon CloudFormation: Validate and Deploy。命令面板将引导您逐步选择模板、堆栈名称、参数、功能和其他部署选项。在 JetBrains IDE 中，使用验证和部署工具栏按钮，在编辑器中右键单击模板文件或右键单击树中的堆栈。JetBrains 会显示一个向导对话框，您可以在其中配置所有部署选项，包括模板选择、堆栈名称、参数、功能、标签和高级选项。

验证的工作原理

IDE 会在部署前自动执行验证检查，并根据常见的故障原因对模板进行验证，包括：

  • 无效的属性语法或架构不匹配：这些问题通常在撰写过程中被 cfn-lint 检测出来，但如果您在未解决这些问题的情况下继续进行部署，那么在创建或更新堆栈时，CloudFormation 的部署时验证也会显示出同样的错误。

  • 资源名称与您账户中的现有资源冲突。

  • 特定于服务的约束，例如 S3 存储桶名称冲突或缺少加密。

如果验证检测到错误，IDE 会直接在模板中突出显示问题，并在诊断面板中列出错误。每个问题都包括导致故障的特定属性或资源，并附上相应的解决建议。如果没有阻止错误，则可以继续进入部署阶段。

如果发现警告（非阻止问题），会出现一个对话框，让您可以选择继续进行部署操作，或者取消操作并进行修正。

IDE 将打开一个偏差感知更改集，其中显示当前模板与已部署堆栈配置之间的任何差异。这使您能够在执行之前查看、确认或取消更改集。取消部署会删除更改集。

偏差感知更改集能够增强 CloudFormation 的部署流程，使您能够安全地处理堆栈的偏差问题。当您的资源的实际状态与 CloudFormation 模板中所定义的内容不一致时，就会出现堆栈偏差，这种情况通常因通过 Amazon Web Services 管理控制台、CLI 或 SDK 进行的手动更改导致。CloudFormation 偏差感知更改集将处理后的堆栈配置与实时资源状态进行比较，IDE 会显示这些差异，这样您就可以在部署之前使资源恢复合规性。

查看堆栈事件

部署开始后，您可以从 CloudFormation 面板实时监控进度。在堆栈事件下，您将看到部署期间执行的操作列表。每个事件都包含详细信息，例如：

  • 时间戳：事件发生的时间

  • 资源：正在创建、更新或删除的特定 Amazon 资源

  • 状态：操作的当前状态（例如 CREATE_IN_PROGRESS、UPDATE_COMPLETE 或 ROLLBACK_IN_PROGRESS）

  • 原因：其他背景信息或错误消息（如果适用）

您也可以通过此面板查看堆栈的资源和输出。堆栈事件视图有助于您跟踪部署进度、识别潜在问题，并确认您的堆栈是否已成功完成部署。

在 IDE 中初始化 CloudFormation 项目（仅限 VS Code）

在 IDE 中初始化 CloudFormation 项目可帮助您使用正确的文件夹和环境配置设置结构化工作区，以便进行服务端验证和部署。这些在线工作流需要 Amazon 凭证，但是语言服务器的本地创作和静态验证功能不需要。您可以直接从 IDE 来初始化一个新的 CloudFormation 项目，从而创建此建议设置。此功能目前仅在 VS Code 中可用，在 JetBrains IDE 中不受支持。

要初始化 CloudFormation 项目，请执行以下操作：

  • 打开命令面板

    • 从 VS Code，打开命令面板（macOS 上的 Ctrl+Shift+P 或 Cmd+Shift+P）。

    • 选择 Amazon CloudFormation：CFN Init：初始化项目。

  • 选择项目目录

    • 默认情况下，IDE 将使用您当前的工作目录。

    • 您可以将此路径更改为您希望存储 CloudFormation 模板所在的任何文件夹。

  • 选择您的 Amazon 凭证配置文件

    • 系统将提示您选择 Amazon 凭证配置文件。所选配置文件用于环境检测、服务端验证和部署。

  • 设置环境

    • 系统将提示您创建或选择环境。

    • 环境定义了您的模板在何处以及以何种方式进行部署或验证（例如，开发环境、测试环境或生产环境）。您可以使用 Amazon CloudFormation：CFN Init：添加环境来选择或更改您的环境。

    • 您可以使用 Amazon CloudFormation: CFN Init: Remove Environment 移除您选择的环境。

  • （可选）导入参数文件

    • 如果您已经有现有的参数文件，那么该 IDE 会在初始化时允许您导入这些文件。

    • IDE 会自动检测兼容的文件，并将它们链接到您的项目中，以便在模板验证和部署过程中使用。

  • 命名并最终确定项目

    • 提供项目名称，例如 beta-environment，然后完成设置。

    • IDE 将为您创建初始项目结构和配置文件。

您可以直接从 IDE 中进行验证、预览部署操作，或者在不同环境中进行切换。

开源

CloudFormation 语言服务器基于 Apache-2.0 许可证开源，让客户能够全面了解模板诊断、架构验证以及静态分析的执行方式。对于在采用工具之前需要来源级可见性的客户来说，这减少了安全性和合规性方面的摩擦。

该代码库已在 GitHub 上公开发布：https://github.com/aws-cloudformation/cloudformation-languageserver/。

需要帮助？

在 Amazon Web Services re:Post 上试用 CloudFormation 社区。