AWS GenU の cdk.json 徹底解説

Posted at 2026-03-27

AWS GenU の cdk.json 徹底解説

はじめに

AWS Generative AI Use Cases（通称 GenU）は、AWS が提供する生成AIアプリケーションのリファレンス実装です。
デプロイには AWS CDK を使用しており、その設定ファイルである cdk.json を理解することが、カスタマイズや運用の第一歩となります。

本記事では、cdk.json の各設定項目を カテゴリ別に分かりやすく解説します。

全体構造

cdk.json は大きく以下の3つのセクションで構成されています。

1. `app` セクション

"app": "npx ts-node --prefer-ts-exts bin/generative-ai-use-cases.ts"

CDK アプリのエントリーポイントを指定します。
ts-node を使って TypeScript ファイルを直接実行しています。

2. `watch` セクション

"watch": {
  "include": ["**"],
  "exclude": [
    "README.md",
    "cdk*.json",
    "**/*.d.ts",
    ...
  ]
}

cdk watch コマンド実行時の監視対象ファイルを制御します。

キー	説明
`include`	監視対象に含めるパターン（`**` = 全ファイル）
`exclude`	監視対象から除外するパターン

3. `context` セクション

GenU の動作をカスタマイズする主要な設定が集まっています。

3-1. 基本設定

"env": "",
"tagKey": null,
"tagValue": null,
"dashboard": false,
"anonymousUsageTracking": true,
"guardrailEnabled": false,
"useCaseBuilderEnabled": true,
"hiddenUseCases": {}

キー	デフォルト値	説明
`env`	`""`	環境名（例: `dev`, `prod`）。複数環境を管理する際に使用
`tagKey` / `tagValue`	`null`	AWSリソースに付与するタグのキーと値
`dashboard`	`false`	CloudWatch ダッシュボードの作成有無
`anonymousUsageTracking`	`true`	匿名の使用状況トラッキングの有効化
`guardrailEnabled`	`false`	Amazon Bedrock Guardrails の有効化
`useCaseBuilderEnabled`	`true`	ユースケースビルダー機能の有効化
`hiddenUseCases`	`{}`	非表示にするユースケースの指定
`crossAccountBedrockRoleArn`	`""`	クロスアカウントで Bedrock を使用する際のロール ARN

3-2. RAG 設定

RAG（Retrieval-Augmented Generation）に関連する設定が2系統あります。

Amazon Kendra を使った RAG

"ragEnabled": false,
"kendraIndexArn": null,
"kendraIndexLanguage": "ja",
"kendraDataSourceBucketName": null,
"kendraIndexScheduleEnabled": false,
"kendraIndexScheduleCreateCron": null,
"kendraIndexScheduleDeleteCron": null

キー	デフォルト値	説明
`ragEnabled`	`false`	Kendra を使った RAG の有効化
`kendraIndexArn`	`null`	既存の Kendra インデックスの ARN（指定しない場合は新規作成）
`kendraIndexLanguage`	`"ja"`	Kendra インデックスの言語設定
`kendraDataSourceBucketName`	`null`	Kendra のデータソースとなる S3 バケット名
`kendraIndexScheduleEnabled`	`false`	インデックスのスケジュール同期の有効化
`kendraIndexScheduleCreateCron`	`null`	インデックス作成のスケジュール（cron形式）
`kendraIndexScheduleDeleteCron`	`null`	インデックス削除のスケジュール（cron形式）

Amazon Bedrock Knowledge Bases を使った RAG

"ragKnowledgeBaseEnabled": false,
"ragKnowledgeBaseId": null,
"ragKnowledgeBaseStandbyReplicas": false,
"ragKnowledgeBaseAdvancedParsing": false,
"ragKnowledgeBaseAdvancedParsingModelId": "anthropic.claude-3-sonnet-20240229-v1:0",
"ragKnowledgeBaseBinaryVector": false,
"embeddingModelId": "amazon.titan-embed-text-v2:0",
"rerankingModelId": null,
"queryDecompositionEnabled": false

