Amplify Gen2から知るAWS CDK Toolkit Libraryの使い方/How to use the AWS CDK Toolkit Library as known from Amplify Gen2

Transcript

1. AWS Amplify Gen2から知るAWS CDK Toolkit Library の使い方 AWS CDK Conference 2025 presented by JAWS-UG 2025-07-12 株式会社永和システムマネジメント 村上雅彦 (a.k.a @fossamagna) 1
2. 自己紹介 名前: 村上 雅彦 所属: 株式会社永和システムマネジメント コミュニティ活動: Amplify Japan User Group 運営メ ンバー、AWS Community Builder (Front-End Web & Mobile since 2022) X (Twitter): @fossamagna GitHub: @fossamagna 2
3. このセッションで話すこと AWS CDK Toolkit Library、このライブラリを どういった時に使うのか？ 使うと何ができるのか？ について、実際にライブラリを利用している Amplify Gen2 ( @aws-amplify/backend ) の実装を通して紹介します。 3
4. AWS CDK Toolkit Library とは？ 公式ドキュメント: https://docs.aws.amazon.com/ja_jp/cdk/v2/guide/toolkit-library.html AWS CDK Toolkit Libraryは、AWS CDKをプログラムで操作するためのライブラリ です。 4
5. 何ができるのか？ AWS 上でプログラムによるアクセスを必要とする CDK アクションを実行できま す。AWS CDK Toolkit Libraryを使用すると、ブートストラップ、合成、デプロイな どのアクションを、コマンドラインインターフェイス (CLI) コマンドではなくコー ドで実装できます。 CLIで馴染みのある cdk deploy や cdk synth といったコマンド相当の処理を あなた の書いたプログラムから実行できる ようになります。 5
6. どういう時に使うのか？ (ユースケース) このライブラリを使用すると、カスタムツールを作成したり、専用の CLI アプリ ケーションを構築したり、CDK のプログラムによるアクセス機能を開発ワークフ ローに統合したりできます。 まさに Amplify Gen2 は、このライブラリを使って独自のCLI ( npx ampx ) を構築して いる良い例です。 6
7. AWS CDK Toolkit Libraryの基本的な使い方 npm: https://www.npmjs.com/package/@aws-cdk/toolkit-lib わずか5ステップで使い始めることができます。 1. @aws-cdk/toolkit-lib をインストール 2. Toolkit インスタンスを作成 3. CDKアプリ用のクラウドアセンブリソースを作成 4. CDKアプリのプログラムアクションを定義 5. (オプション) CDKツールキットをさらにカスタマイズ 7
8. コード例: cdk deploy を実行する // 1. `@aws-cdk/toolkit-lib`をインストール＆パッケージインポート import { Toolkit } from '@aws-cdk/toolkit-lib'; import { App, Stack } from 'aws-cdk-lib'; import * as s3 from 'aws-cdk-lib/aws-s3'; // 2. `Toolkit` インスタンスを作成 const toolkit = new Toolkit(); // 3. CDKアプリ用のクラウドアセンブリソースを作成（インラインで S3 バケットを作成） const cloudAssemblySource = await toolkit.fromAssemblyBuilder(async () => { const app = new App(); const stack = new Stack(app, 'SimpleStorageStack'); new s3.Bucket(stack, 'MyFirstBucket', { versioned: true }); return app.synth(); }); // 4. CDKアプリのプログラムアクションを定義(デプロイを実行) await toolkit.deploy(cloudAssemblySource); 8
9. Toolkit Libraryが提供する「アクション」 synth list diff deploy rollback watch drift destroy bootstrap refactor 9
10. Amplify Gen2で使われているアクション Amplify Gen2 ( @aws-amplify/backend ) では、以下の3つのアクションが使われていま す。 deploy : ampx deploy/sandbox でデプロイ実行 synth : ampx deploy/sandbox でデプロイ実行前にクラウドアセンブリソースを 作成 destroy : ampx sandbox でデプロイした環境を破棄 10
11. Amplify Gen2の実装から学ぶカスタマイズ術 AWS CDK Toolkit Libraryの真価は、そのカスタマイズ性にあります。 Amplify Gen2の実装を例に、次のポイントを見ていきましょう。 1. IIoHost : CLIのUI/UXをカスタマイズ 2. Cloud Assembly Source : CDKアプリのソースを動的に生成 3. エラーハンドリング: 安全なエラー処理 11
12. 1. IIoHost : CLIのUI/UXをカスタマイズ IIoHost はCDK Toolkitとアプリケーションとの間の通信を定義するインターフェース 独自の IIoHost を実装することで、CDKからの出力（プログレスバーなど）や、対話 的な問い合わせ（これらの変更をデプロイしますか？など）への応答をカスタマイズ できます。 export interface IIoHost { /** * メッセージ: 操作の進捗や状態通知 (応答不要) */ notify(msg: IoMessage<unknown>): Promise<void>; /** * リクエスト: 利用者からの応答が必要な問いかけ */ requestResponse<T>(msg: IoRequest<unknown, T>): Promise<T>; } 12
13. Amplify Gen2の実装: AmplifyIOHost Amplify Gen2は AmplifyIOHost という独自の IIoHost を実装しています。 requestResponse は常にデフォルト応答を返す（非対話的） notify はイベントハンドラ( AmplifyEventLogger )を呼び出す TTYが有効な場合、リソース毎のプログレスバーを表示 リッチで分かりやすい進捗表示を実現 13
14. デプロイ時の表示: CLI利用 0:00 / 3:56 14
15. デプロイ時の表示: Toolkit Library(AmplifyIOHost)利用時 0:00 / 6:14 15
16. 2. Cloud Assembly Source : CDKアプリのクラウドアセンブリソースを動 的に生成 ICloudAssemblySource は、CDKアプリからクラウドアセンブリを作成方法を定義す るインタフェースです。 クラウドアセンブリソース：CloudFormationのテンプレートやLambdaソースのア セットなど、synthプロセスで作成されるソース CDK Toolkitには以下のヘルパーメソッドが定義されていて、目的に応じてクラウドア ッセンブリーソースを設定できるようになっています。 fromCdkApp: ts-node app.ts のようなCDKがサポートしている任意の言語で既存 のCDKアプリを操作する場合に利用 fromAssemblyBuilder: synthプロセスをプログラムで制御する場合に利用 fromAssemblyDirectory: synth済みのクラウドアセンブリソースを使用する場合に 利用 16
17. Amplify Gen2の実装: tsxの利用 Amplify Gen2では fromAssemblyBuilder ヘルパーを使い、動的にCloud Assembly を生成 amplify/backend.ts をエントリーポイントとして tsx で読み込む this.cdkToolkit.fromAssemblyBuilder( async () => { // tsx (tsImport)で.amplify/backend.ts をエントリーポイントとして読み込む await tsImport( pathToFileURL(this.backendLocator.locate()).toString(), import.meta.url, ); return new CloudAssembly(this.absoluteCloudAssemblyLocation); }, { contextStore: new MemoryContext(contextParams), outdir: this.absoluteCloudAssemblyLocation, // .amplify/artifacts/cdk.outに出力 }, ); 17
18. 3. エラーハンドリング CDK Toolkit Libraryからスローされるエラーには、発生元（ toolkit or user ）を示す フラグが付与されています。 注意点: instanceof でエラーの型を判定するとバグの元になります。公式が提供 するヘルパー関数 ( isToolkitError ) を使いましょう。 import { isToolkitError } from '@aws-cdk/toolkit-lib'; try { // ... toolkit action } catch (e) { if (isToolkitError(e)) { // Handle toolkit-specific error console.error(`Toolkit error: ${e.message}`); } else { // Handle other errors } } 18
19. まとめ AWS CDK Toolkit Library を使うと、CDKの各種アクションをプログラムから実行 できる。 ユースケースは、カスタムCLIの構築や開発ワークフローへの統合。 Amplify Gen2 は、このライブラリを活用した好例。 IoHost や CloudAssemblySource などのカスタマイズポイントを理解すること で、より高度で柔軟なツールを開発できる。 AWS CDKを利用したツールや開発ワークフローでの利用時にはCDK Toolkit Libraryを検 討してみてください！ 19
20. 参考資料 公式ドキュメント https://docs.aws.amazon.com/ja_jp/cdk/v2/guide/toolkit-library.html npm https://www.npmjs.com/package/@aws-cdk/toolkit-lib AWS Blog Build custom CLIs, deployment automation, and more with the AWS CDK Toolkit Library 20
21. ご清聴ありがとうございました。 21