CDKインフラストラクチャ

AWS CDKはAWS CloudFormationを通じてクラウドインフラストラクチャをコードで定義するフレームワークです。

TypeScriptインフラストラクチャジェネレータは、TypeScriptで記述されたAWS CDKインフラストラクチャアプリケーションを作成します。生成されたアプリケーションにはCFN Guardチェックによるセキュリティベストプラクティスが含まれています。

使用方法

インフラストラクチャプロジェクトの生成

新しいインフラストラクチャプロジェクトは2つの方法で生成できます：

VSCode

1. インストール Nx Console VSCode Plugin まだインストールしていない場合
2. VSCodeでNxコンソールを開く
3. クリック Generate (UI) "Common Nx Commands"セクションで
4. 検索 @aws/nx-plugin - ts#infra
5. 必須パラメータを入力
6. クリック Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#infra

yarn

yarn nx g @aws/nx-plugin:ts#infra

npm

npx nx g @aws/nx-plugin:ts#infra

bun

bunx nx g @aws/nx-plugin:ts#infra

変更されるファイルを確認するためにドライランを実行することもできます

pnpm

pnpm nx g @aws/nx-plugin:ts#infra --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#infra --dry-run

npm

npx nx g @aws/nx-plugin:ts#infra --dry-run

bun

bunx nx g @aws/nx-plugin:ts#infra --dry-run

オプション

パラメータ	型	デフォルト	説明
name 必須	string	-	The name of the application.
ruleSet	string	aws_prototyping	Rule set to validate your AWS resources with.
directory	string	packages	The directory of the new application.

ジェネレータの出力

ジェネレータは<directory>/<name>ディレクトリに以下のプロジェクト構造を作成します：

• Directorysrc

  • main.ts デプロイするCDKステージをインスタンス化するアプリケーションエントリポイント
  • Directorystages CDKステージ定義

    • application-stage.ts ステージでデプロイするスタックの集合を定義
  • Directorystacks CDKスタック定義

    • application-stack.ts メインアプリケーションスタック
• cdk.json CDK設定ファイル
• project.json プロジェクト設定とビルドターゲット

Tip

インフラストラクチャはTypeScriptプロジェクトです。一般的な使用方法についてはTypeScriptプロジェクトドキュメントを参照してください。

CDKインフラストラクチャの実装

src/stacks/application-stack.ts内でCDKインフラストラクチャの記述を開始できます。例：

src/stacks/application-stack.ts

import { Stack, StackProps } from 'aws-cdk-lib';
import { Bucket } from 'aws-cdk-lib/aws-s3'
import { Construct } from 'constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    // インフラストラクチャをここに記述
    new Bucket(this, 'MyBucket');
  }
}

ステージとスタック

トップレベルのsrc/main.tsファイルが<namespace>-sandboxという名前のCDKステージをインスタンス化していることに気付くでしょう。このステージは開発とテスト用に設計されています。

src/main.ts

new ApplicationStage(app, 'project-sandbox', {
  env: {
    account: process.env.CDK_DEFAULT_ACCOUNT,
    region: process.env.CDK_DEFAULT_REGION,
  },
});

betaやprodステージを追加して別々の環境にデプロイすることも可能です：

src/main.ts

new ApplicationStage(app, 'project-beta', {
  env: {
    account: '123456789012', // betaアカウント
    region: 'us-west-2',
  },
});
new ApplicationStage(app, 'project-prod', {
  env: {
    account: '098765432109', // prodアカウント
    region: 'us-west-2',
  },
});

ステージはアプリケーションを構成するスタックの集合を定義します。ステージ内で任意の数のスタックをインスタンス化できます：

src/stages/application-stage.ts

import { Stage, StageProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { BackendStack } from '../stacks/backend-stack.js';
import { FrontendStack } from '../stacks/frontend-stack.js';

/**
 * アプリケーションを構成するCDKスタックの集合を定義
 */
export class ApplicationStage extends Stage {
  constructor(scope: Construct, id: string, props?: StageProps) {
    super(scope, id, props);

    new BackendStack(this, 'Backend', {
      crossRegionReferences: true,
    })

    new FrontendStack(this, 'Frontend', {
      crossRegionReferences: true,
    });
  }
}

APIインフラストラクチャ

tRPC APIまたはFastAPIジェネレータを使用してAPIを作成した場合、packages/common/constructsにデプロイ用のコンストラクトが既に存在します。

例えばmy-apiというtRPC APIを作成した場合、コンストラクトをインポートしてインスタンス化するだけで必要なインフラストラクチャを追加できます：

src/stacks/application-stack.ts

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyApi } from ':my-scope/common-constructs';

