これは v2 AWS CDK デベロッパーガイドです。古い CDKv1 は 2022 年 6 月 1 日にメンテナンスを開始し、2023 年 6 月 1 日にサポートを終了しました。
翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
コンストラクトは、AWS Cloud Development Kit (AWS CDK) アプリケーションの基本的な構成要素です。コンストラクトは、1 つ以上の AWS CloudFormation リソースとその設定を表すアプリケーション内のコンポーネントです。コンストラクトをインポートして設定することで、アプリケーションを 1 つずつ構築していきます。
コンストラクトをインポートして使用する
コンストラクトは、AWS コンストラクトライブラリ から CDK アプリケーションにインポートするクラスです。また、独自のコンストラクトを作成および配布することや、サードパーティーの開発者によって作成されたコンストラクトを使用することもできます。
コンストラクトは、コンストラクトプログラミングモデル (CPM) の一部です。CDK for Terraform (CDKtf)、CDK for Kubernetes (CDK8s)、Projen など、他のツールでも使用できます。
また、多数のサードパーティーが AWS CDK と互換性のあるコンストラクトを公開しています。AWS CDK コンストラクトパートナーのエコシステムについては、Construct Hub
コンストラクトレベル
コンストラクトライブラリからのコンストラクトは、3 AWS つのレベルに分類されます。各レベルは、抽象化のレベルが段階的に上がっていきます。抽象化が高いほど、設定が容易になり、必要な専門知識も少なくなります。抽象化が低いほど、より高度なカスタマイズが可能になりますが、より多くの専門知識が必要になります。
- レベル 1 (L1) コンストラクト
-
L1 コンストラクトは、CFN リソース とも呼ばれ、最下位のコンストラクトであり、抽象化は行いません。各 L1 コンストラクトは、単一の AWS CloudFormation リソースに直接マッピングされます。L1 コンストラクトでは、特定の AWS CloudFormation リソースを表すコンストラクトをインポートします。次に、コンストラクトインスタンス内でリソースのプロパティを定義します。
L1 コンストラクトは、AWS に精通した上で、AWS CloudFormation リソースプロパティの定義を完全に制御する必要がある場合に最適です。
AWS コンストラクトライブラリでは、L1 コンストラクトには
Cfn
で始まり、その後に対応する AWS CloudFormation リソースの識別子が続く名前が付けられます。たとえば、CfnBucket
コンストラクトはAWS::S3::Bucket
AWS CloudFormation リソースを表す L1 コンストラクトです。L1 コンストラクトは、AWS CloudFormation リソース仕様から生成されます。リソースが AWS CloudFormation に存在する場合、それは L1 コンストラクトとして AWS CDK で利用可能になります。新しいリソースまたはプロパティが AWS コンストラクトライブラリで利用可能になるまでは、最大 1 週間かかる場合があります。詳細については、「AWS CloudFormation ユーザーガイド」の「AWS リソースおよびプロパティタイプのリファレンス」を参照してください。
- レベル 2 (L2) コンストラクト
-
キュレーションされたコンストラクトとも呼ばれる L2 コンストラクトは、CDK チームによって慎重に開発され、通常は最も広く使用されているコンストラクトタイプです。L2 コンストラクトは、L1 コンストラクトと同様に、単一の AWS CloudFormation リソースに直接マッピングされます。L1 コンストラクトと比較して、L2 コンストラクトは直感的なインテントベースの API を通してより高度な抽象化を提供します。L2 コンストラクトには、適切なデフォルトプロパティ設定、ベストプラクティスのセキュリティポリシー、および多くのボイラープレートコードやグルーロジックを生成する機能が含まれています。
L2 コンストラクトは、ほとんどのリソースにヘルパーメソッドも提供します。これにより、プロパティ、アクセス許可、リソース間のイベントベースのインタラクションなどをより簡単かつ迅速に定義できます。
s3.Bucket
クラスは、Amazon Simple Storage Service (Amazon S3) バケットリソースの L2 コンストラクトの一例です。AWS コンストラクトライブラリには、安定して本番環境で使用できるように指定された L2 コンストラクトが含まれています。開発中の L2 コンストラクトは実験的なものとして指定され、別個のモジュールとして提供されます。
- レベル 3 (L3) コンストラクト
-
L3 コンストラクトは、パターンとも呼ばれ、最も高度な最高レベルです。各 L3 コンストラクトには、アプリケーション内の特定のタスクまたはサービスを達成するために連携するように設定された、複数リソースの集合を含めることができます。L3 コンストラクトは、アプリケーション内の特定のユースケースの AWS アーキテクチャ全体を作成するために使用されます。
完全なシステム設計、または大規模なシステムの主要部分を提供するために、L3 コンストラクトは、独自の考えに基づくデフォルトのプロパティ設定を提供します。これらは、問題を解決し、解決策を提供するための特定のアプローチを軸に構築されています。L3 コンストラクトを使用すると、入力とコードの量を最小限に抑えながら、複数のリソースをすばやく作成して設定できます。
ecsPatterns.ApplicationLoadBalancedFargateService
クラスは、Amazon Elastic Container Service (Amazon ECS) クラスター上で実行され、Application Load Balancer をフロントに配置した AWS Fargate サービスを表す L3 コンストラクトの一例です。L2 コンストラクトと同様に、本番稼働用の準備ができている L3 コンストラクトは、AWS コンストラクトライブラリに含まれています。開発中のものは、別個のモジュールで提供されます。
コンストラクトの定義
コンポジション
コンポジションは、コンストラクトを通して高レベルの抽象化を定義するための重要なパターンです。高レベルのコンストラクトは、任意の数の低レベルのコンストラクトから構成できます。ボトムアップの観点からは、デプロイする AWS リソースを個別に整理するためにコンストラクトを使用します。必要な階層数で、目的に応じて便利な抽象化を使用します。
コンポジションを使用することで、再利用可能なコンポーネントを定義し、他のコードと同様に共有することができます。たとえば、チームはバックアップ、グローバルレプリケーション、自動スケーリング、モニタリングなど、Amazon DynamoDB テーブルに対する会社のベストプラクティスを実装するコンストラクトを定義できます。チームは、コンストラクトを内部的に他のチームと共有することも、公開することもできます。
チームは、他のライブラリパッケージと同様にコンストラクトを使用できます。ライブラリが更新されると、開発者は他のコードライブラリと同様に、新しいバージョンの改善やバグ修正にアクセスできるようになります。
初期化
コンストラクトは、Construct
基底クラスを拡張したクラスとして実装されます。コンストラクトの定義は、クラスのインスタンス化によって行います。すべてのコンストラクトは、初期化時に以下の 3 つのパラメータを取ります。
-
scope – コンストラクトの親または所有者。これはスタックでも別のコンストラクトでもかまいません。スコープは、コンストラクトツリー内のコンストラクトの場所を決定します。通常は、現在のオブジェクトを表す
this
(Python ではself
) をスコープとして渡すべきです。 -
id — スコープ内で一意でなければならない識別子です。識別子は、 コンストラクト内で定義されているすべての名前空間として機能します。これは、リソース名やAWS CloudFormation論理 ID などの一意の識別子を生成するために使用されます。
識別子が一意である必要があるのはスコープ内のみです。これにより、含まれる可能性のあるコンストラクトと識別子を気にせずにコンストラクトをインスタンス化して再利用でき、コンストラクトを組み合わせてより高いレベルの抽象化を作成できるようになります。さらに、スコープを使用すると、コンストラクトのグループを一度に参照できます。例としては、タグ付けや、コンストラクトのデプロイ先の指定などが挙げられます。
-
props – 言語に応じて、コンストラクトの初期設定を定義するプロパティまたはキーワード引数のセット。高レベルのコンストラクトであるほど多くのデフォルト値が提供され、すべての prop 要素がオプションである場合は、props パラメータを完全に省略することができます。
構成
ほとんどのコンストラクトは、3 番目の引数 (Python ではキーワード引数) として props
を受け入れます。これは、コンストラクトの設定を定義する名前と値のコレクションです。以下の例では、AWS Key Management Service (AWS KMS) の暗号化と静的ウェブサイトホスティングが有効になっているバケットを定義しています。暗号化キーの明示的な指定はされていないため、Bucket
コンストラクトは新しい kms.Key
を定義してバケットに関連付けます。
new s3.Bucket(this, 'MyEncryptedBucket', {
encryption: s3.BucketEncryption.KMS,
websiteIndexDocument: 'index.html'
});
コンストラクトの操作
コンストラクトは、基底クラスである Construct クラスを拡張したクラスです。コンストラクトをインスタンス化すると、コンストラクトオブジェクトは一連のメソッドとプロパティを公開します。これにより、コンストラクトを操作し、システムの他の部分への参照として渡すことができます。
AWS CDK フレームワークは、コンストラクトの APIs に制限を加えません。作成者は必要な API を定義できます。ただし、s3.Bucket
などの AWS コンストラクトライブラリに含まれている AWS コンストラクトは、ガイドラインおよび一般的なパターンに従います。これにより、すべての AWS リソースで一貫したエクスペリエンスが得られます。
ほとんどの AWS コンストラクトには、そのコンストラクトに対する AWS Identity and Access Management (IAM) アクセス許可をプリンシパルに付与するために使用できる一連の許可メソッドがあります。以下の例では、IAM グループ data-science
に対し、Amazon S3 バケット raw-data
から読み取りを行うためのアクセス許可を付与します。
const rawData = new s3.Bucket(this, 'raw-data');
const dataScience = new iam.Group(this, 'data-science');
rawData.grantRead(dataScience);
もう 1 つの一般的なパターンは、AWS コンストラクトが、他の場所から提供されたデータからリソースの属性の 1 つを設定することです。属性には、Amazon リソースネーム (ARN)、名前、または URL などが含まれます。
以下のコードは AWS Lambda 関数を定義し、環境変数のキューの URL を介して Amazon Simple Queue Service (Amazon SQS) キューに関連付けます。
const jobsQueue = new sqs.Queue(this, 'jobs');
const createJobLambda = new lambda.Function(this, 'create-job', {
runtime: lambda.Runtime.NODEJS_18_X,
handler: 'index.handler',
code: lambda.Code.fromAsset('./create-job-lambda-code'),
environment: {
QUEUE_URL: jobsQueue.queueUrl
}
});
AWS コンストラクトライブラリの最も一般的な API パターンについては、「リソースと AWS CDK」を参照してください。
アプリケーションとスタックのコンストラクト
AWS コンストラクトライブラリの App
および Stack
クラスは、一意のコンストラクトです。他のコンストラクトと比較すると、それらは AWS リソースを独自に設定することはありません。代わりに、他のコンストラクトにコンテキストを提供するために使用されます。AWS リソースを表すすべてのコンストラクトは、直接または間接的に、Stack
コンストラクトのスコープ内で定義する必要があります。Stack
コンストラクトは、App
コンストラクトのスコープ内で定義されます。
CDK アプリケーションの詳細については、「AWS CDK アプリケーション」を参照してください。CDK スタックの詳細については、「AWS CDK スタックの概要」を参照してください。
以下の例では、単一のスタックを持つアプリケーションを定義します。スタック内では、L2 コンストラクトを使用して Amazon S3 バケットリソースを設定します。
import { App, Stack, StackProps } from 'aws-cdk-lib';
import * as s3 from 'aws-cdk-lib/aws-s3';
class HelloCdkStack extends Stack {
constructor(scope: App, id: string, props?: StackProps) {
super(scope, id, props);
new s3.Bucket(this, 'MyFirstBucket', {
versioned: true
});
}
}
const app = new App();
new HelloCdkStack(app, "HelloCdkStack");
コンストラクトの使用
L1 コンストラクトの使用
L1 コンストラクトは個々の AWS CloudFormation リソースに直接マッピングされます。設定に必要なリソースは自分で用意しなければなりません。
この例では、L1 CfnBucket
コンストラクトを使用して bucket
オブジェクトを作成します。
const bucket = new s3.CfnBucket(this, "amzn-s3-demo-bucket", {
bucketName: "amzn-s3-demo-bucket"
});
単純なブール語、文字列、数値、コンテナではないコンストラクトのプロパティは、サポートされている言語ごとに異なる方法で処理されます。
const bucket = new s3.CfnBucket(this, "amzn-s3-demo-bucket", {
bucketName: "amzn-s3-demo-bucket",
corsConfiguration: {
corsRules: [{
allowedOrigins: ["*"],
allowedMethods: ["GET"]
}]
}
});
重要
L1 コンストラクトで L2 プロパティタイプを使用することはできません。その逆も同様です。L1 コンストラクトを使用する場合は、使用している L1 コンストラクトに定義されているタイプを必ず使用してください。他の L1 コンストラクトの型を使用しないでください (名前が同じものもありますが、同じ型ではありません)。
言語固有の API リファレンスの中には、現在 L1 プロパティタイプへのパスにエラーがあるか、これらのクラスがまったく記載されていないものがあります。これは近いうちに修正したいと考えています。それまでの間、このような型は常に、それらが使用される L1 コンストラクトの内部クラスであることに注意してください。
L2 コンストラクトの使用
以下の例では、Bucket
L2 コンストラクトからオブジェクトを作成して、Amazon S3 バケットを定義します。
import * as s3 from 'aws-cdk-lib/aws-s3';
// "this" is HelloCdkStack
new s3.Bucket(this, 'MyFirstBucket', {
versioned: true
});
MyFirstBucket
は、AWS CloudFormation が作成するバケットの名前ではありません。これは、CDK アプリケーションのコンテキスト内で新しいコンストラクトに与えられる論理識別子です。physicalName 値は、AWS CloudFormation リソースに名前を付けるために使用されます。
サードパーティーのコンストラクトの使用
Construct Hub
独自のコンストラクトの作成
既存のコンストラクトを使用するだけでなく、独自のコンストラクトを記述し、誰でもアプリで使用できるようにすることもできます。AWS CDK において、すべてのコンストラクトは対等です。AWS コンストラクトライブラリからのコンストラクトは、NPM、Maven、または PyPI を介して公開されたサードパーティーライブラリからのコンストラクトと同様に扱われます。また、社内のパッケージリポジトリに公開されたコンストラクトも同じように扱われます。
新しいコンストラクトを宣言するには、Construct 基底クラスを拡張するクラスを constructs
パッケージで作成し、初期化引数のパターンに従います。
以下の例は、Amazon S3 バケットを表すコンストラクトを宣言する方法を示しています。S3 バケットは、誰かがファイルをアップロードするたびに Amazon Simple Notification Service (Amazon SNS) 通知を送信します。
export interface NotifyingBucketProps {
prefix?: string;
}
export class NotifyingBucket extends Construct {
constructor(scope: Construct, id: string, props: NotifyingBucketProps = {}) {
super(scope, id);
const bucket = new s3.Bucket(this, 'bucket');
const topic = new sns.Topic(this, 'topic');
bucket.addObjectCreatedNotification(new s3notify.SnsDestination(topic),
{ prefix: props.prefix });
}
}
注記
NotifyingBucket
コンストラクトは、Bucket
ではなく、Construct
を継承しています。これは、Amazon S3 バケットと Amazon SNS トピックをバンドルするために、継承ではなく構成を使用しているためです。一般的に、AWS CDK コンストラクトを開発する場合、継承よりもコンポジションが優先されます。
NotifyingBucket
コンストラクターは、scope
、id
、props
という典型的なコンストラクトの署名を持っています。最後に挙げた引数 props
は、props はすべてオプションであるため、オプション (デフォルト値 {}
) になります。(規定クラス Construct
は props
引数を取りません)。このコンストラクトのインスタンスは、props
なしでアプリに定義できます。たとえば以下のようになります。
new NotifyingBucket(this, 'MyNotifyingBucket');
または、props
(Java では追加パラメータ) を使用して、フィルタリングするパスプレフィックスを指定できます。たとえば以下のようになります。
new NotifyingBucket(this, 'MyNotifyingBucket', { prefix: 'images/' });
通常、コンストラクト上のいくつかのプロパティまたはメソッドも公開する必要があります。コンストラクトの背後にトピックが隠れてしまう形では、コンストラクトのユーザーがサブスクライブできなくなるため、あまり有益とは言えません。topic
プロパティを追加すると、以下の例に示すように、利用者が内部トピックにアクセスできるようになります。
export class NotifyingBucket extends Construct {
public readonly topic: sns.Topic;
constructor(scope: Construct, id: string, props: NotifyingBucketProps) {
super(scope, id);
const bucket = new s3.Bucket(this, 'bucket');
this.topic = new sns.Topic(this, 'topic');
bucket.addObjectCreatedNotification(new s3notify.SnsDestination(this.topic), { prefix: props.prefix });
}
}
これで、利用者はトピックをサブスクライブできるようになりました。たとえば以下のようになります。
const queue = new sqs.Queue(this, 'NewImagesQueue');
const images = new NotifyingBucket(this, '/images');
images.topic.addSubscription(new sns_sub.SqsSubscription(queue));
詳細はこちら
以下のビデオでは、CDK コンストラクトの包括的な概要と、CDK アプリケーションでの CDK コンストラクトの使用方法について説明します。