キー	デフォルト値	説明
`ragKnowledgeBaseEnabled`	`false`	Bedrock Knowledge Bases を使った RAG の有効化
`ragKnowledgeBaseId`	`null`	既存の Knowledge Base の ID（指定しない場合は新規作成）
`ragKnowledgeBaseStandbyReplicas`	`false`	OpenSearch Serverless のスタンバイレプリカ有効化（コスト増加に注意）
`ragKnowledgeBaseAdvancedParsing`	`false`	高度なドキュメント解析（PDF等の構造化解析）の有効化
`ragKnowledgeBaseAdvancedParsingModelId`	`"anthropic.claude-3-sonnet-..."`	高度解析に使用するモデル ID
`ragKnowledgeBaseBinaryVector`	`false`	バイナリベクトルの使用有無
`embeddingModelId`	`"amazon.titan-embed-text-v2:0"`	埋め込みモデルの ID
`rerankingModelId`	`null`	再ランク付けモデルの ID
`queryDecompositionEnabled`	`false`	クエリ分解の有効化

3-3. 認証設定

"selfSignUpEnabled": true,
"allowedSignUpEmailDomains": null,
"samlAuthEnabled": false,
"samlCognitoDomainName": "",
"samlCognitoFederatedIdentityProviderName": ""

キー	デフォルト値	説明
`selfSignUpEnabled`	`true`	ユーザーの自己サインアップの許可
`allowedSignUpEmailDomains`	`null`	サインアップを許可するメールドメインのリスト（例: `["example.com"]`）
`samlAuthEnabled`	`false`	SAML 認証の有効化
`samlCognitoDomainName`	`""`	SAML 用 Cognito ドメイン名
`samlCognitoFederatedIdentityProviderName`	`""`	SAML フェデレーション ID プロバイダー名

selfSignUpEnabled: false かつ allowedSignUpEmailDomains を指定することで、特定のドメインのみアクセス許可できます。

3-4. モデル設定

"modelRegion": "us-east-1",
"modelIds": [
  "global.anthropic.claude-sonnet-4-6",
  "global.anthropic.claude-sonnet-4-5-20250929-v1:0",
  "global.anthropic.claude-opus-4-6-v1",
  "global.anthropic.claude-opus-4-5-20251101-v1:0",
  "global.anthropic.claude-haiku-4-5-20251001-v1:0",
  "global.amazon.nova-2-lite-v1:0",
  "us.amazon.nova-premier-v1:0",
  "us.amazon.nova-pro-v1:0",
  "us.amazon.nova-lite-v1:0",
  "us.amazon.nova-micro-v1:0",
  "us.deepseek.r1-v1:0"
],
"imageGenerationModelIds": ["amazon.nova-canvas-v1:0"],
"videoGenerationModelIds": ["amazon.nova-reel-v1:0"],
"speechToSpeechModelIds": ["amazon.nova-sonic-v1:0"],
"endpointNames": []

キー	デフォルト値	説明
`modelRegion`	`"us-east-1"`	Bedrock モデルを使用するリージョン
`modelIds`	（複数）	テキスト生成に使用するモデル ID のリスト
`imageGenerationModelIds`	`["amazon.nova-canvas-v1:0"]`	画像生成に使用するモデル ID のリスト
`videoGenerationModelIds`	`["amazon.nova-reel-v1:0"]`	動画生成に使用するモデル ID のリスト
`speechToSpeechModelIds`	`["amazon.nova-sonic-v1:0"]`	音声-音声変換に使用するモデル ID のリスト
`endpointNames`	`[]`	SageMaker エンドポイント名のリスト

モデル ID のプレフィックスについて

global. → グローバル推論プロファイル（複数リージョンを横断）
us. → 米国リージョンの推論プロファイル
プレフィックスなし → 指定リージョンのモデルを直接使用

3-5. エージェント・フロー設定

