コンストラクトライブラリからの AWS コンストラクトのカスタマイズ - AWS Cloud Development Kit (AWS CDK) v2
エスケープハッチの使用ハッチのエスケープ解除Raw オーバーライドカスタムリソース

これは AWS CDK v2 デベロッパーガイドです。古い CDK v1 は 2022 年 6 月 1 日にメンテナンスを開始し、2023 年 6 月 1 日にサポートを終了しました。

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

コンストラクトライブラリからの AWS コンストラクトのカスタマイズ

エスケープハッチ、未加工の上書き、カスタムリソースを使用して、 AWS コンストラクトライブラリからコンストラクトをカスタマイズします。

エスケープハッチの使用

AWS コンストラクトライブラリは、さまざまなレベルの抽象化のコンストラクトを提供します。

最上位レベルでは、 AWS CDK アプリケーションとその中のスタックは、クラウドインフラストラクチャ全体、またはその重要なチャンクを抽象化したものです。パラメータ化して、さまざまな環境にデプロイしたり、さまざまなニーズに合わせてデプロイしたりできます。

抽象化は、クラウドアプリケーションを設計および実装するための強力なツールです。 AWS CDK は、抽象化を使用して構築するだけでなく、新しい抽象化を作成するための能力も提供します。既存のオープンソースの L2 および L3 コンストラクトをガイダンスとして使用して、独自の L2 および L3 コンストラクトを構築して、組織のベストプラクティスと提案を反映することができます。

抽象化は完全ではありません。また、優れた抽象化でも可能なすべてのユースケースに対応することはできません。開発中に、ニーズにほぼ適合するコンストラクトが見つかり、小規模または大規模なカスタマイズが必要になる場合があります。

このため、 AWS CDK にはコンストラクトモデルから抜け出す方法があります。これには、下位レベルの抽象化または別のモデルへの完全な移行が含まれます。エスケープハッチを使用すると、 AWS CDK パラダイムをエスケープし、ニーズに合った方法でカスタマイズできます。その後、変更を新しいコンストラクトにまとめることで、根本的な複雑さを抽象化し、他のデベロッパーにクリーンな API を提供できます。

エスケープハッチを使用できる状況の例を次に示します。

  • AWS サービス機能は を通じて使用できますが AWS CloudFormation、L2 コンストラクトはありません。

  • AWS サービス機能は を通じて利用でき AWS CloudFormation、サービスの L2 コンストラクトはありますが、まだ機能を公開していません。L2 コンストラクトは CDK チームによってキュレートされるため、新機能ではすぐには利用できない場合があります。

  • この機能は、 ではまだ利用できません AWS CloudFormation 。

    機能が利用可能かどうかを判断するには AWS CloudFormation、AWS 「リソースタイプとプロパティタイプのリファレンス」を参照してください。

L1 コンストラクトのエスケープハッチを開発する

サービスで L2 コンストラクトを使用できない場合は、自動的に生成された L1 コンストラクトを使用できます。これらのリソースは、 CfnBucketや などCfn、 で始まる名前で認識できますCfnRole。同等の AWS CloudFormation リソースを使用するのとまったく同じ方法でインスタンス化します。

例えば、分析を有効にして低レベルの Amazon S3 バケット L1 をインスタンス化するには、次のように記述します。

TypeScript
new s3.CfnBucket(this, 'MyBucket', {
  analyticsConfigurations: [
    { 
      id: 'Config',
      // ...        
    } 
  ]
});
JavaScript
new s3.CfnBucket(this, 'MyBucket', {
  analyticsConfigurations: [
    { 
      id: 'Config'
      // ...        
    } 
  ]
});
Python
s3.CfnBucket(self, "MyBucket",
    analytics_configurations: [
        dict(id="Config",
             # ...
             )
    ]
)
Java
CfnBucket.Builder.create(this, "MyBucket")
    .analyticsConfigurations(Arrays.asList(java.util.Map.of(    // Java 9 or later
        "id", "Config", // ...
    ))).build();
C#
new CfnBucket(this, 'MyBucket', new CfnBucketProps {
    AnalyticsConfigurations = new Dictionary<string, string>
    {
        ["id"] = "Config",
        // ...
    }
});

対応するCfnXxxクラスを持たないリソースを定義したいというまれなケースがあります。これは、リソース仕様でまだ公開されていない新しい AWS CloudFormation リソースタイプである可能性があります。このような場合は、 cdk.CfnResourceを直接インスタンス化し、リソースタイプとプロパティを指定できます。以下の例ではこれを示しています。

