✍️ CDK Pipeline で self-mutation 時の CLI バージョンを固定する方法と落とし穴

AWS CDK Pipeline を使ってインフラを継続的デプロイする中で、self-mutation ステップで意図しない CDK CLI バージョンが使用される問題に直面しました（バージョンアップに追随していないのが根本的な問題なのですが・・・）。この記事では、問題の原因とその対処方法をまとめます。

---

発生した問題

CDK Pipeline の selfMutation を有効にしていたところ、以下のような問題が発生：

• synth ステップでは npm install -g aws-cdk@2.139.0 を指定していたにもかかわらず、
• self-mutation ステップで再び npm install -g aws-cdk@2 が実行されてしまい、CLI のバージョンが最新に書き換えられてしまう

その結果：

• aws-cdk-lib と cdk CLI のバージョンにズレが発生
• cdk deploy 時にバージョン不整合によるエラーが発生

---

よくある誤解

初期対応として CodeBuildStep に以下のように指定しても、

installCommands: [
  'npm install -g aws-cdk@2.139.0',
  'npm ci',
],

この設定は synth ステップにしか効かず、self-mutation ステップには影響しない。

---

解決策：cliVersion の使用

CDK Pipelines では、CodePipeline のコンストラクタに cliVersion オプションを指定することで、self-mutation ステップで使用される CLI バージョンを固定できます。

new pipelines.CodePipeline(this, 'Pipeline', {
  cliVersion: '2.139.0', // ✅ これで自己変異ステップの CLI バージョンを固定
  synth: new pipelines.CodeBuildStep('Synth', {
    input: pipelines.CodePipelineSource.gitHub('your-org/your-repo', 'main'),
    installCommands: [
      'npm install -g aws-cdk@2.139.0',
      'npm ci',
    ],
    commands: ['npx cdk synth'],
  }),
});

これにより、self-mutation ステップで npm install -g aws-cdk@2 ではなく、明示的に @2.139.0 が使われるようになります。

---

まとめ

• CDK Pipeline の self-mutation ステップは内部的に npm install -g aws-cdk@2 を実行する
• これにより CLI バージョンが最新に上書きされ、バージョン不整合の原因になる
• cliVersion を CodePipeline に指定することで self-mutation ステップの CLI バージョンを固定できる

本件のように CDK Pipeline の内部動作を知っておくことで、思わぬ不具合を防ぐことができます。