コンテナ実行契約
Web サービスのイメージが従うルール、プラットフォームが設定する変数、新しいバージョンの公開後に前のバージョンがどれだけ動き続けるかを説明します。
ルール#
| 項目 | 要件 | 満たさない場合 |
|---|---|---|
| 起動コマンド | CMD または ENTRYPOINT が必要です。 | バージョンは受け付けられません。 |
| ポート | $PORT で HTTP を提供します。 | 設定 → EXPOSE → 8080 の順に決まります。プロジェクトの設定をご覧ください。 |
| プラットフォーム | linux/amd64。 | Agent Lab は常にこのプラットフォーム向けにビルドします。 |
| ユーザー | root 以外の USER を推奨します。 | root または未指定の場合は uid 10001、グループ 0 で実行します。イメージにないユーザーを指定したバージョンは受け付けられません。 |
| ファイルシステム | /tmp 以外は読み取り専用です。 | 他の場所への書き込みは失敗します。 |
| クラウドの認証情報 | 提供されません。 | 外部サービスにはプロジェクトのシークレットを使って接続します。 |
uid 10001 で実行される場合、イメージが読むファイルはグループ 0 から読める必要があります。
お知らせ#
プラットフォームが調整した内容は、バージョンのページにお知らせとして表示されます。AI ツールはデプロイの状態から同じコードを読み取れます。
| コード | 意味 | 対応 |
|---|---|---|
imageUserForced | イメージが root で実行されるため、uid 10001 で実行します。 | 不要です。お知らせを消すには、Dockerfile で root 以外の USER を設定します。 |
imagePortFromExpose | サービスはイメージが EXPOSE している 1 つのポートで待ち受けます。 | 不要です。 |
imagePortsAmbiguous | イメージが複数のポートを EXPOSE していて 8080 がないため 8080 で実行しますが、サーバーの待ち受けポートではない可能性が高いです。 | 「設定 › 実行設定 › ポート」で正しいポートを選んでサービスを再起動するか、Dockerfile でそのポートだけを EXPOSE します。 |
プラットフォームが設定する変数#
| 変数 | 値 |
|---|---|
PORT | HTTP を提供するポート。 |
AGENTLAB_RELEASE_ID | このコンテナが実行しているバージョンの ID。AI ツールがデプロイ状況から得る ID と同じです。 |
AGENTLAB_ENVIRONMENT | 実行している環境。本番環境では main、それ以外は環境の名前です。 |
これらの名前で変数やシークレットを追加することはできません。プラットフォームがこの 2 つを設定する前から AGENTLAB_RELEASE_ID や AGENTLAB_ENVIRONMENT を持っていたプロジェクトでは、その値は残り、ほかの設定もこれまでどおり保存できますが、コンテナにはプラットフォームの値が渡されます。都合のよいときに削除してください。
この 2 つの変数が追加される前にデプロイしたバージョンには、これらはありません。新しいバージョンをデプロイすると設定されます。
新しいバージョンが公開されるとき#
- 新しいバージョンが起動する 新しいバージョンの準備ができるまで、前のバージョンがすべてのインスタンスで処理を続けます。
- トラフィックが切り替わる 数秒のうちに、訪問者からの新しいリクエストとスケジュールジョブの呼び出しは新しいバージョンに送られます。前のバージョンが処理中のリクエストは、そのまま前のバージョンで完了します。
- 前のバージョンがインスタンスを 1 つ残す 切り替えから最大 15 分間、前のバージョンは 1 つのインスタンスで動き続けます。新しいリクエストは届きませんが、キューの処理、定期的なポーリング、タイマーなど、自分で始めた処理は続きます。
- 前のバージョンが停止する プロセスに
SIGTERMが送られ、30 秒以内に終了しなければ強制終了されます。
つまり、切り替え後も前のバージョンのコードが最大 15 分 30 秒動くことがあります。また、再起動ではインスタンスを 1 つずつ置き換えるため、同じバージョンのインスタンスが短い間重なります。インスタンスが複数のプロジェクトでは、常に複数が同時に動いています。
バックグラウンドワーカー#
ジョブ用のテーブルやキューなど、共有の場所から処理を取ってくる場合は、ワーカーが同時に複数動いても問題ないように書いてください。
SIGTERMで終了する。 新しい処理は取らず、手元の処理は終わらせるか戻して、30 秒以内に終了します。- 処理ごとに確保してから実行する。 行ロック(
SELECT … FOR UPDATE SKIP LOCKED)か、有効期限付きでワーカーが更新し続けるリースを使います。こうすると同じ処理を 2 つのプロセスが同時に行うことはなく、処理を持ったまま止まったプロセスの分も別のプロセスが引き継ぎます。 - 処理は公開中のバージョンに任せる。 ワーカーは
AGENTLAB_RELEASE_IDで自分がどのバージョンかわかります。公開中のバージョンを知るには、AGENTLAB_RELEASE_IDを返すエンドポイントを追加し、ワーカーから自分の公開アドレスを呼び出します。応答するのは公開中のバージョンだけです。返ってきた ID が自分と違えば、新しい処理を取るのをやめます。 - 誰が処理したかを残す。
AGENTLAB_RELEASE_IDをログと、ワーカーが変更する行に書き込んでおくと、どのバージョンが処理したかを後から確認できます。
// Web サーバーは GET /release で process.env.AGENTLAB_RELEASE_ID を返します。
const mine = process.env.AGENTLAB_RELEASE_ID;
let stopping = false;
process.on("SIGTERM", () => {
stopping = true; // ループが終わったら Web サーバーを閉じて終了する
});
async function isLive() {
try {
const res = await fetch("https://your-app-address/release");
return res.ok && (await res.text()) === mine;
} catch {
return false;
}
}
async function work() {
while (!stopping) {
if (await isLive()) {
await claimAndRunOne(); // 例:SELECT … FOR UPDATE SKIP LOCKED
} else {
await new Promise((resolve) => setTimeout(resolve, 10_000));
}
}
}プロジェクトを呼び出すスケジュールジョブも、実行ごとに送り先のバージョンを記録します。ジョブの実行履歴の outcome.releaseId です。
起動時にファイルを書き込むイメージ#
起動時に /tmp 以外へ書き込むイメージがあります。たとえば nginx:alpine は /var/cache/nginx に書き込むため、読み取り専用のファイルシステムでは起動に失敗します。書き込みが不要なイメージを使うか、書き込み先を /tmp に変えてください。
FROM nginxinc/nginx-unprivileged:alpine
COPY dist/ /usr/share/nginx/html/静的ファイルを配信するだけなら
静的サイトとしてデプロイしてください。nginx を自分で動かす必要はありません。