コンテンツにスキップ

パラメータで任意の機能をオンにする

ECS の配備で、既定ではオフの機能をスタックのパラメータでオンにします。プレビュー用のサブドメイン、KMS の保存時の鍵、リモートの MCP、提供ルート、タイマーと外部のエンジン、WAF です。 どのパラメータも、既定のままなら何も足さず、今のスタックは変わりません。

あなたがやること 起きること
30-ingress を、そのパラメータだけを指定してデプロイする 指定したパラメータだけが変わり、ほかは前の値のまま。Control Plane のサービスが入れ替わる
update.sh でリリースを上げる ここのパラメータには触らない。オンにしたものはオンのまま、オフのものはオフのまま
パラメータ スタック オンにするもの
PreviewDomain 30-ingress ワークスペースのサービスを、起動ごとのサブドメインのルートで見せる
CustodianKmsKey / CustodianKmsKeyArn 10-data / 30-ingress Control Plane が保存するシークレットを KMS キーで守る
WorkspaceDekRandom 30-ingress ホームごとに別のキーを持たせる(KMS のときだけ)
McpEnabled / McpOAuth 30-ingress /mcp を公開し、外のクライアントを OAuth でサインインさせる
ProvidedRoutes 30-ingress 配備が費用を持つ Bedrock を、予算の中でメンバーに使わせる(受け入れの確認用)
タイマー・GitHub サインイン・外部のエンジン 30-ingress Control Plane の時間の設定、GitHub でのサインインの追加の設定、LAN や別の配備のエンジン
WafRateLimitPer5Min / WafIpReputation 30-ingress ALB の前に AWS WAF を置く

update.sh が上書きするのは、ImageTag と、ほかのスタックから読む値(EfsBackup・WorkspaceSubnets・EgressProxyAddr・EgressTokenSecretArn・EgressArchiveBucket)だけです。

  • ほかのパラメータは前の値のままです
  • スタックにまだないパラメータは、テンプレートの既定の値になります。新しいパラメータを足したリリースに上げても、何もオンになりません

そのため、ここの機能は 30-ingress を個別にデプロイしてオンにします。

ターミナルウィンドウ
aws cloudformation deploy --stack-name <ingress stack> --template-file cfn/30-ingress.yaml --s3-bucket "$CFN_BUCKET" --s3-prefix cfn \
--capabilities CAPABILITY_NAMED_IAM --parameter-overrides McpEnabled=on McpOAuth=on
  • CFN_BUCKET は 20-platform の出力 CfnTemplatesBucket です(ECS に構築する)
  • --parameter-overrides には、変えたいパラメータだけを書きます
  • 値を空に戻すときは、--parameter-overrides Key= では空になりません。clear-params.sh を使います(パラメータを空に戻す)

プレビュー用のサブドメインを使う

Section titled “プレビュー用のサブドメインを使う”

メンバーがワークスペースで動かすサービスを、起動ごとの URL で見せます。

ターミナルウィンドウ
--parameter-overrides PreviewDomain=pv.example.com ...
  • 起動のたびにランダムなラベルができ、許可したポート(既定は 3000, 8080)が https://{slug}-{port}.pv.example.com/ で届きます
  • ルートで届くので、React・Next.js・Spring Boot の組み合わせのように、サブパスの /preview/{port} では動かないアプリも見せられます
  • 空(既定)なら何も作らず、プレビューはサブパスだけです
パラメータが足すもの 中身
ACM の証明書 *.{PreviewDomain}
ListenerCertificate その証明書を、今の 443 のリスナーに SNI で付ける
Route 53 ワイルドカードのエイリアス 1 つ
Control Plane の環境 プレビュー用のドメイン

今の証明書には触りません。SAN を足すと証明書が作り直されるので、プレビュー用に別の証明書を作ります。 ワークスペースごとに DNS に書くものはありません。1 つのワイルドカードと 1 つの証明書が、すべてのワークスペースとポートに使われるので、URL を発行するたびに API を呼んだり、DNS の反映を待ったりすることもありません。

