这是 AWS CDK v2 开发者指南。旧版 CDK v1 于 2022 年 6 月 1 日进入维护阶段，并于 2023 年 6 月 1 日终止支持。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

AWS 合成时的 CDK 验证

在合成时进行验证

您的 AWS CDK 应用程序会在综合时以 CloudFormation 模板的形式生成基础设施描述。这些模板在合成后会立即进行验证。 AWS CDK 内置了一组验证规则，您可以使用其他验证工具（例如 CDK Nag）或您的组织已经在使用的任何策略 CDK-specific 验证工具（例如 G AWS CloudFormation uard 或 OPA）对其进行扩展。如果有任何违规行为，合成将失败，控制台将打印一份报告。通过对合成模板进行离线验证，您可以尽早发现并修复基础架构的潜在问题。您将使用验证来发现可能导致部署失败、常见配置错误或不符合公司标准的问题。

什么是验证，什么不是

AWS CDK 在综合时执行的验证是为改善开发者体验而尽力进行的验证；它本身并不是一个完整的标准合规机制。它可以验证通常由 CDK 应用程序生成的模板，但它不能影响合成之外发生的操作。例如，直接在控制台中或通过服务 API 执行的操作。此外，由于 CDK 应用程序是用通用编程语言编写的，因此坚定的开发人员可以根据需要绕过验证机制。这就是为什么 CDK 验证是一种尽早验证的左移机制，应与另一种机制结合使用，以验证所需的规则集，例如钩子AWS CloudFormation 或 Config。AWS

对于应用程序开发人员

添加验证插件

验证由验证插件执行。使用 AWS 资源综合规则集的默认插件将根据 @ aws/cloudformation-validat e 自动添加到您的应用程序中。如果要向应用程序添加其他插件，请使用以下Validations类：

import { Validations } from 'aws-cdk-lib';
import { CfnGuardValidator } from '@cdklabs/cdk-validator-cfnguard';

const app = new App();

// Add a validation plugin to the entire app
Validations.of(app).addPlugins(new CfnGuardValidator());

// Or add to a particular stage
const prodStage = new Stage(app, 'ProdStage');
Validations.of(prodStage).addPlugins(new CfnGuardValidator());

合成后，将立即调用以这种方式注册的所有插件，来验证在您定义的范围内生成的所有模板。特别是，如果在 App 对象中注册模板，则所有模板都将接受验证。

验证报告

当你合成 AWS CDK 应用程序时，将调用验证器插件并打印结果。下面显示了一个示例报告。

lib/my-custom-l3-construct.ts:10:5
ERROR [CT.S3.PR.1]: Require an Amazon S3 bucket to have block public access settings configured (cdk-validator-cfnguard)
   MyStack/MyCustomL3Construct/Bucket/Resource (MyCustomL3ConstructBucket8C61BCA7) constructs.Construct
   Suggested fix: [FIX]: The parameters 'BlockPublicAcls', 'BlockPublicPolicy', 'IgnorePublicAcls', 'RestrictPublicBuckets' must be set to true under the bucket-level 'PublicAccessBlockConfiguration'.
   Acknowledge with 'cdk-validator-cfnguard::s3_bucket_level_public_access_prohibited_check'

lib/my-custom-l3-construct.ts:10:5
ERROR [CT.S3.PR.10]: Require an Amazon S3 bucket to have server-side encryption configured using an AWS KMS key (cdk-validator-cfnguard)
   MyStack/MyCustomL3Construct/Bucket/Resource (MyCustomL3ConstructBucket8C61BCA7) constructs.Construct
   Suggested fix: [FIX]: Set an encryption rule in 'BucketEncryption.ServerSideEncryptionConfiguration' with a 'ServerSideEncryptionByDefault.SSEAlgorithm' configuration of 'aws:kms' or 'aws:kms:dsse'
   Acknowledge with 'cdk-validator-cfnguard::s3_bucket_default_encryption_kms_check'

...

默认情况下，将以人类可读的格式打印报告。如果您想要 JSON 格式的报告，请通过 CLI 使用 @aws-cdk/core:validationReportJson 进行启用，或将其直接传递给应用程序：

const app = new App({
  context: { '@aws-cdk/core:validationReportJson': true },
});

或者，您可以使用项目目录中的cdk.json或cdk.context.json文件来设置此上下文键值对（请参阅上下文值和 AWS CD K）。

如果您选择 JSON 格式， AWS CDK 会将策略验证报告打印到云汇编目录policy-validation-report.json中名为的文件中。对于默认的人类可读格式，报告将打印为标准输出。

确认警告

如果您评估了警告或错误并认为该警告或错误不适用于您，则可以使用该acknowledge方法将其禁止。抑制是基于作用域的，适用于给定作用域下的所有构造。

import { Validations } from 'aws-cdk-lib';

