AWS Cloud Development Kit v2 開発者プレビューのお知らせ

AWS Cloud Development Kit (AWS CDK) v2が開発者プレビューとして、TypeScript、Python、Java、C#、Go言語で利用できるようになりました。AWS CDKは、使い慣れたプログラミング言語を使ってクラウドアプリケーションのリソースをモデル化し、プロビジョニングするためのオープンソースのソフトウェア開発フレームワークです。AWS CDKを使用すると、インフラストラクチャをコードとして定義し、AWS CloudFormationを通じてプロビジョニングすることができます。AWS CDKは、実績のあるデフォルト値で事前に設定された高レベルなコンポーネントを提供しているため、専門家でなくてもクラウドアプリケーションを構築することができます。また、組織の要件を組み込んだ独自のカスタムコンポーネントを構成して共有することができるため、チームが新しいプロジェクトを迅速に開始することができます。

2019年7月には、TypeScriptとPython向けのAWS CDK v1の一般提供を発表しました。それ以降、JavaとC#の追加言語のサポートをリリースし、Go言語バインディングの開発者プレビューをリリースしました。今回はv2のプレビューリリースを発表します。このリリースによりAWS CDKをより簡単に利用できるようになり、また今後のバージョンアップに対応することがより容易になります。

AWS CDK v1アプリケーションの最新マイナーバージョンからv2への移行は、比較的簡単です。まずAWSアカウントで再度ブートストラップ (cdk bootstrap) をする必要がありますが、これは各リージョンで一度だけの作業です。ほとんどのプロジェクトでは、インポート文を更新し、合成(synth) し、デプロイするだけで済みます。リソースに若干の変更があるかもしれませんが、リソースの作り直しが必要になるようなことはありません。

この記事では、AWS CDK v1とv2の間の変更点をご紹介します。

AWS Construct Libraryが一つのパッケージに

AWS CDK v1では、AWS Construct Libraryをサービスごとに多くの小さなパッケージに分割し、使いたいサービスのパッケージをダウンロードするだけで済むように細心の注意を払っていました。

この方法の欠点は、アプリケーションに新しいAWSサービスを追加するたびに、ターミナルに戻って別のパッケージをnpm installまたはpip installしなければならないことでした。さらに、NPMを使用している場合は、これらのパッケージがすべて同じバージョンであることが非常に重要でした。そうでない場合、NPMはいくつかのライブラリの複数のコピーをインストールする可能性があり、それらは適切に相互運用されませんでした。お客様からは、AWS CDKへの依存関係を正しく管理することが難しいというフィードバックをいただきました。

v2からは、AWS Construct Libraryの全てをaws-cdk-libという一つのパッケージに統合しました。このパッケージをインストールすることで、すべてのAWS CDK Constructにアクセスできるようになり、サードパーティのConstruct Libraryも同様にこのパッケージへの依存関係を作るだけで済みます。

また、constructsのプログラミングモデルを、constructsと呼ばれる別のライブラリに抽出しました。これは、相互運用可能なConstructライブラリの大規模なエコシステムの基礎となるもので、すでに cdk8s や terraform-cdk などの姉妹プロジェクトで使用されています。

v2の設計上の選択についての詳細は、GitHubのRFCをご覧ください。

Construct互換レイヤーの移動

AWS CDKのプログラミングモデルの適用範囲をKubernetesなどの他のドメインに広げるための取り組みとして、基本となるConstructクラス (およびいくつかの関連する型) をAWS CDKからconstructsという独立したライブラリに抽出しました。
独自のコンストラクトを定義している場合や、関連するAPIを使用している場合は、constructsライブラリを使用するためにコードを変更する必要があります。
このライブラリを新しい依存関係として宣言した後は、ほとんどの場合、新しいクラスを使用するためにimport文を修正する必要がありますが、ほとんどのクラスやメソッドの名前はそのままなので、簡単に移行できます。
AWS CDKアプリのライフサイクルにフックするなど、AWS CDKの高度な機能を使用している場合は、より多くの変更が必要になります。すべての詳細は、関連するリリースノートに記載されています。

実験的(Experimental)なAPIの新しいライフサイクル

v2では実験的なクラス、メソッド、プロパティの扱い方にも変更を加えています。