"agentEnabled": false,
"searchAgentEnabled": false,
"searchEngine": "Brave",
"searchApiKey": "",
"agents": [],
"inlineAgents": false,
"mcpEnabled": false,
"flows": [],
"agentBuilderEnabled": false,
"createGenericAgentCoreRuntime": false,
"agentCoreRegion": null,
"agentCoreExternalRuntimes": [],
"agentCoreGatewayArns": [],
"researchAgentEnabled": false,
"researchAgentBraveApiKey": "",
"researchAgentTavilyApiKey": ""

キー	デフォルト値	説明
`agentEnabled`	`false`	Bedrock Agents 機能の有効化
`searchAgentEnabled`	`false`	Web 検索エージェントの有効化
`searchEngine`	`"Brave"`	検索エンジンの選択（`Brave` / `Tavily`）
`searchApiKey`	`""`	検索エンジンの API キー
`agents`	`[]`	使用する Bedrock Agent の設定リスト
`inlineAgents`	`false`	インラインエージェントの有効化
`mcpEnabled`	`false`	MCP（Model Context Protocol）の有効化
`flows`	`[]`	Bedrock Flows の設定リスト
`agentBuilderEnabled`	`false`	エージェントビルダー機能の有効化
`createGenericAgentCoreRuntime`	`false`	汎用エージェントコアランタイムの作成
`agentCoreRegion`	`null`	エージェントコアを使用するリージョン
`agentCoreExternalRuntimes`	`[]`	外部エージェントコアランタイムのリスト
`agentCoreGatewayArns`	`[]`	エージェントコアゲートウェイの ARN リスト
`researchAgentEnabled`	`false`	リサーチエージェントの有効化
`researchAgentBraveApiKey`	`""`	リサーチエージェント用 Brave API キー
`researchAgentTavilyApiKey`	`""`	リサーチエージェント用 Tavily API キー

3-6. ネットワーク・アクセス制御設定

"allowedIpV4AddressRanges": null,
"allowedIpV6AddressRanges": null,
"allowedCountryCodes": null,
"closedNetworkMode": false,
"closedNetworkVpcIpv4Cidr": "10.0.0.0/16",
"closedNetworkVpcId": null,
"closedNetworkSubnetIds": null,
"closedNetworkCertificateArn": null,
"closedNetworkDomainName": null,
"closedNetworkCreateTestEnvironment": true,
"closedNetworkCreateResolverEndpoint": true

パブリックアクセス制御

キー	デフォルト値	説明
`allowedIpV4AddressRanges`	`null`	アクセスを許可する IPv4 CIDR リスト（例: `["203.0.113.0/24"]`）
`allowedIpV6AddressRanges`	`null`	アクセスを許可する IPv6 CIDR リスト
`allowedCountryCodes`	`null`	アクセスを許可する国コードリスト（例: `["JP", "US"]`）

クローズドネットワーク（VPC 閉域網）設定

キー	デフォルト値	説明
`closedNetworkMode`	`false`	VPC 閉域網モードの有効化
`closedNetworkVpcIpv4Cidr`	`"10.0.0.0/16"`	新規作成 VPC の CIDR ブロック
`closedNetworkVpcId`	`null`	既存 VPC の ID（指定時は既存 VPC を使用）
`closedNetworkSubnetIds`	`null`	使用するサブネット ID のリスト
`closedNetworkCertificateArn`	`null`	閉域網用 ACM 証明書の ARN
`closedNetworkDomainName`	`null`	閉域網で使用するドメイン名
`closedNetworkCreateTestEnvironment`	`true`	テスト環境の作成有無
`closedNetworkCreateResolverEndpoint`	`true`	Route 53 Resolver エンドポイントの作成有無

3-7. ドメイン・カスタムURL設定

"hostName": null,
"domainName": null,
"hostedZoneId": null

キー	デフォルト値	説明
`hostName`	`null`	カスタムホスト名（例: `genai`）
`domainName`	`null`	カスタムドメイン名（例: `example.com`）
`hostedZoneId`	`null`	Route 53 ホストゾーン ID

