GenU閉域モードを深掘りする～バージョンアップ編～

概要

ここまでの記事では、オンプレミスからの名前解決、閉域モードのネットワーク・フロントエンド・認証、バックエンドの処理、そしてデフォルトで無効になっている機能の有効化と、GenUの各機能を深掘りしてきました。

今回は「バージョンアップをどうやるか」といった運用の話です。GenUはOSSのサンプル実装で、更新がかなり速いです。バージョンアップに伴い、新しいユースケースやパラメータが増えていきます。一方で実運用では、自社環境向けにパラメータやコードを手直しした状態で動かすことになります。そのため、「自社変更を保ったまま、アップストリームの更新をどうやって取り込むのか」を考えていく必要があります。

今回は、あえて一つ前のバージョン（v5.4.0）で環境を作り、そこからv5.5.0へアップデートするという作業を通して、アップデート運用の方法を検証します。

全体構成

先に置き場所の全体像を決めておきます。登場するのは3か所だけで、ここのイメージが持てれば、後に出てくるコマンドはすべて「どこからどこへ」の話に落ちます。

① アップストリーム（GitHub / upstream）

GenU本体の開発元です。新しいバージョンはここから受け取ります。こちらから書き込む操作は一切ありません（そもそも権限がない）ので、アップストリームを壊す心配はありません。

各リリースにはv5.4.0のようなタグが付いているので、「どの時点のアップストリームか」をタグで指定できます。この後の手順で何度も出てくるv5.4.0やv5.5.0は、このタグを指しています。

② 自社リポジトリ（origin）

自社設定を含むコードの正式な置き場です。今回はCodeCommitを使いました。ここに「アップストリームの写し（main）」と「自社変更入り（custom）」の2本のブランチを持たせ、デプロイはcustomから行います。この2本の使い分けが今回の仕組みの中心なので、次章で改めて説明します。

VPC IDやドメイン名、オンプレミスのCIDRといった環境固有の情報が入るので、公開されているGitHub側ではなく、自社の閉じた場所に置くことが前提になります。

③ 作業環境（PC）

実際にファイルを編集してnpm ciやcdk deployを実行する場所です。

ここでのポイントは、③がリモート（接続先）を2つ持つことです。

リモート名	接続先	用途
origin	② 自社リポジトリ	読み書きする。正式な置き場・デプロイ元
upstream	① アップストリーム（GitHub）	読むだけ。更新をもらう元

1つのフォルダで「アップストリームから取ってくる」と「自社に保存する」の両方ができます。図の矢印はそれぞれ下記の操作に対応します。

操作	向き	内容
git fetch upstream	① → ③	アップストリームの更新情報を取得する。手元のファイルは変わらない
git push origin	③ → ②	手元の変更を自社リポジトリに保存する
git clone / git pull	② → ③	自社リポジトリの内容を作業環境に展開する

正式な置き場が②にあるので、作業環境が変わってもブランチを切り替えるだけで同じものが再現できます。

ブランチ戦略

ブランチは下記2本を使います。

• main：アップストリームの写し。自分では編集しない
• custom：main + 自社変更。デプロイはここから

「自分で触らないブランチ」を1本用意します。これがあると、mainとcustomの差分＝自社変更の全量、という状態が常に保たれます。

流れは3ステップです。

1. v5.4.0の時点でcustomを切り、自社変更を載せる（mainはv5.4.0で停止）
2. アップストリームのv5.5.0をmainに取り込む（mainだけが前進、customは取り残される）
3. mainをcustomにマージする ← ここがアップデート作業の本体

3で、アップストリームも自社も同じ場所を触っていた場合にコンフリクトになります。逆に言うと、コンフリクトが起きる範囲＝自社変更した箇所だけに限定できます。

フェーズ1：初期構築

1-1. 空のリポジトリを作ってアップストリームを丸ごとコピー

aws codecommit create-repository --repository-name genu-test --region ap-northeast-1

# アップストリームをcloneしてあるディレクトリで
git fetch origin --tags
git push --mirror codecommit::ap-northeast-1://genu-test

CodeCommitの接続設定は完了しているものとします。なお、このディレクトリのoriginはGitHub側を指しているため、git fetch origin --tagsでアップストリームの情報を取得しています。

--mirrorはブランチもタグも全部そのまま複製します。過去のリリースタグが一緒に来ることが重要で、これが後で「バージョンを指す目印」として使えます。

1-2. 作業用に持ってきて、リモートを2つにする

