CDKインフラストラクチャ

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

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

使用方法

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

新しいインフラストラクチャプロジェクトは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.
directory	string	packages	The directory of the new application.
enableStageConfig	boolean		Enable centralized stage configuration (credentials, account, region) for multi-environment CDK deployments.

ジェネレータの出力

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

• Directorysrc

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

    • application-stage.ts ステージでデプロイするスタックのコレクションを定義
  • Directorystacks CDKスタック定義

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

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

• Directorypackages/common

  • Directoryinfra-config ステージ設定タイプと認証情報マッピング

    • Directorysrc

      • stages.types.ts ステージ認証情報と設定の型定義
      • stages.config.ts ステージと認証情報のマッピング（編集してください）
      • index.ts 他のパッケージからインポートするための再エクスポート
  • Directoryscripts 集中デプロイ/削除スクリプト

    • Directorysrc

      • infra-deploy.ts デプロイbinスクリプト
      • infra-destroy.ts 削除binスクリプト
      • Directorystage-credentials/ 共有ロジック（認証情報検索、CDKコマンド構築）

        • …

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

ステージとスタック

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

src/main.ts

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

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

enableStageConfigで生成した場合、main.tsは集中設定ファイルからアカウントとリージョンを読み取り、設定がない場合は環境変数にフォールバックします:

src/main.ts (enableStageConfigの場合)

import stagesConfig from ':my-scope/common-infra-config';

const projectStages = stagesConfig.projects?.['packages/infra']?.stages ?? {};
const sandboxConfig = projectStages['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,
    });
  }
}

ステージ認証情報の設定

Note

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

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

enableStageConfigオプションは、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: {
    // キーはワークスペースルートからの相対プロジェクトパスです。
    // これはproject.jsonのパスとデプロイコマンドのパスと一致します。
    'packages/infra': {
      stages: {
        // ステージ名はmain.tsのCDKステージ識別子と一致する必要があります
        // (`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: {
    // 共有ステージはすべてのインフラプロジェクトで利用可能です。
    // プロジェクト固有のエントリが共有エントリより優先されます。
    stages: {
      sandbox: {
        credentials: { type: 'profile', profile: 'personal-sandbox' },
        region: 'us-east-1',
      },
    },
  },
};

export default config;

例えば、デプロイする場合:

pnpm

pnpm nx run infra:deploy my-app-dev/*

yarn

yarn nx run infra:deploy my-app-dev/*

npm

npx nx run infra:deploy my-app-dev/*

bun

bunx nx run infra:deploy 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 = projectStages['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の下）はワークスペース内の任意のインフラプロジェクトに適用されます。これは、複数のプロジェクトが同じsandboxアカウントにデプロイする場合に便利です — 各プロジェクトで繰り返す代わりに、認証情報を一度定義します。

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

Tip

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

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に配置されます。

セキュリティテスト

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

pnpm

pnpm nx run <my-infra>:checkov

yarn

yarn nx run <my-infra>:checkov

npm

npx nx run <my-infra>:checkov

bun

bunx nx run <my-infra>:checkov

セキュリティテスト結果はルートdistフォルダのdist/packages/<my-infra-project>/checkovに配置されます。

Note

Checkovはuvxを使用して実行されるため、事前にuvをインストールする必要があります。

Caution

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

Checkovチェックの抑制

特定のルールをリソースで抑制したい場合、2つの方法があります:

コンストラクトに対するルールの抑制

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

// 指定したコンストラクトのCKV_AWS_XXXを抑制
suppressRules(construct, ['CKV_AWS_XXX'], '理由');

子コンストラクトに対するルールの抑制

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

// Bucketインスタンスの場合、コンストラクトまたはその子孫のCKV_AWS_XXXを抑制
suppressRules(construct, ['CKV_AWS_XXX'], '理由', (construct) => construct instanceof Bucket);

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

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

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

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

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

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

AWSへのデプロイ

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

Caution

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

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