Validations.of(myConstruct).acknowledge({
  id: 'PluginName::MyWarningId',
  reason: 'This is acceptable for our use case',
});

id使用分::隔符将验证源前缀与规则名称分开（例如，Construct-Annotations::或AwsSolutions-S1::）。

AWS CloudFormation 警卫插件

使用该CfnGuardValidator插件允许您使用 AWS CloudFormation Guard 来执行策略验证。CfnGuardValidator 插件中内置了一组精选的 AWS Control Tower 主动控制功能。可在项目文档中找到当前规则集。如综合时策略验证中所述，我们建议组织使用AWS CloudFormation 挂钩设置更权威的验证方法。

对于 AWS Control Tower 客户，可以在整个组织中部署这些相同的主动控制功能。当您在 AWS 控制塔环境中启用 Cont AWS rol Tower 主动控制时，这些控件可以停止部署通过 AWS CloudFormation部署的不合规资源。有关托管的主动控制功能及其工作原理的更多信息，请参阅 AWS Control Tower 文档。

这些 AWS CDK 捆绑控件和托管 Cont AWS rol Tower 主动控件最好一起使用。在这种情况下，您可以使用与 Contro AWS l Tower 云环境中相同的主动控件来配置此验证插件。然后，您可以通过在cdk synth本地运行来快速确信您的 AWS CDK 应用程序将通过 Cont AWS rol Tower 控制。

AWS CDK Nag 插件

您可以使用 CDK Nag 根据多种标准（例如 HIPAA、PCI DSS 等）检查您的基础架构。cdk-nag 的 3.x 版本与 CDK 中的标准化验证机制集成在一起。

对于构造作者：直接添加警告和错误

该Validations类还提供了直接向构造中添加自定义警告和错误的方法。您可以使用此机制直接在构造上报告错误配置，而不必实现验证插件。将报告您以这种方式添加的验证和错误以及验证插件发现的违规行为。

import { Validations } from 'aws-cdk-lib';

const bucket = new s3.Bucket(this, 'MyBucket');

// Add a warning
Validations.of(bucket).addWarning('MyWarningId', 'This bucket does not have versioning enabled');

// Add an error (will cause synthesis to fail)
Validations.of(bucket).addError('MyErrorId', 'This bucket must have encryption enabled');

对于插件作者

AWS CDK 核心框架负责注册和调用插件，然后显示格式化的验证报告。插件的职责是充当 AWS CDK 框架和外部策略验证工具之间的转换层，例如，您的插件可能会使用该工具。可以用 AWS CDK 支持的任何语言创建插件。如果您正在创建可能被多种语言使用的插件，则建议您在中创建插件，TypeScript以便您可以使用 JSII 以每种 AWS CDK 语言发布插件。

创建插件

AWS CDK 核心模块和您的策略工具之间的通信协议由IPolicyValidationPlugin接口定义。要创建新插件，必须编写一个可以实现此接口的类。您需要实现两件事：插件名称（通过覆盖 name 属性）和 validate() 方法。

框架将调用 validate()，同时传递一个 IPolicyValidationContext 对象。待验证模板的位置由 templatePaths 给出。该插件应返回一个 PolicyValidationPluginReport 实例。此对象表示用户在合成结束时将收到的报告。

validate(context: IPolicyValidationContext): PolicyValidationPluginReport {
  // First read the templates using context.templatePaths...
  // ...then perform the validation, and then compose and return the report.
  // Using hard-coded values here for better clarity:
  return {
    success: false,
    violations: [{
      ruleName: 'CKV_AWS_117',
      description: 'Ensure that AWS Lambda function is configured inside a VPC',
      fix: 'https://docs.bridgecrew.io/docs/ensure-that-aws-lambda-function-is-configured-inside-a-vpc-1',
      violatingResources: [{
        resourceName: 'MyFunction3BAA72D1',
        templatePath: '/home/johndoe/myapp/cdk.out/MyService.template.json',
        locations: 'Properties/VpcConfig',
      }],
    }],
  };
}

请注意，不允许插件修改云程序集中的任何内容。任何这样的尝试都将导致合成失败。

如果你的插件依赖于你花钱购买的外部工具，请记住，有些开发者可能还没有在他们的工作站中安装该工具。为了最大限度地减少摩擦，请提供一些安装脚本以及插件包，以实现安装过程的自动化。

处理豁免

如果您的组织有处理豁免的机制，则可以将其作为验证器插件的一部分来实现。

以下示例场景说明了可能的豁免机制：

在这种情况下，开发人员将在内部系统中请求异常，然后需要以某种方式“注册”该异常。在警卫插件示例的基础上，您可以创建一个处理豁免的插件，方法是筛选出在内部票务系统中具有匹配豁免的违规行为。

请参阅现有插件获取实现示例。