CDK Infrastructure

AWS CDKは、クラウドインフラストラクチャをコードで定義し、AWS CloudFormationを通じてプロビジョニングするためのフレームワークです。

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

使用方法

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

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

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

VSCode

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

オプション

パラメータ	型	デフォルト	説明
name 必須	string	-	アプリケーションの名前。
directory	string	packages	新しいアプリケーションのディレクトリ。
subDirectory	string	-	プロジェクトが配置されるサブディレクトリ。デフォルトではプロジェクト名になります。
stageConfig	boolean		マルチ環境CDKデプロイメント用の集中ステージ設定（認証情報、アカウント、リージョン）を有効にします。
preferInstallDependencies	boolean	true	ジェネレーター実行後に依存関係のインストールを優先するかどうか。複数のジェネレーターをバッチ処理する際にインストールを延期する場合はfalseに設定します（後続のジェネレーターがNxプロジェクトグラフを計算できるよう、必要に応じてインストールは実行されます）。最後に一度だけインストールします。

ジェネレーターの出力

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

• Directorysrc

  • main.ts Application entry point instantiating CDK stages to deploy
  • Directorystages CDK Stage definitions

    • application-stage.ts Defines a collection of stacks to deploy in a stage
  • Directorystacks CDK Stack definitions

    • application-stack.ts Main application stack
• cdk.json CDK configuration
• package.json Project manifest defining the project’s package name and dependencies
• project.json Project configuration and build targets
• checkov.yml Checkov configuration file

stageConfigオプションを設定すると、ジェネレーターは集中的な認証情報管理のための2つの共有パッケージも作成します（まだ存在しない場合）：

• Directorypackages/common

  • Directoryinfra-config Stage configuration types and credential mappings

    • Directorysrc

      • stages.types.ts Type definitions for stage credentials and config
      • stages.config.ts Your stage-to-credential mappings (edit this)
      • index.ts Re-exports for importing from other packages
  • Directoryscripts Centralized deploy/destroy scripts

    • Directorysrc

      • infra-deploy.ts Deploy bin script
      • infra-destroy.ts Destroy bin script
      • Directorystage-credentials/ Shared logic (credential lookup, CDK command building)

        • …

TypeScriptプロジェクトの機能

インフラストラクチャは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);

    // Declare your infrastructure here
    new Bucket(this, 'MyBucket');
  }
}

ステージとスタック

CDKはStagesを使用して、特定の環境に一緒にデプロイすべきスタックをグループ化します。生成されたsrc/main.tsは、独自の開発とテストのためのサンドボックスステージを作成します：

src/main.ts

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

// Define other instances of stages, such as beta and prod, below

envプロパティは、CDKにどのAWSアカウントとリージョンにデプロイするかを指示します。CDK_DEFAULT_ACCOUNTとCDK_DEFAULT_REGIONは、アクティブなAWS認証情報からCDK CLIによって自動的に解決されます。詳細については、CDK環境のドキュメントを参照してください。

サンドボックスステージは、deploy-sandboxターゲットがデプロイするステージです。

stageConfigを使用して生成した場合、main.tsは環境変数にフォールバックする代わりに、集中管理された設定ファイルからアカウントとリージョンを読み取ります：

src/main.ts (with stageConfig)

import { resolveStage } from '@my-scope/common-infra-config';

// Looks up the stage under this project (packages/infra), falling back to
// shared stages. Returns undefined when no config exists for the stage.
const sandboxConfig = resolveStage('packages/infra', 'my-app-sandbox');

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

異なる環境にデプロイするために、さらにステージを追加できます。例えば、別々のAWSアカウントをターゲットとするbetaとprodステージ：

src/main.ts

new ApplicationStage(app, 'project-beta', {
  env: {
    account: '123456789012',
    region: 'us-west-2',
  },
});
new ApplicationStage(app, 'project-prod', {
  env: {
    account: '098765432109',
    region: 'us-west-2',
  },
});

ステージは1つ以上のスタックをグループ化します。ステージ内に必要なだけスタックを追加できます：

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';

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,
    });
  }
}

