Projen と AWS CDK のはじめ方

現代のクラウドコンピューティングにおいて、Infrastrcture as Code (IaC) は、クラウドリソースのデプロイと管理に不可欠な要素となっています。AWS Cloud Development Kit (AWS CDK) は、開発者が馴染みのあるプログラミング言語を使用してクラウドリソースを定義できるようにする、人気のオープンソースフレームワークです。関連するオープンソースツールである Projen は、複雑なソフトウェア設定の管理を簡素化する強力なプロジェクト生成ツールです。この記事では、Projen と AWS CDK を使用するための基本的な使い方について学び、Projen を使用することのメリットや課題について議論します。

Projen とは

高品質でモダンなソフトウェアを構築するには、lint、テスト、リリースの自動化などのタスクを処理するために、たくさんのツールと設定ファイルが必要です。各ツールには、JSON や YAML のような固有の設定インターフェースと構文があり、メンテナンスの複雑さが増します。

新しいプロジェクトを始めるとき、ゼロから始めることはめったになく、しばしばプロジェクト生成ツール (例えば、create-react-app) を使用して新しいプロジェクトを生成します。大量の設定が自動的に作成され、それらのファイルの所有権が付与されます。さらに、プロジェクト生成ツールは多数存在し、毎日のように新しいツールが公開されています。

Projen は、開発者がプロジェクトの設定ファイルを効率的に管理し、高品質なソフトウェアを構築できるよう支援するプロジェクト生成ツールです。コード内でプロジェクト構造と設定を定義できるため、さまざまな環境とプロジェクト間でのメンテナンスと共有が容易になります。

Projen は、AWS CDK コンストラクトライブラリ、React アプリケーション、Java プロジェクト、Python プロジェクトなど、複数のプロジェクトタイプをサポートしています。新しいプロジェクトタイプはコントリビューターによって追加され、プロジェクトは複数のプログラミング言語での開発が可能です。 Projen は、jsii ライブラリを使用しています。これにより、API を一度記述すると、複数のプログラミング言語でライブラリを生成できます。さらに、Projen は projenrc ファイルを通じて、プロジェクト全体の設定を管理する単一のインターフェイスを提供します！

次の図は、Projen を使用した AWS クラウドリソースのデプロイプロセスの概要を示しています:

この例では、Projen を使用して、たとえば新しい CDK TypeScript アプリケーションなどの新しいプロジェクトを生成できます。
開発者は、AWS CDK リソースを使用してインフラストラクチャとアプリケーションコードを定義します。プロジェクト構成を変更するために、開発者は package.json などのファイルを直接編集する代わりに、projenrc ファイルを使用します。
プロジェクトは CloudFormation テンプレートを生成します。
CloudFormation テンプレートは AWS アカウントにデプロイされ、AWS クラウドリソースをプロビジョニングします。

Projen_Diagram
図1 – Projen の提供する機能: Projen はプロジェクトの開始をサポートし、プロジェクトの他の要素を気にする代わりにコーディングに集中できるようにします。lint、ユニットテストとコードカバレッジ、リリースとバージョニング、依存関係管理のための複数のGitHub アクションがすぐに利用できます。

Projen のメリットと課題

メリット

一貫性: Projen を使用することで、標準的なプロジェクトテンプレートを定義できるため、異なるプロジェクト間での一貫性を確保できます。異なるプロジェクト生成ツールを使用する必要がなく、Projen のみを使用できます。
バージョン管理: プロジェクト設定がコードで定義されているため、変更履歴の追跡や他者とのコラボレーションが容易になります。
拡張性: Projen は、さまざまなプラグインと拡張機能をサポートしているため、特定のニーズに合わせてプロジェクト設定をカスタマイズできます。
AWS CDK との統合: Projen は AWS CDK とのシームレスな統合を提供し、クラウドリソースの定義とデプロイプロセスを簡略化します。
多言語対応 CDK コンストラクトライブラリ: 一度のビルドによって、複数のランタイムで実行できます。Projen は、TypeScript で開発された CDK コンストラクトを、JSII のサポートにより Java (Maven) や Python (PyPI) に変換および公開できます。
API ドキュメント: CDK コンストラクトの構築時には、コメントから API ドキュメントを生成します。

課題