置き場所 例 PreviewHostedZoneId
Console のゾーンの中 pv.af.example.com 空のまま。DNS の作業はない
Console の兄弟で、Console と同じゾーン pv.example.com(ゾーンが example.com) 空のまま
Console の兄弟で、Console の名前だけが委任されたゾーン pv.example.com(ゾーンが af.example.com) 兄弟のための別のホストゾーンを作り、親から NS で委任して、そのゾーンの ID を渡す
ターミナルウィンドウ
# 兄弟で、委任されたゾーン
--parameter-overrides PreviewDomain=pv.example.com PreviewHostedZoneId=<pv zone id> ...
# Console のゾーンの子。委任は要らない
--parameter-overrides PreviewDomain=pv.af.example.com ...
  • 使うゾーンは、PreviewDomain を含む必要があります。含まないと ACM の DNS 検証が終わらず、スタックは失敗せずに止まったままになります
  • Console の FQDN の子(*.af.example.com)ではなく、兄弟(af.example.com の隣の pv.example.com)にしてください。プレビューのアプリはメンバー自身のコードで、子に置くと、そのアプリが .af.example.com の cookie を書けてしまいます
  • 兄弟でも、登録可能ドメインが同じなら、.example.com の cookie は書けます。完全に分けるには、別の登録ドメインを使います(そのほかの運用上の制御)

どのポートを見せるか、URL を起動をまたいで同じにするか、サインインなしで見せるか(既定はオフで、起動のたびにオフに戻ります)は、メンバーが決めます。

Control Plane が暗号化して保存するシークレットを、AF_MASTER_KEY から導出した鍵ではなく KMS キーで守ります。何が変わり、何に気をつけるかは 保存時のキーを AWS KMS にする にあります。ここではパラメータだけを書きます。

ターミナルウィンドウ
# 10-data: キーを作る(RDS と同じく Persistence に従う)
--parameter-overrides CustodianKmsKey=create ...
# 30-ingress: 10-data の出力 CustodianKmsKeyArn のキーを CP に渡す
--parameter-overrides CustodianKmsKeyArn=arn:aws:kms:<region>:<account>:key/<key-id> ...
  1. 10-data を CustodianKmsKey=create でデプロイします。キーは RDS と同じく Persistence に従います
  2. 10-data の出力 CustodianKmsKeyArn を、30-ingress の CustodianKmsKeyArn に渡します
