CDK 云格式属性混合

每个 CloudFormation 资源属性的自动生成,类型安全 CDK Mixins. 这些允许您将 L1 属性应用到任何使用 Mixins 机制的构造( L1, L2 或自定义) aws-cdk-lib。 。 。 .

使用量

对于每一个 CloudFormation 资源,此软件包提供 CfnXxxPropsMixin 课. 应用它 .with() 或者说 Mixins.of()数字 :

new s3.Bucket(scope, "MyBucket")
  .with(new CfnBucketPropsMixin({
    versioningConfiguration: { status: "Enabled" },
    publicAccessBlockConfiguration: {
      blockPublicAcls: true,
      blockPublicPolicy: true,
    },
  }));

跨服务参考资料

深嵌属性支持跨服务引用:

const myKey = new kms.Key(scope, "MyKey");

new s3.Bucket(scope, "EncryptedBucket")
  .with(new CfnBucketPropsMixin({
    bucketEncryption: {
      serverSideEncryptionConfiguration: [{
        serverSideEncryptionByDefault: {
          sseAlgorithm: "aws:kms",
          kmsMasterKeyId: myKey,
        },
      }],
    },
  }));

合并策略

当使用混音时,其属性会使用合并策略被合并到目标资源上. 策略控制了混合和现有资源定义同一属性时会发生什么.

有两个内在战略:

PropertyMergeStrategy.combine() (默认)

深地将从混合物中嵌入的物体合并入目标. 当一个属性的现有值和新值都是平面对象时,它们的键会相继被合并——保留了现有的键并添加了新的键. 初级、数组和不匹配类型被混合值所取代.

如果您想要在不丢失已经设置的内容的情况下添加配置, 这样做是有用的 :

const combineBucket = new s3.CfnBucket(scope, "CombineBucket");
combineBucket.publicAccessBlockConfiguration = { blockPublicAcls: true };

// Adds blockPublicPolicy while preserving the existing blockPublicAcls
combineBucket.with(new CfnBucketPropsMixin({
  publicAccessBlockConfiguration: { blockPublicPolicy: true },
}));
// Result: { blockPublicAcls: true, blockPublicPolicy: true }

PropertyMergeStrategy.override()

用混合值取代已有属性值. 每个财产都按原样复制,而不检查嵌入物. 目标上任何先前的值都会被丢弃.

当您想要完全替换配置时, 这样做是有用的 :

const overrideBucket = new s3.CfnBucket(scope, "OverrideBucket");
overrideBucket.publicAccessBlockConfiguration = { blockPublicAcls: true };

// Replaces the entire publicAccessBlockConfiguration
overrideBucket.with(new CfnBucketPropsMixin(
  { publicAccessBlockConfiguration: { blockPublicPolicy: true } },
  { strategy: PropertyMergeStrategy.override() },
));
// Result: { blockPublicPolicy: true } — blockPublicAcls is gone

自定义策略

您可以执行 IMergeStrategy 定义自己的合并行为. 这个 apply 方法接收目标对象、源对象和属性密钥允许列表:

class ArrayAppendStrategy implements IMergeStrategy {
  public apply(target: any, source: any, allowedKeys: string[]) {
    for (const key of allowedKeys) {
      if (key in source) {
        if (Array.isArray(target[key])) {
          // append to target
          target[key] = target[key].concat(source[key]);
        } else {
          // override
          target[key] = source[key];
        }
      }
    }
  }
}

递延值(框)

属性混合支持 框后值中的大多数 L2 构造 aws-cdk-lib 内部使用 Boxes 将属性计算推迟到合成时间。 当混音在目标上遇到Box时,合并会被自动推迟——一旦Box解决,合并策略就会运行,确保它运行在最终值上.

这意味着混合剂与使用 Boxes 属性的 L2 构造正确工作,例如 replicas, (中文(简体) ), rules,或 tags,无需用户的特殊处理:

// TableV2 uses a Box internally for replicas.
// The mixin defers the merge and appends the new replica at synthesis time.
const table = new dynamodb.TableV2(scope, 'Table', {
  partitionKey: { name: 'pk', type: dynamodb.AttributeType.STRING },
  // L2 prop: pointInTimeRecovery is a boolean
  replicas: [{ region: 'us-east-1', pointInTimeRecovery: true }],
});

// Mixins always use L1 (CloudFormation) property names and shapes,
// regardless of what the L2 API looks like.
table.with(new CfnGlobalTablePropsMixin({
  replicas: [{
    region: 'eu-west-1',
    // L1 prop: pointInTimeRecoverySpecification is an object
    pointInTimeRecoverySpecification: { pointInTimeRecoveryEnabled: true },
  }],
}, { strategy: PropertyMergeStrategy.combine({ arrays: ArrayMergeStrategy.append() }) }));

// Result (synthesized CloudFormation):
// Replicas:
//   - Region: us-east-1
//     PointInTimeRecoverySpecification:
//       PointInTimeRecoveryEnabled: true
//   - Region: us-west-2        <-- primary region, added by L2
//   - Region: eu-west-1        <-- added by mixin
//     PointInTimeRecoverySpecification:
//       PointInTimeRecoveryEnabled: true

大多数 L2 构造在 aws-cdk-lib 内部使用 Boxes 或 Lazys 将属性计算推迟到合成时间。 属性混和器自动检测到这些并推迟合并直到数值解决,所以合并策略总是在最终值上运行——不需要用户的特殊处理. 无法推迟合并的唯一情况是原始 Token 没有盒子支持。 这在AWS Construction 库中非常罕见,但可能在第三方包中出现. 如果你遇到一个建筑 合并没有预期的效果,请 打开一个问题 这样我们就可以调查了.

每个服务的云格式属性混合

这个软件包为所有AWS服务的每个CloudFormation资源提供自动生成的地产混接器. 每个服务都有自己的子模块来反映 aws-cdk-lib 模块结构. 从相应的服务子模块导入您想要配置的资源的混音 :

import { CfnBucketPropsMixin } from '@aws-cdk/cfn-property-mixins/aws-s3';
import { CfnFunctionPropsMixin } from '@aws-cdk/cfn-property-mixins/aws-lambda';
import { CfnTablePropsMixin } from '@aws-cdk/cfn-property-mixins/aws-dynamodb';
import { CfnLogGroupPropsMixin } from '@aws-cdk/cfn-property-mixins/aws-logs';
import { CfnDistributionPropsMixin } from '@aws-cdk/cfn-property-mixins/aws-cloudfront';
import { CfnDBInstancePropsMixin } from '@aws-cdk/cfn-property-mixins/aws-rds';

命名公约遵循一个一致的模式: 用于 Cloud Formation 资源 AWS::S3::Bucket,混音类是 CfnBucketPropsMixin 并生活在一个 aws-s3 子模块. 混合道具接口的名称 CfnBucketMixinProps 而所有属性都是可选的,所以只需要指定要设置的属性.

属性混合与任何以目标资源为默认子的构造相配合. 这意味着您可以将其应用于 L1 构造, L2 构造,以及自定义构造 :

// L1 construct
new s3.CfnBucket(scope, "L1Bucket")
  .with(new CfnBucketPropsMixin({ versioningConfiguration: { status: "Enabled" } }));

// L2 construct — the mixin finds the CfnBucket default child
new s3.Bucket(scope, "L2Bucket")
  .with(new CfnBucketPropsMixin({ versioningConfiguration: { status: "Enabled" } }));