Microsoft Windows のサポート。Projen が Windows 環境で完全に動作しないという未解決の issue がいくつかあります (https://github.com/projen/projen/issues/2427 と https://github.com/projen/projen/issues/498)。
フレームワークの Projen は、アーキテクチャ、ベストプラクティス、規約についてのいくつかの前提が存在します。
Projen はまだ GA (General Availability、正式リリース版) ではなく、この記事を書いている時点でのバージョンは v0.77.5 です。

Projen の利用手順

ステップ1: 前提条件の設定

AWS アカウント
Node のダウンロードとインストール
yarn のインストール
AWS CLI : 資格情報の設定
AWS CDK を使用したスタックのデプロイには、専用の Amazon S3 バケットやその他のコンテナが、デプロイ中に AWS CloudFormation で利用できるようにしておく必要があります (詳細情報)。

注: Projen をグローバルにインストールする必要はありません。npx を使用して Projen を実行するので、必要なすべてのセットアップステップが処理されます。npx は、次の npm パッケージを実行するツールです。

ローカルの node_modules フォルダ内に存在する
グローバルにインストールされていない

npx は npm バージョン 5.2+ にバンドルされています

ステップ2: 新しい Projen プロジェクトの作成

次のコマンドを使用して、新しい Projen プロジェクトを作成できます:

mkdir test_project && cd test_project
npx projen new awscdk-app-ts

このコマンドは、AWS CDK サポートが含まれた新しい TypeScript プロジェクトを作成します。サポートされているプロジェクトタイプの完全なリストは、公式ドキュメント Projen.io 、またはプロジェクトタイプを指定せずに npx projen new コマンドを実行することで参照できます。また、npx projen new awscdk-construct を使用して再利用可能なコンストラクトを作成し、それを他のパッケージマネージャに公開することもできます。

作成されたプロジェクト構造は次のようになります:

test_project
| .github/
| .projen/
| src/
| test/
| .eslintrc
| .gitattributes
| .gitignore
| .mergify.yml
| .npmignore
| .projenrc.js
| cdk.json
| LICENSE
| package.json
| README.md
| tsconfig.dev.json
| yarn.lock

Projen は次のものを含む新しいプロジェクトを生成しました:

GitHub のワークフローファイルを使用してプロジェクトをビルドおよびアップグレードできる空の git リポジトリ。リリースワークフローは projen のタスクでカスタマイズできます。
.projenrc.js はプロジェクトの主な設定ファイルです
Visual Studio Code との統合のための tasks.json ファイル
空の CDK スタックを含む src フォルダ
License と README ファイル
package.json には、名前、バージョン、依存関係など、プロジェクトに関する機能的なメタデータが含まれています
git でファイルを管理するための .gitignore、.gitattributes ファイル
JavaScript でのパターンを特定する .eslintrc
パッケージマネージャからファイルを除外するための .npmignore
プルリクエストを管理するための .mergify.yml
コンパイラオプションを設定する tsconfig.json

生成されたファイルのほとんどには、次のような免責事項が含まれています:

# ~~ Generated by projen. To modify, edit .projenrc.js and run "npx projen".

Projen の力は、その単一の設定ファイル .projenrc.js にあります。このファイルを編集することで、プロジェクトの lint ルール、依存関係、.gitignore などを管理できます。 Projen は変更をすべての生成されたファイルに反映させることで、プロジェクト全体の依存関係管理を簡素化および統一します。

Projen によって生成されたファイルは手動で編集することを意図していません。手動で変更を加えた場合、次に npx projen コマンドを実行したときに上書きされます。

プロジェクト設定を編集するには、単純に .projenrc.js を編集し、再生成のために npx projen を実行してください。 Projen API の詳細については、こちらのドキュメントを参照してください: 。

Projen は projenrc.js ファイルの設定を使用して、基本的なメタデータ(プロジェクト名、CDK バージョン、デフォルトのリリースブランチなど)を持つ新しい AwsCdkTypeScriptApp をインスタンス化します。このプロジェクトタイプでは、カスタマイズのために追加の API が利用できます(例: ランタイム依存関係の追加)。

プロパティを変更して、Projen の反応を確認してみましょう。例として、projenrc.js のプロジェクト名を更新します:

name: 'test_project_2',

その後、npx projen コマンドを実行します。

完了したら、プロジェクト名が package.json ファイルで更新されたことがわかります。

ステップ 3: AWS CDK リソースの定義

Projen プロジェクト内で、TypeScript などの開発者が馴染みのあるプログラミング言語を使用して AWS CDK リソースを定義できます。たとえば、Amazon Simple Storage Service(Amazon S3) バケットを定義する例を次に示します:

1. src/ ディレクトリの main.ts ファイルに移動します。
2. ファイルの先頭のインポートを次のように変更します:

import { App, CfnOutput, Stack, StackProps } from 'aws-cdk-lib';
import * as s3 from 'aws-cdk-lib/aws-s3';
import { Construct } from 'constructs';

3. 行 9 の「// define resources here...」を次のコードに置き換えます:

const bucket = new s3.Bucket(this, 'MyBucket', {
  versioned: true,
});

new CfnOutput(this, 'TestBucket', { value: bucket.bucketArn });

ステップ 4: 合成とデプロイ

次に、アプリケーションのブートストラップを実行します。ターミナルで以下を実行してください。

$ npx cdk bootstrap

リソースを定義したら、CloudFormation テンプレート(アプリケーションによっては複数)を含むクラウドアセンブリを合成できます。(訳註: linter の仕様上、 main.ts の25行目でスタック名を test-project-devに変更する必要があります。)

$ npx projen build

npx projen build はいくつかのアクションを実行します。

アプリケーションのビルド
CloudFormation テンプレートの生成
テストとリンターの実行

Projen の synth() メソッドは、Projen によって管理されているすべての設定ファイルの実際の合成(および更新)を実行します。これは、Projen で管理されているすべてのファイルを削除し(ファイルがある場合)、ユーザーが指定した最新の設定に基づいてそれらを再合成することによって実現されます。

利用可能な npx projen コマンドの完全なリストは、.projen/tasks.json で確認できます。また、プロジェクト API project.addTask を使用して、必要なカスタムアクションを実行する新しいタスクを追加することもできます! タスクは、シェルスクリプトでバックアップされたプロジェクトコマンドシステムを定義するプロジェクトレベルの機能です。

CDK アプリケーションのデプロイ

$ npx projen deploy

Projen は、CDK によって生成されたテンプレートに基づいて変更セットを作成し実行することで、設定された AWS アカウントに CloudFormation スタックをデプロイするために cdk deploy コマンドを使用します。上記のステップの出力は次のようになるはずです。

deploy | cdk deploy

✨ Synthesis time: 3.28s

toto-dev: start: Building 387a3a724050aec67aa083b74c69485b08a876f038078ec7ea1018c7131f4605:263905523351-us-east-1
toto-dev: success: Built 387a3a724050aec67aa083b74c69485b08a876f038078ec7ea1018c7131f4605:263905523351-us-east-1
toto-dev: start: Publishing 387a3a724050aec67aa083b74c69485b08a876f038078ec7ea1018c7131f4605:263905523351-us-east-1
toto-dev: success: Published 387a3a724050aec67aa083b74c69485b08a876f038078ec7ea1018c7131f4605:263905523351-us-east-1
toto-dev: deploying... [1/1]
toto-dev: creating CloudFormation changeset...

✅ testproject-dev

✨ Deployment time: 33.48s

Outputs:
testproject-dev.TestBucket = arn:aws:s3:::testproject-dev-mybucketf68f3ff0-1xy2f0vk0ve4r
Stack ARN:
arn:aws:cloudformation:us-east-1:263905523351:stack/testproject-dev/007e7b20-48df-11ee-b38d-0aa3a92c162d

✨ Total time: 36.76s

アプリケーションは、設定された AWS アカウントに正常にデプロイされました。また、作成された S3 バケットの Amazon リソースネーム (ARN) は、CloudFormation のスタックの出力タブから利用でき、ターミナルの「Outputs」セクションに表示されます。

クリーンアップ

CloudFormation スタックの削除

ワークショップのこのセクションで作成したリソースをクリーンアップするには、CloudFormation コンソールに移動し、作成したスタックを削除します。プログラムで同じタスクを実行することもできます。

$ npx projen destroy

次の出力が表示されるはずです。

destroy | cdk destroy
Are you sure you want to delete: testproject-dev (y/n)? y
testproject-dev: destroying... [1/1]

✅ testproject-dev: destroyed

S3 バケットの削除

S3 バケットは保持ポリシーが RETAIN に設定されているため削除されません。S3 コンソールに移動し、作成したバケットを削除してください。そのバケットにファイルを追加した場合は、削除する前に空にする必要があります。詳細は、バケットの削除を参照してください。

おわりに

Projen と AWS CDK は、クラウドリソースとプロジェクト構成を管理するための強力な組み合わせを提供します。Projen を利用することで、プロジェクト間の一貫性、バージョン管理、拡張性を確保できます。AWS CDK との統合により、開発者に馴染みのあるプログラミング言語を使用してクラウドリソースを定義およびデプロイできるため、プロセス全体がより開発者フレンドリーなものになります。

クラウド開発のベテランであれ初心者であれ、Projen と AWS CDK は、クラウドリソース管理の合理化されたアプローチを提供します。Infrastructure as Code のメリットを、柔軟でパワフルなモダン開発ツールとともに体験してみてください。

この記事は、Alain Krok, Dinesh Sajwan, Michael Tran らによる Getting started with Projen and AWS CDK を翻訳したものです。翻訳は Solutions Architect の山崎宏紀が担当しました。

Amazon Web Services ブログ