これは AWS CDK v2 デベロッパーガイドです。旧版の CDK v1 は 2022 年 6 月 1 日にメンテナンスを開始し、2023 年 6 月 1 日にサポートを終了しました。

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

CDK コードのリファクタリング時にデプロイされたリソースを保持する

AWS Cloud Development Kit (AWS CDK) リファクタリングを使用すると、コンストラクトの名前変更、スタック間のリソースの移動、アプリケーションの再編成など、CDK コードをリファクタリングしながら、デプロイされたリソースを置き換えるのではなく保持できます。この機能は、意図せずにリソースを置き換えることなく、優れたソフトウェアエンジニアリングのベストプラクティスを維持するのに役立ちます。

リソースの保存による CDK リファクタリングとは

CDK アプリケーションをデプロイすると、 AWS CloudFormation はリソースを論理 IDs。 AWS CDK はIDs とそのコンストラクトツリー内のパスに基づいてこれらの論理 ID を生成します。コンストラクトの ID を変更したり、コード内の別の場所に移動したりすると、 AWS CloudFormation は通常これを新しいリソースを作成し、古いリソースを削除するリクエストとして解釈します。データベース、ストレージバケット、キューなどのステートフルリソースの場合、この置換によりサービスの中断やデータ損失が発生する可能性があります。

CDK リファクタリングは、次の方法でこの課題に対処します。

CDK CLI cdk refactor コマンドまたは CDK Toolkit Library の refactorアクションを使用して、CDK リファクタリングを実行できます。このガイドでは主に CLI アプローチについて説明しますが、基本原則は両方の方法に適用されます。Toolkit Library の使用の詳細については、「CDK Toolkit Library を使用してプログラムによるアクションを実行する」を参照してください。

CDK リファクタリングの利点

CDK リファクタリングは AWS 、CDK 開発者に次の利点を提供します。

CDK CLI cdk refactor コマンドの仕組み

まず、最初の CDK アプリケーションをデプロイして AWS 、アカウントにベースラインリソースを確立します。コンストラクトの名前変更やスタック間のリソースの移動など、CDK コードをリファクタリングした後、 cdk refactor コマンドを使用して、デプロイされたリソースのリファクタリングプロセスを開始します。

リファクタリングコマンドを実行すると、CDK CLI は、現在のコードとデプロイされた状態を比較してローカルの変更を検出します。CDK アプリケーションにデプロイされた状態とまったく同じリソースセットが含まれ、コンストラクトツリー内の場所のみが異なっていることを確認します。次に、CDK CLI は、古いリソースロケーションを新しいロケーションにマッピングするリファクタリングプランを生成します。CDK CLI は提案された変更を表示し、確認後、 AWS CloudFormation のリファクタリング API を使用してリソースIDs を置き換えずに更新します。

バックグラウンドでは、CDK CLI はプロパティと依存関係を比較して移動されたリソースを決定し、機能的に同等だがコンストラクトツリー内のパスが異なるリソースを特定します。リソースの追加、削除、または変更が検出されると、リファクタリングオペレーションはエラーメッセージで拒否されます。

CDK コードのリファクタリング時にリソースを保持する例

この例では、CDK CLI cdk refactor コマンドを使用して CDK コードをリファクタリングしながら、デプロイされたリソースを保持します。

サンプル CDK アプリケーションは、S3 バケット、CloudFront ディストリビューション、Lambda 関数を含む 1 つのスタックで構成されます。コンストラクトツリーは次のように構造化されます。

App
└─ MyStack
   ├─ Bucket
   ├─ Distribution
   └─ Function

アプリケーションコードの例を次に示します。

const app = new cdk.App();
const myStack = new cdk.Stack(app, 'MyStack');

const bucket = new s3.Bucket(myStack, 'Bucket');
const distribution = new cloudfront.Distribution(myStack, 'Distribution', {
  defaultBehavior: { origin: new origins.S3Origin(bucket) }
});
const function = new lambda.Function(myStack, 'Function', {
  // function properties
});

// Synthesize the app
app.synth();

次に、このコードをリファクタリングするとします。

リファクタリング後、コンストラクトツリーは次のようになります。

App
├─ WebStack
│  ├─ WebsiteOrigin
│  └─ Distribution
└─ MyStack
   └─ Function

リファクタリングされたコードは次のとおりです。

// Refactored structure
const app = new cdk.App();

// New WebStack with the bucket and distribution
const webStack = new cdk.Stack(app, 'WebStack');
const bucket = new s3.Bucket(webStack, 'WebsiteOrigin');
const distribution = new cloudfront.Distribution(webStack, 'Distribution', {
  defaultBehavior: { origin: new origins.S3Origin(bucket) }
});

// Original MyStack with just the function
const myStack = new cdk.Stack(app, 'MyStack');
const function = new lambda.Function(myStack, 'Function', {
  // function properties
});

// Synthesize the app
app.synth();

