概要
aws cdk v2の安定板が公開されたので、ドキュメントをGoogle日本語翻訳しながら読んでみる。
引用と感想を適宜挟んでいく。
What is the AWS CDK?
以下の図が分かりやすい。
CloudFormation (IaC) を型の助けを借りつつコードで書けるようにしたものという理解。
追加のドキュメントとリソースは充実しているように見える。どれから読もうか。
Getting started with the AWS CDK
入門。
- CDKの対象ユーザ
- IAMを扱った経験があること
- CDKで使うプログラミング言語の経験があること(Typescript,Python,Java,C#)
- CloudFormationの経験があるとなおよし
- cdkを動かす環境で、
aws cliで使うAWSクレデンシャルがすでにあること-
aws configureが設定済で、
aws s3 lsでバケットを見れる程度と理解
-
aws configureが設定済で、
重要な概念: コンストラクト
| 概念 | 意味 |
|---|---|
| Construct | S3バケットなどの具体的なAWSリソースを定義。クラス（型）として表現される。 |
コンストラクトには以下の種類がある
| 略称 | 種別 | 意味 |
|---|---|---|
| L1 | AWS CloudFormation-only | AWSCloudFormationによって定義されたリソースタイプに直接対応.AWS CloudFormation仕様から自動的に生成.常にCfnで始まる名前が付く。(例: S3の場合CfnBucket) |
| L2 | Curated | L1リソースをカプセル化し、適切なデフォルトとベストプラクティスのセキュリティポリシーを提供したもの。特定のユースケースに対応し、インフラストラクチャ開発を簡素化する（例：S3の場合、Bucket) |
| L3 | Patterns | 特定のユースケース向けにAWSアーキテクチャ全体を作成するための複数のリソースを宣言。構成はパラメータに要約される。 |
Constructの基本クラスは、v1ではcdk-coreモジュールにあった。v2ではconstructsモジュールに移動している。これは、Constructクラスはaws-cdk以外にもterraform-cdkやkubernetes-cdkでも使われるようになったため。
ブートストラップ
Assetをアップロードする先のコンテナ(S3バケット)を、デプロイ先のアカウント・リージョンに作成すること。
Assetとは、AWSLambda関数やDockerイメージなど、スタックとともにデプロイされる外部ファイルのこと。CDKはAssetをコンテナにアップロードして、デプロイ中にCloudFormationで利用する。
AWS CDK Toolkit (CLI)
AWS CDK Toolkitは、AWSCDKアプリとやり取りするために使用するメインツール。
コマンドラインインターフェイス（CLI）とも呼ばれる。
コードを実行し、AWSCloudFormationテンプレートを生成してデプロイする。
また、展開、差分、削除、およびトラブルシューティングの機能もある。
詳細はAWS CDK Toolkitを参照
NextSteps
次のステップ
ワークショップはcdk v1を最初に触ったときに手を動かして概念を知るのに役になった。ほとんど同じかな？
Construc Hubはコンストラクトの定義を集めた場所かしら。困ったら参照するドキュメントとして覚えておいたほうがよさそう。
Your first AWS CDK app
最初のAWSCDKアプリ。
アプリをデプロイするまでを解説している。とりあえず読み進めたいので、自分は手を動かすのはスキップ。initで作成される内容のv1との比較だけやってみた。v1とv2の比較。
大きな違いはないように見える。
そもそもv1の最新のinitが作られるファイルが自分が1年前にinitで作ったファイルと違っていた。
Add an Amazon S3 bucket
最初のコンストラクトなので、解説が入っている。大事そうなので抜粋。
import * as cdk from 'aws-cdk-lib';
import { aws_s3 as s3 } from 'aws-cdk-lib';
export class HelloCdkStack extends cdk.Stack {
constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
super(scope, id, props);
new s3.Bucket(this, 'MyFirstBucket', {
versioned: true
});
}
}
new s3.Bucket(scope, id, props)の3つのパラメータについて詳しく見ている。
| パラメータ | 概要 | 説明 |
|---|---|---|
| scope | スタックのスコープを指定 | コンストラクト内にコンストラクトを定義して階層を作ることもできる。例ではスタックが親であることを指定(this=Stack) |
| id | AWSCDKアプリ内のリソースの論理ID | デプロイ全体でリソースを一意に識別する。定義を変更したときCDKがリソースを更新するために必要。スコープ内で一意である必要がある。作成するリソースにはこのIDと別の名前をつけることもできる（例： bucketNameプロパティに指定) |
| props | リソースに設定するプロパティ | 例ではversioned=true。バケット内のファイルのバージョン管理を有効にするプロパティを設定 |
Destroying the app's resources
バケットを変更しなかった場合RemovalPolicy、スタックの削除は正常に完了しますが、バケットは孤立します（スタックに関連付けられなくなります）。
ノートに結構大事なことが書いてあるので覚書。
設定によっては、Stackで定義したコンストラクトが削除されないパターンがある。
意図しないリソースが残っていないか、stackをdestroyした後は確認しておいたほうがよいかもしれない。
Concepts
ざっくり、気になったら読むとかでも良さそう。
初心者（今後、忘れ去った自分）が読んでおくとよいものに○をつけておく。
| 項目 | 初 | 感想 |
|---|---|---|
| Constructs | ○ | L1とかL2の説明があるので、CDK触ったことなければ読んで損はない。 |
| Apps | ○ | ライフサイクルが分かる |
| Stacks | デプロイ単位、という以上のことはテクニカルなことをするときに使いそう。 | |
| Environments | 複数環境を一気に定義とかの参考かな | |
| Resources | 他のStackで作ったリソースにアクセスしたくなったら読むと良さそう | |
| Identifiers | 重要な概念や最初のAppでIDの大事なことは説明されているので、より詳細を知りたくなれば | |
| Tokens | ちょっと凝ったことするときに見るとヒントになるかも | |
| Parameters | 一般にオススメしないらしい。既存のCloudFormationの移行とかだと見るかも？ | |
| Tagging | とりあえずタグはつけておいたほうがいいと思うが、最初に必須とまでは。。。 | |
| Assets | 重要な概念のブートストラップで概要は十分。v2でs3以外も選択肢に入ったので気になる人は | |
| Permissions | ○ | 初心者が最初にハマりがちな権限。最初は意味が分からなくていい。後でそういえば、、となりそうな情報が書かれている。 |
| Context | Runtime context。StackやConstrutに関連付けるキーと値のペア。cdk.jsonやcdk.context.jsonの詳細が知りたければ | |
| Feature flags | Contextに設定できる、v1からの破壊的な変更を元の挙動に戻すフラグ。initで設定される"@aws-cdk/core:stackRelativeExports"などの解説 |
|
| Aspects | Stack内のリソースに一気にタグつけ | |
| Escape hatches | CloudFormationではできるけどCDKではまだ出来ないってときに。CloudFormationで何ができるかは「AWS resource and property types reference」を参照 | |
| Bootstrapping | 「重要な概念」でブートストラップは説明済。v1とv2は別のものを使うとか、v1のデフォルトで課金対象となっていたCMKをv2ではデフォルトから外したとかv2でs3以外も選べるとか |
Best practices
ベストプラクティス。以下に概要を抜粋。意図は省略するため、元記事を読んだほうが良い。
| カテゴリ | 概要 |
|---|---|
| 組織 | CDKを採用する際に、会社の他のメンバーのトレーニングと指導を担当する専門家のチーム(1人~規模により様々)を配置すること |
| コーディング | シンプルに始めて、必要なときにだけ複雑さを追加。アーキテクチャのベストプラクティスに従う。複数のアプリケーションを同じリポジトリに配置することは可能だが非推奨。インフラストラクチャとランタイムコードは同じパッケージを推奨。 |
| コンストラクト | Stackではなく、Constructを使用してアプリをモデル化する。環境変数の参照はAWS CDKアプリのトップレベルに制限する。リソースの論理IDは変更しない。 |
| アプリケーション | synthタイミングのロジックは使わない(ex. bad: CloudFormationが提供するFn::If / good: CDKのコード上でif)。物理名ではなく、生成されたリソース名を使用する。削除ポリシーとログ保持を定義する。cdk.context.jsonで冪等性を担保する。AWSCDKにロールとセキュリティグループを管理させる(grantHogeメソッドの利用) |
スタック分割のベストプラクティス
- 通常、できるだけ多くのリソースを同じスタックに保持する方が簡単なので、それらを一緒に保持する。
- ※ 分離する必要があることがわかっている場合は除く
- ステートフルリソース（データベースなど）をステートレスリソースとは別のスタックに保持する。
- ステートフルスタックでターミネーション保護をオンにできるため
- → データ損失のリスクなく、ステートレススタックを自由に作成・破棄。
- ステートフルリソースは、コンストラクトの名前変更に対し、慎重にする必要があるため
- 名前を変更すると、リソースが置き換えられるので、移動や名前変更がされる可能性のあるコンストラクト内にネストしてはいけない
- （キャッシュのように、失われた場合に状態を再構築できる場合を除く）
- 名前を変更すると、リソースが置き換えられるので、移動や名前変更がされる可能性のあるコンストラクト内にネストしてはいけない
- ステートフルスタックでターミネーション保護をオンにできるため
API reference
APIリファレンス。バージョニングや互換性について。
AWS CDK 2 AWS CDK Reference Documentation は今後、必要になったら読みに行く場所になりそう。
How tos
ハウツー。AWS CDKの短いコードサンプル。
困ったときにお世話になりそう。
| 項目 | 概要 |
|---|---|
| 環境変数から値を取得する | process.env |
| AWSCloudFormationのパラメーターを使用する | コンセプト - パラメータを参照 |
| 既存のAWSCloudFormationテンプレートをインポート |
CfnIncludeのL1コンストラクト型が利用できる |
| AWSCloudFormationパブリックレジストリのリソースを使用 | CloudFormationコンソールやcliからの設定方法 |
| SystemsManagerパラメータストアから値を取得 |
StringParameter.ValueForStringParameterでトークンを取得 |
| AWS SecretsManagerから値を取得 |
Secret.FromSecretAttributesを利用 |
| 複数のスタックを持つアプリを作成する | 2つのリージョンへのデプロイ例 |
| CloudWatchアラームを設定 | Queueでメトリックを作ってアラームを設定する例 |
| コンテキスト変数から値を取得 | cdk.jsonに書くか-c hoge=fugaのようにコマンドラインオプションで渡す |
| CDKパイプラインを使用したCI/CD | パイプラインスタックとアプリケーションスタックを定義。デプロイ後の検証など |
AWS CDK Toolkit（cdkコマンド）
ツールキットコマンドなど。オプションについても書いてあるので、使い始めは参照することが多くなるかも。
CDKとAWS SAM CLI の統合(プレビュー版)
sam-beta-cdk local invokeでlambdaのローカルinvokeができたりする。
v1のときにsam-beta-cdkのlambdaのローカル実行をWindows10+Vagrant+VirtualBox+Ubuntuで試してみたメモで試したことがあるが、時間が経っているから変わっている部分があるかも。
使ってみた。Feature Flagsを一つfalseにしないと動かなかった。
Testing constructs
Constructのテスト
aws-cdk-lib/assertionsを使ったテスト手順。
スナップショットテストはv1からのマイグレーションで便利そう。
日本語だとCDKv2で@aws-cdk/assertionsを試してみるの記事とかよいかも。
Troubleshooting
AWSCDKの一般的な問題のトラブルシューティング.
エラーメッセージでぐぐるとこのページに飛ばされそう。
2022.11.06追記 cdk.jsonのcontextについて
cdkのバージョンが上がるにつれ、冪等性を保つための項目がどんどん増えている。
以下はcdk init --language typescriptしたときに作成されるデフォルトファイルの、v20とv50の間での差分
{
"app": "npx ts-node --prefer-ts-exts bin/cdk.ts",
"watch": {
"include": [
"**"
],
"exclude": [
"README.md",
"cdk*.json",
"**/*.d.ts",
"**/*.js",
"tsconfig.json",
"package*.json",
"yarn.lock",
"node_modules",
"test"
]
},
"context": {
"@aws-cdk/aws-apigateway:usagePlanKeyOrderInsensitiveId": true,
"@aws-cdk/core:stackRelativeExports": true,
"@aws-cdk/aws-rds:lowercaseDbIdentifier": true,
"@aws-cdk/aws-lambda:recognizeVersionProps": true,
+ "@aws-cdk/aws-lambda:recognizeLayerVersion": true,
"@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1.2_2021": true,
"@aws-cdk-containers/ecs-service-extensions:enableDefaultLogDriver": true,
"@aws-cdk/aws-ec2:uniqueImdsv2TemplateName": true,
+ "@aws-cdk/core:checkSecretUsage": true,
+ "@aws-cdk/aws-iam:minimizePolicies": true,
+ "@aws-cdk/aws-ecs:arnFormatIncludesClusterName": true,
+ "@aws-cdk/core:validateSnapshotRemovalPolicy": true,
+ "@aws-cdk/aws-codepipeline:crossAccountKeyAliasStackSafeResourceName": true,
+ "@aws-cdk/aws-s3:createDefaultLoggingPolicy": true,
+ "@aws-cdk/aws-sns-subscriptions:restrictSqsDescryption": true,
+ "@aws-cdk/aws-apigateway:disableCloudWatchRole": true,
+ "@aws-cdk/core:enablePartitionLiterals": true,
"@aws-cdk/core:target-partitions": [
"aws",
"aws-cn"
]
}
}
CDK V2で追加された機能
| プロパティ | 意味 |
|---|---|
| "@aws-cdk/aws-lambda:recognizeLayerVersion" | Lambda 関数に関連付けられたレイヤーを更新すると、新しいバージョンの関数が作成されることを確認する |
| "@aws-cdk-containers/ecs-service-extensions:enableDefaultLogDriver" | デフォルトで、サービス拡張コンテナへのログインを有効にする |
| "@aws-cdk/aws-ec2:uniqueImdsv2TemplateName" | InstanceRequireImdsv2Aspectで作られた名前が一意であることを確認する |
| "@aws-cdk/core:checkSecretUsage" | 安全な場所でのみ Secrets Manager の値を使用できる |
| "@aws-cdk/aws-iam:minimizePolicies" | 可能であれば、IAM ポリシーの作成を最小限に抑える |
| "@aws-cdk/aws-ecs:arnFormatIncludesClusterName" | Amazon EC2 または Fargate クラスターをインポートするときに、新しい ARN 形式を使用する |
| "@aws-cdk/core:validateSnapshotRemovalPolicy" |
SNAPSHOTにRemoval Policyが提供されていないリソースを指定したときにcdk synthが失敗するようにする*
|
| "@aws-cdk/aws-codepipeline:crossAccountKeyAliasStackSafeResourceName" |
cross-account key aliasがパイプライン内で一意であることを確認する |
| "@aws-cdk/aws-s3:createDefaultLoggingPolicy" | デプロイ時にバケット ポリシーを自動的に作成するサービスで S3 バケットを使用する場合は、AWS CDK で必要なポリシーを構成する |
| "@aws-cdk/aws-sns-subscriptions:restrictSqsDescryption" | Amazon SNS トピックにサブスクライブされた Amazon SQS キューで、Amazon SNS 全体ではなくトピックのみに復号化のアクセス許可を制限する |
CDK V1とV2でデフォルトの設定が異なる部分
falseに設定するとv1の挙動に戻すことができる。
| プロパティ | フラグを設定するタイミング |
|---|---|
| "@aws-cdk/aws-apigateway:usagePlanKeyOrderInsensitiveId" | アプリケーションが複数の Amazon API Gateway API キーを使用し、それらを使用プランに関連付ける場合 |
| "@aws-cdk/core:stackRelativeExports" | アプリケーションが複数のスタックを使用し、あるスタックから別のスタックのリソースを参照する場合。れにより、AWS CloudFormation エクスポートの構築に絶対パスと相対パスのどちらが使用されるかが決まる |
| "@aws-cdk/aws-rds:lowercaseDbIdentifier" | アプリケーションが Amazon RDS データベース インスタンスまたはデータベース クラスターを使用し、これらの識別子を明示的に指定する場合 |
| "@aws-cdk/aws-lambda:recognizeVersionProps" | falseにした時の挙動 -> Lambda関数の変更を検知した場合にmetadataをCDKは含めるようになる。metadataの変更のみの場合に、duplicate versions are not allowedのエラーでデプロイに失敗する。 |
| "@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1.2_2021" | アプリケーションが Amazon CloudFront ディストリビューションで TLS_V1_2_2019 セキュリティ ポリシーを使用している場合 |
| "@aws-cdk/aws-apigateway:disableCloudWatchRole" | |
| "@aws-cdk/core:enablePartitionLiterals" |
CDKでの設定法
setContextメソッドで設定可能。
cdk v2 guide context
AWS CDKでcdk.jsonのコンテキスト(context)を使用する方法
const app = new cdk.App()
app.node.setContext('@aws-cdk/aws-apigateway:usagePlanKeyOrderInsensitiveId', false)
参考
AWS Cloud Development Kit (AWS CDK) v2 is now generally available
AWS CloudFormationを介して機能を利用できるかどうかを判断