はじめに
クラウドインフラはCDKで管理する時代だ。という波に乗って、自分が主管のAWSアカウントをCDKに移行して展開しよう！ というモチベーションから始めたのですが、「そもそも何言っているのかわからない」とか「既存リソースのCDK移行に関してドキュメントが少ない」という点でとても苦労してきました。
というわけで、本記事はそんな私と同じ道を歩む方への道しるべとして、２つの内容で構成しております。
- CDKの概念をざっくりと知る
- 既存のリソースをCDKに移行する
注意事項
以下については解説しません
- CDKのコーディング
- ゼロベースでCDKを始める方法
CDKとは何か
CDKを理解するにあたっては、まず登場人物を整理するところから始めましょう。
※前提：CDKは、ローカルのVSCodeで動作するものとします。
単語
- CDKコード
- CDKの本体。Typescript, Pythonなど、様々な言語で記述できる
- テンプレート（ローカル）
- CDKコードを記述し、
cdk synthコマンドを実行すると、コードが変換されて生成される - yamlファイル
-
cdk synthはあくまでローカル上で動作する
- CDKコードを記述し、
- テンプレート（クラウド上）
-
cdk deployコマンドを実行すると、ローカルのテンプレートがPushされる（同時にスタックに反映される） - yamlファイル
- CDKを触る上では、あまり意識しなくていい
-
- スタック
- Cloudformationが管理するリソースのセット
- テンプレートを元に作成される、デプロイ可能な最小単位
- 実態というよりは概念に近い
- AWS実態リソースを直接変更した場合、このスタックには反映されない
- AWS実態リソース
- Lambda, EC2, VPC, IAM, Stepfunctions, etc...
主要コマンド
-
cdk synth- CDKコードを、Cloudformationのテンプレートに変換する
- コードのエラーなどはここで検知される
- あくまでローカル上のみで動作する
-
cdk deploy- CloudformationのテンプレートをAWS上に反映させ、スタックを介して実態リソースを更新する
-
cdk synthコマンドが内包されており、CDKが未変換の場合は変換してからPushされる
-
cdk diff- ローカルのテンプレートと、Cloudformation上のスタック（こうあるだろうと管理されたリソース群）の差異を検出するコマンド
- ローカルで行ったコーディングが、どのような変化をもたらすかを検出できる
- ただし、AWSの実態リソースとスタックの実態が異なっていた場合、それは検出できないので注意
- driftsコマンド
- 正確には
aws cloudformation describe-stack-resource-drifts --stack-name your-stack-nameのようなコマンドで、CDK関連のコマンドではない - AWSの実リソースとスタック間での差異を検出する
- 正確には
基本的なコマンドの順序は、
- cdk synth : コードをテンプレートに変換
- cdk diff : 変換されたテンプレートとスタックの差異を表示
- 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移行に関するものだと書いてあったのですが、正直わかりにくいのでそれぞれ解説します。
cdk import
- AWS上の実態リソースを『スタックに』取り込むコマンド。つまり、CloudFormationの管理下に加えるコマンド。逆に言えば、それだけしかしてくれない
- CloudFormationのテンプレートやCDKコードに変換してくれる機能はない
- 実際にこのコマンドで移行するには、CDKコードで対象リソースをしっかり記述してから、
cdk importでスタックに取り込む必要がある。ロケットのランデブーみたいなイメージ
cdk migrete
- 実際にCDKコードを生成できる
- 主に3つのオプションがある
-
--from-scan：AWSリソースから直接CDK化する。エラーが多すぎてやりたくない -
--from-stack：cdk import した後、ここからCDK化することもできそう -
--from-path：Cloudformationテンプレートから作成する
-
これらのコマンドを組み合わせれば、移行はできます。
ただ、AWSは2023年後半にIaCジェネレータという「実態リソース」⇒「CDK/テンプレート」の変換フローを作ってくれているので、そちらに乗っかるのがよさそうです。
IaCジェネレータとは
概念的には以下のようなイメージです。
手順
- アカウント内の全リソースをスキャン
- スキャンしたリソースのうち、必要なものを選択してテンプレートに変換
- テンプレートをダウンロード
- ダウンロードしたテンプレートファイルを元にして、
cdk migrate --from-pathコマンドでCDKコード化する
以下は実際のコンソール画面でお見せします。
CDKに移行する
- まず最初に、CDK管理させたいリソース（Lambda, Stepfunctions, etc...）にタグ付けします（必須ではないですが、強くおすすめします。尋常じゃなく面倒なことになります）
- マネコンから「Cloudformation -> IaCジェネレータ」を選択します
-
スキャンを開始します。（私はすでにスキャンしているので該当ボタンが「再スキャン」になっています）
-
スキャンが終わったら、「テンプレートを作成」をクリック
-
テンプレート名は任意です。ただ、削除ポリシーは「保持」にすることを強くお勧めします。CDK移行後にあやまってコード削除してDeployしたりローカルのスタックを削除すると、今あるリソースが消えてしまいます
-
テンプレートに取り込むリソースを選択します。このとき、最初に設定したタグで検索して、一括選択してしまいましょう。タグ付けしていないと、最悪数千件のリソースをポチポチ選択したり、エラーでやり直しになったりします
- テンプレートの作成が完了したら、「テンプレートの表示」⇒「該当テンプレートを選択」⇒「アクション」⇒「CDKを表示するコマンド」を選びます
- 指示に従って、テンプレートのダウンロードとCDK化コマンドを実行すれば完了です。私の場合はここでいくつかのエラーが出たので、言われたことをしらみつぶしにエラー対処していきました
- ※cdkをインストールしている必要があるので、まだインストールしていない人は公式サイトを参考に環境整備をしてください
- ここまでできれば、CDKコードがローカルに生成されていることかと思います
-
./bin/配下のファイルに、自分のアカウントIDとリージョンを記述する必要があるのでお忘れなく
テンプレートからスタックを作成する（2024/10/10 追記）
作業中にEIPが二重で作成されてしまったり、「既存のリソースが存在する」と言われうまくいかなかったので、試行錯誤してうまく取り込めるようにしてみました。
実リソースがスタックに取り込まれていないと、CDK Deploy コマンドがリソースを新規作成しようとしてエラーとなるようです。
というわけで、まずは以下画像のようにスタックを更新する必要があります。
CDK側にスタック情報をインポートする（2024/10/10 追記）
この状態だと、CDK側が実リソースを認識していないのかまだうまくいきません。
そこでimportコマンドを使用してスタック情報を取り込みます。
cdk import --force
私の環境では--forceコマンドを使用しなければ上書きできませんでした。
ただこのコマンドはリソースを上書きするようなので、この時点で削除保護が付与されていなかったり、CDKのクリティカルな部分を編集していると問題が発生するかもしれません。
CDKを編集する
不満があるとすれば、変数の命名がとても長いことと、コードが高レベルではなく低レベルレイヤーの関数だということでしょうか？ 高レベル関数ならnew stepfunctions.StateMachineとなるようなのですが、Cfnとついているのは低レベル関数のようです
- というわけで、ここまでできたらあとは自分の思うがままに編集して、AWS上のリソースを更新できます
- 私は手始めに、1ファイルにまとめられていたリソース群と、メインファイルに直接書かれていたStepfunctionsコードを分割しました（古くて今際使われていないっぽい記法もあったのですが、アプローチはこちらのサイトを参考にしました）
- 編集が完了したら、
cdk synthでエラーチェックとテンプレート化を実施します。その後、cdk diffコマンドを実行して、不用意な変更がされていないか確かめました
補足 個別のImportについて（2024/10/10 追記）
さんざんIaCジェネレータの話をしてきましたが、VPCのようにUI上で強力な生成ツールが存在したり、リソースが大量すぎて手動での追加は無理！ という場合は除いて、基本的には個別にImportする方が確実です。
こちらの記事に個別インポートの方法がわかりやすく掲載されていました。
以上で準備完了です！！！
これで現状のAWS実態リソースをCDK管理下に置き、さらにCDKコード化する手順は終わりです。後は、思うがままにCDKライフを楽しんでいきましょう！！
おわりに
CDKを既存リソースの移管前提で触り始めたとき、新しい概念が多く、かつドキュメントも少なく、だいぶ苦労してしまいました。ただまあ私の結論としては、 リソースの全移行はやらないほうがいい ということでしょうか。それが肌感でわかっただけでも、とても収穫が多かったです。
とはいえまだ理解を進めている最中ですので、間違っている箇所がありましたらご指摘いただければ幸いです。
参考文献
スペシャルサンクス
ChatGPT先生
編集履歴
2024/10/10
CDK deploy がうまくいかなかったので、実リソースをスタックへインポートする手順を追加。