https://makky12.hatenablog.com/entry/2025/07/28/120500

今回のお話

前回の記事で、AWS CDK Toolkit Libraryに関する基本的な使い方を紹介しました。

そこで今回はその続きとして、AWS CDK Toolkit Libraryに関する設定、特に「CDK CLIで行っていたあの機能、AWS CDK Toolkit Libraryではどうやるの？」ということを紹介しようと思います。

なお、AWS CDK Toolkit LibraryのAWS公式サイトはこちら。 aws.amazon.com

※今回紹介予定だったエラーハンドリングについては、諸事情で次回以降に紹介します。

アジェンダ

deploy/destoryするスタックを指定するには？
cdk.out（クラウドアセンブリ≒CloudFormationテンプレート）ファイルを出力するには？
コンテキスト情報を読み込むには？
プロファイルを指定するには？

deploy/destoryするスタックを指定するには？

CDK Toolkit Libraryでdeploy や destroy するスタックを指定するには、各メソッドの第2引数の「stacks」に StackSelector を指定してあげればOKです。

具体的にはこんな感じです。

// toolkitやcloudAssemblyはすでに定義済みの前提。以下同じ
import { Toolkit, StackSelectionStrategy } from '@aws-cdk/toolkit-lib';  
  
await toolkit.deploy(cloudAssembly, {
  stacks: {
    strategy: StackSelectionStrategy.PATTERN_MUST_MATCH,
    patterns: [stackName],
    failOnEmpty: true  // デフォルトtrueだから本来は不要
   },
});

StackSelector各プロパティの説明は以下の通りです。

プロパティ	説明	初期値	備考
strategy	スタックを検索するパターン	なし	入力必須
patterns	strategyがMATCH系の値だった場合に、検索するパターンを指定	なし	パターン配列形式で複数指定可能。またワイルドカードによる指定も可能
failOnEmpty	検索条件に一致するスタックがなかった場合、エラーをthrowするかどうか	true	falseの場合エラーなしで終了する。個人的にはtrueでいいと思う

なお、strategy に指定する値は以下の通りです。（StackSelectionStrategy というenumが用意されています。下記では「StackSelectionStrategy」は省略）

値	説明	備考
ALL_STACKS	全スタックを対象とする
MAIN_ASSEMBLY	現在扱っているクラウドアセンブリのメインのスタック（最上位のスタック）を対象とする
ONLY_SINGLE	現在扱っているクラウドアセンブリにスタックが一つしかない場合、そのスタックを対象とする	スタックがない、または複数ある場合はエラーとなる
PATTERN_MATCH	patternsに記載したパターンに一致するすべてのスタックを対象とする	MATCH系。patternの指定が必須
PATTERN_MUST_MATCH	patternsに記載したパターンに最も一致するスタックを対象とする	MATCH系。patternの指定が必須。一致するスタックがない場合はエラーとなる。もっとも一致するスタックが複数ある場合はそれらがすべて対象となる
PATTERN_MUST_MATCH_SINGLE	patternsに記載したパターンに最も一致する1つのスタックのみを対象とする	MATCH系。patternの指定が必須。スタックがない、または複数ある場合はエラーとなる

cdk.out（クラウド アセンブリ ≒ CloudFormationテンプレート）ファイルを出力するには？

CDK CLIでは、cdk synth や cdk deploy を行った際「cdk.out」というクラウドアセンブリファイル（≒CloudFormationテンプレートファイル）が出力されました。

しかしCDK Toolkit Libraryの場合、クラウドアセンブリを fromAssemblyBuilder や fromAssemblyDirectory で作成した場合、これが出力されません。（fromCdkApp で作成した場合は出力されます）

この「cdk.out」ファイルを必ず出力させる方法ですが、fromAssemblyBuilder の第2引数の「outdir」プロパティにcdk.outファイルのパスを指定することで出力可能です。*1

const assembly = await toolkit.fromAssemblyBuilder(async () => {
  const app = new App();
  new HogeStack(app, 'HogeStack');
  return app.synth();
}, {
  // こんな感じ
  outdir: path.resolve(__dirname, './cdk.out'),
});

コンテキスト情報を読み込むには？

CDK CLIでは「cdk.json」ファイルにcontext（CDK内部でユーザー定義定数として扱えるキー＆値）を設定することで、CDKのデプロイ時などにその値を反映させることができました。

しかし先ほどの「cdk.out」ファイル同様、CDK Toolkit Libraryの場合、クラウドアセンブリを fromAssemblyBuilder や fromAssemblyDirectory で作成した場合、これが読み込みされません。（これも fromCdkApp で作成した場合は読み込みされます）

この「cdk.json」を必ず読み込みさせる方法ですが、fromAssemblyBuilder の第2引数の「contextStore」プロパティに CdkAppMultiContext クラスのクラスインスタンスを設定することで可能です。

const assembly = await toolkit.fromAssemblyBuilder(async () => {
  const app = new App();
  new HogeStack(app, 'HogeStack');
  return app.synth();
}, {
  // こんな感じ。
  // cdk.jsonファイルのディレクトリパスを指定する点に注意
  contextStore: new CdkAppMultiContext(path.resolve(__dirname, '.')),
});

また既存のcontext値を上書きしたり、cdk,jsonにない新規のcontext値を設定したい場合、以下の方法で可能です。

CdkAppMultiContext クラスコンストラクタの第2引数 commandlineContext にキー＆値を設定する。
CdkAppMultiContext クラスの update メソッドにキー＆値を設定する。

// コンストラクタで上書き
const assembly = await toolkit.fromAssemblyBuilder(async () => {
  const app = new App();
  new HogeStack(app, 'HogeStack');
  return app.synth();
}, {
  contextStore: new CdkAppMultiContext(path.resolve(__dirname, '.'), {
    environment: 'stg';
  }),
});
  
// updateメソッドで上書き
const ctxStore = new CdkAppMultiContext(path.resolve(__dirname, '.'));
ctsStore.update({
  environment: 'prod';
});
  
const assembly = await toolkit.fromAssemblyBuilder(async () => {
  const app = new App();
  new HogeStack(app, 'HogeStack');
  return app.synth();
}, {
  contextStore: ctxStore,
});

なおCDK Toolkit Libraryでのcdk.outやcdk.jsonなどの挙動についての詳細は、AWS Heroの後藤さんがブログにまとめていますので、詳しく知りたい方はそちらもご参照ください。
CDK Toolkit Library と CDK CLI の違い - 365歩のテック

プロファイルを指定するには？

CDK CLIでは、各種コマンド実行時に --profile オプションでAWS CLIのプロファイル情報を指定することが可能でした。

CDK Toolkit Libraryで実行時にプロファイルを指定するには、前回紹介したように Toolkit コンストラクタ引数の sdkConfig.baseCredentials に下記のように値を設定することで可能です。

なお、AWS公式サイトでは sdkConfig に直接 {profile: 'xxx'} を指定してますが、実際にはこの方法では設定できません（エラーになる）

import { Toolkit, BaseCredentials } from '@aws-cdk/toolkit-lib';
  
// AWS公式サイトでは下記コードが書いてあるが、これだと動かない
const toolkit = new Toolkit({
  sdkConfig: { profile: "xxxxx" },
});
  
// 正しいコードはこちら。
const toolkit = new Toolkit({
  sdkConfig: { 
    baseCredentials: BaseCredentials.awsCliCompatible({ profile: 'xxxxx' }), 
  },
});