ステージ認証情報の設定

ステージ設定

このセクションは、stageConfigを使用して生成した場合に適用されます。これがない場合、ジェネレーターはAWS認証情報を自分で管理する（例：デプロイ前にAWS_PROFILEをエクスポートする）、よりシンプルなセットアップを生成します。

異なるAWSアカウントをターゲットとする複数のステージがある場合、認証情報を手動で管理することはエラーが発生しやすく、特にステージの数が増えるにつれてその傾向が強まります。

stageConfigオプションは、2つの共有パッケージを生成することでこれを解決します：

• packages/common/infra-config — 各ステージをそのAWS認証情報、アカウント、リージョンにマッピングする単一の設定ファイル。これはワークスペース内の任意のパッケージからインポート可能なので、CDKのmain.tsは同じ信頼できる情報源からアカウントとリージョンを読み取ることができます。
• packages/common/scripts — 自動認証情報解決を備えたCDKをラップするinfra-deployとinfra-destroyコマンド。deployを実行すると、スクリプトは設定を読み取り、CDK子プロセスに適切なAWS環境変数を設定し、cdk deployを実行します。シェル環境は変更されません。

認証情報の設定

packages/common/infra-config/src/stages.config.tsを編集して、ステージをAWS認証情報にマッピングします：

packages/common/infra-config/src/stages.config.ts

import type { StagesConfig } from './stages.types.js';

const config: StagesConfig = {
  projects: {
    // The key is the project path relative to the workspace root.
    // This matches the path in project.json and in deploy commands.
    'packages/infra': {
      stages: {
        // Stage names must match the CDK stage identifiers in main.ts
        // (the first argument to `new ApplicationStage(app, 'my-app-dev', ...)`).
        'my-app-dev': {
          credentials: { type: 'profile', profile: 'dev-account' },
          region: 'us-east-1',
        },
        'my-app-prod': {
          credentials: {
            type: 'assumeRole',
            assumeRole: 'arn:aws:iam::123456789012:role/DeployRole',
          },
          region: 'us-west-2',
          account: '123456789012',
        },
      },
    },
  },
  shared: {
    // Shared stages are available to all infra projects.
    // Project-specific entries take priority over shared ones.
    stages: {
      sandbox: {
        credentials: { type: 'profile', profile: 'personal-sandbox' },
        region: 'us-east-1',
      },
    },
  },
};

export default config;

デプロイする際、例えば：

pnpm