ターミナルウィンドウ
# 30-ingress。上の CustodianKmsKeyArn と一緒に
--parameter-overrides CustodianKmsKeyArn=arn:aws:kms:<region>:<account>:key/<key-id> WorkspaceDekRandom=on ...
  • CustodianKmsKeyArn なしで WorkspaceDekRandom=on にすると、テンプレートのルールがスタックの操作を失敗させ、ロールバックします。変更セットは作れて、失敗はスタックのイベントに出ます
  • オンにする前に確かめることと、オフに戻したときに起きることは、ホームごとにキーを分ける にあります
  • ワークスペースごとの SSM パラメータ secret-key-next は /af-ws/* の下にあり、Control Plane のロールとワークスペースの実行ロールがすでに読めます

Control Plane のデータベースに対して af-cp を実行する

Section titled “Control Plane のデータベースに対して af-cp を実行する”

af-cp rewrap-keys(KMS に切り替える前の値を暗号化し直す)と af-cp home-dek-status(ホームごとのキーを数える・一覧する・消す)は、Control Plane と同じ環境で動かします。同じ AF_MASTER_KEY・AF_KMS_KEY_ID・データベースの設定・タスクロールが要ります。

ECS では、Control Plane のタスク定義を使い、コマンドだけを差し替えた単発のタスクとして、Control Plane のサブネットとセキュリティグループで動かします。まず --dry-run で実行します。

ターミナルウィンドウ
aws ecs run-task --cluster <cluster> --launch-type FARGATE \
--task-definition <the Control Plane task definition> \
--network-configuration 'awsvpcConfiguration={subnets=[<private subnet>],securityGroups=[<Control Plane security group>]}' \
--overrides '{"containerOverrides":[{"name":"cp","command":["rewrap-keys","--dry-run"]}]}'

出力は Control Plane のロググループに出ます。各コマンドが何をし、いつ実行するかは、保存時のキーを AWS KMS にする と ホームごとにキーを分ける にあります。

ターミナルウィンドウ
# 30-ingress: /mcp を公開し、(任意で)ホスト型の MCP クライアントが OAuth でサインインできるようにする
aws cloudformation deploy --stack-name <ingress stack> --template-file cfn/30-ingress.yaml --s3-bucket "$CFN_BUCKET" --s3-prefix cfn \
--capabilities CAPABILITY_NAMED_IAM --parameter-overrides McpEnabled=on McpOAuth=on
パラメータ 中身
McpEnabled=on /mcp を公開する
McpOAuth=on ホストされた MCP クライアントを OAuth でサインインさせる。McpEnabled=on が要り、ないとテンプレートのルールが操作を失敗させる
McpOAuthTrustedHosts 信頼するクライアントのホストの、予備の一覧(カンマ区切り)。空なら Control Plane の既定

3 つとも既定はオフ(空)です。何を公開し、どのホストを信頼するかは MCP と外部接続のサインインを運用する にあります。

配備が費用を持つ Bedrock を、管理者が決めた予算の中でメンバーに使わせます。受け入れの確認のためのスイッチです。

ターミナルウィンドウ
# 30-ingress: 配備が料金を払う Bedrock(受け入れの確認用だけ)
aws cloudformation deploy --stack-name <ingress stack> --template-file cfn/30-ingress.yaml --s3-bucket "$CFN_BUCKET" --s3-prefix cfn \
--capabilities CAPABILITY_NAMED_IAM --parameter-overrides ProvidedRoutes=on

ProvidedRoutes=on は 4 つのことをします。

すること 中身
Control Plane のスイッチ 提供ルートをオンにする
ルートのロールを作る Bedrock のモデルを呼ぶことだけができ、メンバーのセッションタグを付けた Control Plane のタスクロールだけが引き受けられる
Control Plane に権限を与える タスクロールが、そのロールを引き受けられる
内部の経路を開く エージェントからのモデル呼び出しが通る、Service Connect の af-cp-internal:8098。タイムアウトは 15 分の期限より長く、60 秒の ALB は経由しない

オンにしたら、次のことをします。

  1. スタックの出力 DeploymentRouteRoleArn を、PUT /api/admin/provided-routes/deployment で登録します
  2. テナントに許可を与え、予算を REST で設定します。テナントに上限を付けて許可し、メンバーに予算を設定するまで、誰も使えません
  3. 動いているワークスペースを停止して起動し直します。起動したときの環境のままなので、そのままではルートを使えません

オフなら何も足しません。予算の決めかたと、登録のリクエスト本文は、cfn/PARAMETERS.md の「Provided routes」 にあります。

タイマー・GitHub サインイン・外部のエンジンを設定する

Section titled “タイマー・GitHub サインイン・外部のエンジンを設定する”
ターミナルウィンドウ
aws cloudformation deploy --stack-name <ingress stack> --template-file cfn/30-ingress.yaml --s3-bucket "$CFN_BUCKET" --s3-prefix cfn \
--capabilities CAPABILITY_NAMED_IAM \
--parameter-overrides WsIdleTimeout=4h ComfyUrl=http://10.0.0.5:8188 ComfyApiKey=on

運用のガイドが設定できるとしている Control Plane の変数には、それぞれパラメータがあります。空(既定)なら環境に何も足しません。update.sh も、これらを設定したり消したりしません。

種類 パラメータ
タイマー SessionIdleTimeout・InteractionIdleTimeout・WsIdleTimeout・PresenceIdleTimeout・BackgroundHoldMax・WorkspaceStartDeadline・UsageSampleInterval・AgentSilentStopAfter
GitHub でのサインイン GithubLoginClientId・GithubLabelJa・GithubLabelEn・GithubMembershipTtl・GithubMembershipGrace
外部のエンジン LlmUrl・ComfyUrl・RemoteEngineUrl・RemoteEngineKeys

タイマーの意味と既定の値は アイドル停止と強制停止を使う と 上限と既定値 にあります。

シークレットはスイッチで読む

Section titled “シークレットはスイッチで読む”

3 つのシークレットは、それぞれのスイッチを on にしたときだけ、SSM の SecureString から読みます。先に SSM パラメータを作ってからスイッチをオンにします。存在しないパラメータを指していると、タスクが起動しません。

スイッチ(既定は off) 読む SSM パラメータ
GithubLoginSecret <SsmPrefix>/github-login-client-secret
ComfyApiKey <SsmPrefix>/comfy-api-key
RemoteEngineToken <SsmPrefix>/remote-engine-token
  • SsmPrefix の既定は /af-cp で、実行ロールはすでにこの下を読めます。/af-cp/ と /af-ws/ の外に変えたときは、実行ロールの ssm-read ポリシーをそのプレフィックスに広げます
  • LAN のエンジンには、VPC からの経路(VPN・ピアリング・Transit Gateway)が要ります。スタックは作りません
  • WS_ENV はあえて公開していません。タスク定義に平文でシークレットが入るのを避けるためです

詳細は cfn/PARAMETERS.md の「Control Plane timers, GitHub sign-in extras and LAN / borrowed engines」 にあります。

30-ingress は、ALB の前に AWS WAF の Web ACL を置けます。設定はあえて 2 つだけです。

ターミナルウィンドウ
--parameter-overrides WafRateLimitPer5Min=3000 WafIpReputation=on ...
パラメータ 中身
WafRateLimitPer5Min 1 つの IP から 5 分間に何回のリクエストでブロックするか。0(既定)なら Web ACL を作らない。Console のポーリングも含めて数えるので、1 つの NAT の裏にいるオフィス全体が出す量よりずっと上にする
WafIpReputation AWS が管理する IP の評価リスト。本文ではなく送信元で判定する。WafRateLimitPer5Min が 0 より大きいときだけ使える
  • 上限を 100 にして 150 回のリクエストを送ると、約 45 秒で 403 になりました。上限を上げると、次の評価でその IP のブロックが解除されます
  • IP の評価リストは、オンにして数分で、/.env などを探るスキャナーを止めました

シグネチャのルールは使わない

Section titled “シグネチャのルールは使わない”

Core rule set・SQLi・XSS・LFI のルールは、あえて用意していません。

  • この製品では、チャットのメッセージ、ファイルの書き込み、ターミナルの入力など、ふつうのリクエストの本文にソースコードやシェルのコマンドが入ります。'; DROP TABLE・../../etc/passwd・<script> は正しい通信です
  • これらのルールは、実際の作業をランダムに 403 で拒否します。誰かが WAF を疑うより先に、製品の不具合に見えてしまいます
  • WAF は既定で本文の先頭 8 KB しか見ないので、シグネチャのルールは見た目ほどの効果がありません

閉じた配備では、上流で絞る方が安く確実です。00-network の AlbIngressCidr を自社の範囲にすれば、通信は ALB に届きません。

WAF の費用は、Web ACL が月に約 5 ドル、ルール 1 つにつき月 1 ドル、100 万リクエストにつき 0.60 ドルです。

エージェント向け

この指示をエージェントに送ると、このページを読ませられます。

https://agent-fleet.org/docs/ja/operate/aws-ecs/options/index.md を読んで