第5回でローカルに作った「請求書発行のキュー」と「毎日・毎月の定期実行」を、ECS 上で動かします。キューは Amazon SQS(=AWS のメッセージキューサービス)に切り替え、ワーカー(=キューに積まれた仕事を順番に処理するプログラム)とスケジューラをそれぞれ ECS のサービスにします。あわせて、前回見送ったマイグレーション(=DB のテーブルを作る・変える処理)を実行する専用のタスクを用意します。
「夜間のバッチ処理が止まっていたのに、何日も誰も気づかなかったことがある。裏で動く処理は、どうやって見張ればいいの?」
結論から言うと、ワーカーとスケジューラは web と同じイメージを「コマンドだけ変えた別サービス」として動かし、止め方(SIGTERM で処理中のジョブを終えてから止まる)と、失敗したジョブの行き先(failed_jobs とデッドレターキュー)を最初に決めておきます。「止まったことに気づける」仕組みは、この行き先を見張るアラームとして第12回で仕上げます。
(2026年10月29日 追記:記事どおりに再現できるよう、必要なコードと手順を追加しました)
前回(第9回:ECR・ECS on Fargate・ALB)では、web サービスと ALB を作りました。今回はその隣に worker・scheduler のサービスと migrate のタスク定義を並べます。新しく作るファイルは全文を、すでにあるファイルは変更箇所を差分で載せています。
これまでと同じく terraform apply は行っていません。terraform validate・AWS に接続しない形での plan・ローカルの Docker(SQS 互換サーバーを使用)での動作確認までを行っています。
キューとスケジューラを ECS で動かすための構成
| 役割 | ECS での形 | コマンド | 台数 |
|---|---|---|---|
| web | サービス(第9回) | php-fpm(既定) | 2台〜 |
| worker | サービス | php artisan queue:work sqs | 1台〜(ジョブの量で決める) |
| scheduler | サービス | php artisan schedule:work | 常に1台 |
| migrate | タスク定義のみ(必要なときに1回起動) | php artisan migrate --force | デプロイごとに1回 |
4つとも第6回で作った同じ app イメージです。今回追加・変更するファイルは次のとおりです。
| ファイル | 内容 |
|---|---|
infra/terraform/sqs.tf | ジョブのキューとデッドレターキュー(DLQ) |
infra/terraform/ecs_worker.tf / ecs_scheduler.tf / ecs_migrate.tf | 各タスク定義とサービス |
infra/terraform/ecs_cluster.tf / iam.tf | キューを SQS に切り替える環境変数、タスクロールに SQS の権限 |
composer.json / composer.lock | SQS を使うための AWS SDK for PHP を追加 |
config/queue.php | SQS の設定(キューの URL、ローカル確認用の接続先) |
compose.sqs.yaml / docker/local/elasticmq.conf | SQS 互換サーバーでのローカル確認用 |
SQS のキューとデッドレターキューを作る
可視性タイムアウトはジョブの timeout より長く
infra/terraform/sqs.tf を新しく作ります。
# infra/terraform/sqs.tf
# SQS:ジョブのキューと、デッドレターキュー(DLQ)(第10回)
#
# web / scheduler ──SendMessage──▶ [jobs] ──ReceiveMessage──▶ worker
# │ 5 回受信しても削除されない(ワーカーが処理を終えられない)
# ▼
# [jobs-dlq](14 日保管。第12回でアラームを付ける)
#
# Laravel 側でジョブが tries 回失敗した場合は、failed_jobs テーブルに記録してメッセージを削除する。
# DLQ に移るのは、ワーカーの強制終了などで Laravel が失敗の記録までたどり着けなかったメッセージ。
resource "aws_sqs_queue" "jobs_dlq" {
name = "${local.name_prefix}-jobs-dlq"
message_retention_seconds = 1209600 # 14 日(最大)。原因を調べて再投入するまでの猶予
sqs_managed_sse_enabled = true
tags = { Name = "${local.name_prefix}-jobs-dlq" }
}
resource "aws_sqs_queue" "jobs" {
name = "${local.name_prefix}-jobs"
# 受信したメッセージを他のワーカーから見えなくする時間。ジョブの timeout(IssueInvoice は 60 秒)より長くする。
# 短いと、処理中のジョブが別のワーカーにもう一度渡され、二重に実行される
visibility_timeout_seconds = 90
# ロングポーリング:メッセージが無いときに最大 10 秒待ってから空の応答を返す(空の受信の回数と費用を減らす)
receive_wait_time_seconds = 10
message_retention_seconds = 345600 # 4 日(既定)
sqs_managed_sse_enabled = true
redrive_policy = jsonencode({
deadLetterTargetArn = aws_sqs_queue.jobs_dlq.arn
maxReceiveCount = 5 # Laravel の tries(3)より大きくし、通常の再試行は Laravel に任せる
})
tags = { Name = "${local.name_prefix}-jobs" }
}
# DLQ に送ってよいのは jobs キューだけ
resource "aws_sqs_queue_redrive_allow_policy" "jobs_dlq" {
queue_url = aws_sqs_queue.jobs_dlq.id
redrive_allow_policy = jsonencode({
redrivePermission = "byQueue"
sourceQueueArns = [aws_sqs_queue.jobs.arn]
})
}
SQS では、ワーカーがメッセージを受け取ると、一定時間ほかのワーカーからは見えなくなります。これが可視性タイムアウトです。この時間内にワーカーが「処理済み」として削除しなければ、メッセージは再び見えるようになり、別のワーカーが受け取ります。
第5回の IssueInvoice は $timeout = 60(60秒で打ち切り)にしているので、可視性タイムアウトは 90 秒にしました。ローカルの database キューでは retry_after という設定で同じことを決めていましたが、SQS の場合はキュー側の設定が使われます。
📰 出典:Job Expirations and Timeouts(Laravel 12.x ドキュメント)
📰 出典:Amazon SQS 可視性タイムアウト(Amazon SQS デベロッパーガイド)
この関係はコードの変更で崩れやすいため、テストでも確認するようにしました。
tests/Feature/SqsQueueConfigTest.php を新しく作ります。
<?php
// tests/Feature/SqsQueueConfigTest.php
declare(strict_types=1);
namespace Tests\Feature;
use App\Jobs\IssueInvoice;
use Illuminate\Queue\SqsQueue;
use Illuminate\Support\Facades\Queue;
use ReflectionProperty;
use Tests\TestCase;
/**
* 本番(ECS)の SQS 接続設定(第10回)
* AWS には接続せず、ECS のタスク定義と同じ環境変数で SQS のキューが組み立てられるかを確認する。
*/
class SqsQueueConfigTest extends TestCase
{
private const QUEUE_URL = 'https://sqs.ap-northeast-1.amazonaws.com/111122223333/admin-stg-jobs';
public function test_queue_url_is_used_as_is_without_account_prefix(): void
{
config([
'queue.connections.sqs.queue' => self::QUEUE_URL,
'queue.connections.sqs.key' => null,
'queue.connections.sqs.secret' => null,
]);
$queue = Queue::connection('sqs');
$this->assertInstanceOf(SqsQueue::class, $queue);
$this->assertSame(self::QUEUE_URL, $queue->getQueue(null));
$this->assertSame('ap-northeast-1', $queue->getSqs()->getRegion());
}
public function test_issue_invoice_timeout_is_shorter_than_visibility_timeout(): void
{
// SQS の可視性タイムアウト(infra/terraform/sqs.tf の 90 秒)より短くないと、
// 処理中のジョブが別のワーカーにもう一度渡されてしまう
$timeout = (new ReflectionProperty(IssueInvoice::class, 'timeout'))->getDefaultValue();
$this->assertLessThan(90, $timeout);
}
}
失敗したジョブの行き先は2つある
失敗したジョブがどこに行くかは、次の2段構えです。
| 状況 | 行き先 | 見るところ |
|---|---|---|
ジョブの中で例外が起き、tries(3回)を使い切った | Laravel が failed_jobs テーブルに記録し、SQS のメッセージは削除。IssueInvoice::failed() で請求を下書きに戻す | php artisan queue:failed |
| ワーカーが強制終了されるなど、Laravel が失敗の記録までたどり着けないまま5回受信された | SQS が DLQ(デッドレターキュー)に移す | DLQ のメッセージ数 |
DLQ(=処理できなかったメッセージの退避場所)は、ワーカー自体に問題がある場合の最後の受け皿です。どちらも「放っておくと誰も気づかない」場所なので、第12回で DLQ にメッセージが入ったらアラームを出すようにします。
📰 出典:Amazon SQS のデッドレターキューの使用(Amazon SQS デベロッパーガイド)
Laravel を SQS に切り替える
SQS のドライバーを使うには AWS SDK for PHP が必要です。開発用のコンテナで Composer を使って追加します(composer.json と composer.lock が更新されます)。筆者の環境では、ほかの依存関係とそろえて 2025年5月時点の 3.343 系の版を使っています。
docker compose run --rm --no-deps app composer require "aws/aws-sdk-php:^3.343"
config/queue.php に次の変更を加えます(+ が追加、- が削除)。
--- a/config/queue.php
+++ b/config/queue.php
@@ -52,6 +52,12 @@
'after_commit' => false,
],
+ /*
+ | 本番(ECS)で使う SQS(第10回)
+ | - key / secret は ECS では設定しない。未設定なら AWS SDK がタスクロールの一時的な認証情報を自動で使う
+ | - SQS_QUEUE にキューの URL をそのまま渡す(URL なら prefix は使われないので、アカウント ID を書かずに済む)
+ | - endpoint はローカルで SQS 互換のサーバー(compose.sqs.yaml の ElasticMQ)を使うときだけ指定する
+ */
'sqs' => [
'driver' => 'sqs',
'key' => env('AWS_ACCESS_KEY_ID'),
@@ -59,7 +65,8 @@
'prefix' => env('SQS_PREFIX', 'https://sqs.us-east-1.amazonaws.com/your-account-id'),
'queue' => env('SQS_QUEUE', 'default'),
'suffix' => env('SQS_SUFFIX'),
- 'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
+ 'region' => env('AWS_DEFAULT_REGION', 'ap-northeast-1'),
+ 'endpoint' => env('SQS_ENDPOINT'),
'after_commit' => false,
],
大事なのは、アクセスキーを設定しないことです。ECS のタスクでは、タスクロールの一時的な認証情報が自動で使えるので、長期間有効なアクセスキーを発行して環境変数に入れる必要はありません。
タスク定義で渡す環境変数は、第9回の共通部分(ecs_cluster.tf の app_environment)を次のように変えます。あわせて、worker・scheduler・migrate で使う共通部分(php_container_base・app_network_configuration)も足します。infra/terraform/ecs_cluster.tf に次の変更を加えます(+ が追加、- が削除)。
--- a/infra/terraform/ecs_cluster.tf
+++ b/infra/terraform/ecs_cluster.tf
@@ -27,7 +27,10 @@ locals {
{ name = "SESSION_DRIVER", value = "database" },
{ name = "SESSION_SECURE_COOKIE", value = "true" },
{ name = "CACHE_STORE", value = "database" },
- { name = "QUEUE_CONNECTION", value = "database" },
+ # キューは SQS(第10回)。認証情報は渡さず、タスクロールの権限で接続する
+ { name = "QUEUE_CONNECTION", value = "sqs" },
+ { name = "SQS_QUEUE", value = aws_sqs_queue.jobs.url },
+ { name = "AWS_DEFAULT_REGION", value = var.region },
# ALB からの X-Forwarded-* を信用する範囲(config/trustedproxy.php)
{ name = "TRUSTED_PROXIES", value = var.vpc_cidr },
]
@@ -43,4 +46,19 @@ locals {
app_image = "${aws_ecr_repository.this["app"].repository_url}:${var.image_tag}"
web_image = "${aws_ecr_repository.this["web"].repository_url}:${var.image_tag}"
+
+ # php コンテナの共通部分(第10回)。worker・scheduler・migrate は merge() で name・command・ログの出し先を足す
+ php_container_base = {
+ image = local.app_image
+ essential = true
+ environment = local.app_environment
+ secrets = local.app_secrets
+ }
+
+ # worker・scheduler・migrate のネットワーク:private サブネット、受け付ける通信のない app SG
+ app_network_configuration = {
+ subnets = aws_subnet.private[*].id
+ security_groups = [aws_security_group.app.id]
+ assign_public_ip = false
+ }
}
web(請求書発行ボタン)と scheduler(月次締め)はジョブを送る側、worker は受け取る側です。タスクロールには、このキューに対する操作だけを許可しました。
infra/terraform/iam.tf に次の変更を加えます(+ が追加、- が削除)。
--- a/infra/terraform/iam.tf
+++ b/infra/terraform/iam.tf
@@ -2,7 +2,7 @@
# ECS のタスク実行ロール:ECS エージェントがタスクを起動するときに使う権限
# - ECR からイメージを取得する、CloudWatch Logs にログを送る(AWS 管理ポリシー)
# - タスク定義の secrets に書いた値を取得する(下のインラインポリシー。対象の ARN だけに絞る)
-# アプリ自身が AWS を使うための「タスクロール」は別に作る(このファイルの下部。第9回)
+# アプリ自身が AWS を使うための「タスクロール」は別に作る(このファイルの下部。第9回で作成、第10回で SQS の権限を追加)
data "aws_iam_policy_document" "ecs_tasks_assume" {
statement {
@@ -48,9 +48,31 @@ resource "aws_iam_role_policy" "ecs_task_execution_secrets" {
}
# ---------- タスクロール(第9回):アプリ(Laravel)自身が AWS のサービスを使うときの権限 ----------
-# 第9回の時点では権限を付けない(DB へは SG と DB ユーザーで接続し、IAM 権限は使わない)。
-# 第10回で SQS の送受信の権限をここに追加する。
+# DB へは SG と DB ユーザーで接続するので IAM の権限は使わない。
+# 第10回:SQS の送受信の権限を追加(下の ecs_task_sqs)
resource "aws_iam_role" "ecs_task" {
name = "${local.name_prefix}-ecs-task"
assume_role_policy = data.aws_iam_policy_document.ecs_tasks_assume.json
}
+
+# タスクロールの権限(第10回):ジョブのキューへの送信(web・scheduler)と受信・削除(worker)
+# Laravel の SQS ドライバーが使う API だけを、このキューに限って許可する
+data "aws_iam_policy_document" "ecs_task_sqs" {
+ statement {
+ sid = "UseJobQueue"
+ actions = [
+ "sqs:SendMessage",
+ "sqs:ReceiveMessage",
+ "sqs:DeleteMessage",
+ "sqs:ChangeMessageVisibility", # 再試行までの待ち時間(backoff)の設定に使う
+ "sqs:GetQueueAttributes", # キューの件数の取得(queue:monitor など)に使う
+ ]
+ resources = [aws_sqs_queue.jobs.arn]
+ }
+}
+
+resource "aws_iam_role_policy" "ecs_task_sqs" {
+ name = "use-job-queue"
+ role = aws_iam_role.ecs_task.id
+ policy = data.aws_iam_policy_document.ecs_task_sqs.json
+}
サンプルでは web・worker・scheduler で1つのタスクロールを共有しています。さらに絞るなら、web と scheduler には送信だけ、worker には受信と削除だけのロールを分けて作ります。
worker サービス:SIGTERM で安全に止める
infra/terraform/ecs_worker.tf を新しく作ります。
# infra/terraform/ecs_worker.tf
# worker サービス:SQS のジョブを処理する(第10回)
#
# web と同じ app イメージを、コマンドだけ queue:work に変えて動かす。画面の台数とは別に台数を決められる。
#
# 停止のしかた(デプロイ・台数の削減のとき)
# 1. ECS がコンテナに SIGTERM を送る
# 2. queue:work は新しいジョブを取らず、処理中のジョブを終えてから終了する(pcntl 拡張が必要:第6回で導入済み)
# 3. stopTimeout(90 秒)を過ぎても終わらなければ SIGKILL で強制終了
# → 処理中だったメッセージは可視性タイムアウト後にキューに戻り、再試行される
resource "aws_ecs_task_definition" "worker" {
family = "${local.name_prefix}-worker"
requires_compatibilities = ["FARGATE"]
network_mode = "awsvpc"
cpu = var.worker_cpu
memory = var.worker_memory
execution_role_arn = aws_iam_role.ecs_task_execution.arn
task_role_arn = aws_iam_role.ecs_task.arn
runtime_platform {
operating_system_family = "LINUX"
cpu_architecture = "X86_64"
}
container_definitions = jsonencode([
merge(local.php_container_base, {
name = "worker"
# --tries:ジョブ側で指定がない場合の最大試行回数。--max-time:1 時間で終了し、ECS が新しいタスクに入れ替える(メモリの肥大化対策)
command = ["php", "artisan", "queue:work", "sqs", "--sleep=3", "--tries=3", "--max-time=3600"]
stopTimeout = 90 # ジョブの timeout(60 秒)+ ロングポーリングの待ち(10 秒)+ 余裕。Fargate の上限は 120 秒
logConfiguration = {
logDriver = "awslogs"
options = {
awslogs-group = aws_cloudwatch_log_group.ecs["worker"].name
awslogs-region = var.region
awslogs-stream-prefix = "worker"
}
}
}),
])
tags = { Name = "${local.name_prefix}-worker" }
}
resource "aws_ecs_service" "worker" {
name = "worker"
cluster = aws_ecs_cluster.main.id
task_definition = aws_ecs_task_definition.worker.arn
desired_count = var.worker_desired_count
launch_type = "FARGATE"
network_configuration {
subnets = local.app_network_configuration.subnets
security_groups = local.app_network_configuration.security_groups
assign_public_ip = local.app_network_configuration.assign_public_ip
}
# デプロイ時は新しいワーカーを先に起動してから古いワーカーを止める(ジョブの処理が途切れない)
deployment_minimum_healthy_percent = 100
deployment_maximum_percent = 200
tags = { Name = "${local.name_prefix}-worker" }
}
local.php_container_base は、イメージ・環境変数・秘密情報をまとめた共通部分です(ecs_cluster.tf)。worker・scheduler・migrate はこれに merge() で名前とコマンドとログの出し先を足しています。
デプロイや台数の削減でワーカーを止めるとき、ECS はまずコンテナに SIGTERM(=終了のお願いの合図)を送り、stopTimeout の秒数を過ぎても終わらなければ強制終了します。Laravel の queue:work は SIGTERM を受けると、新しいジョブを取らずに処理中のジョブを終えてから終了します(PHP の pcntl 拡張が必要で、第6回のイメージに入れてあります)。
stopTimeout をジョブの timeout より短くすると、処理の途中で強制終了されるおそれがあります。万一途中で止まっても、メッセージは可視性タイムアウトの後にキューに戻って再試行されます。第5回で、請求書発行のジョブを「発行中の請求だけを処理する」ように作ったのは、このような再実行があっても二重に発行しないためです。
📰 出典:タスク定義パラメータ(stopTimeout)(Amazon ECS デベロッパーガイド)
scheduler サービス:常に1台だけ動かす
infra/terraform/ecs_scheduler.tf を新しく作ります。
# infra/terraform/ecs_scheduler.tf
# scheduler サービス:routes/console.php の定期実行(締め処理・期限超過チェック)を動かす(第10回)
#
# 常に 1 台だけ動かす。デプロイ時も「古いタスクを止めてから新しいタスクを起動する」設定にして、
# 2 台が同時に動く時間を作らない。万一重なっても、各スケジュールの onOneServer() が
# キャッシュ(CACHE_STORE=database)のロックで 1 台だけに実行させる。
resource "aws_ecs_task_definition" "scheduler" {
family = "${local.name_prefix}-scheduler"
requires_compatibilities = ["FARGATE"]
network_mode = "awsvpc"
cpu = 256
memory = 512
execution_role_arn = aws_iam_role.ecs_task_execution.arn
task_role_arn = aws_iam_role.ecs_task.arn
runtime_platform {
operating_system_family = "LINUX"
cpu_architecture = "X86_64"
}
container_definitions = jsonencode([
merge(local.php_container_base, {
name = "scheduler"
command = ["php", "artisan", "schedule:work"]
logConfiguration = {
logDriver = "awslogs"
options = {
awslogs-group = aws_cloudwatch_log_group.ecs["scheduler"].name
awslogs-region = var.region
awslogs-stream-prefix = "scheduler"
}
}
}),
])
tags = { Name = "${local.name_prefix}-scheduler" }
}
resource "aws_ecs_service" "scheduler" {
name = "scheduler"
cluster = aws_ecs_cluster.main.id
task_definition = aws_ecs_task_definition.scheduler.arn
desired_count = 1 # 変数にしない(2 台以上にする意味がない)
launch_type = "FARGATE"
network_configuration {
subnets = local.app_network_configuration.subnets
security_groups = local.app_network_configuration.security_groups
assign_public_ip = local.app_network_configuration.assign_public_ip
}
# デプロイ時は古いタスクを先に止める(0%)→ 新しいタスクを 1 台起動(最大 100%)
# 入れ替えの 1〜2 分は定期実行が止まるが、schedule:work は毎分その時刻の予定を確認するだけなので、
# 実行時刻ちょうどに入れ替えが重なった場合だけその回が飛ぶ(締め処理の時刻にはデプロイしない運用にする)
deployment_minimum_healthy_percent = 0
deployment_maximum_percent = 100
tags = { Name = "${local.name_prefix}-scheduler" }
}
スケジューラが2台動くと、締め処理が2回走ってしまいます。web や worker と違って、デプロイ時は「古いタスクを先に止める」設定にしました。さらに、第5回で各スケジュールに付けた onOneServer() が、DB のキャッシュのロックを使って1台だけに実行させるので、二重の備えになります。
代わりに、入れ替えの間の1〜2分はスケジューラが止まります。毎日1時・毎月1日6時のような処理の時刻にはデプロイしない、という運用ルールで補います。
マイグレーションは専用のタスクで1回だけ
infra/terraform/ecs_migrate.tf を新しく作ります。
# infra/terraform/ecs_migrate.tf
# マイグレーション用の one-off タスク定義(第10回)
#
# サービスにはせず、デプロイの前に 1 回だけ RunTask で起動する(第11回で GitHub Actions から実行)。
# web の起動時に migrate を流さないのは、2 台以上が同時に起動したときに同じマイグレーションを
# 並行して実行してしまうのを避けるため。また、失敗したときにデプロイそのものを止められる。
#
# aws ecs run-task --cluster <cluster> --task-definition <family> --launch-type FARGATE \
# --network-configuration "$(terraform output -raw migrate_network_configuration)"
resource "aws_ecs_task_definition" "migrate" {
family = "${local.name_prefix}-migrate"
requires_compatibilities = ["FARGATE"]
network_mode = "awsvpc"
cpu = 256
memory = 512
execution_role_arn = aws_iam_role.ecs_task_execution.arn
task_role_arn = aws_iam_role.ecs_task.arn
runtime_platform {
operating_system_family = "LINUX"
cpu_architecture = "X86_64"
}
container_definitions = jsonencode([
merge(local.php_container_base, {
name = "migrate"
# --force:APP_ENV=production での確認プロンプトを出さずに実行する
command = ["php", "artisan", "migrate", "--force"]
logConfiguration = {
logDriver = "awslogs"
options = {
awslogs-group = aws_cloudwatch_log_group.ecs["migrate"].name
awslogs-region = var.region
awslogs-stream-prefix = "migrate"
}
}
}),
])
tags = { Name = "${local.name_prefix}-migrate" }
}
AWS に反映するときは、第9回の「初回のデプロイ手順」の0・2・4と同じく、変更をコミットして新しいタグでイメージを作り直し(AWS SDK を追加したため)、terraform.tfvars の image_tag を新しいタグにして apply します。
実行は AWS CLI で行います。ネットワークの指定はそのまま渡せる形で outputs.tf に出力しています(infra/terraform で実行)。
NETCONF=$(docker run --rm -v $PWD:/w -w /w -v $HOME/.aws:/root/.aws:ro -e AWS_PROFILE=<プロファイル名> \
hashicorp/terraform:1.11.4 output -raw migrate_network_configuration)
aws ecs run-task --cluster admin-stg --task-definition admin-stg-migrate --launch-type FARGATE \
--network-configuration "$NETCONF"
# 終了を待って、終了コードが 0 かを確認する
aws ecs wait tasks-stopped --cluster admin-stg --tasks <上のコマンドが返した taskArn>
aws ecs describe-tasks --cluster admin-stg --tasks <taskArn> --query 'tasks[0].containers[0].exitCode'
これで第9回ではできなかったログイン画面の表示ができるようになります。最初の管理者ユーザーは、本番イメージにシーダー用のパッケージが入っていないため、第12回で説明する ECS Exec などで作成します。
変数・出力・変数の例を追加する
worker の台数・CPU・メモリを変数にし、キューの URL やマイグレーション用の値を出力します。第9回までの3つのファイルに、次の変更を加えます(+ が追加、- が削除)。
--- a/infra/terraform/variables.tf
+++ b/infra/terraform/variables.tf
@@ -162,3 +162,22 @@ variable "enable_container_insights" {
type = bool
default = false
}
+
+# ---------- worker(第10回) ----------
+variable "worker_cpu" {
+ description = "worker タスクの CPU(1024 = 1 vCPU)"
+ type = number
+ default = 256
+}
+
+variable "worker_memory" {
+ description = "worker タスクのメモリ(MiB)"
+ type = number
+ default = 512
+}
+
+variable "worker_desired_count" {
+ description = "worker タスクの台数。ジョブが溜まりやすければ増やす"
+ type = number
+ default = 1
+}
--- a/infra/terraform/outputs.tf
+++ b/infra/terraform/outputs.tf
@@ -69,3 +69,29 @@ output "ecs_task_role_arn" {
description = "ECS タスクロール(アプリ用)の ARN"
value = aws_iam_role.ecs_task.arn
}
+
+output "sqs_queue_url" {
+ description = "ジョブのキューの URL(SQS_QUEUE)"
+ value = aws_sqs_queue.jobs.url
+}
+
+output "sqs_dlq_url" {
+ description = "デッドレターキューの URL"
+ value = aws_sqs_queue.jobs_dlq.url
+}
+
+output "migrate_task_definition_family" {
+ description = "マイグレーション用タスク定義のファミリー名(RunTask で指定する)"
+ value = aws_ecs_task_definition.migrate.family
+}
+
+output "migrate_network_configuration" {
+ description = "aws ecs run-task の --network-configuration にそのまま渡せる値(第10回)"
+ value = jsonencode({
+ awsvpcConfiguration = {
+ subnets = local.app_network_configuration.subnets
+ securityGroups = local.app_network_configuration.security_groups
+ assignPublicIp = "DISABLED"
+ }
+ })
+}
--- a/infra/terraform/terraform.tfvars.example
+++ b/infra/terraform/terraform.tfvars.example
@@ -42,3 +42,8 @@ web_memory = 1024
web_desired_count = 2
log_retention_days = 30
enable_container_insights = false
+
+# ---------- worker(第10回) ----------
+worker_cpu = 256
+worker_memory = 512
+worker_desired_count = 1
ローカルで SQS 互換のサーバーを使う準備
AWS の SQS の代わりに、SQS 互換のサーバー(ElasticMQ)をローカルで動かして確かめます。第6回の compose.prod.yaml に重ねて使う compose.sqs.yaml と、ElasticMQ の設定ファイルを新しく作ります。
# compose.sqs.yaml
# 本番用イメージのキューを SQS 互換サーバー(ElasticMQ)に切り替えてローカルで確認する(第10回)
# docker compose -f compose.prod.yaml -f compose.sqs.yaml up -d
#
# AWS の認証情報はダミー(ElasticMQ は検証しない)。本番の ECS ではタスクロールの権限を使い、キーは設定しない。
x-sqs-env: &sqs-env
QUEUE_CONNECTION: sqs
SQS_ENDPOINT: http://elasticmq:9324
SQS_QUEUE: http://elasticmq:9324/000000000000/admin-local-jobs
AWS_DEFAULT_REGION: ap-northeast-1
AWS_ACCESS_KEY_ID: local-dummy
AWS_SECRET_ACCESS_KEY: local-dummy
services:
app:
environment: *sqs-env
depends_on:
- elasticmq
queue:
environment: *sqs-env
command: ["php", "artisan", "queue:work", "sqs", "--sleep=3", "--tries=3", "--max-time=3600"]
depends_on:
- elasticmq
scheduler:
environment: *sqs-env
depends_on:
- elasticmq
elasticmq:
image: softwaremill/elasticmq-native:1.6.12
volumes:
- ./docker/local/elasticmq.conf:/opt/elasticmq.conf:ro
# docker/local/elasticmq.conf
# ローカル確認用の SQS 互換サーバー(ElasticMQ)の設定(第10回)
# 本番の SQS(infra/terraform/sqs.tf)と同じく、可視性タイムアウト 90 秒・5 回受信で DLQ へ移す
include classpath("application.conf")
queues {
admin-local-jobs {
defaultVisibilityTimeout = 90 seconds
receiveMessageWait = 10 seconds
deadLettersQueue {
name = "admin-local-jobs-dlq"
maxReceiveCount = 5
}
}
admin-local-jobs-dlq {}
}
ローカル確認用の設定がイメージに入らないよう、.dockerignore にも追加します(+ が追加、- が削除)。
--- a/.dockerignore
+++ b/.dockerignore
@@ -22,6 +22,7 @@ tests
.phpunit.result.cache
infra
docker/dev
+docker/local
compose*.yaml
Dockerfile
.dockerignore
動作確認の方法
# テスト
docker compose run --rm --no-deps app php artisan test
# 本番用イメージ+SQS 互換サーバー(ElasticMQ)で確認
docker build --target app -t admin-app . && docker build --target web -t admin-web .
docker compose -f compose.prod.yaml -f compose.sqs.yaml up -d mysql elasticmq
docker compose -f compose.prod.yaml -f compose.sqs.yaml run --rm app php artisan migrate --force
docker compose -f compose.prod.yaml -f compose.sqs.yaml up -d
docker compose -f compose.prod.yaml -f compose.sqs.yaml logs -f queue
本番用イメージは AWS SDK を追加した後のコードで作り直してから試します。筆者の環境で確認したことは次のとおりです。
php artisan testは 68件すべて成功(SQS の接続設定と、timeout と可視性タイムアウトの関係のテストを追加)- 請求の発行をキューに積むと、キューの件数が 1 → ワーカーのログに
請求書を発行しました→ 請求が発行済みになり、キューの件数が 0 に戻る docker compose stop queueでワーカーが終了コード 0 で止まる(SIGTERM での正常終了)- 削除されないメッセージを5回受信すると、DLQ に移る(ElasticMQ でも可視性タイムアウト 90 秒・5回で DLQ の設定にしてある)
- Terraform は
fmt -check・validateが成功し、AWS に接続しないplanでPlan: 67 to add(第9回の58件に、キュー2つ・DLQ の許可設定・SQS の権限・worker と scheduler のタスク定義とサービス・migrate のタスク定義の9件が追加)
AWS 上での確認(SQS のメッセージ数の増減、タスクロールでの接続、aws ecs run-task での migrate のログ、ECS がタスクを止めるときに SIGTERM から stopTimeout までに終了すること)は、AWS アカウントがないため行っていません。ElasticMQ は SQS の動きを再現するためのもので、本物の SQS とすべて同じとは限りません。
つまずきやすい点・セキュリティ上の注意
- ワーカーは古いコードのまま動き続ける:
queue:workはコードを読み込んだまま動くので、新しいイメージにしたら必ずサービスを更新(再デプロイ)します。第11回の CI では、web と一緒に worker・scheduler も更新します。 - DB のパスワードの自動ローテーション:第8回で触れたとおり、起動したままのタスクは古いパスワードを持ち続けます。ワーカーは
--max-time=3600で1時間ごとに入れ替わるため新しい値を読み込みますが、web と scheduler は再デプロイが必要です。 - ジョブの中身に秘密情報を入れない:SQS のメッセージには、ジョブのクラス名と引数(モデルの ID など)が入ります。サーバー側の暗号化(
sqs_managed_sse_enabled)はしていますが、メッセージ自体にパスワードなどを載せないようにします。 - 締め処理の時刻とデプロイ:scheduler の入れ替え中に予定時刻が来ると、その回は実行されません。処理の時刻を運用チームと共有しておきます。
発注者向けメモ:裏で動く処理は「止まったら誰が気づくか」を決める
ワーカーとスケジューラは画面が無いため、止まっても利用者からの問い合わせでは気づけません。開発を依頼するときは、次の点を仕様として決めておくと安心です。
| 決めること | 決めないと起きること |
|---|---|
| ジョブが失敗したときの扱い(自動で再試行する回数、最終的に失敗したら誰に知らせるか) | 請求書が発行されないまま、月末に発覚する |
| 定期処理が動かなかったときの検知と、手動で再実行する手順 | 締め処理が漏れ、翌月に手作業で修正する |
| ワーカーの台数(画面とは別) | 月初に処理が溜まり、発行まで時間がかかる。逆に常に多いと費用が増える |
| デプロイしてはいけない時間帯 | 締め処理の時刻にデプロイして、その回が飛ぶ |
費用の面では、worker と scheduler も Fargate のタスクとして常に動くので、台数 × CPU・メモリ × 時間の費用が発生します。SQS は使った分(リクエスト数)の料金で、この規模の管理画面では大きな割合にはなりにくい部品です。
開発会社への質問例です。
- 「ジョブが失敗したら、誰にどうやって通知されますか?手動でやり直す手順はありますか?」
- 「定期処理が実行されたかどうかは、どこで確認できますか?」
- 「デプロイの途中で処理中のジョブはどうなりますか?二重に実行されることはありませんか?」
- 「データベースの変更(マイグレーション)は、いつ・どうやって本番に反映しますか?失敗したらどうなりますか?」
まとめと次回予告
第10回では、画面の裏で動く処理を ECS に載せました。
- キューを SQS に切り替え、可視性タイムアウト(90秒)をジョブの timeout(60秒)より長くする
- 失敗したジョブは Laravel の
failed_jobs、ワーカーごと落ちたものは DLQ に行く - worker は SIGTERM で処理中のジョブを終えてから止まり、
stopTimeoutはジョブの timeout より長くする - scheduler は常に1台、デプロイ時も同時に2台にならない設定にし、
onOneServer()で二重に守る - マイグレーションは専用のタスク定義を RunTask で1回だけ実行する
次回は「GitHub Actions で CI/CD:OIDC でキーを持たずにデプロイ」です。テスト → イメージの build と push → マイグレーション → web・worker・scheduler のデプロイまでを、AWS のアクセスキーを使わずに自動化します。
この連載の記事一覧
この記事は連載「Laravel+Vue.jsで作る管理画面をECSで動かす」の1回です。連載のほかの回は次のとおりです(連載の一覧ページ)。
- 【Laravel+Vue.jsで作る管理画面をECSで動かす 第1回】全体像と開発環境:Laravel 12+Vue 3 スターターキットを Docker で動かす
- 【Laravel+Vue.jsで作る管理画面をECSで動かす 第2回】顧客マスタの一覧と登録:FormRequest でバリデーションする
- 【Laravel+Vue.jsで作る管理画面をECSで動かす 第3回】ロールと Policy:誰が何をできるかをコードで決める
- 【Laravel+Vue.jsで作る管理画面をECSで動かす 第4回】案件管理と一覧画面の作り込み:検索・並べ替え・ページング
- 【Laravel+Vue.jsで作る管理画面をECSで動かす 第5回】請求と非同期処理:キューとスケジューラをローカルで動かす
- 【Laravel+Vue.jsで作る管理画面をECSで動かす 第6回】本番用コンテナイメージを作る:マルチステージ Dockerfile
- 【Laravel+Vue.jsで作る管理画面をECSで動かす 第7回】Terraform の土台とネットワーク:state 管理と VPC
- 【Laravel+Vue.jsで作る管理画面をECSで動かす 第8回】RDS for MySQL と秘密情報:パスワードをコードに書かない
- 【Laravel+Vue.jsで作る管理画面をECSで動かす 第9回】ECR・ECS on Fargate・ALB:管理画面をインターネットに公開する
- 【Laravel+Vue.jsで作る管理画面をECSで動かす 第10回】キューワーカーとスケジューラを ECS で動かす(この記事)
- 【Laravel+Vue.jsで作る管理画面をECSで動かす 第11回】GitHub Actions で CI/CD:OIDC でキーを持たずにデプロイ
- 【Laravel+Vue.jsで作る管理画面をECSで動かす 第12回】運用編:ログ・監視・スケーリング・切り戻し










コメント
コメント一覧 (2件)
[…] 前回(第10回:キューワーカーとスケジューラを ECS で動かす)で、web・worker・scheduler のサービスと、マイグレーション用のタスク定義がそろいました。今回はそれを自動で更新する仕組みを作ります。 […]
[…] キューワーカーとスケジューラを ECS で動かす […]