pnpm nx deploy infra my-app-dev/*

yarn

yarn nx deploy infra my-app-dev/*

npm

npx nx deploy infra my-app-dev/*

bun

bunx nx deploy infra my-app-dev/*

デプロイスクリプトは：

1. コマンド引数からステージ名my-app-devを抽出します
2. 設定内で認証情報を検索します：最初にprojects['packages/infra']の下、次にsharedの下
3. 見つかった場合、CDK子プロセスのみにAWS_PROFILEを設定します（またはIAMロールを引き受けます）
4. 見つからなかった場合、環境内の既存のAWS認証情報にフォールバックします

これは、設定のない既存のワークフローが引き続き機能することを意味します — スクリプトは一致するエントリを見つけた場合にのみ認証情報を適用します。

認証情報のタイプ

2つの認証情報戦略がサポートされています：

• profile — ~/.aws/configから名前付きAWS CLIプロファイルを使用します。スクリプトはCDKプロセスにAWS_PROFILEを設定します。
• assumeRole — 指定されたロールARNでSTS AssumeRoleを呼び出し、一時的な認証情報をCDKに渡します。オプションで、AssumeRole呼び出しのソース認証情報としてprofile、クロスアカウント信頼ポリシー用のexternalId、および秒単位のsessionDurationを指定できます。

アカウントとリージョン

各ステージ設定には、必須のregionとオプションのaccountが含まれます：

• region（必須） — デプロイ先のAWSリージョン（例：us-east-1、eu-west-2）。
• account（オプション） — AWSアカウントID。省略した場合、CDKはデプロイ時にアクティブな認証情報から推測します。CDKがアカウントとリージョンをどのように解決するかについては、CDK環境のドキュメントを参照してください。

生成されたmain.tsは、CDKの合成とデプロイが同じ環境設定を使用するように、これらの値を設定から読み取ります：

src/main.ts

const sandboxConfig = resolveStage('packages/infra', 'my-app-sandbox');
new ApplicationStage(app, 'my-app-sandbox', {
  env: {
    account: sandboxConfig?.account ?? process.env.CDK_DEFAULT_ACCOUNT,
    region: sandboxConfig?.region ?? process.env.CDK_DEFAULT_REGION,
  },
});

共有ステージとプロジェクト固有のステージ

共有ステージ（shared.stagesの下）は、ワークスペース内の任意のインフラストラクチャプロジェクトに適用されます。これは、複数のプロジェクトが同じサンドボックスアカウントにデプロイする場合に便利です — 各プロジェクトで繰り返す代わりに、認証情報を一度定義します。

プロジェクト固有のステージ（projects['packages/infra'].stagesの下）は、そのプロジェクトにのみ適用されます。同じステージ名に対して両方が存在する場合、プロジェクト固有のエントリが優先されます。

ステージ設定のコミット

チームがステージ認証情報の単一の信頼できる情報源を共有できるように、stages.config.tsをコミットすることをお勧めします。個人のプロファイル名が含まれている場合は、.gitignoreに追加して、代わりにローカルオーバーライドを使用できます。

APIインフラストラクチャ

tRPC APIまたはFastAPIジェネレーターを使用してAPIを作成した場合、それらをデプロイするためのいくつかのコンストラクトがpackages/common/constructsで既に利用可能であることに気付くでしょう。

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

src/stacks/application-stack.ts

import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyApi } from '@my-scope/common-constructs';

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

    // Add infrastructure for your API
    new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

Webサイトインフラストラクチャ

React Websiteジェネレーターを使用した場合、それをデプロイするためのコンストラクトがpackages/common/constructsに既にあることに気付くでしょう。例えば：

src/stacks/application-stack.ts

import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyWebsite } from '@my-scope/common-constructs';

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

    // Add infrastructure for your website
    new MyWebsite(this, 'MyWebsite');
  }
}

CDK Webサイトコンストラクト

CDKでは、Webサイトコンストラクトはスタック内の任意の時点で宣言できます — ランタイム設定は合成時に遅延解決されます。Terraformの場合、Webサイトモジュールがランタイム設定に追加するモジュールに対して適切なdepends_onを持つことを確認してください。

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

buildターゲットの一部として、デフォルトのコンパイル、リント、テストターゲットの実行に加えて、インフラストラクチャプロジェクトはCloudFormationに_合成_されます。これは、synthターゲットを実行することで、スタンドアロンの方法でも実行できます：

pnpm

pnpm nx synth <my-infra>

yarn

yarn nx synth <my-infra>

npm

npx nx synth <my-infra>

bun

bunx nx synth <my-infra>

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

セキュリティテスト

プロジェクトには、Checkovを使用してインフラストラクチャのセキュリティチェックを実行するcheckovターゲットが追加されます。

pnpm

pnpm nx checkov <my-infra>

yarn

yarn nx checkov <my-infra>

npm

npx nx checkov <my-infra>

bun

bunx nx checkov <my-infra>

セキュリティテストの結果は、ルートのdistフォルダー内のdist/packages/<my-infra-project>/checkovにあります。

UV経由のCheckov

Checkovはuvxを使用して実行されるため、まだインストールしていない場合はuvをインストールする必要があります。

抑制されたCheckovルール

一部のCheckovルールは、checkov.ymlファイルを介してデフォルトで抑制されています。ユースケースに基づいてこれらを確認することをお勧めします。

Checkovチェックの抑制

リソースに対して特定のルールを抑制したい場合があります。これは2つの方法で行うことができます：

特定のコンストラクトでルールを抑制する

import { suppressRules } from '@my-scope/common-constructs';

// suppresses the CKV_AWS_XXX for the given construct.
suppressRules(construct, ['CKV_AWS_XXX'], 'Reason');

子孫コンストラクトでルールを抑制する

import { suppressRules } from '@my-scope/common-constructs';

// Supresses the CKV_AWS_XXX for the construct or any of its descendants if it is an instance of Bucket
suppressRules(construct, ['CKV_AWS_XXX'], 'Reason', (construct) => construct instanceof Bucket);

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

初めてAWSアカウントにCDKアプリケーションをデプロイする場合、ブートストラップする必要があります。ブートストラップは、CDKがデプロイを管理するために必要なリソース（アセット用のS3バケット、IAMロールなど）を作成します。

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

次に、デプロイする予定の各アカウントとリージョンに対してブートストラップコマンドを実行します：

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

詳細については、CDKブートストラップのドキュメントを参照してください。

AWSへのデプロイ

プロジェクトには3つのデプロイターゲットがあり、それぞれ異なる状況に適しています：

ターゲット	使用目的
deploy-sandbox	開発中に独自のサンドボックスステージをデプロイする。ステージ引数は不要。
deploy	任意のステージをデプロイする。デプロイしたいステージまたはスタックを指定する。
deploy-ci	CI/CDパイプラインからデプロイする。事前に合成されたクラウドアセンブリを使用する。

まず、AWS認証情報が設定されていることを確認してください。stageConfigを使用して生成し、packages/common/infra-config/src/stages.config.tsでステージ認証情報を設定している場合、デプロイコマンドはターゲットステージの正しい認証情報を自動的に解決して適用します。それ以外の場合は、環境にAWS認証情報が設定されていることを確認してください（例：AWS_PROFILEまたは環境変数経由）。利用可能なオプションについては、AWS認証情報のドキュメントを参照してください。

サンドボックスステージのデプロイ

deploy-sandboxターゲットは、main.tsが宣言するサンドボックスステージをデプロイするため、ステージ名を覚えておく必要はありません：

pnpm

pnpm nx deploy-sandbox <my-infra>

yarn

yarn nx deploy-sandbox <my-infra>

npm

npx nx deploy-sandbox <my-infra>

bun

bunx nx deploy-sandbox <my-infra>

これは、開発中にAWSでアプリケーションの独自のコピーを実行する最も迅速な方法です。

より高速なデプロイのためのExpressモード

デプロイターゲットは、デフォルトで完全なリソースの安定化を待機し、速度よりも一貫性を優先します。開発中の反復を高速化するには、CDKの--expressフラグを渡すことでCloudFormation expressモードを選択します：

pnpm

pnpm nx deploy-sandbox <my-infra> --express

yarn

yarn nx deploy-sandbox <my-infra> --express

npm

npx nx deploy-sandbox <my-infra> --express

bun

bunx nx deploy-sandbox <my-infra> --express

Expressモードは、完全な安定化を待つのではなく、リソース設定が適用されたことが確認されると終了し、伝播はバックグラウンドで継続されるため、反復サイクルが大幅に高速化されます。これは開発と反復を目的としています。

特定のステージのデプロイ

deployターゲットは、指定したステージまたはスタックをデプロイします。サンドボックス以外のステージや、単一のスタックをデプロイする場合に使用します：

pnpm

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

yarn

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

npm

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

bun

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

main.tsで定義されている限り、任意のステージを指定できます。個別のスタックをデプロイするには、完全なスタック名を指定します：

pnpm

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

yarn

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

npm

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

bun

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

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

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

pnpm

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

yarn

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

npm

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

bun

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

このターゲットは、通常のdeployターゲットとは少し異なり、その場で合成するのではなく、事前に合成されたクラウドアセンブリをデプロイします。これにより、パッケージバージョンの変更による潜在的な非決定性を回避し、すべてのパイプラインステージが同じクラウドアセンブリを使用してデプロイすることを保証します。

AWSインフラストラクチャの削除

リソースを削除するには、destroyターゲットを使用します：

pnpm

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

yarn

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

npm

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

bun

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

詳細情報

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