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.

ジェネレータの出力

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

• Directorysrc

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

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

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

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という名前のCDKStageをインスタンス化していることに気付くでしょう。このステージは開発とテスト用に設計されています。

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

セキュリティテスト

プロジェクトに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アプリケーションをデプロイする場合、事前にブートストラップが必要です。

まず、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 Developer GuideとAPI Referenceを参照してください。