10
6

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 1 year has passed since last update.

aws-cdkのv2が来たのでドキュメントを読んでみたメモ

Last updated at Posted at 2021-12-04

概要

aws cdk v2の安定板が公開されたので、ドキュメントをGoogle日本語翻訳しながら読んでみる。
引用と感想を適宜挟んでいく。

What is the AWS CDK?

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でバケットを見れる程度と理解

重要な概念: コンストラクト

概念 意味
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-cdkkubernetes-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

最初のコンストラクトなので、解説が入っている。大事そうなので抜粋。

lib/hello-cdk-stack.ts
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 の統合(プレビュー版)

AWSクラウド開発キット(CDK)(プレビュー)

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の間での差分

cdk.json
{
  "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で追加された機能

Feature flagsより

プロパティ 意味
"@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" SNAPSHOTRemoval 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を介して機能を利用できるかどうかを判断

10
6
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
10
6

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?