git clone codecommit::ap-northeast-1://genu-test
cd genu-test
git remote add upstream https://github.com/aws-samples/generative-ai-use-cases.git
git remote -v

origin（CodeCommit）とupstream（GitHub）の2つが表示されればOKです。先ほどの図の③が完成しました。

1-3. mainをv5.4.0に固定する

今mainはv5.5.0の先まで進んでいるので、v5.4.0まで巻き戻します。

git checkout main
git reset --hard v5.4.0
git push --force origin main

git describe --tags   # → v5.4.0

フェーズ2：自社変更を載せる

git checkout -b custom

変更はcustomブランチに対して行います。今回入れた変更は2種類です。

変更A：オンプレCIDRからのインバウンド許可

閉域構成のVPCエンドポイントのセキュリティグループに、オンプレミス側CIDRからの443を許可します。ハードコードせず、他のGenUパラメータと同じようにcdk.json / parameter.tsから渡せる形にしました。GenUのパラメータはzodスキーマで型定義されているので、触るファイルは4つです。

// packages/cdk/lib/stack-input.ts
closedNetworkCreateResolverEndpoint: z.boolean().default(true),
onpreVpcCidrBlock: z.string().nullish(),   // ← 追加

// packages/cdk/lib/construct/closedNetwork/closed-vpc.ts
export interface ClosedVpcProps {
  // ...
  readonly onpreVpcCidrBlock?: string | null;   // ← 追加
}

// 値が指定されていればルールを追加する（未指定なら従来動作のまま）
if (props.onpreVpcCidrBlock) {
  securityGroup.addIngressRule(
    ec2.Peer.ipv4(props.onpreVpcCidrBlock),
    ec2.Port.tcp(443),
    'Allow access from on-premises network'
  );
}

WebSocket用のセキュリティグループにも同様に443と8443を追加しています。

変更B：各種パラメータ（parameter.ts）の変更

自社環境向けに、VPC ID・ドメイン名・Cognito設定などparameter.ts内の各パラメータも実環境の値に変更しています。

コミット

git status
git add packages/cdk/parameter.ts packages/cdk/lib/stack-input.ts <以下略>
git commit -m "GenUカスタマイズ 20260812-01"
git push origin custom

フェーズ3：v5.4.0でデプロイして動かす

③作業環境（PC）で実行します。

git checkout custom
npm ci
npm run cdk:deploy

デプロイ後、GenUのコンソールに接続できること、およびVPCエンドポイントのセキュリティグループにオンプレCIDRが登録されていることを確認します。

これでv5.4.0の環境が動いている状態になりました。ここからアップデートを実施していきます。

フェーズ4：v5.5.0へのアップデート

全体の流れは下記になります。

① アップストリームの情報を取ってくる

git fetch upstream --tags

fetchは取ってくるだけで、手元のファイルに変化はありません。

② 差分を先に確認する

自分が変更したファイルについて、アップストリーム側で何が変わったのかをマージする前に確認します。

git diff v5.4.0 v5.5.0 -- packages/cdk/parameter.ts \
  packages/cdk/lib/stack-input.ts \
  packages/cdk/lib/closed-network-stack.ts \
  packages/cdk/lib/construct/closedNetwork/closed-vpc.ts

読み取れたことは主に3点です。

(1) 追加系の変更が中心

stack-input.tsにはResearch Agent関連のパラメータやAgentCoreのVPC設定が追加され、デフォルトモデルIDがClaude 5世代・Opus 4.x系とNova 2系に入れ替わっていました。parameter.tsはgetParams内に6行追加のみ。自社変更とは別の場所なので、コンフリクトの心配は薄いと判断できます。

(2) 自社変更と同じファイルの、近い場所が変わっている

closed-vpc.tsのVPCエンドポイント定義に5行追加されています。

// Cognito VPC Endpoints (Private Link)
CognitoIdp: ec2.InterfaceVpcEndpointAwsService.COGNITO_IDP,
CognitoIdentity: new ec2.InterfaceVpcEndpointAwsService('cognito-identity'),
// S3 Interface Endpoint (for presigned URL access from frontend)
S3: ec2.InterfaceVpcEndpointAwsService.S3,

(3) 構成そのものが変わる変更が含まれている

cognito-private-proxy.ts（255行）がファイルごと削除され、closed-network-stack.tsからCognitoPrivateProxyの呼び出しも消えています。

つまり閉域からCognitoへ届かせる方法が、独自のAPI Gatewayプロキシから、CognitoのVPCエンドポイント（PrivateLink）に置き換わったということです。

