今日から始めるCDK！ ～既存リソースをCDK移行する～

はじめに

クラウドインフラはCDKで管理する時代だ。という波に乗って、自分が主管のAWSアカウントをCDKに移行して展開しよう！　というモチベーションから始めたのですが、「そもそも何言っているのかわからない」とか「既存リソースのCDK移行に関してドキュメントが少ない」という点でとても苦労してきました。

というわけで、本記事はそんな私と同じ道を歩む方への道しるべとして、２つの内容で構成しております。

1. CDKの概念をざっくりと知る
2. 既存のリソースをCDKに移行する

注意事項

以下については解説しません

• CDKのコーディング
• ゼロベースでCDKを始める方法

CDKとは何か

CDKを理解するにあたっては、まず登場人物を整理するところから始めましょう。
※前提：CDKは、ローカルのVSCodeで動作するものとします。

単語

1. CDKコード
   • CDKの本体。Typescript, Pythonなど、様々な言語で記述できる
2. テンプレート（ローカル）
   • CDKコードを記述し、cdk synthコマンドを実行すると、コードが変換されて生成される
   • yamlファイル
   • cdk synthはあくまでローカル上で動作する
3. テンプレート（クラウド上）
   • cdk deploy コマンドを実行すると、ローカルのテンプレートがPushされる（同時にスタックに反映される）
   • yamlファイル
   • CDKを触る上では、あまり意識しなくていい
4. スタック
   • Cloudformationが管理するリソースのセット
   • テンプレートを元に作成される、デプロイ可能な最小単位
   • 実態というよりは概念に近い
   • AWS実態リソースを直接変更した場合、このスタックには反映されない
5. AWS実態リソース
   • Lambda, EC2, VPC, IAM, Stepfunctions, etc...

主要コマンド

1. cdk synth
   • CDKコードを、Cloudformationのテンプレートに変換する
   • コードのエラーなどはここで検知される
   • あくまでローカル上のみで動作する
2. cdk deploy
   • CloudformationのテンプレートをAWS上に反映させ、スタックを介して実態リソースを更新する
   • cdk synthコマンドが内包されており、CDKが未変換の場合は変換してからPushされる
3. cdk diff
   • ローカルのテンプレートと、Cloudformation上のスタック（こうあるだろうと管理されたリソース群）の差異を検出するコマンド
   • ローカルで行ったコーディングが、どのような変化をもたらすかを検出できる
   • ただし、AWSの実態リソースとスタックの実態が異なっていた場合、それは検出できないので注意
4. driftsコマンド
   • 正確にはaws cloudformation describe-stack-resource-drifts --stack-name your-stack-name のようなコマンドで、CDK関連のコマンドではない
   • AWSの実リソースとスタック間での差異を検出する

基本的なコマンドの順序は、

1. cdk synth : コードをテンプレートに変換
2. cdk diff : 変換されたテンプレートとスタックの差異を表示
3. cdk deploy : テンプレートをスタックに反映

という風になります。
マネコンで編集した実態コードを上書きしたくない場合は、最初にDriftsコマンドを使うといいかと思います。

つまりCDKとは何か？

ここまでの図を見ていただければわかるかと思いますが、実態はCloudformationのテンプレートであり、CDKはテンプレートを生成するためのものです。
もともと存在していたテンプレートのYamlファイルを様々な言語でラップして、管理性や再利用性を向上させたというわけです。

既存のリソースをCDKに移行するには？

さて、基本的な登場人物を理解したところで、次は既存のリソースをCDKに取り込むにはどうすればいいかについて解説します。
まず最初に言わなければならないのは、簡単ではないということです。エラーが多々発生し、一定程度のCDKやコーディングの知識が必要なのに加え、生成されるコードが人間Likeにできない場合もあるので、最小限必要な部分（DBやS3など、データが入っていたり、運用中のリソース）以外はゼロベースで作った方が良い気がしています。

本記事では解説しませんが、ゼロからCDKを作成する方法はAWSの公式記事から始めるとよさそうです。（AWSの日本語ページより、英語ページをChromeで翻訳したほうがわかりやすいです）

こちらはコーディングの例が載っている公式Githubです。

CDK移行に関するコマンド

とはいえ、「ゼロベースで作るなんて面倒くさい！」もしくは「このリソースは作り直したくない！」というものがある場合は、実態リソースからCDKへの移行を試したいですよね。
どんな方法があるのかとググってみると、cdk import, cdk migrateコマンドがどうやらCDK移行に関するものだと書いてあったのですが、正直わかりにくいのでそれぞれ解説します。

