パラメータで任意の機能をオンにする
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 を置く |
パラメータを変える
Section titled “パラメータを変える”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=onCFN_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 の反映を待ったりすることもありません。
ドメインとゾーンを決める
Section titled “ドメインとゾーンを決める”| 置き場所 | 例 | 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 を起動をまたいで同じにするか、サインインなしで見せるか(既定はオフで、起動のたびにオフに戻ります)は、メンバーが決めます。
保存時のキーを KMS にする
Section titled “保存時のキーを KMS にする”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> ...10-dataをCustodianKmsKey=createでデプロイします。キーは RDS と同じくPersistenceに従います10-dataの出力CustodianKmsKeyArnを、30-ingressのCustodianKmsKeyArnに渡します
ホームごとにキーを分ける
Section titled “ホームごとにキーを分ける”# 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 にする と ホームごとにキーを分ける にあります。
リモートの MCP を公開する
Section titled “リモートの MCP を公開する”# 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 と外部接続のサインインを運用する にあります。
提供ルートを使う
Section titled “提供ルートを使う”配備が費用を持つ 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=onProvidedRoutes=on は 4 つのことをします。
| すること | 中身 |
|---|---|
| Control Plane のスイッチ | 提供ルートをオンにする |
| ルートのロールを作る | Bedrock のモデルを呼ぶことだけができ、メンバーのセッションタグを付けた Control Plane のタスクロールだけが引き受けられる |
| Control Plane に権限を与える | タスクロールが、そのロールを引き受けられる |
| 内部の経路を開く | エージェントからのモデル呼び出しが通る、Service Connect の af-cp-internal:8098。タイムアウトは 15 分の期限より長く、60 秒の ALB は経由しない |
オンにしたら、次のことをします。
- スタックの出力
DeploymentRouteRoleArnを、PUT /api/admin/provided-routes/deploymentで登録します - テナントに許可を与え、予算を REST で設定します。テナントに上限を付けて許可し、メンバーに予算を設定するまで、誰も使えません
- 動いているワークスペースを停止して起動し直します。起動したときの環境のままなので、そのままではルートを使えません
オフなら何も足しません。予算の決めかたと、登録のリクエスト本文は、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」 にあります。
WAF を置く
Section titled “WAF を置く”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 を読んで