CDK Migrate: AWS CDK への移行コマンドの発表

本日は、AWS Cloud Development Kit (CDK) の新機能である CDK Migrate についてご紹介します。この機能を使用することで、ユーザーは以前にデプロイされた AWS CloudFormation テンプレートや CloudFormation スタック、Infrastrcture as Code (IaC) の管理外で作成されたリソースを CDK アプリケーションに移行できます。この機能は、CloudFormation の管理外で作成されたリソースをテンプレートにインポートし、新しく生成された CloudFormation スタックに取り込むのに役立つ CloudFormation IaC ジェネレーターと同時に公開されています。IaC ジェネレーターの詳細は、AWS CloudFormation にアプリケーション全体をインポートをご覧ください。

AWS でリソースを作成および管理する方法には、「クリック操作」(マネジメントコンソールでの作成および更新)、AWS API、Infractrcture as Code (IaC) を使用するなどの、さまざまな方法があります。IaC を使用してリソースのライフサイクルを管理することは推奨されるプラクティスですが、導入するためのプロセスが必要かもしれません。IaC の利用に慣れていない担当者は、コンソールを使用してリソースを作成し、更新する可能性が高いでしょう。これは小規模なユースケースや新しいサービスのテストには許容できるかもしれませんが、環境の複雑さが増すにつれて、維持管理はより困難になります。同じ構成を他のアカウント、環境、リージョンに再デプロイする必要がある場合、状況はさらに悪化します。構成を複製しようとすると人的ミスが非常に起こりやすくなります。IaC は、ユーザーが一度定義すればどこでも同じ構成をデプロイできるようにし、この問題を解決します。IaC への移行を遅らせてきた人にとって、IaC ジェネレーターと CDK Migrate を使用して IaC の世界へ飛び込む時が来ました。これらの機能によって移行を加速および簡素化できます。

はじめに

AWS CDK へのリソースの移行の最初のステップは、ユーザーが IaC を利用するのに最適なメカニズムを理解することです。

IaC を宣言的に定義したい (YAML のような設定言語を介してリソースを管理したい) ユーザーの場合、CloudFormation テンプレートを生成したり、CloudFormation スタック内の既存リソースを管理したりできる IaCジェネレーターを検討することをおすすめします。
高級プログラミング言語を介して IaC を管理したり、それらのテンプレートの上に高度な抽象化と自動化を構築したいユーザーの場合、AWS Cloud Development Kit と CDK Migrate が優れたオプションとなります。

CDK CLI には、既存の CDK アプリケーションにリソースをインポートする機能もあります。CDK migrate を使用する場合と CDK import を使用する場合の使用例を確認しましょう。

CDK Migrate

ユーザーは、1 つまたは複数のリソースを新規の CDK アプリケーションに移行したいと考えています。
- 移行対象の AWS リージョン内の既存リソースの例:
  - IaC 管理外で作成されたリソース
  - デプロイ済みの CloudFormation スタック
ユーザーは CloudFormation テンプレートから新規の CDK アプリケーションに移行したいと考えています。
ユーザーは、既存のリソースおよび CloudFormation テンプレートから CDK コードを生成するための一貫した体験を求めています。
CDK Migrate 機能は AWS CDK の利用を加速させることを目的として設計されていますが、制限事項があることを理解することが重要です。制限事項の詳細については、ドキュメントをご確認ください。

CDK Import

ユーザーは、CDK の外で作成された 1 つ以上のリソースをインポートしたい既存の CDK アプリケーションを持っています。
- AWS リージョン内の移行対象となる既存リソースの例:
  - IaC 管理外で (クリック操作によって) 作成されたリソース
  - デプロイ済みの CloudFormation スタック
- ユーザーは独自に CDK アプリ内でリソースを定義する必要があり、CDK コードで定義されたリソースがアカウント内の実際のリソースに直接マッピングされることを確認します。この機能を使用するには複数のステップのプロセスに従う必要があります。詳細はこちらを参照してください。

