MENU

問い合わせ

    お問い合わせ


    【Laravel+Vue.jsで作る管理画面をECSで動かす 第10回】キューワーカーとスケジューラを ECS で動かす

    第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 sqs1台〜(ジョブの量で決める)
    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.lockSQS を使うための AWS SDK for PHP を追加
    config/queue.phpSQS の設定(キューの URL、ローカル確認用の接続先)
    compose.sqs.yaml / docker/local/elasticmq.confSQS 互換サーバーでのローカル確認用

    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回です。連載のほかの回は次のとおりです(連載の一覧ページ)。

    システム制作・運用・保守のお問い合わせはこちら

      お問い合わせ


      よかったらシェアしてね!
      • URLをコピーしました!
      • URLをコピーしました!

      この記事を書いた人

      株式会社THIRD HERO代表取締役 朝野貴朗
      Webシステム開発を中心に、toC向けサービスサイトの運営、ツール開発などを行ってまいりました。

      コメント

      コメント一覧 (2件)

      目次