CDK リファクタリングを行わないと、論理 IDs が変更されるため、 AWS CloudFormation は新しいリソースを作成し、古いリソースを削除します。

CDK リファクタリングでは、CDK CLI はこれらのパスの変更を検出し、 AWS CloudFormation のリファクタリング機能を使用して基盤となるリソースを維持します。を実行するとcdk refactor、CLI に以下の変更が表示されます。

$ cdk refactor

The following resources were moved or renamed:

┌───────────────────────────────┬───────────────────────────────┬───────────────────────────────────┐
│ Resource Type                 │ Old Construct Path            │ New Construct Path                │
├───────────────────────────────┼───────────────────────────────┼───────────────────────────────────┤
│ AWS::S3::Bucket               │ MyStack/Bucket/Resource       │ WebStack/WebsiteOrigin/Resource   │
├───────────────────────────────┼───────────────────────────────┼───────────────────────────────────┤
│ AWS::CloudFront::Distribution │ MyStack/Distribution/Resource │ WebStack/Distribution/Resource    │
└───────────────────────────────┴───────────────────────────────┴───────────────────────────────────┘

Do you wish refactor these resources (y/n)?

を入力して確認するとy、CDK CLI にリファクタリングオペレーションの進行状況が表示されます。

Refactoring...
✅  Stack refactor complete

確認後、CDK CLI はリファクタリングオペレーションを実行し、両方のリソースを保持しながら、新しいコード構造に合わせて論理 IDs を更新します。

同じマッピングは、スタック別に整理された cdk diff コマンドの出力にも表示されます。

Stack MyStack
Resources
[-] AWS::S3::Bucket Bucket Bucket1234567 destroy (OR move to WebStack.WebsiteOrigin1234567 via refactoring)
[-] AWS::CloudFront::Distribution Distribution Distribution1234567 destroy (OR move to WebStack.Distribution1234567)
...

Stack WebStack
Resources
[+] AWS::S3::Bucket WebsiteOrigin WebsiteOrigin1234567 (OR move from MyStack.Bucket1234567)
[+] AWS::CloudFront::Distribution Distribution Distribution1234567 (OR move from MyStack.Distribution1234567)
...

CDK リファクタリングの使用を開始する

リファクタリングを開始するには、以下の前提条件を満たします。

オーバーライドファイルを使用してリファクタリングのあいまいさを解決する

CDK CLI は、コードとデプロイされたリソースの比較に基づいて、すべてのリソースマッピングを自動的に計算します。ほとんどの場合、この自動検出はうまく機能しますが、CLI が単独で解決できないあいまいさに遭遇することがあります。CDK CLI にガイダンスを提供するには、オーバーライドファイルを使用します。

複数の環境にわたるスタックのリファクタリング

CDK アプリケーションには、異なる環境 (AWS アカウントとリージョン) にデプロイする複数のスタックを含めることができます。このようなアプリケーションでリファクタリング中にリソースを保持する場合、CDK CLI は特定の方法で環境を処理します。

この動作により、リソースは元の AWS アカウントとリージョン内に留まります。これは、CloudFormation リソースをアカウントまたはリージョンの境界を越えて物理的に移動できないために必要です。

たとえば、CDK アプリケーションが開発環境と本番環境の両方のスタックを定義している場合、リファクタリングオペレーションは環境ごとに個別に実行されます。リソースは、開発環境内または本番稼働環境内のスタック間で移動できますが、開発から本番稼働、またはその逆に移動することはできません。

置き換え用に設計されたリソースの処理

一部の CDK コンストラクトは、設計の一環として CloudFormation のリソース置換動作に依存しています。たとえば、API Gateway の Deploymentおよび Lambda の Versionコンストラクトは、プロパティが変更されたときに新しいリソースを作成するように設計されています。

リファクタリングするときは、リソースの置き換えにつながる変更を含めないでください。それ以外の場合、CDK CLI はこれらのリソースを検出して保持することがあります。つまり、置き換えるように設計されたリソースは、リファクタリングオペレーションとは別に処理する必要があります。

置き換えるように設計されたリソースを適切に管理するには：

この 2 ステップのアプローチにより、置き換えられるように設計されたリソースが適切に処理されると同時に、他のリソースの CDK リファクタリングのメリットを享受できます。

一般的な考慮事項と制限事項

CDK リファクタリング中にリソースを保存するときは、以下の考慮事項に留意してください。

CI/CD パイプラインを使用したリファクタリング

CI/CD パイプラインでリファクタリング機能を使用するには、パイプラインの一部として CDK CLI を実行できる必要があります。リファクタリングを CI/CD ワークフローに統合する際の重要な考慮事項を以下に示します。

関連リソース

CDK CLI cdk refactor コマンドのオプションと引数については、「」を参照してください cdk refactor 。

CDK Toolkit Library の refactorアクションを開始するには、「CDK Toolkit Library を使用してプログラムによるアクションを実行する」を参照してください。