源内（genai-web）をAWSにCDKでデプロイする手順とハマりやすい注意点

「手順通りにやったはずなのに、cdk deploy が途中で止まった」

源内（genai-web）のデプロイは、パラメータファイルさえ用意しておけばCDKのコマンド1回で完了します。ただし実際に手を動かすと、公式ドキュメントだけでは分からない準備不足や設定漏れにぶつかることがあります。

この記事では、源内をデプロイする際の手順と、事前準備の不足が原因で起きやすい代表的な注意点をまとめます。

この記事でわかること

• 源内（genai-web）をデプロイする際の全体の流れ
• デプロイ前に確認しておくべき準備事項
• 事前準備の不足で起きやすい2つの注意点と対処法
• デプロイ後に確認すべき動作確認のポイント

前提知識

• 源内PoCの始め方 で事前準備（AWSアカウント・Bedrockモデルアクセス・CDK bootstrap）を先に確認しておいてください
• 源内AIのコードをGitHubから読む で、デプロイによって立ち上がるAWSリソースの全体像を解説しています

デプロイの全体像

genai-webのデプロイは、大きく3段階に分かれます。

実際のデプロイコマンドは、パラメータファイルで指定した環境名を渡す形になります。

npm -w packages/cdk run cdk -- deploy --all --require-approval never -c env=<環境名>

このコマンドを実行すると、CloudFront・S3・API Gateway・Lambda・Cognito・DynamoDBなどのリソースが自動的に構築されます。IP制限・地理的制限を設定した場合はWAF（Web ACL）も追加されます。この記事で扱うのはgenai-web単体のデプロイで、RAG機能を提供する別リポジトリgenai-ai-apiのデプロイは対象外です。リソースの詳しい役割はアーキテクチャ解説記事を参照してください。

全体像を押さえたところで、まず事前準備で確認しておくべきことを整理します。

事前準備で確認しておくべきこと

デプロイ本体に入る前に、以下の4点を確認しておきます。

1. パラメータファイルを用意します。テンプレート（self-hosting-template.ts）をコピーして環境ごとの設定ファイルを作り、appEnv（環境名）や allowedIpV4AddressRanges（IP制限）・modelIds（利用モデル）などの項目を編集します。編集後は parameter.ts の deploy_envs に登録しておきます。この登録作業を忘れると、デプロイコマンドの -c env= で環境を指定できません
2. Bedrockのモデルアクセスが有効化されているかを、利用予定のリージョンで確認します。使用するモデルのアクセスが「Granted」になっているかをBedrockコンソールで確認します
3. CDK bootstrapが必要なリージョンで完了しているかを確認します。WAFを使う予定がある場合、CloudFront用WAFはus-east-1固定でデプロイされる仕様のため、CDKの仕様上、東京リージョン（ap-northeast-1）とus-east-1の両方でbootstrapが必要になります
4. デプロイに使うIAMロール・ユーザーの権限を確認します。CDKデプロイには、CloudFormation・IAM・各種AWSリソースの作成権限が必要です。組織のガードレール（SCP等）で制限されている項目がないか事前に確認しておきます

これらを確認した上で、実際にデプロイを実行します。

デプロイ前に知っておきたい2つの注意点

事前準備の不足に起因する代表的な注意点を2つ紹介します。

Bedrockのモデルアクセス未有効化によるAccessDeniedException

デプロイ自体は成功するものの、実際にチャット機能を使うと AccessDeniedException が返ってくることがあります。

Amazon Bedrockは、IAM権限（bedrock:InvokeModel）とは別に、Bedrockコンソール上でのモデルアクセス許可という2段階のゲートを持っています。どちらか一方が欠けていてもこのエラーになる、というのが原因です。特にAnthropicモデルなど一部のサードパーティモデルは、AWS Marketplaceのサブスクリプションが自動的に開始される仕組みのため、IAMロールにAWS Marketplace関連の権限がないとサブスクリプションが失敗し、以降の呼び出しでもこのエラーが返り続けます。

Bedrockコンソールでモデルアクセスのステータスが「Granted」になっているかを確認しておくと安心です。権限を付与した直後は、サブスクリプションの反映に数分かかることがあるため、すぐに解消しない場合は少し待って再実行してみてください。

CDK bootstrap漏れによるWAFスタックのデプロイ失敗

WAF（IP制限・地理的制限）を有効にする設定でデプロイすると、CloudFront用WAFスタックのデプロイでエラーになることがあります。

CloudFront用のWAF（Web ACL）はus-east-1固定でデプロイされる仕様のため、CDKの仕様上、東京リージョンだけでなくus-east-1でも cdk bootstrap を実行しておく必要があるのが原因です。この手順を見落とすと、デプロイ途中でスタックが止まってしまいます。

デプロイ前に、東京リージョンとus-east-1の両方で cdk bootstrap を実行済みかを確認しておいてください。

この2点を押さえておけば、事前準備段階でつまずくケースの大半は防げます。準備が整ったら、実際にリソースが正しく動作しているかを確認します。

デプロイ後の動作確認

デプロイが完了したら、以下を順に確認します。

• CloudFront経由でポータル画面にアクセスできるか
• Cognitoでユーザーを作成し、ログインができるか
• チャット機能で実際にBedrockのモデルから応答が返ってくるか
• チーム管理機能で、想定する部署・グループ単位の権限分離ができるか

これらが確認できれば、デプロイは完了です。

まとめ

源内（genai-web）のデプロイは、パラメータファイルさえ整えればCDKのコマンド1回で完了しますが、Bedrockのモデルアクセスやbootstrap漏れなど、事前準備の不足が原因でつまずくケースがあります。この記事で紹介した2点はいずれも準備段階で防げるものです。

まずは事前準備の4点（パラメータファイル・モデルアクセス・bootstrap・IAM権限）を確認するところから始めてみてください。なお、genai-webをベースに独自のRAG機能・Guardrailなどを追加していくと、素のデプロイでは出会わない別種のエラーにも遭遇します。そうした拡張時の詰まりポイントは、源内AIシリーズの別記事で扱う予定です。

参考文献

• genai-web デプロイ手順 — パラメータファイルの設定・実際のデプロイコマンド
• Request access to models - Amazon Bedrock — Bedrockのモデルアクセスリクエストの手順
• Resolve the AccessDeniedException error in Amazon Bedrock (AWS re:Post) — AccessDeniedExceptionの原因と解決策
• GitHub: digital-go-jp/genai-web — 源内Web公式リポジトリ
• 源内PoCの始め方——最小構成で2週間・月$10から試す方法 — 事前準備の詳細
• 源内AIのコードをGitHubから読む——genai-webとgenai-ai-apiのAWS構成 — デプロイで立ち上がるAWSリソースの詳細