v1では実験的ではないコードはすべてセマンティックバージョニングに従っていましたが、APIが実験的であるとマークされている場合には、APIを大幅に改善できると判断した場合は、破壊的変更を可能としていました。これにより、我々がAPIを容易に改良できるという利点がある一方で、お客様はパッケージに「実験的(experimental)」というバナーが表示されていることに気づかず、不意にAPIが変更されたり、安定性と有用性を評価した上でプロダクションにスタックをデプロイすることを選択したりする必要がありました。

AWS CDK v2では、マイナーバージョンのリリースにおいて、APIを意図的に壊すような変更はしません。その代わりに、新しいライフサイクルを導入し、新しい実験的なConstructライブラリは、メインのaws-cdk-libライブラリから完全に独立したライブラリとして、インキュベーション期間を経ます。パッケージは@aws-cdk-experiments/aws-xxxのように実験的な状態であることを明確に示す名前で配布され、リリース前の状態であることを明確に示すためにバージョン番号0.xが付けられます。新しいパッケージが成熟し、いくつかの実世界のシナリオで使用されたあとに、安定したモジュールとしてaws-cdk-libに含められます。

つまり、aws-cdk-libのすべてのメソッド、クラス、プロパティは、次のメジャーバージョンのアップデートまで存在が保証されており、コードに手を入れることなく、いつでも新しいマイナーバージョンにアップデートすることができます。

この移行を行うために検討したいくつかの選択肢についての考え方は、GitHub repoで読むことができます。

開発者プレビューのリリースでは、experimental パッケージのハイレベルなConstruct (L2) がaws-cdk-libから削除されていますが、個別に利用することはまだできません。AWS CloudFormation (L1) クラスは通常通り含まれています。コミュニティとコアチームの両方が実験的なL2 Constructの構築とメンテナンスに取り組んでおり、なるべく早くリリースできるように努力しています。

非推奨(Deprecated)なAPIの削除

CDK v1をリリースして以来、多くのバグや不具合を修正してきました。その一環として、多くのシンボル (クラス、プロパティ、メソッド) を非推奨とし、それらのシンボルに代わるより良いものを提供してきました。

CDK v2のクリーンアップ作業の一環として、これらの非推奨シンボルは完全に削除されました。非推奨なAPIのいずれかをまだ使用している場合は、AWS CDKのアプリケーションとライブラリを更新して、代替バージョンに切り替える必要があります。

AWS CDKはすでに廃止されたAPIを報告するための標準的な言語機能を使用しているので、識別子に取り消し線がついていたり、IDEの警告リストに非推奨(Deprecated) が表示されていたりします。これによりコードを書いているときにAPIの廃止が予定されていることに気づいたかもしれません。それらのAPIを使用していなければ、v2に移行する際には、この点について何もする必要はありません。

しばらくコードを触っていない場合や、Pythonを使っている場合 (IDEにdeprecationのレポートがない) は、cdk synthの操作中に廃止されるAPIの使用について警告するAWS CDK CLIのアップデートを間もなくリリースしますので、アップグレードする前に廃止されるAPIを使用していないことを確認してください。

Feature flagsの新しい動作がデフォルトに

AWS CDK v1では、Feature flagsという概念を導入しました。これにより、互換性のないAWS CDKアプリケーションの動作を変更することなく、AWS CDKにバグフィックスや改良を加えることができるようになりました。一方、既存のAWS CDKアプリケーションは必要に応じてFeature flagsを選択することができます。Feature flagsの完全なリストは、GitHubで文書化されています。

AWS CDK v2では、v2に移行された新規および既存のアプリは、すべてのFeature flagsが有効になっています。ほとんどの機能は、以前の動作に戻すことはできませんが、AWSアプリケーションに中断やダウンタイムを発生させずにv2にアップグレードすることが不可能な場合は、いくつかについて以前の動作に戻すことができるようにしています。AWS CDKアプリケーションをv1からv2に移行する場合は、cdk diffコマンドを実行して、アプリケーションへの影響を確認することをお勧めします。

新しいブートストラップリソースがデフォルトに

複数のAWSアカウントへのAWS CDKアプリケーションの継続的なデプロイのサポートを構築する過程で、私たちはAWS CDKが作成するブートストラップリソースを変更しました。

v1では、新しいブートストラップリソースを作成し、それらを使用することはオプションで、cdk.jsonのFeature flag (@aws-cdk/core:newStyleStackSynthesis)によって有効になっていました。

v2では、新しいブートストラップリソースがデフォルトとなり、これらの新しいリソースを利用するために、スタックテンプレートが少し変更されます。最大の変更点は以下の通りです。