このブログでは、ローカルの CloudFormation テンプレートを取り込み、新しい CDK アプリケーションに変換する方法の例を紹介します。

利用手順

はじめに、CDK アプリケーションに変換される以下の CloudFormation テンプレートを利用します。このテンプレートは、AWS Lambda 関数、AWS Identity and Access Management (IAM) ロール、Amazon S3 バケットを、動的に値を指定するためのパラメータを使用して作成します。

以下がテンプレート全文です:

AWSTemplateFormatVersion: "2010-09-09"
Description: AWS CDK Migrate Demo Template
Parameters:
  FunctionResponse:
    Description: Response message from the Lambda function
    Type: String
    Default: Hello World
  BucketTag:
    Description: The tag value of the S3 bucket
    Type: String
    Default: ChangeMe
Resources:
  LambdaExecutionRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              Service: lambda.amazonaws.com
            Action: sts:AssumeRole
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
  HelloWorldFunction:
    Type: AWS::Lambda::Function
    Properties:
      Role: !GetAtt LambdaExecutionRole.Arn
      Code:
        ZipFile: |
          import os
          def lambda_handler(event, context):
            function_response = os.getenv('FUNCTION_RESPONSE')
            return {
              "statusCode": 200,
              "body": function_response
            }
      Handler: index.lambda_handler
      Runtime: python3.11
      Environment:
        Variables:
          FUNCTION_RESPONSE: !Ref FunctionResponse
  S3Bucket:
    Type: AWS::S3::Bucket
    Properties:
      PublicAccessBlockConfiguration:
        BlockPublicAcls: true
        BlockPublicPolicy: true
        IgnorePublicAcls: true
        RestrictPublicBuckets: true
      BucketEncryption:
        ServerSideEncryptionConfiguration:
          - ServerSideEncryptionByDefault:
              SSEAlgorithm: AES256
      Tags:
        - Key: Application
          Value: Git-Sync-Demo
        - Key: DynamicTag
          Value: !Ref BucketTag
Outputs:
  S3BucketName:
    Description: The name of the S3 bucket
    Value: !Ref S3Bucket
    Export:
      Name: !Sub ${AWS::StackName}-S3BucketName

これは、migrate コマンドを実行するときに使用するテンプレートです。
このデモは CloudFormation テンプレートを CDK アプリケーションに移行するものですが、以前にデプロイ済みのスタックや IaC で作成されていないリソースも移行できます。

Migrate

CloudFormation テンプレートから CDK への移行は、単一のコマンド cdk migrate で実行できます。
ローカルの CloudFormation テンプレートファイル (ここでは demo-template.yaml とします) を指定するだけで、CLI がテンプレートを CDK アプリケーションに変換します。
このコマンドの出力と結果は、CDK コードと依存関係で構成されるディレクトリになりますが、スタックはデプロイされません。

cdk migrate --stack-name CDK-Local-Template-Migrate-Demo --language typescript --from-path ./demo-template.yaml

CDK Migrate command

上記のコマンドでは、CDK CLI に --from-path パラメータを使用して CloudFormation テンプレートファイルを取り込み、CDK アプリケーションで利用する言語を選択するよう指示しています。CDK CLI はテンプレートを変換するとともに、CDK アプリケーションに必要な依存関係を備えたプロジェクトフォルダを作成します。

移行が完了すると、CDK アプリケーションはプロジェクト構造やファイルとともに使用準備が整いますが、まだデプロイされていません。以下は生成されたファイル構造です:

cdk app directory structure

上記の出力は、デプロイの準備ができた CDK Typescript アプリケーションのディレクトリ構造を表しています。CDK コードは bin と lib の 2 つのディレクトリに格納されています。bin ディレクトリ内には、CDK アプリケーションを作成し、CDK Stack クラスを呼び出すコードがあります。ファイル名は、migrate コマンドの実行時に –stack-name パラメータに渡された入力と一致するので、この場合のファイル名は bin/cdk-local-template-migrate-demo.ts です。以下は生成されたコードです:

CDK App Code

CdkLocalTemplateMigrateDemoStack がインポートされ、インスタンス化されます。これは、既存の CloudFormation テンプレート (またはスタックやリソース) から変換されたコードが存在する場所です。上記のファイル名の付け方と同様に、CDK スタックコードのファイル名と場所は lib/cdk-local-template-migrate-demo-stack.ts です。変換されたコードを見てみましょう。

CDK Stack Code

上記の自動生成されたコードをオリジナルの CloudFormation テンプレートと比較すると、リソースの定義が似ていることがわかります。これは、migrate コマンドが CloudFormation で利用可能なすべてのリソースを表現できる、L1 コンストラクトを使用して CDK コードを生成しているためです。
CDK コンストラクトとコンストラクトが提供するさまざまなレベルの抽象化について詳しくは、このビデオをチェックしてください。

CloudFormation のパラメータは、インターフェイス内に定義されたプロパティに変換され、Stack クラスに渡されます。Stack クラスのコード内では、元の CloudFormation パラメータで設定されたデフォルト値に基づいて、プロパティのデフォルト値が設定されます。それらのデフォルト値を指定した値で上書きしたい場合は、次のようにプロパティを CDK スタックに渡すことができます:

CDK App Code Cleaned Up

新しく作成した CDK アプリケーションで、AWS アカウントにデプロイする準備が整いました。

デプロイ

このアカウントとリージョンで CDK を初めて使用する場合は、cdk bootstrap コマンドを実行してください。このコマンドは、CDK がリージョンとアカウントにリソースを適切にデプロイするために必要なアセットを作成します。
詳細はこちらをご覧ください。ブートストラッププロセスが完了すると、デプロイに進むことができます。

作成された CDK アプリケーションはデプロイの準備ができていますが、デプロイする前に cdk diff を実行してデプロイされる内容を確認することをおすすめします。diff コマンドを実行すると、変更セットが作成され、提案されている変更 (この場合は新規のスタックとリソース) が表示されます。(訳註: 環境によって以下の GIF 画像が表示されない場合があります。cdk diff の実行の様子が示されています。)

Cdk Diff command

出力から、すべての新しいリソースが作成されようとしていることがわかります。cdk diff コマンドが、既存のリソースやスタックに対して実行された場合 (上記のプロパティの更新のように変更がないと仮定します)、diff は既存のリソースへの変更を示しません。

次に、cdk deploy コマンドの実行によりスタックをデプロイします。デプロイが完了したら、AWS コンソールに移動し、Lambda 関数を確認してください。Lambda 関数のテストを実行すると、レスポンスは “CDK Migrate Demo Blog” という functionResponse プロパティの更新内容と一致するはずです。(訳註: body が null となる場合、lib/cdk-local-template-migrate-demo-stack.ts で CfnFunction の environment で functionResponse を FUNCTION_RESPONSE に変更してください。本事象に関連する issue #28997 #29027 が報告されています。) Lambda test execution output

まとめ

この投稿では、CDK migrate コマンドが、CloudFormation テンプレートからであれ、以前にデプロイされた CloudFormation スタックからであれ、CloudFormation IaC ジェネレータ機能を介してリソースをインポートする方法からであれ、リソースを CDK に移行してインフラストラクチャをコードとして管理できるようにするのにどのように役立つかについて説明しました。この機能をテストしてフィードバックや機能リクエストを GitHub のリポジトリにぜひ投稿してください。さらに、CDK のご利用が初めての方のために、スタートアップの際に役立つリソースがいくつかあります。

AWS CDK Immersion Day ワークショップ
CDK Live! (ライブストリームとチュートリアルの YouTube チャンネル)
CDK ベストプラクティスガイド

本記事は、Announcing CDK Migrate: A single command to migrate to the AWS CDK を翻訳したものです。翻訳はソリューションアーキテクトの山崎宏紀が担当しました。

Amazon Web Services ブログ