ECS に構築する
AWS の ECS に Agent Fleet を構築し、Control Plane を起動して、IdP でサインインできるところまで進めます。 スタックの構成と順番は ECS 構成の全体像 にあります。
| あなたがやること | 起きること |
|---|---|
| アカウントごとに 1 回、サービスにリンクされたロールを作る。費用を分けるなら、Billing の請求情報へのアクセスもオンにする | ECS のクラスターを作れるようになる。Control Plane が費用を読めるようになる |
00-network・10-data・20-platform をデプロイする |
ネットワーク、EFS と RDS、ECR・クラスター・IAM ロールができる |
| イメージを ECR に push する | ECS がイメージを取れるようになる |
使うなら、40-ec2-pool・50-tts・60-engines をデプロイする |
スロットプール・読み上げ・自前の推論エンジンができる |
| Control Plane のシークレットを SSM に入れ、IdP にリダイレクト URI を登録する | Control Plane がシークレットを読み、IdP がサインインを戻せるようになる |
30-ingress をデプロイする |
証明書・ALB・DNS・Control Plane のサービスができ、Console にサインインできる |
| 費用を分けるなら、構築した日にワークスペースを 1 つ起動する | Control Plane がタグを書き、AWS がキーを見つけたあと(最大 24 時間)、Control Plane がコスト配分タグを有効にする |
コマンドは、リポジトリの deploy/aws/ecs/ で実行します。standup.sh も同じ順番で構築しますが、capture-env.sh で取っておいた既存の配備のパラメータ(params/30-ingress など)から再構築するためのスクリプトです。そのパラメータがない新しい環境では、すぐに終了します。初めて構築するときは、このページの手順で構築してください。
はじめる前に(アカウントごとに 1 回)
Section titled “はじめる前に(アカウントごとに 1 回)”サービスにリンクされたロールを作る
Section titled “サービスにリンクされたロールを作る”新しいアカウントには AWSServiceRoleForECS がなく、Service Connect の既定の名前空間を持つクラスターを作ると「ECS Service Linked Role is not ready」で失敗します。
自前の推論エンジン(60-engines)を動かすなら、CreateFleet の前に AWS が求める AWSServiceRoleForEC2Fleet も作っておきます。なくても呼び出しが通ったアカウントはありましたが、作っておく方が安全です。
standup.sh はこの 2 つを作ります。手で作るときは次のとおりです。何度実行しても結果は同じで、再実行したときの「has been taken」のエラーは無視して構いません。
aws iam create-service-linked-role --aws-service-name ecs.amazonaws.com || trueaws iam create-service-linked-role --aws-service-name ec2fleet.amazonaws.com || true# `spot` の offer を宣言する配備では、次も:aws iam create-service-linked-role --aws-service-name spot.amazonaws.com || truespot のオファーを宣言する配備では、3 行目も実行します。
請求情報へのアクセスをオンにする(任意)
Section titled “請求情報へのアクセスをオンにする(任意)”費用をメンバーごとに分けるなら、支払いアカウントの Billing のコンソールで「IAM ユーザーとロールによる請求情報へのアクセス」をオンにします。テンプレートでは設定できません。
オフのままだと、ポリシーが付いていても CpTaskRole の ce:GetCostAndUsage はすべて失敗します。
コスト配分タグの有効化は、構築したあとに行います(費用をメンバーごとに分ける)。
土台のスタックをデプロイする
Section titled “土台のスタックをデプロイする”スタックに必要な capabilities
Section titled “スタックに必要な capabilities”| スタック | --capabilities |
理由 |
|---|---|---|
00-network |
CAPABILITY_IAM |
egress ゲートウェイのインスタンスロールを宣言している |
10-data |
CAPABILITY_AUTO_EXPAND CAPABILITY_IAM |
Transform: AWS::LanguageExtensions を宣言している。Persistence=retain では、AWS Backup が EFS のバックアップに使う、名前のない IAM ロールも作る |
20-platform |
CAPABILITY_NAMED_IAM |
名前付きの IAM ロールを作る |
40-ec2-pool・60-engines・30-ingress |
CAPABILITY_NAMED_IAM |
Control Plane のタスクロールに、名前付きの管理ポリシーを付ける |
足りないと、変更セットは InsufficientCapabilitiesException … Requires capabilities : [CAPABILITY_IAM] などで拒否されます。
順番にデプロイする
Section titled “順番にデプロイする”-
00-networkをデプロイしますターミナルウィンドウ aws cloudformation deploy --stack-name af-ecs-network --template-file cfn/00-network.yaml \--capabilities CAPABILITY_IAM \--profile af-sandbox --region ap-northeast-1 -
10-dataをデプロイします。データを残す配備ではPersistence=retainにしますターミナルウィンドウ aws cloudformation deploy --stack-name af-ecs-data \--template-file cfn/10-data.yaml --capabilities CAPABILITY_AUTO_EXPAND CAPABILITY_IAM \--parameter-overrides Persistence=retain \--profile af-sandbox --region ap-northeast-1 -
20-platformをデプロイしますターミナルウィンドウ aws cloudformation deploy --stack-name af-ecs-platform \--template-file cfn/20-platform.yaml --capabilities CAPABILITY_NAMED_IAM \--profile af-sandbox --region ap-northeast-1
Persistence の既定は delete で、スタックを消すと EFS と RDS も消えます。
イメージを ECR に push する
Section titled “イメージを ECR に push する”ECR のリポジトリは 20-platform が持っています。先に 20-platform をデプロイしてください。スタックの外でリポジトリを先に作ると、あとで 20-platform をデプロイすると AlreadyExists で失敗します。
release-ecr.sh はリポジトリがあることを確かめるだけで、作りません。
# イメージがこのマシンにあるとき(deploy/release/build.sh でビルドしたもの):VERSION=<v> ./release-ecr.sh --profile af-sandbox --region <region># ビルドしたマシンが別のときは、オフライン用のイメージの tar(B)から:VERSION=<v> ./release-ecr.sh --profile af-sandbox --region <region> \ --images-tar agent-fleet-images-<v>.tar.gz- 1 行目は、
deploy/release/build.shでビルドしたイメージがこのマシンにあるとき、2 行目は別のマシンで作ったイメージの tar から push するときです release-ecr.shがaf-engine-toolsを ECR に入れるのは、60-enginesのスタックがすでにあるときだけです(アップグレード)。初めて60-enginesを構築するときは、次の 任意のスタックをデプロイする で自分で入れますaf-engine-toolsは GHCR にしかなく、ローカルでビルドも配布もしないので、タグを付けて push するのではなく、レジストリ間でcrane copyします。ECR にも GHCR にもそのタグがないと、スクリプトは止まります。先にengine-tools-image.ymlをそのタグで実行してください
手で push する
Section titled “手で push する”スクリプトは次のコマンドを並べたものです。
aws ecr get-login-password --region <region> | docker login --username AWS \ --password-stdin <acct>.dkr.ecr.<region>.amazonaws.com# ローカル用にビルド済みのイメージにタグを付けて push する(ここで重いビルドはしない):docker tag agent-fleet/control-plane:<tag> <acct>.dkr.ecr.<region>.amazonaws.com/af-control-plane:<tag>docker tag agent-fleet/workspace:<tag> <acct>.dkr.ecr.<region>.amazonaws.com/af-workspace:<tag>docker push <acct>.dkr.ecr.<region>.amazonaws.com/af-control-plane:<tag>docker push <acct>.dkr.ecr.<region>.amazonaws.com/af-workspace:<tag>任意のスタックをデプロイする
Section titled “任意のスタックをデプロイする”イメージを push したあと、30-ingress の前に、使うものだけを 40-ec2-pool(ecs-ec2)・50-tts(読み上げ)・60-engines(自前の推論)の順にデプロイします。
-
50-ttsと60-enginesのサービスは、エンジンのイメージ(af-voicevox、af-engine-tools・af-llamacpp・af-comfyui)が ECR にないと起動できず、スタックがCREATE_IN_PROGRESSのまま進みません。スタックより先に ECR に入れます -
初めての
60-enginesでは、af-engine-toolsを60-enginesのEngineToolsImageTagのタグで GHCR からコピーしますターミナルウィンドウ crane copy ghcr.io/k-k1/agent-fleet/engine-tools:<EngineToolsImageTag> <acct>.dkr.ecr.<region>.amazonaws.com/af-engine-tools:<EngineToolsImageTag> -
standup.shはこの順番でイメージをコピーしてからデプロイしますが、取っておいたパラメータがあるときの再構築専用です。初めて構築するときは手でコピーします。読み上げのaf-voicevoxは 日本語の読み上げを足す の「有効にする」、推論エンジンのaf-llamacpp・af-comfyuiは 推論エンジンを足す の「有効にする」の手順 3 にあります -
各スタックのパラメータとイメージは、EC2 スロットプールを使い始める・日本語の読み上げを足す・推論エンジンを足す にあります
Control Plane を起動する(30-ingress)
Section titled “Control Plane を起動する(30-ingress)”サインインは Control Plane 自身が行います(AuthMode=oauth)。Google、または任意の OIDC の IdP(Entra ID・Okta・Keycloak・Auth0・Cognito・GitLab)を使えます。ALB は TLS を終端するだけです。
Control Plane の状態は RDS の Postgres に、ワークスペースのホームは EFS に置きます。どちらも 10-data のエクスポートを参照して設定されるので、先に 10-data をデプロイしておく必要があります。
1. Control Plane のシークレットを SSM に入れる
Section titled “1. Control Plane のシークレットを SSM に入れる”シークレットは SSM の SecureString に置き、実行ロールが読みます。平文の環境変数には入れません。
RG=ap-northeast-1aws ssm put-parameter --profile af-sandbox --region $RG --type SecureString \ --name /af-cp/cookie-secret --value "$(openssl rand -hex 32)"aws ssm put-parameter --profile af-sandbox --region $RG --type SecureString \ --name /af-cp/master-key --value "$(openssl rand -hex 32)"# 次の 2 つのどちらか、または両方。有効にした IdP の分だけ使われるaws ssm put-parameter --profile af-sandbox --region $RG --type SecureString \ --name /af-cp/google-client-secret --value "<GOOGLE_OAUTH_CLIENT_SECRET>" # 自分のターミナルで。共有しないaws ssm put-parameter --profile af-sandbox --region $RG --type SecureString \ --name /af-cp/oidc-client-secret --value "<AF_OIDC_<ID>_CLIENT_SECRET>"- IdP のシークレットは、使う IdP の分だけ入れます。値は自分のターミナルで入力し、共有の画面には出さないでください
master-keyをaws/ssmではなく自前の KMS キーで暗号化するときは、そのput-parameterに--key-id <キーの ARN>を足します。そのうえで、先に20-platformのMasterKeyKmsKeyArnを同じ ARN にしておきます。Control Plane のタスクが起動する前に、実行ロールにkms:Decryptの権限が要るからです。詳しくは 保存時のキーを AWS KMS にする にあります
GitHub と Bitbucket の OAuth アプリは、配備の設定ではありません。CloudFormation のパラメータも SSM の項目もなく、テナント管理者が Console で登録します(連携に使う OAuth アプリを選ぶ)。
2. IdP にリダイレクト URI を登録する
Section titled “2. IdP にリダイレクト URI を登録する”IdP のクライアントで、許可するリダイレクト URI に https://<your-fqdn>/oauth2/callback を足します。有効にするすべての IdP で、この 1 つの URI を使います。
IdP ごとのクライアントの作りかたは サインインの方法を設定する にあります。
3. 30-ingress をデプロイする
Section titled “3. 30-ingress をデプロイする”30-ingress.yaml のサイズは 51,200 バイトの上限のすぐ下で、上限を超えることも許容しています。将来のリリースで超えてもデプロイできなくならないよう、いつも 20-platform が作った S3 Bucket を経由して渡します(テンプレートのサイズの上限に気をつける)。
Google でサインインする配備では次のとおりです。
CFN_BUCKET=$(aws cloudformation describe-stacks --stack-name <platform stack> --query "Stacks[0].Outputs[?OutputKey=='CfnTemplatesBucket'].OutputValue" --output text --profile <p> --region <r>)aws cloudformation deploy --stack-name af-ecs-ingress \ --template-file cfn/30-ingress.yaml --s3-bucket "$CFN_BUCKET" --s3-prefix cfn --capabilities CAPABILITY_NAMED_IAM \ --parameter-overrides GoogleClientId=<id> \ Fqdn=af.example.com HostedZoneId=<your-zone-id> \ AllowedEmails=you@example.com SuperAdminEmails=you@example.com \ --profile af-sandbox --region $RGMicrosoft Entra ID(や Okta・Keycloak など)の配備では、GoogleClientId の代わりに Oidc* のパラメータを渡します。GoogleClientId が空なら、Google は選択肢に出ないだけです。
--parameter-overrides OidcProviderId=ENTRA \ OidcIssuer=https://login.microsoftonline.com/<tenant-guid>/v2.0 \ OidcClientId=<application-client-id> OidcTrust=issuer \ OidcLabelJa="Microsoft でサインイン" OidcLabelEn="Sign in with Microsoft" \ Fqdn=af.example.com HostedZoneId=<your-zone-id> \ AllowedDomains=example.co.jp SuperAdminEmails=you@example.co.jp| パラメータ | 中身 |
|---|---|
Fqdn / HostedZoneId |
Console の名前と、それを含む Route 53 のホストゾーン。ゾーンはこのアカウントにある必要があります |
AllowedEmails / AllowedDomains |
サインインを許すメールアドレスとドメイン |
SuperAdminEmails |
配備管理者(super_admin)になる人 |
OidcIssuer |
Entra ID ではテナントの GUID で固定します。/common/ や /organizations/ では世界中の Microsoft アカウントがサインインの画面まで進めてしまい、個人のアカウントは自分のメールアドレスを書き換えられます。そのため Control Plane は、OidcAllowedTids が設定されていないかぎり起動しません |
ImageTag |
リリースのイメージでは ImageTag=<v> を足します。既定の dev は、開発用に push した :dev に合わせたものです |
ACM の DNS 検証と Route 53 のエイリアスは自動で設定されます。最初にデプロイするときは、証明書の発行で数分長くかかります。
4. 動いたことを確かめる
Section titled “4. 動いたことを確かめる”https://<your-fqdn>/readyzが 200 を返すことを確かめます。/healthzはデータベースが落ちていても 200 を返すので、確かめるのは/readyzです- Console を開き、
SuperAdminEmailsの人でサインインします - 費用をメンバーごとに分けるなら、ここでワークスペースを 1 つ起動します(費用をメンバーごとに分ける)
費用をメンバーごとに分ける(任意)
Section titled “費用をメンバーごとに分ける(任意)”任意ですが、あとから取り戻せないので、使うなら構築した日に始めます。
スタックをデプロイしただけでは何も起きません。 テンプレートが付けるのは CpTaskRole の ce:GetCostAndUsage の権限だけです。タグを書くのは動いている Control Plane で、コスト配分タグを有効にする CloudFormation のリソースはありません。順番は次のとおりです。
- 構築する前に、請求情報へのアクセスをオンにしておきます(請求情報へのアクセスをオンにする)
- スタックをデプロイし、Control Plane を起動します(このページの上の手順)
- ワークスペースを 1 つ起動します。 Control Plane がリソースにタグを書きます。誰も使っていなくても、構築した日に起動してください
- AWS がタグのキーを見つけるのを待ちます(最大 24 時間)
- コスト配分タグを有効にします。ふだんは Control Plane が自動で行います(下を参照)
| 要点 | 中身 |
|---|---|
| さかのぼらない | 有効にする前の日の費用は、誰の分かを後から分けられません。待つ間の費用も同じです |
| キーごとにアカウントで 1 回 | 有効にするのはタグのキーだけで、値の区別はありません。テナントやメンバーが増えても、追加の作業はいりません |
| 支払いアカウントだけ | AWS Organizations では、管理(支払い)アカウントだけが有効にできます |
| 見たことのないキーは有効にできない | AWS がまだ実際のリソースで見ていないキーは ValidationException: Tag keys not found で拒否されます |
af-workspace は有効にしない |
値がメンバーのメールアドレスから作られるので、有効にすると請求データ(CUR・Cost Explorer・請求書の CSV)にそのアドレスが載ります。Control Plane が費用の突き合わせに使うのは、ランダムな ID の af-membership です |
Control Plane は、AWS が各キーを見つけるまで、ポーリングのたびにタグの有効化をやり直します。af-workspace は飛ばし、人がオフにしたタグには触りません。
手で有効にするのは、CpTaskRole から CostAllocationTagActivation の文を外したときか、Console が有効にできなかったと伝えてきたときだけです。
aws ce update-cost-allocation-tags-status --region us-east-1 \ --cost-allocation-tags-status '[{"TagKey":"af-membership","Status":"Active"}, {"TagKey":"af-tenant","Status":"Active"},{"TagKey":"af-role","Status":"Active"}, {"TagKey":"af-pool","Status":"Active"},{"TagKey":"af-slot-size","Status":"Active"}]'AWS が何を見つけたかは list-cost-allocation-tags でわかります。Inactive で載っているキーはすぐ Active にでき、載っていないキーは、まだどのリソースにも書かれていません。待つのは、そのキーが初めて現れるときだけです。
- ECS 構成の全体像
- データベースに届かないときのアラームを設定する:構築したら、続けて設定してください
- パラメータで任意の機能をオンにする
- デプロイに必要な IAM 権限
- ECS で困ったとき
エージェント向け
この指示をエージェントに送ると、このページを読ませられます。
https://agent-fleet.org/docs/ja/operate/aws-ecs/install/index.md を読んで