アセットがCloudFormationテンプレートのパラメータを使用しなくなったため、CloudFormationテンプレートの50個のパラメータ制限に縛られることなく、好きなだけアセットを使用できるようになりました。
クロスアカウントによるデプロイがすぐに使えるようになっており、あるAWSアカウントの認証情報を使って(Assume Role)、AWS CDKアプリを別のアカウントにデプロイすることができます (アカウント間に正しい信頼関係が設定されていることが前提です)。
すべてのアセットイメージがプッシュされるAmazon Elastic Container Registry (Amazon ECR)のリポジトリが、ブートストラップリソースに含まれるようになりました

AWS CDK v2で書かれた全てのAWS CDKアプリケーションは、新しいブートストラップリソースが利用可能であることを期待しています。もしまだ前述したFeature flagsにより手動で新しいブートストラップリソースにオプトインしていない場合は、全てのAWSアカウントとリージョンごとにv2 AWS CDK CLIでcdk bootstrapを実行し、一度再ブートストラップする必要があります。

v1からv2への移行

v2にアップグレードしたい既存のAWS CDKアプリケーションがある場合、コードの移行プロセスは以下の通りです。

新しい aws-cdk-lib と constructs ライブラリに依存するように、パッケージの依存関係を更新します。
パッケージマネージャを実行して、新しい依存関係をダウンロードします。
import文を変更します (コアのAWS CDKクラスはすべての言語でルートのAWS CDK名前空間に移動され、Constructは別の名前空間に移動しました)。
cdk.json のコンテキストオブジェクトからすべての機能フラグを削除します。
アプリケーションコードを更新した後、AWS CDK CLI のバージョン2をインストールします。
npm install -g aws-cdk@2.0.0-rc.1
アプリケーション環境のブートストラップを再度行います。
cdk bootstrap

コアクラスを除いて、ほぼ全てのAWS Constructライブラリの名前を同じにしていますので、スタック内のリソースの置き換えに支障をきたすことはないでしょう。以下のセクションでは、各言語での変更点を説明します。

Typescript

TypeScriptで書かれたAWS CDKアプリケーションの場合は、package.jsonファイルを以下のコードのように更新してください (@aws-cdk/assertも新しいバージョンに変更することを忘れずに)

{
    "dependencies": {
        "aws-cdk-lib": "^2.0.0-rc.1",
        "@aws-cdk/assert": "^2.0.0-rc.1",
        "constructs": "^10.0.0"
     }
}

TypeScriptで書かれたConstructライブラリの場合は、package.jsonの内容が若干異なります。アプリケーションに必要なaws-cdk-libの最低バージョン（仮に2.0.0-rc.1とします）を設定して、package.jsonを以下のコードのように更新する必要があります。

{
    "peerDependencies": {
    "aws-cdk-lib": "^2.0.0-rc.1",
    "constructs": "^10.0.0"
  },
   "devDependencies": {
    "aws-cdk-lib": "2.0.0-rc.1",  // <-- note: no ^ to make sure we test against the minimum version
    "@aws-cdk/assert": ^2.0.0-rc1.1",
    "constructs": "^10.0.0",
    "typescript": "~3.9.0"
  }  
}

以下を実行して、新しい依存関係をインストールします。

npm install
# or
yarn install

インポート文を以下のように変更します。

import { Construct }  from 'constructs';
import { App, Stack, aws_s3 as s3 } from 'aws-cdk-lib';

Python

Pythonで書かれたAWS CDKアプリケーションの場合は、setup.pyを以下のように更新してください。

install_requires=[
     "aws-cdk-lib>=2.0.0-rc1.1",
     "constructs>=10.0.0",
    # ...
]

新しい依存関係のインストール

pip install -r requirements.txt

他のバージョンのAWS CDKは、pip uninstallでアンインストールすることを忘れずに。

インポートの変更

import constructs
import aws_cdk as cdk
from aws_cdk import aws_s3 as s3

クラス参照の変更

class MyConstruct(constructs.Construct):
      # ...

class MyStack(cdk.Stack):
      # ...

s3.Bucket(...)

Java

pom.xmlファイルのsoftware.amazon.awscdkの依存関係をすべて削除し、以下のように置き換えます。

<dependency>
        <groupId>software.amazon.awscdk</groupId>
        <artifactId>aws-cdk-lib</artifactId>
        <version>2.0.0-rc.1</version>