TypeScript
new cdk.CfnResource(this, 'MyBucket', {
  type: 'AWS::S3::Bucket',
  properties: {
    // Note the PascalCase here! These are CloudFormation identifiers.
    AnalyticsConfigurations: [
      {
        Id: 'Config',
        // ...
      }
    ] 
  }
});
JavaScript
new cdk.CfnResource(this, 'MyBucket', {
  type: 'AWS::S3::Bucket',
  properties: {
    // Note the PascalCase here! These are CloudFormation identifiers.
    AnalyticsConfigurations: [
      {
        Id: 'Config'
        // ...
      }
    ] 
  }
});
Python
cdk.CfnResource(self, 'MyBucket',
  type="AWS::S3::Bucket",
  properties=dict(
    # Note the PascalCase here! These are CloudFormation identifiers.
    "AnalyticsConfigurations": [
      {
        "Id": "Config",
        # ...
      }
    ] 
  }
)
Java
CfnResource.Builder.create(this, "MyBucket")
        .type("AWS::S3::Bucket")
        .properties(java.util.Map.of(    // Map.of requires Java 9 or later
            // Note the PascalCase here! These are CloudFormation identifiers
            "AnalyticsConfigurations", Arrays.asList(
                    java.util.Map.of("Id", "Config", // ...
                    ))))
        .build();
C#
new CfnResource(this, "MyBucket", new CfnResourceProps
{
    Type = "AWS::S3::Bucket",
    Properties = new Dictionary<string, object>
    {   // Note the PascalCase here! These are CloudFormation identifiers
        ["AnalyticsConfigurations"] = new Dictionary<string, string>[]
        {
            new Dictionary<string, string> {
                ["Id"] = "Config"
            }
        }
    }
});

L2 コンストラクトのエスケープハッチを開発する

L2 コンストラクトに機能が欠落している場合、または問題を回避しようとしている場合は、L2 コンストラクトによってカプセル化されている L1 コンストラクトを変更できます。

すべての L2 コンストラクトには、対応する L1 コンストラクトがそれらに含まれます。例えば、高レベルBucketコンストラクトは低レベルCfnBucketコンストラクトをラップします。は AWS CloudFormation リソースに直接CfnBucket対応しているため、 で利用できるすべての機能が公開されます AWS CloudFormation。

