# 使用 `cloudformation-validate` 验证模板
<a name="cloudformation-validate"></a>

该开源 [`cloudformation-validate` 项目](https://github.com/aws-cloudformation/cloudformation-validate)会在本地检查 JSON 和 YAML CloudFormation 模板，并在 GitHub 上提供。它可以查找无效的模板结构、损坏的引用、安全问题和最佳实践问题。每项调查发现都包括问题、其严重程度以及其在模板中的位置。

该工具包括所需的规则和 CloudFormation 资源定义，因此安装后无需网络访问或 Amazon 凭证即可运行。

**Topics**
+ [选择验证方法](#cloudformation-validate-ways-to-use)
+ [安装命令行工具](#cloudformation-validate-install)
+ [运行验证](#cloudformation-validate-run)
+ [添加自定义规则](#cloudformation-validate-custom-rules)
+ [嵌入验证库](#cloudformation-validate-library)
+ [将 与 结合使用Amazon CDK](#cloudformation-validate-cdk)
+ [了解验证范围](#cloudformation-validate-scope)

## 选择验证方法
<a name="cloudformation-validate-ways-to-use"></a>
+ **命令行**：运行 `cfn-validate` 以从终端或自动构建检查一个模板或目录中的每个模板。
+ **库**：向 Rust、Node.js、Python、Go 或 JVM 应用程序添加验证器，然后在代码中处理结果。
+ **Amazon CDK**：在 CDK 合成模板后自动验证模板。
+ **自定义规则**：添加以 CEL、Rego 或 Guard 规则语言编写的检查。有关支持的规则格式和示例，请参阅 GitHub 上的 [Custom Rules Reference](https://github.com/aws-cloudformation/cloudformation-validate/blob/main/src/CUSTOM_RULES.md)。有关 Guard 规则语法，请参阅本指南中的[使用 Guard 验证模板](cloudformation-guard.md)。

## 安装命令行工具
<a name="cloudformation-validate-install"></a>

在 GitHub 上打开[最新的 `cfn-validate` 版本](https://github.com/aws-cloudformation/cloudformation-validate/releases/latest)，然后下载适用于您的操作系统和处理器的 `cfn-validate` 文件。按照 GitHub 上的[安装指南](https://github.com/aws-cloudformation/cloudformation-validate/blob/main/INSTALLATION.md)将文件重命名为 `cfn-validate`，将其添加到您的 `PATH`，然后验证下载的文件。

## 运行验证
<a name="cloudformation-validate-run"></a>

该命令使用以下语法：

```
cfn-validate {{TEMPLATE_OR_DIRECTORY}} [OPTIONS]
```

检查一个模板：

```
cfn-validate template.yaml
```

传递一个目录，以递归方式检查每个 `.yaml`、`.yml` 和 `.json` 文件：

```
cfn-validate ./templates/
```

该命令将结构化的 JSON 验证报告写入标准输出。使用 `--format standard` 可获得精简输出，使用 `--format detailed` 可获得默认详细报告。

该命令在未发现错误或致命诊断时会返回 `0`，在发现错误或致命诊断时会返回 `1`，在出现使用或初始化错误（例如无效选项或文件不存在）时会返回 `2`。

有关所有引擎、筛选条件、输出格式和参数，请参阅 GitHub 上的 [`cfn-validate` CLI 参考](https://github.com/aws-cloudformation/cloudformation-validate/blob/main/src/cfn-validate/README.md)。

## 添加自定义规则
<a name="cloudformation-validate-custom-rules"></a>

使用 `--rule-source` 加载自定义 Rego 或 CEL 规则文件。使用 `--guard-rule-source` 加载 Guard 规则文件或目录。您可以重复任一选项以加载多个规则源：

```
cfn-validate template.yaml --rule-source ./rules/my-rule.rego
cfn-validate template.yaml --guard-rule-source ./guard-rules/
```

有关规则格式和示例，请参阅 GitHub 上的 [Custom Rules Reference](https://github.com/aws-cloudformation/cloudformation-validate/blob/main/src/CUSTOM_RULES.md)。

## 嵌入验证库
<a name="cloudformation-validate-library"></a>

安装适用于所用编程语言的已发布程序包，以便从您的应用程序运行相同的离线检查。创建一次验证引擎，将其重复用于多个模板，然后处理针对每个模板返回的结构化诊断。您还可以通过库 API 配置自定义 CEL、Rego 或 Guard 规则。


| 语言 | 发布的程序包 | API 和示例 | 
| --- | --- | --- | 
| Rust | [crates.io 上的 `cloudformation-validate`](https://crates.io/crates/cloudformation-validate) | [Rust API 和示例](https://github.com/aws-cloudformation/cloudformation-validate/blob/main/src/bindings-rust/README.md) | 
| Node.js | [npm 上的 `@aws/cloudformation-validate`](https://www.npmjs.com/package/@aws/cloudformation-validate) | [Node.js API 和示例](https://github.com/aws-cloudformation/cloudformation-validate/blob/main/src/bindings-wasm/README.md) | 
| Python | [PyPI 上的 `cloudformation-validate`](https://pypi.org/project/cloudformation-validate/) | [Python API 和示例](https://github.com/aws-cloudformation/cloudformation-validate/blob/main/src/bindings-python/README.md) | 
| Go | [CloudFormation Validate Go 模块](https://pkg.go.dev/github.com/aws-cloudformation/cloudformation-validate/src/bindings-go/go) | [Go API 和示例](https://github.com/aws-cloudformation/cloudformation-validate/blob/main/src/bindings-go/README.md) | 
| JVM（Java 或 Kotlin） | [Maven Central 上的 `software.amazon.cloudformation:cloudformation-validate`](https://central.sonatype.com/artifact/software.amazon.cloudformation/cloudformation-validate) | [JVM API 和示例](https://github.com/aws-cloudformation/cloudformation-validate/blob/main/src/bindings-jvm/README.md) | 

有关安装说明和支持的平台，请参阅[语言绑定安装指南](https://github.com/aws-cloudformation/cloudformation-validate/blob/main/INSTALLATION.md#language-bindings)。

如需查看各种语言的完整示例以及各 API 指南的链接，请参阅 GitHub 上项目文档中的[作为库嵌入](https://github.com/aws-cloudformation/cloudformation-validate#embedding-as-a-library)。

## 将 与 结合使用Amazon CDK
<a name="cloudformation-validate-cdk"></a>

如果您使用 Amazon CDK，则无需单独安装验证器。Amazon CDK 构造库包含一个默认 `CloudFormationValidatePlugin`，其会在合成 CloudFormation 模板后自动运行相同的检查。

```
cdk synth
```

CDK 会在其验证结果中报告可能的部署失败和最佳实践调查发现。当您想要添加自定义 Rego 或 Guard 规则时，可以显式配置 `CloudFormationValidatePlugin`。

有关插件配置、确认和验证报告，请参阅《Amazon CDK API 参考》**中的 [Template and Policy Validation](https://docs.amazonaws.cn/cdk/api/v2/docs/aws-cdk-lib-readme.html#template-and-policy-validation)。

## 了解验证范围
<a name="cloudformation-validate-scope"></a>

有关本地验证的限制以及部署前需采取的步骤，请参阅[了解验证范围](template-guide.md#template-validation-scope)。