</dependency>
<dependency>
       <groupId>software.constructs</groupId>
       <artifactId>constructs</artifactId>
       <version>10.0.0</version>
</dependency>

新しい依存関係のインストール

mvn package

インポートの変更

import software.constructs.Construct;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
import software.amazon.awscdk.App;
import software.amazon.awscdk.services.s3.Bucket;

.NET

.csprojファイルでAmazon.CDK.*の参照をすべて削除し、以下のように置き換えます。

<PackageReference Include="Amazon.CDK.Lib" Version="2.0.0-rc.1" />
<PackageReference Include="Constructs" Version="10.0.0" />

新しい依存関係のインストール

dotnet restore

インポートの変更

using Constructs;
using Amazon.CDK;
using Amazon.CDK.AWS.S3;

cdk.jsonの変更

これらの変更はすべての言語に適用されます。

cdk.json からすべてのFeature flagsを削除します。v1 で作成されたFeature flagsはすべてデフォルトで有効になっているためです。v1 の動作に戻すために、これらのFeature flagsのうち以下の3つだけを無効にすることができます。

アプリケーションが複数のAmazon API Gateway APIキーを使用し、それらを利用プランに関連付ける場合(@aws-cdk/aws-apigatewayモジュールの場合のみ)、@aws-cdk/aws-apigateway:ausentPlanKeyOrderInsensitiveIdを使用します。
アプリケーションが Amazon Relational Database Service (Amazon RDS) の DB インスタンスまたは DB クラスタを使用し、これらの識別子を明示的に指定する場合は、@aws-cdk/aws-rds:lowercaseDbIdentifier を使用します。
アプリケーションが複数のスタックを使用し、あるスタックから他のスタックへリソースを参照する場合は、AWS CloudFormationのエクスポート機能を使用します。@aws-cdk/core:stackRelativeExportsを使用します。

これらのFeature flagsは、以下のコードをcdk.jsonに書くことで無効にすることができます。

{
   "context": {
     "@aws-cdk/aws-rds:lowercaseDbIdentifier": false,
     "@aws-cdk/aws-apigateway:usagePlanKeyOrderInsensitiveId": false,
     "@aws-cdk/core:stackRelativeExports": false,
   }
}

これらのフラグを無効にする必要があるかどうかを確認するには、cdk diffコマンドを使用して、テンプレートの変更を確認します。

合成(synthesize)されたインフラの予期せぬ変化

CDK の変更点を確認するためにcdk diff コマンドを実行すると、テンプレートに予期せぬ変更が生じることがあります。これらの変更は、非推奨の動作が、以前はFeature flagsによって隠されていた機能に置き換えられた結果です。

これらの変更は多くの場合、v2にアップグレードしたことによるものではなく、CDKの古いバージョンからアップグレードしたことによるものです。古いバージョンの 1.x を使用している場合は、まず最新の 1.x にアップグレードし、アプリケーションを合成してデプロイしてから v2 へのアップグレードを行ってください。

もし、v1とv2で合成したインフラの違いが原因でスタックをデプロイできない状況に陥り、それが前のセクションで説明したFeature flagsのいずれにも該当しない場合は、GitHubでお知らせください。

まとめ

AWS CDK v2は大きな設計変更ではありませんが、パッケージのバージョン管理が容易になり、定期的に新しいバージョンのAWS CDKにアップデートできるようになりました。詳細については、v2開発者ガイドとv2 APIリファレンスを参照してください。aws-cdkのGitHubリポジトリでは、バグレポート、機能リクエスト、プルリクエストを受け付けています。

<3 AWS CDK チーム

本記事は、AWS CDKチームによる “Announcing AWS Cloud Development Kit v2 Developer Preview“を翻訳したものです。

翻訳はPrototyping Solution Architect の工藤朋哉が担当しました。

Amazon Web Services ブログ

AWS Cloud Development Kit v2 開発者プレビューのお知らせ

AWS Construct Libraryが一つのパッケージに

Construct互換レイヤーの移動

実験的(Experimental)なAPIの新しいライフサイクル

非推奨(Deprecated)なAPIの削除

Feature flagsの新しい動作がデフォルトに

新しいブートストラップリソースがデフォルトに

v1からv2への移行

Typescript

Python

Java

.NET

cdk.jsonの変更

合成(synthesize)されたインフラの予期せぬ変化

まとめ

お役立ちリンク

フォローお願いいたします