export class ApplicationStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // APIのインフラストラクチャを追加
    new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

ウェブサイトインフラストラクチャ

CloudScapeウェブサイトジェネレータを使用した場合、packages/common/constructsにデプロイ用のコンストラクトが存在します。例：

src/stacks/application-stack.ts

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyWebsite } from ':my-scope/common-constructs';

export class ApplicationStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // ウェブサイトのインフラストラクチャを追加
    new MyWebsite(this, 'MyWebsite');
  }
}

ウェブサイトのランタイム設定にすべてのAPI設定を含めるためには、APIコンストラクトの後にウェブサイトを宣言することが重要です。

インフラストラクチャの合成

buildターゲットの一部として、デフォルトのコンパイル、リンター、テストターゲットに加え、インフラストラクチャプロジェクトをCloudFormationに合成します。synthターゲットを実行することで単独でも実行可能です：

pnpm

pnpm nx run <my-infra>:synth

yarn

yarn nx run <my-infra>:synth

npm

npx nx run <my-infra>:synth

bun

bunx nx run <my-infra>:synth

合成されたクラウドアセンブリはルートdistフォルダのdist/packages/<my-infra-project>/cdk.outに配置されます。

AWSアカウントのブートストラップ

初めてAWSアカウントにCDKアプリケーションをデプロイする場合、事前にブートストラップが必要です。

まず、AWSアカウントの認証情報を設定してください。

次にcdk bootstrapコマンドを使用します：

npx cdk bootstrap aws://<account-id>/<region>

詳細はCDKドキュメントを参照してください。

AWSへのデプロイ

ビルド後、deployターゲットを使用してインフラストラクチャをAWSにデプロイできます。

Caution

CI/CDパイプラインでのデプロイにはdeploy-ciターゲットを使用してください。詳細は後述します。

まず、AWSアカウントの認証情報を設定してください。

次にデプロイターゲットを実行します：

pnpm

pnpm nx run <my-infra>:deploy <my-infra>-sandbox/*

yarn

yarn nx run <my-infra>:deploy <my-infra>-sandbox/*

npm

npx nx run <my-infra>:deploy <my-infra>-sandbox/*

bun

bunx nx run <my-infra>:deploy <my-infra>-sandbox/*

Tip

上記コマンドは<my-infra>-sandboxステージの全スタックをデプロイします。main.tsで定義されていれば他のステージも指定可能です。

完全なスタック名を指定することで個別のスタックをデプロイすることもできます：

pnpm

pnpm nx run <my-infra>:deploy <my-infra>-sandbox/Application

yarn

yarn nx run <my-infra>:deploy <my-infra>-sandbox/Application

npm

npx nx run <my-infra>:deploy <my-infra>-sandbox/Application

bun

bunx nx run <my-infra>:deploy <my-infra>-sandbox/Application

CI/CDパイプラインでのAWSデプロイ

CI/CDパイプラインでAWSにデプロイする場合はdeploy-ciターゲットを使用します。

pnpm

pnpm nx run <my-infra>:deploy-ci my-stage/*

yarn

yarn nx run <my-infra>:deploy-ci my-stage/*

npm

npx nx run <my-infra>:deploy-ci my-stage/*

bun

bunx nx run <my-infra>:deploy-ci my-stage/*

このターゲットは通常のdeployターゲットと異なり、事前合成済みのクラウドアセンブリを使用します。これによりパッケージバージョンの変更による非決定性の問題を回避し、すべてのパイプラインステージで同一のクラウドアセンブリを使用してデプロイできます。

AWSリソースの削除

destroyターゲットを使用してリソースを削除します：

pnpm

pnpm nx run <my-infra>:destroy <my-infra>-sandbox/*

yarn

yarn nx run <my-infra>:destroy <my-infra>-sandbox/*

npm

npx nx run <my-infra>:destroy <my-infra>-sandbox/*

bun

bunx nx run <my-infra>:destroy <my-infra>-sandbox/*

詳細情報

CDKの詳細についてはCDK開発者ガイドとAPIリファレンスを参照してください。