EC2 1 台に構築する
CloudFormation で EC2 インスタンスを 1 台構築し、その上で Docker Compose の配備を動かします。 要るのは AWS CLI だけで、Terraform は使いません。片付けもコマンド 1 つです。
| あなたがやること | 起きること |
|---|---|
| SSH のキーを手元で作り、スタックをデプロイする | Ubuntu 24.04 のインスタンス(cloud-init で Docker 入り)、Elastic IP、Route 53 の A レコード、取り込んだキーペアができる |
| 手元でリリースのバンドルとイメージを作り、インスタンスに送る | インスタンスで git をクローンせずに、バンドルだけで配備を構築できる |
インスタンスで .env を書き、docker compose up -d する |
Caddy が Let’s Encrypt の証明書を取り、Console が https://<Fqdn> で開く |
| いらなくなったらスタックを消す | スタックの中のものがすべて消える |
ECS の配備ではなく、1 台の VM の上の Docker Compose です。ECS は デプロイ先を選ぶ で比べます。
| 用意するもの | 補足 |
|---|---|
| AWS CLI と、デプロイに使う IAM 権限 | EC2・Route 53・CloudFormation。SSM の書き込みも IAM の capability も要りません |
| Route 53 のパブリックホストゾーン | ドメインがそのゾーンに委任されていないときは、下の DNS の注意 |
| x86_64(amd64)のマシンの Docker | リリースのバンドルとイメージを作ります。インスタンスは amd64 なので、Apple Silicon などの arm64 のマシンで作ったイメージは動きません |
| サインイン用の IdP のクライアント | サインインの方法を設定する |
1. スタックを構築する
Section titled “1. スタックを構築する”SSH のキーは手元で作ります。秘密鍵は手元から出ません。取り込むのは公開鍵だけなので、ssm:PutParameter の権限は要りません。
ssh-keygen -t ed25519 -N '' -f agent-fleet-test-key # -> agent-fleet-test-key(.pub)
aws cloudformation deploy \ --stack-name agent-fleet-test \ --template-file cfn.yaml \ --parameter-overrides \ HostedZoneName=example.com. \ Fqdn=af.example.com \ SSHLocation=<your-ip>/32 \ PublicKey="$(cat agent-fleet-test-key.pub)"
# 出力(パブリック IP・FQDN・ssh のコマンド)を読むaws cloudformation describe-stacks --stack-name agent-fleet-test \ --query 'Stacks[0].Outputs' --output tableコマンドは deploy/aws/ec2-single/ で実行します。
| パラメータ | 既定 | 意味 |
|---|---|---|
HostedZoneName |
(必須) | 既存の Route 53 のパブリックホストゾーン。末尾のドットを付けます(example.com.) |
Fqdn |
(必須) | Console のホスト名。TLS と OAuth のリダイレクトに使います |
SSHLocation |
0.0.0.0/0 |
SSH を許す CIDR。自分の <ip>/32 にして絞ります |
PublicKey |
(必須) | 取り込む SSH の公開鍵(*.pub の中身) |
InstanceType |
t3.large |
t3.medium・t3.large・t3.xlarge。t3.medium(4 GB)なら下の メモリの小さいインスタンス |
VolumeSizeGb |
30 |
ルートボリュームのサイズ |
LatestUbuntuAmi |
Canonical の SSM パラメータ | 最新の Ubuntu 24.04 の AMI。そのままにします。どのリージョンでも使えます |
出力には PublicIp・Fqdn・ConsoleUrl・OAuthRedirectUri・SshCommand が出ます。セキュリティグループは 22 番を SSHLocation に、80 番と 443 番を全体に開きます。
DNS の注意
Section titled “DNS の注意”Route 53 の A レコードが効くのは、ドメインがそのホストゾーンに委任されているときだけです(レジストラの NS レコードが、ゾーンの awsdns-* のサーバーを指している状態)。
ドメインをほかの DNS で管理しているときは、次のどちらかにします。
- その DNS に A レコードを足します
- DNS を使わず、Elastic IP の sslip.io を使います。
Fqdn・PUBLIC_DOMAINを<ダッシュ区切りの IP>.sslip.io(例:203-0-113-7.sslip.io)にすると、設定なしでその IP に解決され、本物の Let’s Encrypt の証明書も取れます
2. バンドルをインスタンスに送る
Section titled “2. バンドルをインスタンスに送る”手元でイメージとバンドルを作り、インスタンスにコピーします。インスタンスでは git をクローンしません。
cd ../../.. # リポジトリのルートVERSION=0.1.0 deploy/compose/release.sh --savescp -i deploy/aws/ec2-single/agent-fleet-test-key \ deploy/compose/dist/agent-fleet-images-0.1.0.tar.gz \ deploy/compose/dist/agent-fleet-0.1.0.tar.gz \ ubuntu@<public-ip>:~0.1.0 は例です。作るバージョンに置き換えます。--save を付けると、バンドル(agent-fleet-<版>.tar.gz)に加えて、イメージを docker save した tar(agent-fleet-images-<版>.tar.gz)もできます。
3. インスタンスで起動する
Section titled “3. インスタンスで起動する”ssh -i deploy/aws/ec2-single/agent-fleet-test-key ubuntu@<public-ip># VM で:tar xzf agent-fleet-0.1.0.tar.gz && cd agent-fleet-0.1.0./load-images.sh ~/agent-fleet-images-0.1.0.tar.gz # または gunzip|docker loadcp .env.example .env# 次を設定する: DATA_DIR=/srv/agent-fleet/data、DOCKER_GID=$(getent group docker|cut -d: -f3)、# PUBLIC_DOMAIN / PUBLIC_BASE_URL=https://<Fqdn>、サインインの IdP(GOOGLE_OAUTH_*、# AF_OIDC_PROVIDERS + AF_OIDC_<ID>_*、AF_GITHUB_ALLOWED_ORGS +# GITHUB_OAUTH_CLIENT_ID/_SECRET のどれか、または複数)、AF_COOKIE_SECRET、# AF_MASTER_KEY(新しく作る)、AF_OAUTH_ALLOWED_DOMAINS、SUPER_ADMIN_EMAILSsudo mkdir -p /srv/agent-fleet/data && sudo chown 1000:1000 /srv/agent-fleet/datadocker compose up -ddocker compose logs -f caddy cp.envの各値の意味とシークレットの作り方は Docker Compose で構築する と同じです- 80 番と 443 番が開いているので、Caddy が
<Fqdn>の本物の Let’s Encrypt の証明書を取ります - IdP のクライアントに
https://<Fqdn>/oauth2/callbackを登録します。有効にするどの IdP でも、この 1 つで足ります https://<Fqdn>を開いてサインインします
最初の管理者については次のとおりです。
- 最初の管理者を通すのは
AF_OAUTH_ALLOWED_DOMAINSです。そのあとは、管理パネルでテナントに招待した人は、そこに入っていなくてもサインインできます - テナント専用のサインインページは
https://<Fqdn>/login/<slug>です SUPER_ADMIN_EMAILSは起動のときに 1 回だけ読まれ、配備管理者を決めるのはこの値だけです。アドレスを外して再起動すると、データベース上のロールも外れます
メモリの小さいインスタンス
Section titled “メモリの小さいインスタンス”t3.medium(4 GB)では、ワークスペースを起動する前に .env の WS_MEMORY を下げます(例: 2g)。下げないと、Claude のインストールの途中でインスタンスがメモリ不足になります。
インスタンスのメタデータを守る
Section titled “インスタンスのメタデータを守る”インスタンスは、ホップ数 1 の IMDSv2 を必須にしています(cfn.yaml の MetadataOptions)。
- テンプレートはインスタンスプロファイルを付けません。あとから付けた場合でも、ホストネットワークで動く Control Plane(1 ホップ)には届き、docker ブリッジ上のワークスペース(2 ホップ)には届かないようにするための設定です
- ワークスペースは
AWS_EC2_METADATA_DISABLED=true付きで起動します。Control Plane にAF_WS_WORKLOAD_AWS=1があるときは付けませんが、ホップ数の制限は外れないので、どちらでもインスタンスプロファイルには届きません - このテンプレートは、配備が費用を払う Bedrock のルート(provided routes)を提供しません。Control Plane がルート用のロールを引き受けるための AWS の ID がないからです。代わりに ECS のスタックの
ProvidedRoutes=onを使います
この設定より前に作ったスタックには、スタックを更新するのではなく、動いているインスタンスに直接適用します。LatestUbuntuAmi は更新のたびに解決し直され、新しい AMI ならインスタンスが作り直されるからです。
aws ec2 modify-instance-metadata-options --instance-id <id> \ --http-tokens required --http-put-response-hop-limit 1 --http-endpoint enabled動いていたワークスペースは、Console で停止して起動するまで、古いコンテナと環境のままです(docker compose up -d では作り直されません)。停止して起動したあと、ワークスペースのシェルで確かめます。
| 確かめること | AF_WS_WORKLOAD_AWS がオフ(既定) |
AF_WS_WORKLOAD_AWS=1 |
|---|---|---|
echo ${AWS_EC2_METADATA_DISABLED:-unset} |
true と出る |
unset(意図どおり) |
プロファイルなしの aws sts get-caller-identity |
「Unable to locate credentials」で失敗する | — |
| 下のトークンリクエスト | 200 が出ない |
200 が出ない |
curl -s -o /dev/null -m 3 -w '%{http_code}' -X PUT -H 'X-aws-ec2-metadata-token-ttl-seconds: 60' http://169.254.169.254/latest/api/tokenほかの形態の扱いは そのほかの運用上の制御 にあります。
4. 片付ける
Section titled “4. 片付ける”スタックの中のものは、すべて消えます。
aws cloudformation delete-stack --stack-name agent-fleet-testaws cloudformation wait stack-delete-complete --stack-name agent-fleet-testElastic IP・セキュリティグループ・インスタンス・Route 53 のレコード・キーペアが、スタックと一緒に消えます。 試験に使った サインインの IdP のクライアント(Google Cloud Console の OAuth クライアントや、Entra・Okta などのアプリの登録)も消します。そのシークレットは試験のあいだ使われていました。
キーペアが消えずに DELETE_FAILED になるとき
Section titled “キーペアが消えずに DELETE_FAILED になるとき”AWS::EC2::KeyPair のハンドラーは、取り込んだキーでも SSM の Parameter Store に触れます。デプロイしたユーザーに ssm:* がない(AmazonSSMReadOnlyAccess だけなど)と、キーペアが InternalFailure で消えず、スタックが DELETE_FAILED になります。
そのリソースだけ残してスタックを消し、キーペアを直接消します。
aws cloudformation delete-stack --stack-name agent-fleet-test --retain-resources KeyPairaws cloudformation wait stack-delete-complete --stack-name agent-fleet-testaws ec2 delete-key-pair --key-name agent-fleet-test-keyデプロイするユーザーに /ec2/keypair/* の ssm:PutParameter・ssm:DeleteParameter を与えておけば、この問題は起きません。
エージェント向け
この指示をエージェントに送ると、このページを読ませられます。
https://agent-fleet.org/docs/ja/operate/aws-ec2-single/index.md を読んで