1. cdk import

• AWS上の実態リソースを『スタックに』取り込むコマンド。つまり、CloudFormationの管理下に加えるコマンド。逆に言えば、それだけしかしてくれない
• CloudFormationのテンプレートやCDKコードに変換してくれる機能はない
• 実際にこのコマンドで移行するには、CDKコードで対象リソースをしっかり記述してから、cdk import でスタックに取り込む必要がある。ロケットのランデブーみたいなイメージ

1. cdk migrete

• 実際にCDKコードを生成できる
• 主に3つのオプションがある
  1. --from-scan：AWSリソースから直接CDK化する。エラーが多すぎてやりたくない
  2. --from-stack：cdk import した後、ここからCDK化することもできそう
  3. --from-path：Cloudformationテンプレートから作成する

これらのコマンドを組み合わせれば、移行はできます。
ただ、AWSは2023年後半にIaCジェネレータという「実態リソース」⇒「CDK/テンプレート」の変換フローを作ってくれているので、そちらに乗っかるのがよさそうです。

IaCジェネレータとは

概念的には以下のようなイメージです。

手順

1. アカウント内の全リソースをスキャン
2. スキャンしたリソースのうち、必要なものを選択してテンプレートに変換
3. テンプレートをダウンロード
4. ダウンロードしたテンプレートファイルを元にして、cdk migrate --from-pathコマンドでCDKコード化する

以下は実際のコンソール画面でお見せします。

CDKに移行する

• まず最初に、CDK管理させたいリソース（Lambda, Stepfunctions, etc...）にタグ付けします（必須ではないですが、強くおすすめします。尋常じゃなく面倒なことになります）

• マネコンから「Cloudformation -> IaCジェネレータ」を選択します

• スキャンを開始します。（私はすでにスキャンしているので該当ボタンが「再スキャン」になっています）

• スキャンが終わったら、「テンプレートを作成」をクリック

• テンプレート名は任意です。ただ、削除ポリシーは「保持」にすることを強くお勧めします。CDK移行後にあやまってコード削除してDeployしたりローカルのスタックを削除すると、今あるリソースが消えてしまいます

• テンプレートに取り込むリソースを選択します。このとき、最初に設定したタグで検索して、一括選択してしまいましょう。タグ付けしていないと、最悪数千件のリソースをポチポチ選択したり、エラーでやり直しになったりします

• テンプレートの作成が完了したら、「テンプレートの表示」⇒「該当テンプレートを選択」⇒「アクション」⇒「CDKを表示するコマンド」を選びます

• 指示に従って、テンプレートのダウンロードとCDK化コマンドを実行すれば完了です。私の場合はここでいくつかのエラーが出たので、言われたことをしらみつぶしにエラー対処していきました
• ※cdkをインストールしている必要があるので、まだインストールしていない人は公式サイトを参考に環境整備をしてください

• ここまでできれば、CDKコードがローカルに生成されていることかと思います
• ./bin/配下のファイルに、自分のアカウントIDとリージョンを記述する必要があるのでお忘れなく

CDKを編集する

不満があるとすれば、変数の命名がとても長いことと、コードが高レベルではなく低レベルレイヤーの関数だということでしょうか？　高レベル関数ならnew stepfunctions.StateMachineとなるようなのですが、Cfnとついているのは低レベル関数のようです

• というわけで、ここまでできたらあとは自分の思うがままに編集して、AWS上のリソースを更新できます
• 私は手始めに、1ファイルにまとめられていたリソース群と、メインファイルに直接書かれていたStepfunctionsコードを分割しました（古くて今際使われていないっぽい記法もあったのですが、アプローチはこちらのサイトを参考にしました）

• 編集が完了したら、cdk synthでエラーチェックとテンプレート化を実施します。その後、cdk diffコマンドを実行して、不用意な変更がされていないか確かめました

以上で準備完了です！！！
これで現状のAWS実態リソースをCDK管理下に置き、さらにCDKコード化する手順は終わりです。後は、思うがままにCDKライフを楽しんでいきましょう！！

おわりに

CDKを既存リソースの移管前提で触り始めたとき、新しい概念が多く、かつドキュメントも少なく、だいぶ苦労してしまいました。ただまあ私の結論としては、 リソースの全移行はやらないほうがいい ということでしょうか。それが肌感でわかっただけでも、とても収穫が多かったです。

とはいえまだ理解を進めている最中ですので、間違っている箇所がありましたらご指摘いただければ幸いです。

参考文献

スペシャルサンクス
　ChatGPT先生