③ mainをv5.5.0に進める

git checkout main
git merge v5.5.0
git push origin main

mainは自分では触っていないので、ここは問題なく通ります。

④ customにマージする

git checkout custom
git merge main

結果はこうなりました。

Auto-merging packages/cdk/lib/closed-network-stack.ts
Auto-merging packages/cdk/lib/construct/closedNetwork/closed-vpc.ts
Auto-merging packages/cdk/lib/stack-input.ts
Auto-merging packages/cdk/parameter.ts

コンフリクトは発生せず、4ファイルすべてGitが自動で合成しました。

git commit -m "merge v5.5.0 into custom"
git push origin custom

コンフリクトした場合は、該当ファイルに<<<<<<< HEAD / ======= / >>>>>>> mainの印が入ります。この3行を消して正しい最終形を自分で書き、git addしてgit commitします。

⑤ npm ci の実行

マージ直後にcdk:diffを実行すると下記のようなエラーが発生しました。

TSError: ⨯ Unable to compile TypeScript:
lib/construct/web.ts:14:29 - error TS2307:
  Cannot find module '@cdklabs/deploy-time-build' or its corresponding type declarations.

v5.5.0で新しい依存パッケージが追加されているのに、node_modulesがv5.4.0のままだったためです。

npm ci

バージョンアップ時はpackage.json / package-lock.jsonも更新されるので、マージ後にnpm ciを実行します。

⑥ デプロイ前に実リソースの差分を見る

デプロイ前に、実際に何が変わるのかをcdk diffで確認します。

npm run cdk:diff

[-]が削除されるリソース、[+]が追加されるリソースです。Cognitoプロキシ関連の削除とVPCエンドポイントの追加が見えます。想定外のものが消える表示が出たら、デプロイを止めて調査を行います。

⑦ デプロイ

npm run cdk:deploy

デプロイ後、GenUのコンソールにアクセスできることを確認します。

つまずいた箇所：Cognitoプロキシの削除でデプロイが止まる

②の差分確認で注意点として挙げていた箇所が、そのままデプロイ時の問題になりました。

何が起きたか

v5.5.0ではCognitoプロキシ（API Gateway）が削除されます。ところが、このプロキシの情報はスタックをまたいで受け渡されているため、単純に消せません。

CloudFormationには「他のスタックから参照されているExportは削除できない」というルールがあります。

• ClosedNetworkStack側：v5.5.0のコードにはプロキシがないので、Exportを削除しようとする
• GenerativeAiUseCasesStack側：まだ参照が残っている

この状態でデプロイすると、下記のエラーで止まります。

Cannot delete export ... as it is in use by GenerativeAiUseCasesStack

「参照をやめてから消す」順番にしないと通らない、というのが原因です。

どう対応したか

Export名だけを一時的に残す、2段階のデプロイで抜けました。

段階1ではclosed-network-stack.tsに、削除されるExportと同じ名前のCfnOutputを追加します。値はlist-exportsで調べた現在の値をそのまま書きます。リソースとしてのプロキシは消えますが、Exportという「名札」だけが残るので、CloudFormationのチェックを通過できます。この間に参照元のスタックが更新され、参照が外れます。

段階2でその名札を外します。ここは手作業で消すのではなく、段階1のコミットをgit revertで取り消しました。

git revert --no-edit <段階1のコミットID>
git push origin custom

最後に、Exportが残っていないことを確認して完了です。

aws cloudformation list-exports --query "Exports[?contains(Name,'CognitoPrivateProxy')]"

なお、v5.5.0のコードを確認すると、閉域ネットワークスタックからの値の受け渡し方法自体が見直されています。Fn::ImportValueによるクロススタック参照をやめ、cdk-remote-stackのRemoteOutputs経由で値を渡す形に変わっており、ソース内のコメントにも「Exportの削除でデッドロックしないように」という趣旨の説明が入っています。今回のつまずきは、v5.4.0以前の構成が残っている環境を移行するときに発生するものです。

まとめ

アップデート完了後は下記の状態になります。mainとcustomの差分が、そのまま自社変更の全量になります。

手順	コマンド	目的
①	git fetch upstream --tags	アップストリーム情報の取得
②	git diff <前> <次> -- <変更ファイル>	事前の影響調査
③	git checkout main && git merge <次>	写しの更新
④	git checkout custom && git merge main	自社変更との合成
⑤	npm ci	依存関係の追従
⑥	npm run cdk:diff	実リソース変更の事前確認
⑦	npm run cdk:deploy	反映