L1 コンストラクトにアクセスするための基本的なアプローチは、 construct.node.defaultChild (Python: default_child) を使用し、正しいタイプにキャストし (必要な場合）、プロパティを変更することです。ここでも、 の例を見てみましょうBucket。

TypeScript
// Get the CloudFormation resource
const cfnBucket = bucket.node.defaultChild as s3.CfnBucket;

// Change its properties
cfnBucket.analyticsConfiguration = [
  { 
    id: 'Config',
    // ...        
  } 
];
JavaScript
// Get the CloudFormation resource
const cfnBucket = bucket.node.defaultChild;

// Change its properties
cfnBucket.analyticsConfiguration = [
  { 
    id: 'Config'
    // ...        
  } 
];
Python
# Get the CloudFormation resource
cfn_bucket = bucket.node.default_child

# Change its properties
cfn_bucket.analytics_configuration = [
    {
        "id": "Config",
        # ...
    }
]
Java
// Get the CloudFormation resource
CfnBucket cfnBucket = (CfnBucket)bucket.getNode().getDefaultChild();

cfnBucket.setAnalyticsConfigurations(
        Arrays.asList(java.util.Map.of(    // Java 9 or later
            "Id", "Config", // ...
        ));
C#
// Get the CloudFormation resource
var cfnBucket = (CfnBucket)bucket.Node.DefaultChild;

cfnBucket.AnalyticsConfigurations = new List<object> {
    new Dictionary<string, string>
    {
        ["Id"] = "Config",
        // ...
    }
};

このオブジェクトを使用して、 Metadataや などの AWS CloudFormation オプションを変更することもできますUpdatePolicy。

TypeScript
cfnBucket.cfnOptions.metadata = {
  MetadataKey: 'MetadataValue'
};
JavaScript
cfnBucket.cfnOptions.metadata = {
  MetadataKey: 'MetadataValue'
};
Python
cfn_bucket.cfn_options.metadata = {
    "MetadataKey": "MetadataValue"
}
Java
cfnBucket.getCfnOptions().setMetadata(java.util.Map.of(    // Java 9+
    "MetadataKey", "Metadatavalue"));
C#
cfnBucket.CfnOptions.Metadata = new Dictionary<string, object>
{
    ["MetadataKey"] = "Metadatavalue"
};

ハッチのエスケープ解除

には、抽象化レベルを上げる機能 AWS CDK も用意されています。抽象化レベルは「アンエスケープ」ハッチと呼ばれます。などの L1 コンストラクトがある場合はCfnBucket、新しい L2 コンストラクト (Bucketこの場合は ) を作成して L1 コンストラクトをラップできます。

これは、L1 リソースを作成するが、L2 リソースを必要とするコンストラクトで使用する場合に便利です。また、L1 コンストラクトでは利用できない .grantXxxxx() のような便利な方法を使用する場合にも役立ちます。

という名前の L2 クラスで静的メソッドを使用して、より高い抽象化レベルに移行します.fromCfnXxxxx()。例えば、Amazon S3 バケットBucket.fromCfnBucket()の場合です。L1 リソースは唯一のパラメータです。

TypeScript
b1 = new s3.CfnBucket(this, "buck09", { ... });
b2 = s3.Bucket.fromCfnBucket(b1);
JavaScript
b1 = new s3.CfnBucket(this, "buck09", { ...} );
b2 = s3.Bucket.fromCfnBucket(b1);
Python
b1 = s3.CfnBucket(self, "buck09", ...)
 b2 = s3.from_cfn_bucket(b1)
Java
CfnBucket b1 = CfnBucket.Builder.create(this, "buck09")
								// ....
		                        .build();
IBucket b2 = Bucket.fromCfnBucket(b1);
C#
var b1 = new CfnBucket(this, "buck09", new CfnBucketProps { ... });
var v2 = Bucket.FromCfnBucket(b1);

L1 コンストラクトから作成された L2 コンストラクトは、リソース名、ARN、またはルックアップから作成されたものと同様に、L1 ARNs リソースを参照するプロキシオブジェクトです。これらのコンストラクトを変更しても、最終的な合成 AWS CloudFormation テンプレートには影響しません (L1 リソースがあるため、代わりに変更できます）。プロキシオブジェクトの詳細については、「」を参照してくださいAWS アカウント内のリソースの参照。

混同を避けるため、同じ L1 コンストラクトを参照する複数の L2 コンストラクトを作成しないでください。 L1 例えば、前のセクション「」の手法Bucketを使用して CfnBucketから を抽出する場合、その Bucket.fromCfnBucket()で を呼び出して 2 つ目のBucketインスタンスを作成しないでくださいCfnBucket。実際には期待どおりに機能しますが (合成AWS::S3::Bucketされているもののみ）、コードの保守が困難になります。

Raw オーバーライド

L1 コンストラクトに欠落しているプロパティがある場合は、raw オーバーライドを使用してすべての型付けをバイパスできます。これにより、合成されたプロパティを削除することもできます。

次の例に示すように、いずれかのaddOverrideメソッド (Python: add_override) を使用します。

TypeScript
// Get the CloudFormation resource
const cfnBucket = bucket.node.defaultChild as s3.CfnBucket;

// Use dot notation to address inside the resource template fragment
cfnBucket.addOverride('Properties.VersioningConfiguration.Status', 'NewStatus');
cfnBucket.addDeletionOverride('Properties.VersioningConfiguration.Status');

// use index (0 here) to address an element of a list
cfnBucket.addOverride('Properties.Tags.0.Value', 'NewValue');
cfnBucket.addDeletionOverride('Properties.Tags.0');

// addPropertyOverride is a convenience function for paths starting with "Properties."
cfnBucket.addPropertyOverride('VersioningConfiguration.Status', 'NewStatus');
cfnBucket.addPropertyDeletionOverride('VersioningConfiguration.Status');
cfnBucket.addPropertyOverride('Tags.0.Value', 'NewValue');
cfnBucket.addPropertyDeletionOverride('Tags.0');
JavaScript
// Get the CloudFormation resource
const cfnBucket = bucket.node.defaultChild ;

// Use dot notation to address inside the resource template fragment
cfnBucket.addOverride('Properties.VersioningConfiguration.Status', 'NewStatus');
cfnBucket.addDeletionOverride('Properties.VersioningConfiguration.Status');

// use index (0 here) to address an element of a list
cfnBucket.addOverride('Properties.Tags.0.Value', 'NewValue');
cfnBucket.addDeletionOverride('Properties.Tags.0');

// addPropertyOverride is a convenience function for paths starting with "Properties."
cfnBucket.addPropertyOverride('VersioningConfiguration.Status', 'NewStatus');
cfnBucket.addPropertyDeletionOverride('VersioningConfiguration.Status');
cfnBucket.addPropertyOverride('Tags.0.Value', 'NewValue');
cfnBucket.addPropertyDeletionOverride('Tags.0');
Python
# Get the CloudFormation resource
cfn_bucket = bucket.node.default_child

# Use dot notation to address inside the resource template fragment
cfn_bucket.add_override("Properties.VersioningConfiguration.Status", "NewStatus")
cfn_bucket.add_deletion_override("Properties.VersioningConfiguration.Status")

# use index (0 here) to address an element of a list
cfn_bucket.add_override("Properties.Tags.0.Value", "NewValue")
cfn_bucket.add_deletion_override("Properties.Tags.0")

# addPropertyOverride is a convenience function for paths starting with "Properties."
cfn_bucket.add_property_override("VersioningConfiguration.Status", "NewStatus")
cfn_bucket.add_property_deletion_override("VersioningConfiguration.Status")
cfn_bucket.add_property_override("Tags.0.Value", "NewValue")
cfn_bucket.add_property_deletion_override("Tags.0")
Java
// Get the CloudFormation resource
CfnBucket cfnBucket = (CfnBucket)bucket.getNode().getDefaultChild();

// Use dot notation to address inside the resource template fragment
cfnBucket.addOverride("Properties.VersioningConfiguration.Status", "NewStatus");
cfnBucket.addDeletionOverride("Properties.VersioningConfiguration.Status");

// use index (0 here) to address an element of a list
cfnBucket.addOverride("Properties.Tags.0.Value", "NewValue");
cfnBucket.addDeletionOverride("Properties.Tags.0");

// addPropertyOverride is a convenience function for paths starting with "Properties."
cfnBucket.addPropertyOverride("VersioningConfiguration.Status", "NewStatus");
cfnBucket.addPropertyDeletionOverride("VersioningConfiguration.Status");
cfnBucket.addPropertyOverride("Tags.0.Value", "NewValue");
cfnBucket.addPropertyDeletionOverride("Tags.0");
C#
// Get the CloudFormation resource
var cfnBucket = (CfnBucket)bucket.node.defaultChild;

// Use dot notation to address inside the resource template fragment
cfnBucket.AddOverride("Properties.VersioningConfiguration.Status", "NewStatus");
cfnBucket.AddDeletionOverride("Properties.VersioningConfiguration.Status");

// use index (0 here) to address an element of a list
cfnBucket.AddOverride("Properties.Tags.0.Value", "NewValue");
cfnBucket.AddDeletionOverride("Properties.Tags.0");

// addPropertyOverride is a convenience function for paths starting with "Properties."
cfnBucket.AddPropertyOverride("VersioningConfiguration.Status", "NewStatus");
cfnBucket.AddPropertyDeletionOverride("VersioningConfiguration.Status");
cfnBucket.AddPropertyOverride("Tags.0.Value", "NewValue");
cfnBucket.AddPropertyDeletionOverride("Tags.0");

カスタムリソース

この機能が を介してではなく AWS CloudFormation、直接 API コールを介してのみ使用できない場合は、 AWS CloudFormation カスタムリソースを作成して、必要な API コールを行う必要があります。を使用してカスタムリソース AWS CDK を記述し、通常のコンストラクトインターフェイスにラップできます。コンストラクトのコンシューマーの観点から見ると、エクスペリエンスはネイティブに見えます。

カスタムリソースを構築するには、リソースの CREATE、、UPDATEおよび DELETEライフサイクルイベントに応答する Lambda 関数を記述する必要があります。カスタムリソースが単一の API コールのみを行う必要がある場合は、 の使用を検討してくださいAwsCustomResource。これにより、 AWS CloudFormation デプロイ中に任意の SDK 呼び出しを実行できます。それ以外の場合は、独自の Lambda 関数を作成して、完了するために必要な作業を実行する必要があります。

件名が大きすぎて、ここでは完全に説明できませんが、次のリンクから始めてください。