hostName, domainName, hostedZoneId をすべて設定すると、https://genai.example.com のようなカスタム URL でアクセスできるようになります。

3-8. CDK フィーチャーフラグ設定

context の末尾には多数の CDK フィーチャーフラグが含まれています。これらは CDK の動作を制御するためのフラグで、基本的に変更不要です。

"@aws-cdk/aws-lambda:recognizeLayerVersion": true,
"@aws-cdk/core:checkSecretUsage": true,
"@aws-cdk/core:target-partitions": ["aws", "aws-cn"],
...

代表的なフラグを以下に示します。

フラグ	説明
`@aws-cdk/aws-lambda:recognizeLayerVersion`	Lambda Layer のバージョン認識を改善
`@aws-cdk/core:checkSecretUsage`	Secret の未使用チェック
`@aws-cdk/core:target-partitions`	対象 AWS パーティション（商用・中国）
`@aws-cdk/aws-iam:minimizePolicies`	IAM ポリシーの最小化
`@aws-cdk/aws-ec2:restrictDefaultSecurityGroup`	デフォルト SG のインバウンド/アウトバウンドを制限
`@aws-cdk/customresources:installLatestAwsSdkDefault`	カスタムリソースでの最新 SDK インストール（`false`推奨）

設定フロー全体像

カスタマイズ例

例1: 社内利用（特定ドメインのみ + IP制限）

"selfSignUpEnabled": false,
"allowedSignUpEmailDomains": ["your-company.com"],
"allowedIpV4AddressRanges": ["203.0.113.0/24"],
"dashboard": true

例2: Bedrock Knowledge Bases を使った RAG 環境

"ragKnowledgeBaseEnabled": true,
"embeddingModelId": "amazon.titan-embed-text-v2:0",
"rerankingModelId": "amazon.rerank-v1:0",
"queryDecompositionEnabled": true

例3: カスタムドメインの設定

"hostName": "genai",
"domainName": "your-company.com",
"hostedZoneId": "ZXXXXXXXXXXXXXXXXX"

まとめ

カテゴリ	主な設定項目	ポイント
基本設定	`env`, `dashboard`	環境ごとの識別に活用
RAG設定	`ragEnabled`, `ragKnowledgeBaseEnabled`	Kendra か Knowledge Bases かを選択
認証設定	`selfSignUpEnabled`, `samlAuthEnabled`	セキュリティ要件に応じて設定
モデル設定	`modelRegion`, `modelIds`	使用するモデルと推論プロファイルを指定
エージェント設定	`agentEnabled`, `mcpEnabled`	必要な機能のみ有効化
ネットワーク設定	`allowedIpV4AddressRanges`, `closedNetworkMode`	アクセス制御の方針に応じて設定
CDKフラグ	`@aws-cdk/...`	基本的に変更不要

cdk.json を適切に設定することで、GenU を自組織のセキュリティ要件やユースケースに合わせてカスタマイズできます。まずは RAG設定 と 認証設定 を中心に見直してみましょう！

参考リンク

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up

AWS GenU の cdk.json 徹底解説

AWS GenU の cdk.json 徹底解説

はじめに

全体構造

1. app セクション

2. watch セクション

3. context セクション

3-1. 基本設定

3-2. RAG 設定

Amazon Kendra を使った RAG

Amazon Bedrock Knowledge Bases を使った RAG

3-3. 認証設定

3-4. モデル設定

3-5. エージェント・フロー設定

3-6. ネットワーク・アクセス制御設定

パブリックアクセス制御

クローズドネットワーク（VPC 閉域網）設定

3-7. ドメイン・カスタムURL設定

3-8. CDK フィーチャーフラグ設定

設定フロー全体像

カスタマイズ例

例1: 社内利用（特定ドメインのみ + IP制限）

例2: Bedrock Knowledge Bases を使った RAG 環境

例3: カスタムドメインの設定

まとめ

参考リンク

1. `app` セクション

2. `watch` セクション

3. `context` セクション