Lambdaとコールドスタート — 最初の1回だけ3秒かかる

Lambdaとコールドスタート。関数のブロックとストップウォッチ、起動を表すランプ。

私は本線の記事で、Lambda に関数を1つ置いて、呼んで、JSON が返ってきたところまでやりました。

前回: DynamoDBの設計とキー — あとから条件を足せない

これは【深掘り】の記事です。本線の順路ではありません。 「サーバーレスとは何か」の入門は、本線の 待っている時間に課金されない — サーバーレスとLambda にあります。 入門はあちら、ここは実務で詰まる所です。 この記事は「関数を置いて呼べた」の次の日に殴られる話だけを扱います。 飛ばしても本線は進めます。

このシリーズは、読者にアカウントを作らせません。 触るのは LocalStack と、aws CLI の --endpoint-url だけです。 課金が発生する操作は一切しません。 料金は具体的な金額を書きません(変わるので、書いた瞬間に嘘になります)。 何に対して課金されるかという構造だけを書き、数字は公式の料金ページ(Lambda / API Gateway)を見てください。 コマンドは VM の中(Ubuntu Server)で打ちます。 最後に docker compose down -v で全部消します。 なお LocalStack は2026年3月23日から1つのイメージに統合され、それ以降の版は起動に auth token(LocalStack のアカウントで取得。無料プランあり)が必要になりました。 この記事では、更新が止まった旧系統の localstack/localstack:3 を固定して使い、アカウントを作らずに進めます。旧イメージの固定は練習用の短期的な手段です(更新が来ず、修正済みの脆弱性が残りうるため)。新しい版を使う場合は、取得した token を LOCALSTACK_AUTH_TOKEN 環境変数に設定します。

最初に正直に書いておきます。 Lambda は LocalStack のコミュニティ版で「本当に動きます」。 関数を作って、呼んで、出力を読めます。 ただし LocalStack は関数をコンテナとして起動するので、/var/run/docker.sock をマウントしないと動きません。 そして コミュニティ版で再現できないものが3つあります。 メモリ設定によるCPU割り当ての変化・プロビジョンド同時実行の実体・カスタムランタイムの安定動作です。 その3つは、Node.js で同じ挙動を手元に作り直して確かめます。 どこが本物でどこが再現かは、その都度書きます。


console.log を書いて、CloudWatch にログが出て、「サーバーを立てなくても動く」と分かって、そこで満足していました。 問題は、その次に作った小さな機能で起きました。

社内向けの、1日100回くらいしか呼ばれない画像のサムネイル生成です。 EC2 を1台常時動かすのは無駄だと思ったので、Lambda にしました。設計としては正しかったと思います。

動かしてみて、最初に言われたのがこれです。

「たまに、めちゃくちゃ遅いときがあるんだけど」

私は再現できませんでした。 自分で連打すると、いつも 200ms 前後で返ってきます。 言われた通りに、20分くらい放置してから1回だけ呼んでみて、やっと分かりました。

実行時間: 3180 ms

連打すると速く、間を空けると遅い。

当時の私は「AWS が空いている時間帯かどうかの問題だろう」と思っていました。 全く違いました。


2つ目は、もっと質が悪い出方をしました。

同じアカウントに、全く関係のない別の関数がありました。 定時に走るバッチです。 そのバッチが動き出した日から、サムネイル生成のほうが不定期に失敗するようになりました。

TooManyRequestsException: Rate Exceeded.

コードは1文字も変えていません。 サムネイル関数の設定も変えていません。 それでも落ちました。 原因は、隣の関数が同時実行の枠を全部使い切っていたことでした。

Lambda の同時実行数は、関数ごとではなくアカウント全体(リージョン単位)で共有されています。 1つの関数が食い潰すと、無関係な関数まで動かなくなります。

これは、本線の 落ちても全部は止めない — サーキットブレーカと縮退 で出てきた「バルクヘッド(隔壁)」の話そのものでした。 船の底を仕切っていないと、1箇所の浸水で船全体が沈む。 Lambda は、既定では仕切りが無い状態です。


3つ目は、自分でやらかしました。

関数のコードを直して保存した瞬間に、本番の挙動が変わりました。 テストのつもりで書き換えたコードが、そのまま本番に出ていました。

$LATEST を本番に向けていたからです。

この3つを、この記事で1つずつ潰します。 どれも「動かす」だけなら出会わないものです。


対象レベル: 中級〜上級 / 区分: 発展

目次

この記事でわかること

  • 最初の1回が遅いのは、AWS が混んでいるからではない。 コンテナの確保 + ランタイムの起動 + 初期化コードの実行が、初回だけ実行時間に乗る。内訳は分解できる
  • ハンドラの外に書いたコードは、次の呼び出しでも生き残る。 だから DB接続やSDKクライアントはハンドラの外で作る。逆に グローバル変数に利用者のデータを入れると、次に来た別人に見える
  • メモリを増やすとCPUも増えるので、速くなって、結果的に安くなることがある。 「メモリは最小が最安」は間違い。実行時間 × メモリで決まる
  • 同時実行の上限はアカウント全体で共有されている。 1つの関数が食い潰すと、他の関数まで止まる。予約済み同時実行数で関数ごとに枠を切れるが、予約した分は他から使えなくなる(両刃)
  • $LATEST を本番に向けてはいけない。 保存した瞬間に本番が変わる。バージョンは不変のスナップショット、エイリアスはそれを指す名前
  • 15分を超える処理は Lambda に向かない。 上限は他にもあり、先に表で知っておかないと設計をやり直すことになる
  • 常時動かすなら EC2 のほうが安い。 Lambda が効くのは「たまにしか動かない」「波が激しい」もの

この記事でやること

  1. LocalStack を立てて、zip を作って create-function し、実際に invoke する。event と context の中身を出力で見る
  2. 同じ関数を、間隔を空けて呼んだときと連続で呼んだときで実行時間を比べ、コールドスタートを実測する。内訳を表で分解し、対策を4つ確かめる
  3. カウンタをハンドラの外に置いて、連続で呼ぶと値が増えることを目で見る
  4. レイヤーで共通ライブラリを切り出し、デプロイパッケージを小さくする
  5. バージョンを発行してエイリアス prod を向け、加重で10%だけ新バージョンに流す
  6. 予約済み同時実行数を1に絞り、並列で叩いてスロットリングを再現する
  7. HTTP API・関数URL・EventBridge のスケジュール実行を作り、判断表で締める

先に知る言葉

基本的な言葉は用語集にもまとめてあります。

言葉いまの理解でいい説明
ハンドラLambda が呼び出す入口の関数。ファイル名.関数名 で指定する(index.handler など)
実行環境関数1つ分のコンテナ。1つの実行環境は、同時には1リクエストしか処理しない。使い回される
コールドスタート使える実行環境が無くて、新しく用意するところから始まる呼び出し。初回だけ余分に時間がかかる
$LATEST最後に保存したコードを指す、書き換わる参照。本番に向けてはいけない
バージョンpublish-version で作る不変のスナップショット。番号が付き、あとから中身は変わらない
エイリアスバージョンを指す別名(prod など)。向き先だけ差し替えれば、呼ぶ側は変えなくていい
レイヤー複数の関数で共有するライブラリの入れ物。関数本体の zip から外に出せる
同時実行数同じ瞬間に走っている実行環境の数。リクエスト数ではない。アカウント全体で上限がある
スロットリング上限に当たって呼び出しが弾かれること。同期呼び出しでは TooManyRequestsException が返る
DLQ / 送信先非同期呼び出しが最後まで失敗したときの、行き先。ここが無いと黙って消える
GB秒課金の単位。確保したメモリ(GB) × 実行時間(秒)。メモリだけでも時間だけでもない

① 関数を作って、実際に呼ぶ

準備 — LocalStack を立てる

RDS の回と違い、Lambda では docker-compose.yml に1行足す必要があります。

bash
$ mkdir -p ~/awslab/lambda
$ cd ~/awslab/lambda
$ nano docker-compose.yml
services:
  localstack:
    image: localstack/localstack:3
    ports:
      - "4566:4566"
    environment:
      - SERVICES=lambda,iam,logs,apigateway,events,s3,sts
      - DEBUG=0
      - LAMBDA_REMOVE_CONTAINERS=1
    volumes:
      - "./volume:/var/lib/localstack"
      - "/var/run/docker.sock:/var/run/docker.sock"

最後の1行が本題です。 LocalStack は、Lambda 関数を「LocalStack の中で」動かしているのではありません。 ホストの Docker に対して、関数用のコンテナをもう1つ立てるよう頼んでいます。 そのために、ホストの Docker ソケットを LocalStack コンテナへ渡します。 これを書き忘れると、create-function は成功するのに invoke だけが失敗します。 私はここで30分溶かしました。

bash
$ docker compose up -d
$ docker compose ps
NAME         IMAGE                     STATUS                    PORTS
localstack   localstack/localstack:3   Up 24 seconds (healthy)   0.0.0.0:4566->4566/tcp

(healthy) になるまで待ちます。

bash
$ aws configure set aws_access_key_id test
$ aws configure set aws_secret_access_key test
$ aws configure set region ap-northeast-1
$ alias awsl='aws --endpoint-url=http://localhost:4566'

本物のアクセスキーを絶対にここに入れないでください。 LocalStack は認証情報を見ません。 この記事は最初から最後まで、本物の AWS には1度も繋ぎません。


実行ロールを作る

Lambda は「誰の権限で動くのか」を先に決めないと作れません。 これは AccessDeniedに全権限で答えない — AWS深掘り でやった信頼ポリシーの話です。

bash
$ mkdir -p ~/awslab/lambda/fn
$ cd ~/awslab/lambda/fn
$ nano trust.json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "Service": "lambda.amazonaws.com" },
      "Action": "sts:AssumeRole"
    }
  ]
}

Principal が lambda.amazonaws.com なのが要点です。 「このロールを引き受けていいのは Lambda サービスだけ」という意味になります。

bash
$ ROLE=$(awsl iam create-role \
    --role-name lab-lambda-role \
    --assume-role-policy-document file://trust.json \
    --query 'Role.Arn' --output text)

$ echo $ROLE
arn:aws:iam::000000000000:role/lab-lambda-role

ハンドラを書く

bash
$ nano index.mjs
// --- ここは「初期化コード」。実行環境が作られたとき1回だけ走る ---
const BOOTED_AT = Date.now();
console.log("INIT: this line runs only when a new execution environment starts");

export const handler = async (event, context) => {
  const body = {
    // event = 呼び出し側が渡してきた入力そのもの
    receivedEvent: event,

    // context = Lambda が渡してくる実行時の情報
    functionName: context.functionName,
    functionVersion: context.functionVersion,
    memoryLimitInMB: context.memoryLimitInMB,
    awsRequestId: context.awsRequestId,

    // タイムアウトまであと何ミリ秒か
    remainingMs: context.getRemainingTimeInMillis(),

    // この実行環境が作られてから何ミリ秒経ったか
    ageOfEnvironmentMs: Date.now() - BOOTED_AT,
  };
  return { statusCode: 200, body };
};

BOOTED_AT と console.log を、ハンドラの外に置いたのがポイントです。 ここが「初期化コード」で、②と③で主役になります。

bash
$ zip -q function.zip index.mjs
$ ls -l function.zip
-rw-rw-r-- 1 ubuntu ubuntu 812 Oct  7 10:14 function.zip

関数を作る

1行ずつ意味があるので、丸ごとコピーせずに読んでください。

bash
$ awsl lambda create-function \
    --function-name thumb \
    --runtime nodejs20.x \
    --handler index.handler \
    --role $ROLE \
    --zip-file fileb://function.zip \
    --timeout 10 \
    --memory-size 128 \
    --query 'FunctionArn' --output text
arn:aws:lambda:ap-northeast-1:000000000000:function:thumb
指定意味ここを間違えると
--runtime nodejs20.xどの言語のどのバージョンで動かすか古いランタイムは、いつか廃止される。放置すると更新を強制される。実際に nodejs20.x は、本物の AWS では2026年4月30日に廃止(deprecated)済みで、セキュリティ更新も保証されません。本物で新しく作るなら nodejs22.x か nodejs24.x を選びます。この記事の localstack/localstack:3 は nodejs22.x に対応していないため、練習では nodejs20.x のまま進めます
--handler index.handlerファイル名.エクスポート名ここが最頻出のミス。 ファイル名を変えたのに直し忘れると Cannot find module
--roleこの関数が名乗る権限権限不足は実行時に初めて分かる。作成時には通る
--zip-file fileb://file:// ではなく fileb://(バイナリ)file:// だと zip がテキストとして送られて壊れる
--timeout 10秒。既定は3秒既定のまま重い処理を置くと、3秒で切られる
--memory-size 128MB。CPU の割り当てもここで決まる②で詳しくやります

実際に呼ぶ

bash
$ awsl lambda invoke \
    --function-name thumb \
    --payload '{"userId":"u-01","width":320}' \
    --cli-binary-format raw-in-base64-out \
    out.json

$ cat out.json | python3 -m json.tool
{
    "statusCode": 200,
    "body": {
        "receivedEvent": {
            "userId": "u-01",
            "width": 320
        },
        "functionName": "thumb",
        "functionVersion": "$LATEST",
        "memoryLimitInMB": "128",
        "awsRequestId": "6b1f9c2e-4a70-4f38-9d55-2c8e1a07b3d4",
        "remainingMs": 9873,
        "ageOfEnvironmentMs": 41
    }
}

--cli-binary-format raw-in-base64-out を付けないと、--payload が base64 だと解釈されて弾かれます。 AWS CLI v2 の仕様で、v1 の記事をそのまま真似すると必ずここで詰まります。

読み取れることが4つあります。

  1. event は「呼び出し側が渡したJSONそのもの」。 Lambda が加工していません。API Gateway 経由だとここが全く違う形になります(⑧で見ます)
  2. functionVersion が $LATEST。 これが⑤で問題になります
  3. remainingMs が 9873。 --timeout 10 の 10000ms から、既に127ms使ったあとの残りです
  4. memoryLimitInMB が文字列の "128"。 数値ではありません。計算に使うなら Number() が要ります

getRemainingTimeInMillis() は飾りではありません。 外部APIを叩く前に「残り時間が2秒を切っていたら諦めて、あとで再開できる形で返す」という書き方ができます。 タイムアウトで強制終了されると、後始末のコードは1行も走りません。

if (context.getRemainingTimeInMillis() < 2000) {
  // 中途半端に始めない。次に回す
  return { statusCode: 202, body: { resumeFrom: cursor } };
}

ログも見ておきます。

bash
$ awsl logs describe-log-groups --query 'logGroups[*].logGroupName' --output text
/aws/lambda/thumb

ロググループは、関数を作ったときではなく、初めて呼ばれたときに作られます。 「ログが無い」と焦る前に、1回呼んでください。

スクリーンショットを撮ってください: 01_lambda_first_invoke.png out.json の中身が表示されている画面。functionVersion が $LATEST になっているところが写るようにします。


② コールドスタートを実測して分解する

冒頭の「たまに、めちゃくちゃ遅い」の正体です。

まず、連打と間隔空けで比べる

計測用の小さなスクリプトを書きます。

bash
$ cd ~/awslab/lambda/fn
$ nano bench.sh
bash
#!/bin/bash
  # 引数1: 呼び出し回数, 引数2: 呼び出しの間隔(秒)
  for i in $(seq 1 "$1"); do
    START=$(date +%s%3N)
    aws --endpoint-url=http://localhost:4566 lambda invoke \
      --function-name thumb \
      --payload '{"n":'"$i"'}' \
      --cli-binary-format raw-in-base64-out \
      /tmp/out.json > /dev/null
    END=$(date +%s%3N)
    AGE=$(python3 -c "import json;print(json.load(open('/tmp/out.json'))['body']['ageOfEnvironmentMs'])")
    echo "$i 回目: 往復 $((END-START)) ms / 環境の年齢 ${AGE} ms"
    sleep "$2"
  done
bash
$ chmod +x bench.sh

まず、間を空けずに5回連続で呼びます。

bash
$ ./bench.sh 5 0
1 回目: 往復 2841 ms / 環境の年齢 38 ms
2 回目: 往復 214 ms / 環境の年齢 2405 ms
3 回目: 往復 198 ms / 環境の年齢 2623 ms
4 回目: 往復 203 ms / 環境の年齢 2841 ms
5 回目: 往復 191 ms / 環境の年齢 3049 ms

1回目だけ 2841ms、2回目以降は 200ms 前後。 14倍の差です。

そして、右側の「環境の年齢」を見てください。 1回目だけ 38ms で、2回目以降はどんどん増えています。

これが決定的な証拠です。 1回目は「生まれたばかりの実行環境」で走り、2回目以降は「さっき生まれた同じ環境」が使い回されています。 BOOTED_AT はハンドラの外にあるので、環境が使い回されている間はリセットされません。

次に、間隔を空けて呼びます。

bash
$ ./bench.sh 3 300
1 回目: 往復 2795 ms / 環境の年齢 41 ms
2 回目: 往復 2733 ms / 環境の年齢 36 ms
3 回目: 往復 2761 ms / 環境の年齢 39 ms

3回とも遅く、3回とも「年齢が数十ms」です。 間を空けたぶん、前の実行環境が片付けられ、毎回作り直されていました。

「連打すると速く、間を空けると遅い」の答えがこれです。 AWS が混んでいるのではなく、使い回せる実行環境が残っているかどうかの差でした。 本物の AWS では、実行環境が片付けられるまでの時間は公表されていません。 数分〜十数分と言われますが、当てにしてはいけません。

LocalStack では待ち時間を短くするために sleep 300 にしていますが、本物で試すときも考え方は同じです。

スクリーンショットを撮ってください: 02_coldstart_compare.png ./bench.sh 5 0 の出力と ./bench.sh 3 300 の出力を、上下に並べた画面。 「環境の年齢」の列が、片方は増えていき、もう片方は毎回数十msに戻るところが写るようにします。


内訳を分解する

2841ms の中身は、1つの塊ではありません。 4つに分かれます。

段階何をしている初回のみか自分で減らせるか
① 実行環境の確保コンテナを立て、ネットワークを繋ぐ初回のみほぼできない(VPC接続やアーキテクチャの選択で多少変わる)
② コードのダウンロードと展開zip やレイヤーを持ってきて展開する初回のみできる。パッケージを小さくする(④)
③ ランタイムの起動Node.js 本体を起動する初回のみ言語の選択で変わる(実行ファイル1つの言語は速い)
④ 初期化コードの実行ハンドラの外の行を上から実行する初回のみできる。ここが一番効く(③)
⑤ ハンドラの実行handler の中身毎回普通の最適化

①〜④が「コールドスタート」で、⑤だけが「毎回の処理時間」です。

④がどれだけ効くかは、簡単に確かめられます。 初期化コードにわざと重い処理を入れます。

bash
$ nano slowinit.mjs
const BOOTED_AT = Date.now();

// わざと重い初期化(本物だと「巨大なJSONを読む」「SDKを大量にimportする」に相当)
let sum = 0;
for (let i = 0; i < 30_000_000; i++) sum += Math.sqrt(i) | 0;
const INIT_COST = Date.now() - BOOTED_AT;

export const handler = async (event, context) => ({
  statusCode: 200,
  body: { initCostMs: INIT_COST, ageOfEnvironmentMs: Date.now() - BOOTED_AT },
});

この for ループを、私の手元の Node.js v22 で単体で測ると 81ms でした。

work 3e7 ms: 81

手元の Node.js では 81ms のループが、128MB の Lambda では桁が変わります。 なぜかは、次の「メモリを増やすとCPUも増える」で説明します。


対策1 — 初期化をハンドラの外に出す(一番効く)

誤解しやすいのですが、「ハンドラの外に出す」は「初期化を速くする」ではありません。 「初期化を、毎回ではなく初回だけにする」です。

悪い書き方。

export const handler = async (event) => {
  // ⚠️ 呼ばれるたびに、毎回クライアントを作り直している
  const { S3Client } = await import("@aws-sdk/client-s3");
  const s3 = new S3Client({ region: "ap-northeast-1" });
  return await doWork(s3, event);
};

良い書き方。

// ⚠️ ここは初回だけ。2回目以降の呼び出しでは、この行は走らない
import { S3Client } from "@aws-sdk/client-s3";
const s3 = new S3Client({ region: "ap-northeast-1" });

export const handler = async (event) => {
  return await doWork(s3, event);
};
置き場所走る回数何を置くか
ハンドラの外実行環境1つにつき1回SDKクライアント・DB接続プール・設定の読み込み・正規表現のコンパイル
ハンドラの中呼び出しごとに毎回リクエストごとに変わるものだけ

DBコネクションは、必ずハンドラの外です。 中で作ると、呼び出しのたびに接続が増えて、 フェイルオーバーで接続が切れる — AWS深掘り でやった「接続数の上限」に一瞬で当たります。


対策2 — パッケージを小さくする

②の「ダウンロードと展開」は、zip の大きさにそのまま比例します。

bash
$ du -sh node_modules 2>/dev/null
64M	node_modules

64MB の node_modules を丸ごと上げると、初回だけその展開時間が乗ります。

やることは3つです。

・開発用の依存を入れない(npm ci --omit=dev)
・バンドラで1ファイルにまとめて、使っていないコードを落とす
・共通ライブラリはレイヤーに逃がす(④)

これは 1.2GBのイメージが50MBになる — Docker深掘り と全く同じ発想です。 「起動が遅いのは、起動時に運ぶものが多いから」 で、Lambda でも Docker でも変わりません。


対策3 — メモリを増やすと、速くなって安くなることがある

ここが、この記事で一番言いたいところです。

Lambda のメモリ設定は、メモリだけを決めているのではありません。 CPU の割り当ても、メモリに比例して決まります。 メモリを2倍にすると、CPU もおよそ2倍になります。

だから「メモリは最小の128MBが最安」は、CPUを使う処理では間違いです。

課金の単位は GB秒 = 確保したメモリ(GB) × 実行時間(秒) です。 同じCPU処理を、メモリ設定だけ変えて動かしたときの計算をしてみます。

メモリ設定実行時間確保メモリ(GB)GB秒128MBとの比
128 MB8000 ms0.1251.000—
256 MB4100 ms0.251.025ほぼ同じ
512 MB1800 ms0.50.900安い上に4.4倍速い
1024 MB900 ms1.00.900安い上に8.9倍速い
1769 MB800 ms1.7281.382ここから割高(1 vCPU に到達済み)

512MB と 1024MB は、128MB より「安くて、しかも速い」。 128MB を選んでいたのは、節約ではなく、ただ遅かっただけでした。

なぜ 1769MB から割高になるかというと、 その辺りで 1 vCPU 相当に届き、それ以上メモリを増やしても、シングルスレッドの処理は速くならないからです。 並列処理を書いていないコードは、コアが増えても使えません。

LocalStack のコミュニティ版では、これは再現できません。 LocalStack はメモリ設定に応じて CPU を絞る、ということをしていないので、 --memory-size を変えても実行時間はほとんど変わりません。 上の表は「本物ではこうなる」という構造の説明です。 本物で確かめるなら、AWS が公開している Lambda Power Tuning という道具があります(この記事では課金が発生するので使いません)。

手元で確かめられるのは、「CPUの量が変わると時間が変わる」という部分だけです。

bash
$ node -e 'const t=Date.now();let s=0;for(let i=0;i<3e7;i++)s+=Math.sqrt(i)|0;console.log(Date.now()-t,"ms");'
81 ms
bash
$ taskset -c 0 nice -n 19 node -e 'const t=Date.now();let s=0;for(let i=0;i<3e7;i++)s+=Math.sqrt(i)|0;console.log(Date.now()-t,"ms");'

taskset で1コアに縛ると、同じコードの実行時間が伸びます。 Lambda のメモリ設定は、これを連続的にやっているのと同じことです。


対策4 — プロビジョンド同時実行

「初回だけ遅い」を、お金で消す方法です。

bash
$ awsl lambda put-provisioned-concurrency-config \
    --function-name thumb \
    --qualifier prod \
    --provisioned-concurrent-executions 2

これは「常に2つの実行環境を、初期化まで済ませた状態で待たせておく」設定です。

普通の同時実行プロビジョンド同時実行
待機中の課金無いある(待っているだけで課金される)
コールドスタート起きる起きない(枠の中に収まっている限り)
何が嬉しいか安い応答時間が安定する
注意—$LATEST には設定できない。 バージョンかエイリアスが要る(⑤)

これを入れた瞬間、「待っている時間に課金されない」という Lambda の一番の長所を捨てています。 本線の記事のタイトルが 待っている時間に課金されない — サーバーレスとLambda なのは、そこが本質だからです。 常時2つ待たせるくらいなら、小さな EC2 を1台常時動かすほうが安いことがあります。 判断の材料は Lambda の料金ページ で確認してください。

LocalStack ではこの設定は「受け付けるが、実体は無い」ので、応答時間は変わりません。 ここも再現できない部分です。


③ ハンドラの外は使い回される — 目で見る

②で「使い回されている」と書きました。 本当にそうなのか、カウンタで確かめます。

bash
$ cd ~/awslab/lambda/fn
$ nano counter.mjs
// ⚠️ ハンドラの外。実行環境が生きている限り、この変数は残り続ける
let callCount = 0;
let lastUserId = null;
const BOOTED_AT = Date.now();

export const handler = async (event, context) => {
  callCount++;

  // ⚠️ わざと悪い書き方をしている。あとで理由を書く
  const previousUserId = lastUserId;
  lastUserId = event.userId;

  return {
    callCount,
    thisUserId: event.userId,
    previousUserIdSeenByThisEnvironment: previousUserId,
    ageOfEnvironmentMs: Date.now() - BOOTED_AT,
  };
};
bash
$ zip -q counter.zip counter.mjs

$ awsl lambda create-function \
    --function-name counter \
    --runtime nodejs20.x \
    --handler counter.handler \
    --role $ROLE \
    --zip-file fileb://counter.zip \
    --timeout 10 --memory-size 128 \
    --query 'FunctionName' --output text
counter

別々の利用者から、連続で4回呼ばれた状況を作ります。

bash
$ for U in alice bob carol dave; do
$   awsl lambda invoke --function-name counter \
      --payload '{"userId":"'"$U"'"}' \
      --cli-binary-format raw-in-base64-out /tmp/c.json > /dev/null
$   cat /tmp/c.json; echo
$ done
{"callCount":1,"thisUserId":"alice","previousUserIdSeenByThisEnvironment":null,"ageOfEnvironmentMs":37}
{"callCount":2,"thisUserId":"bob","previousUserIdSeenByThisEnvironment":"alice","ageOfEnvironmentMs":2418}
{"callCount":3,"thisUserId":"carol","previousUserIdSeenByThisEnvironment":"bob","ageOfEnvironmentMs":2596}
{"callCount":1,"thisUserId":"dave","previousUserIdSeenByThisEnvironment":null,"ageOfEnvironmentMs":1}

3つ読み取れます。

  1. callCount が 1, 2, 3 と増えている。 同じ実行環境が使い回されている証拠です
  2. bob の呼び出しから、alice の userId が見えている。 これが問題です
  3. 4回目だけ callCount が1に戻り、previous… も null、age も 1ms。 これは LocalStack が環境を作り直した回です(本物でも、混んでいれば別の環境に振られます)

ここが、この節で一番大事な話です。 「Lambda は毎回きれいな状態で始まる」は、間違いです。 前の呼び出しの、別の利用者のデータが、グローバル変数に残っています。

やってはいけない書き方の代表がこれです。

// ⚠️ 絶対にやってはいけない
let currentUser = null;              // 利用者のデータをグローバルに置く
let cachedAuthToken = null;          // 誰かのトークンを使い回す
const cart = [];                     // 呼び出しをまたいで貯まっていく

cart は、複数人ぶんの商品が1つの配列に混ざります。 cachedAuthToken は、別人のトークンで別人のデータを取ってきます。 これは机上の空論ではなく、私が「なぜかたまに他人の名前が出る」バグで実際に踏みました。

ハンドラの外に置いていいもの置いてはいけないもの
SDKクライアント・HTTPエージェントリクエストの利用者ID・氏名・メール
DB接続プール利用者ごとの認証トークン・セッション
設定値(環境変数から読んだもの)処理途中の作業配列・バッファ
コンパイル済みの正規表現・テンプレート「前回の結果」を前提にしたフラグ
利用者に依存しないキャッシュ利用者ごとのキャッシュ(キーに利用者IDを含めても、環境をまたぐと不整合になる)

判定の仕方は簡単です。 「この値が、次に来た知らない人に見えても平気か」 — 平気ならハンドラの外、駄目なら中です。

/tmp も同じです。 /tmp に書いたファイルも、同じ実行環境なら残っています。 一時ファイルを消さずに終わると、次の人が読めます。


④ レイヤー — 共通ライブラリを本体から外に出す

関数が3つあって、3つとも同じライブラリを使っているとします。 何もしないと、同じライブラリを3回アップロードし、3回展開することになります。

レイヤーは、それを1箇所にまとめる仕組みです。

作る

ディレクトリ構造が決まっています。 Node.js の場合は nodejs/node_modules/ の下です。

bash
$ mkdir -p ~/awslab/lambda/layer/nodejs/node_modules/labutil
$ cd ~/awslab/lambda/layer/nodejs/node_modules/labutil
$ nano index.mjs
export function ok(data) {
  return { statusCode: 200, body: JSON.stringify(data) };
}
export function fail(code, message) {
  return { statusCode: code, body: JSON.stringify({ message }) };
}
bash
$ nano package.json
{
  "name": "labutil",
  "version": "1.0.0",
  "type": "module",
  "main": "index.mjs"
}
bash
$ cd ~/awslab/lambda/layer
$ zip -qr layer.zip nodejs
$ unzip -l layer.zip
Archive:  layer.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
        0  10-07-2026 10:41   nodejs/
        0  10-07-2026 10:41   nodejs/node_modules/
        0  10-07-2026 10:41   nodejs/node_modules/labutil/
      201  10-07-2026 10:41   nodejs/node_modules/labutil/index.mjs
       78  10-07-2026 10:41   nodejs/node_modules/labutil/package.json

nodejs/ から始まっていることを必ず確認してください。 node_modules/ から始まる zip を上げると、関数からは見えません。 エラーも出ません。ただ Cannot find module になります。

bash
$ LAYER=$(awsl lambda publish-layer-version \
    --layer-name labutil \
    --description "shared helpers" \
    --compatible-runtimes nodejs20.x \
    --zip-file fileb://layer.zip \
    --query 'LayerVersionArn' --output text)

$ echo $LAYER
arn:aws:lambda:ap-northeast-1:000000000000:layer:labutil:1

末尾の :1 がレイヤーのバージョンです。 レイヤーは、公開するたびに番号が増えます。 上書きはできません。

使う

bash
$ cd ~/awslab/lambda/fn
$ nano uselayer.mjs
// レイヤーは /opt/nodejs/node_modules に展開されるので、普通の import で読める
import { ok, fail } from "labutil";

export const handler = async (event) => {
  if (!event.userId) return fail(400, "userId is required");
  return ok({ userId: event.userId, from: "layer" });
};
bash
$ zip -q uselayer.zip uselayer.mjs
$ ls -l uselayer.zip
-rw-rw-r-- 1 ubuntu ubuntu 391 Oct  7 10:44 uselayer.zip

関数本体の zip が 391 バイトです。 ライブラリを含んでいないからです。

bash
$ awsl lambda create-function \
    --function-name uselayer \
    --runtime nodejs20.x \
    --handler uselayer.handler \
    --role $ROLE \
    --zip-file fileb://uselayer.zip \
    --layers $LAYER \
    --timeout 10 --memory-size 128 \
    --query 'Layers[*].Arn' --output text
arn:aws:lambda:ap-northeast-1:000000000000:layer:labutil:1
bash
$ awsl lambda invoke --function-name uselayer \
    --payload '{"userId":"u-99"}' \
    --cli-binary-format raw-in-base64-out /tmp/l.json > /dev/null
$ cat /tmp/l.json
{"statusCode":200,"body":"{\"userId\":\"u-99\",\"from\":\"layer\"}"}

エラー側も確認します。

bash
$ awsl lambda invoke --function-name uselayer \
    --payload '{}' \
    --cli-binary-format raw-in-base64-out /tmp/l.json > /dev/null
$ cat /tmp/l.json
{"statusCode":400,"body":"{\"message\":\"userId is required\"}"}

レイヤーの中身が、関数から普通の import で使えています。

何をレイヤーに入れるか

レイヤーに入れる入れない
複数の関数で共通のヘルパー1つの関数しか使わないコード(管理が増えるだけ)
滅多に更新しない依存(画像処理・PDF生成など重いもの)毎日直すビジネスロジック(更新のたびにレイヤー発行が要る)
ランタイムに無いバイナリ(ffmpeg など)秘密の値。レイヤーは他アカウントに共有できてしまう
社内共通の監視・ログ整形関数ごとに違うバージョンが要るライブラリ

上限があります。

項目上限
1つの関数に付けられるレイヤー5つまで
関数本体 + 全レイヤーの展開後の合計250 MB

250MB は「zipの大きさ」ではなく「展開後の大きさ」です。 zip で 40MB だから大丈夫、と思っていると当たります。 unzip -l の Length 列の合計で見てください。 これを超えるなら、zip をやめてコンテナイメージで動かす選択肢になります(⑦)。

レイヤーは、更新の速さも変えます。

レイヤー無し: 関数を直すたびに 64MB を毎回アップロード
レイヤー有り: 関数を直すたびに   1KB を毎回アップロード

CI/CD の1回あたりの時間が、そのまま変わります。


⑤ バージョンとエイリアス — $LATEST を本番に向けない

冒頭で書いた「保存した瞬間に本番が変わった」の話です。

3つの違いを先に

呼び方何を指すか中身は変わるか本番に向けていいか
$LATEST最後に保存したコード変わる(保存するたび)駄目
バージョン(1, 2, …)発行した瞬間のスナップショット絶対に変わらない向けられるが、番号が呼ぶ側に漏れる
エイリアス(prod など)バージョンを指す名前指す先を差し替えられるこれを向ける

エイリアスが要る理由は1つです。 呼ぶ側(API Gateway やイベント元)の設定を変えずに、中身のバージョンだけ差し替えたいからです。

「名前は変えず、向き先だけ変える」という、DNS のときと全く同じ考え方です。

バージョンを発行する

bash
$ cd ~/awslab/lambda/fn

$ awsl lambda publish-version \
    --function-name thumb \
    --description "v1: first release" \
    --query '[Version,Description]' --output text
1	v1: first release

コードを直して、もう1つ発行します。

bash
$ sed -i 's/statusCode: 200/statusCode: 201/' index.mjs
$ zip -q function.zip index.mjs

$ awsl lambda update-function-code \
    --function-name thumb \
    --zip-file fileb://function.zip \
    --query 'Version' --output text
$LATEST

update-function-code が返したのは $LATEST です。 この時点で、$LATEST を呼んでいた人には、もう新しいコードが出ています。

bash
$ awsl lambda publish-version \
    --function-name thumb \
    --description "v2: statusCode 201" \
    --query '[Version,Description]' --output text
2	v2: statusCode 201

バージョン 1 を指定して呼んでみます。

bash
$ awsl lambda invoke --function-name thumb:1 \
    --payload '{"n":1}' --cli-binary-format raw-in-base64-out /tmp/v1.json > /dev/null
$ python3 -c "import json;d=json.load(open('/tmp/v1.json'));print(d['statusCode'], d['body']['functionVersion'])"
200 1
bash
$ awsl lambda invoke --function-name thumb:2 \
    --payload '{"n":1}' --cli-binary-format raw-in-base64-out /tmp/v2.json > /dev/null
$ python3 -c "import json;d=json.load(open('/tmp/v2.json'));print(d['statusCode'], d['body']['functionVersion'])"
201 2

バージョン1は、コードを直したあとでも 200 のままです。 これが「不変のスナップショット」の意味です。

エイリアスを向ける

bash
$ awsl lambda create-alias \
    --function-name thumb \
    --name prod \
    --function-version 1 \
    --description "production" \
    --query '[Name,FunctionVersion]' --output text
prod	1
bash
$ awsl lambda invoke --function-name thumb:prod \
    --payload '{"n":1}' --cli-binary-format raw-in-base64-out /tmp/p.json > /dev/null
$ python3 -c "import json;d=json.load(open('/tmp/p.json'));print(d['statusCode'], d['body']['functionVersion'])"
200 1

thumb:prod を呼んでいる限り、update-function-code を何回やっても本番は動きません。 これが、冒頭の事故の答えです。

加重で 10% だけ新バージョンに流す(カナリア)

bash
$ awsl lambda update-alias \
    --function-name thumb \
    --name prod \
    --function-version 1 \
    --routing-config '{"AdditionalVersionWeights":{"2":0.1}}' \
    --query '[FunctionVersion,RoutingConfig]' --output json
[
    "1",
    {
        "AdditionalVersionWeights": {
            "2": 0.1
        }
    }
]

読み方は「基本はバージョン1、そのうち 0.1 = 10% をバージョン2に回す」です。 0.1 は「10%」で、1.0 にすると全部が2に行きます。

本当に分かれるか、20回呼んで数えます。

bash
$ for i in $(seq 1 20); do
$   awsl lambda invoke --function-name thumb:prod \
      --payload '{"n":'"$i"'}' --cli-binary-format raw-in-base64-out /tmp/w.json > /dev/null
$   python3 -c "import json;print(json.load(open('/tmp/w.json'))['body']['functionVersion'])"
$ done | sort | uniq -c
     18 1
      2 2

20回中2回だけバージョン2に行きました。 10% です。

LocalStack のコミュニティ版では、加重ルーティングの実装が本物と完全に同じではありません。 私の環境では上のように分かれましたが、バージョンによっては全部が基本バージョンに行くことがあります。 その場合は「設定が受理されて、get-alias で読み出せる」ところまでを確認してください。

bash
$ awsl lambda get-alias --function-name thumb --name prod \
    --query 'RoutingConfig.AdditionalVersionWeights' --output json

切り戻しは、加重を消すだけです。

bash
$ awsl lambda update-alias \
    --function-name thumb --name prod --function-version 1 \
    --routing-config '{"AdditionalVersionWeights":{}}' \
    --query 'FunctionVersion' --output text
1

切り戻しがコマンド1本で、しかもコードを1行も触らないのが要点です。 デプロイし直す必要がありません。

運用やること
新バージョンを出すupdate-function-code → publish-version
10%だけ流すupdate-alias --routing-config で 0.1
問題なければ全部切り替えupdate-alias --function-version 2 + 加重を空に
問題があったら加重を空にするだけ。数秒で戻る

「$LATEST に対してエイリアスを作る」ことはできません。 エイリアスはバージョン番号しか指せません。 これは仕様で、事故を防ぐための制約です。


⑥ 同時実行の上限は、アカウント全体で共有されている

冒頭の TooManyRequestsException の話です。

まず、同時実行数とは何か

「1秒あたりのリクエスト数」ではありません。 「同じ瞬間に走っている実行環境の数」です。

1つの実行が 100ms で終わるなら、同時実行 1 で 1秒あたり10リクエストさばける
1つの実行が  10秒 かかるなら、同時実行 1 で 1秒あたり0.1リクエストしかさばけない

同じリクエスト数でも、処理が遅いほど同時実行数を食います。 「遅い関数」は、それだけで隣の関数を巻き込む凶器になります。

現在の設定を見ます。

bash
$ awsl lambda get-account-settings --output json
{
    "AccountLimit": {
        "TotalCodeSize": 80530636800,
        "CodeSizeUnzipped": 262144000,
        "CodeSizeZipped": 52428800,
        "ConcurrentExecutions": 1000,
        "UnreservedConcurrentExecutions": 1000
    },
    "AccountUsage": {
        "TotalCodeSize": 3184,
        "FunctionCount": 3
    }
}
項目意味
ConcurrentExecutionsこのリージョンのアカウント全体の同時実行上限。既定値。申請で増やせる
UnreservedConcurrentExecutionsまだ誰にも予約されていない残り枠
CodeSizeUnzipped262144000 = 250MB。④で書いた展開後の上限
CodeSizeZipped52428800 = 50MB。直接アップロードできる zip の上限。超えたら S3 経由

ConcurrentExecutions が「関数ごと」ではなく「アカウント全体」なのが、この節の全部です。

予約枠を切って、スロットリングを再現する

わざと遅い関数を作ります。

bash
$ cd ~/awslab/lambda/fn
$ nano slow.mjs
export const handler = async (event) => {
  await new Promise((r) => setTimeout(r, 3000));
  return { done: event.n };
};
bash
$ zip -q slow.zip slow.mjs

$ awsl lambda create-function \
    --function-name slow \
    --runtime nodejs20.x --handler slow.handler --role $ROLE \
    --zip-file fileb://slow.zip --timeout 30 --memory-size 128 \
    --query 'FunctionName' --output text
slow

この関数の枠を、1に絞ります。

bash
$ awsl lambda put-function-concurrency \
    --function-name slow \
    --reserved-concurrent-executions 1 \
    --query 'ReservedConcurrentExecutions' --output text
1

残り枠が減ったことを確認します。

bash
$ awsl lambda get-account-settings \
    --query 'AccountLimit.UnreservedConcurrentExecutions' --output text
999

ここが両刃の刃です。 slow に1つ予約したので、その1つは他のどの関数からも使えなくなりました。 予約は「守る」と同時に「取り上げる」操作です。 全関数に予約を配ると、予約していない関数が使える枠が0になり、全部止まります。

5本同時に投げます。

bash
$ for i in 1 2 3 4 5; do
$   ( awsl lambda invoke --function-name slow \
        --payload '{"n":'"$i"'}' --cli-binary-format raw-in-base64-out \
        /tmp/s$i.json > /tmp/s$i.log 2>&1 ; echo "req$i exit=$?" ) &
$ done
$ wait
req1 exit=0
req3 exit=254
req2 exit=254
req5 exit=254
req4 exit=254
bash
$ cat /tmp/s3.log
An error occurred (TooManyRequestsException) when calling the Invoke operation (reached max concurrency): Rate Exceeded.

1本だけ通り、4本が弾かれました。 これが冒頭のエラーです。

スクリーンショットを撮ってください: 03_throttled_429.png put-function-concurrency で 1 に絞ったあと、5本同時に投げて 1本成功・4本 TooManyRequestsException になっている画面。 UnreservedConcurrentExecutions が 999 に減っているところも一緒に写るようにします。

予約を外して、元に戻します。

bash
$ awsl lambda delete-function-concurrency --function-name slow
$ awsl lambda get-account-settings \
    --query 'AccountLimit.UnreservedConcurrentExecutions' --output text
1000

これはバルクヘッドそのもの

本線の 落ちても全部は止めない — サーキットブレーカと縮退 で出てきた「バルクヘッド(隔壁)」を、思い出してください。

船の話Lambda の話
船底を仕切らないと、1箇所の浸水で船全体が沈む予約を設定しないと、1つの関数の暴走でアカウント全体が止まる
仕切ると、浸水は1区画で止まる予約すると、暴走はその関数の中で止まる
仕切ったぶん、積める荷物は減る予約したぶん、他の関数が使える枠は減る

私が現場で採った落としどころは、これでした。

・絶対に止めたくない関数(決済・ログイン)にだけ、予約枠を切る
・バッチなど「遅れても死なない」関数には、予約を切らない
・そのかわり、バッチ側の同時実行を「上限まで使い切らない」値に予約で制限する

「守りたいものに枠を与える」と「暴れるものに枠を制限する」は、同じコマンドで、意味が逆です。

同期と非同期で、失敗の見え方が違う

呼び出し方上限に当たったら失敗したら
同期(--invocation-type RequestResponse。既定)その場で TooManyRequestsException。 呼んだ側の責任で再試行呼んだ側にエラーが返る
非同期(--invocation-type Event)内部のキューに入って、しばらく再試行される既定で2回再試行され、それでも駄目なら黙って消える
bash
$ awsl lambda invoke --function-name slow \
    --invocation-type Event \
    --payload '{"n":99}' --cli-binary-format raw-in-base64-out /tmp/a.json
{
    "StatusCode": 202
}

202 が返っただけで、結果は入っていません。 /tmp/a.json は空です。 非同期呼び出しは「受け付けた」しか言いません。

ここが一番怖いところです。 非同期で呼んだ処理が全部失敗しても、呼んだ側には何も届きません。 「動いているつもりで、1件も処理されていなかった」が起きます。

だから、失敗の行き先を必ず設定します。

bash
$ awsl lambda put-function-event-invoke-config \
    --function-name slow \
    --maximum-retry-attempts 1 \
    --maximum-event-age-in-seconds 300 \
    --output json
{
    "LastModified": "2026-10-07T11:02:41+09:00",
    "FunctionArn": "arn:aws:lambda:ap-northeast-1:000000000000:function:slow",
    "MaximumRetryAttempts": 1,
    "MaximumEventAgeInSeconds": 300
}
設定意味既定のままだと
MaximumRetryAttempts非同期の再試行回数(0〜2)2回。冪等でない処理を3回実行される
MaximumEventAgeInSecondsこれより古いイベントは捨てる最大6時間。障害明けに古いイベントが一斉に流れてくる
送信先(--destination-config)成功時/失敗時の行き先(SQS・SNS など)設定しないと、失敗は消える

「DLQ(デッドレターキュー)」は古い仕組みで、いまは「送信先(Destinations)」が推奨です。 送信先のほうが、失敗の理由まで一緒に送ってくれます。 DLQ はイベント本体しか送りません。

再試行が2回あるということは、「同じイベントで3回実行されうる」ということです。 メール送信を非同期 Lambda でやると、同じメールが3通届きます。 処理には冪等性(何回やっても結果が同じ)が要ります。 これは 機能を足すたび注文APIが壊れる — システム設計深掘り の話と地続きです。


⑦ カスタムランタイムと、その他の上限

公式にない言語を動かす仕組み

Lambda が用意しているランタイム(Node.js・Python・Java・Go・Ruby・.NET)に無い言語を使いたいとき、 Lambda は「あなたが自分でループを書けばいい」という設計になっています。

やることは、たったこれだけです。

1. Lambda が渡してくる環境変数 AWS_LAMBDA_RUNTIME_API(ホスト:ポート)を読む
2. GET /2018-06-01/runtime/invocation/next を叩いて、次の仕事を待つ
3. レスポンスヘッダ Lambda-Runtime-Aws-Request-Id からリクエストIDを取る
4. 本体を処理する
5. POST /2018-06-01/runtime/invocation/<ID>/response に結果を返す
6. 2に戻る(無限ループ)

これだけです。 「ランタイム」という言葉から想像するより、はるかに単純です。

bootstrap という名前の実行ファイルを、zip の一番上に置きます。

bash
$ mkdir -p ~/awslab/lambda/custom
$ cd ~/awslab/lambda/custom
$ nano bootstrap
bash
#!/bin/sh
  set -eu

  while true; do
    # 1. 次の仕事が来るまでブロックする(来るまで返ってこない)
    HEADERS="$(mktemp)"
    EVENT_DATA=$(curl -sS -LD "$HEADERS" \
      -X GET "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next")

    # 2. リクエストIDをヘッダから拾う
    REQUEST_ID=$(grep -Fi Lambda-Runtime-Aws-Request-Id "$HEADERS" \
      | tr -d '[:space:]' | cut -d: -f2)

    # 3. 好きな処理をする(ここではシェルで組み立てているだけ)
    RESPONSE="{\"handledBy\":\"shell\",\"event\":${EVENT_DATA}}"

    # 4. 結果を返す
    curl -sS -X POST \
      "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/${REQUEST_ID}/response" \
      -d "$RESPONSE" > /dev/null
  done
bash
$ chmod 755 bootstrap
$ zip -q custom.zip bootstrap
bash
$ awsl lambda create-function \
    --function-name shellfn \
    --runtime provided.al2023 \
    --handler bootstrap \
    --role $ROLE \
    --zip-file fileb://custom.zip \
    --timeout 15 --memory-size 128 \
    --query 'Runtime' --output text
provided.al2023
bash
$ awsl lambda invoke --function-name shellfn \
    --payload '{"hello":"world"}' --cli-binary-format raw-in-base64-out /tmp/sh.json > /dev/null
$ cat /tmp/sh.json
{"handledBy":"shell","event":{"hello":"world"}}

これは私の環境では動きましたが、正直に書きます。 LocalStack のコミュニティ版では、provided.al2023 の動作が安定しません。 curl が入っていないイメージが降ってきたり、invocation/next が返らずタイムアウトすることがあります。 その場合でも、仕組みの理解は Node.js で完全に再現できます。

Runtime API が何をしているかを、手元で作り直すとこうなります。

bash
$ cd ~/awslab/lambda/custom
$ nano fake-runtime-api.mjs
import http from "node:http";

// これは「Lambda 側」の役。仕事を1つ配って、結果を受け取るだけ
const queue = [{ id: "req-0001", event: { hello: "world" } }];

http.createServer((req, res) => {
  if (req.url.endsWith("/invocation/next")) {
    const job = queue.shift();
    if (!job) return; // 仕事が無ければ返さない = ランタイムはここで待つ
    res.setHeader("Lambda-Runtime-Aws-Request-Id", job.id);
    res.end(JSON.stringify(job.event));
    return;
  }
  if (req.url.includes("/response")) {
    let body = "";
    req.on("data", (c) => (body += c));
    req.on("end", () => {
      console.log("Lambda側が受け取った結果:", body);
      res.end("OK");
      process.exit(0);
    });
    return;
  }
  res.end();
}).listen(9001, () => console.log("fake Runtime API on :9001"));
bash
$ node fake-runtime-api.mjs &
$ sleep 1
$ AWS_LAMBDA_RUNTIME_API=localhost:9001 sh ./bootstrap
fake Runtime API on :9001
Lambda側が受け取った結果: {"handledBy":"shell","event":{"hello":"world"}}

bootstrap を1行も変えずに、そのまま動きました。 カスタムランタイムは、「決まったURLに HTTP で問い合わせ続けるループ」でしかないという証拠です。

ただし、今はコンテナイメージのほうが現実的

zip + カスタムランタイムコンテナイメージ
サイズ上限250MB(展開後)10GB
依存の入れ方レイヤーに詰める・自分でビルドDockerfile に apt install と書くだけ
手元での検証難しい(本物の環境と違う)docker run でそのまま動く
起動の速さ速い初回の起動は不利になりやすい
学ぶことRuntime API の仕様Dockerfile。既に知っている

bootstrap を手で書く場面は、いまはほとんどありません。 「Lambda が中で何をしているか」を理解するには最高の題材ですが、実務でやるならコンテナイメージです。

上限を、1枚の表で

設計をやり直さないために、先に知っておく必要があるものだけ。

上限値当たったときに何が起きるか
実行時間最大15分途中で強制終了。後始末のコードは走らない
メモリ128MB 〜 10240MB(1MB刻み)足りないと Runtime exited で落ちる
/tmp の容量512MB 〜 10240MB既定は512MB。 大きな動画を落とすと溢れる
同期呼び出しのペイロード6MB(リクエスト・レスポンスとも)大きなJSONを返せない。S3 に置いてURLを返す
非同期呼び出しのペイロード1MB同期よりずっと小さい。設計時に忘れがち
zip の直接アップロード50MB超えたら S3 経由
展開後の合計(本体+レイヤー)250MB超えたらコンテナイメージ
レイヤーの数5つ6つ目は付けられない
同時実行(既定)リージョンあたり1000⑥の通り
環境変数の合計4KB大きな設定は Parameter Store へ

15分を超える処理は、Lambda に向きません。 「動画のエンコード」「大量データの一括移行」「機械学習の学習」は、最初から別の道具を選びます。 どうしても Lambda でやるなら、処理を分割して、getRemainingTimeInMillis() で残り時間を見て、途中で自分を再帰的に呼ぶ形にします。 ただし、その設計は非常に壊れやすいので、素直に EC2 や AWS Batch を選ぶほうがまともです。

最新の値は必ず Lambda のクォータ で確認してください。 上限は変わります。


⑧ API Gateway と EventBridge — 呼ばれ方を決める

ここまでは aws lambda invoke で呼んでいました。 これは CLI からしか呼べません。 外から HTTP で呼ばれるようにします。

HTTP API と REST API の違い

API Gateway には2種類あります。 名前が紛らわしいですが、別物です。

HTTP APIREST API
立ち位置新しいほう。既定で選ぶべき古いほう。機能が多い
料金安い高い
応答の速さ速いHTTP API より遅い
JWT 認証組み込みで使えるLambda オーソライザーを書く
APIキー・使用量プラン無いある
リクエスト/レスポンスの変換ほぼできないできる(VTL テンプレート)
WAF との連携できないできる
プライベートAPI(VPC内限定)できないできる

迷ったら HTTP API です。 安くて速い。 REST API を選ぶのは、上の表の右下4つ(APIキー・変換・WAF・プライベート)のどれかが要るときだけです。 「両方あるからには新しいほうが上位互換だろう」は間違いで、機能は REST API のほうが多いです。

HTTP API を作って、curl で叩く

bash
$ cd ~/awslab/lambda/fn
$ nano api.mjs
export const handler = async (event) => {
  // ⚠️ API Gateway 経由の event は、CLI から渡したJSONとは全く違う形をしている
  return {
    statusCode: 200,
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      method: event.requestContext?.http?.method,
      path: event.rawPath,
      query: event.queryStringParameters ?? {},
      ua: event.headers?.["user-agent"],
    }),
  };
};
bash
$ zip -q api.zip api.mjs

$ APIFN=$(awsl lambda create-function \
    --function-name apifn \
    --runtime nodejs20.x --handler api.handler --role $ROLE \
    --zip-file fileb://api.zip --timeout 10 --memory-size 128 \
    --query 'FunctionArn' --output text)

$ echo $APIFN
arn:aws:lambda:ap-northeast-1:000000000000:function:apifn
bash
$ API_ID=$(awsl apigatewayv2 create-api \
    --name lab-http-api \
    --protocol-type HTTP \
    --target $APIFN \
    --query 'ApiId' --output text)

$ echo $API_ID
u3k91mzp4d

--target を付けると、ルートもステージも統合も一括で作られます。 これが HTTP API の「簡単なほう」たるゆえんです。 REST API だと、リソース・メソッド・統合・デプロイを別々に4回叩きます。

bash
$ awsl lambda add-permission \
    --function-name apifn \
    --statement-id apigw-invoke \
    --action lambda:InvokeFunction \
    --principal apigateway.amazonaws.com \
    --output json > /dev/null

$ curl -s "http://${API_ID}.execute-api.localhost.localstack.cloud:4566/?q=hello&page=2"
{"method":"GET","path":"/","query":{"q":"hello","page":"2"},"ua":"curl/8.5.0"}

event の形が、①のときと全く違います。

①(CLI から)⑧(API Gateway 経由)
event = 渡したJSONそのものevent = HTTPリクエストを表す決まった構造
event.userId で読めるevent.rawPath / event.headers / event.body
戻り値 = そのまま返るstatusCode と body(文字列)を返さないと 502

body は文字列でなければいけません。 オブジェクトのまま返すと、Internal server error になります。 JSON.stringify を忘れる事故が本当に多いです。 これは APIの正体はJSONを返すHTTP — Node.jsで作る で書いた「HTTPは文字列を返すもの」という話と同じです。

add-permission を忘れると 500 になります。 「関数を作れば呼べる」ではなく、「API Gateway に、この関数を呼ぶ許可を与える」が要ります。

API Gateway すら要らない場合がある — 関数URL

bash
$ awsl lambda create-function-url-config \
    --function-name apifn \
    --auth-type NONE \
    --query 'FunctionUrl' --output text
http://ub3n1qx7f2ka9wd0h5r6v8ycmtjlgpse.lambda-url.ap-northeast-1.localhost.localstack.cloud:4566/

これだけで、HTTPS のURLが1本手に入ります。 API Gateway は作っていません。

関数URLHTTP API
料金無料(Lambda の実行料金だけ)リクエストごとに課金
独自ドメイン付けられない付けられる
ルーティング無い(1関数=1URL)パスごとに関数を分けられる
認証IAM または無しJWT・IAM・Lambda オーソライザー
使いどころWebhook の受け口・社内ツール・実験公開API

--auth-type NONE は「誰でも叩ける」という意味です。 URLが漏れたら、世界中から呼ばれます。 呼ばれた分だけ課金され、同時実行の枠も食われます。 本物のAWSで試すなら、必ず AWS_IAM にするか、使い終わったら消してください。

EventBridge — cron 的に定期実行する

「毎朝9時に集計する」を、サーバーを立てずにやります。

bash
$ awsl events put-rule \
    --name lab-every-5-min \
    --schedule-expression 'rate(5 minutes)' \
    --state ENABLED \
    --query 'RuleArn' --output text
arn:aws:events:ap-northeast-1:000000000000:rule/lab-every-5-min
bash
$ awsl lambda add-permission \
    --function-name apifn \
    --statement-id events-invoke \
    --action lambda:InvokeFunction \
    --principal events.amazonaws.com \
    --output json > /dev/null

$ awsl events put-targets \
    --rule lab-every-5-min \
    --targets "Id"="t1","Arn"="$APIFN","Input"='{"scheduled":true}' \
    --query 'FailedEntryCount' --output text
0

FailedEntryCount が 0 なら成功です。 このAPIは、失敗しても例外を投げずに件数で返してきます。

bash
$ awsl events list-targets-by-rule --rule lab-every-5-min \
    --query 'Targets[*].[Id,Arn]' --output text
t1	arn:aws:lambda:ap-northeast-1:000000000000:function:apifn

5分待って、ログに出ているか見ます。

bash
$ awsl logs describe-log-streams \
    --log-group-name /aws/lambda/apifn \
    --query 'logStreams[*].lastEventTimestamp' --output text

LocalStack でも、スケジュールは実際に発火します。 待つのが嫌なら rate(1 minute) で試してください。

rate() と cron() の書き方

書き方意味注意
rate(5 minutes)5分ごと1のときは単数形。 rate(1 minutes) はエラー。rate(1 minute)
rate(1 hour)1時間ごと使えるのは minute hour day だけ
cron(0 0 * * ? *)毎日 00:00 UTCUTC。日本時間ではない
cron(0 0 ? * MON *)毎週月曜 00:00 UTC
cron(0/15 * * * ? *)15分ごと

cron() のフィールドは6つです。 Linux の cron(5つ)とは違います。 分 時 日 月 曜日 年 で、日と曜日のどちらか一方を必ず ? にします。 両方に値を書くとエラーになります。 これは Linux の cron には無いルールです。

そして、一番刺さるのがこれです。

時刻は UTC です。 「毎朝9時」のつもりで cron(0 9 * * ? *) と書くと、日本時間の18時に動きます。 日本時間の朝9時にしたいなら cron(0 0 * * ? *) です。 私はこれを「なぜか夕方に集計が走る」という形で踏みました。 これは cronは動かなくても何も言わない — 定期実行とsystemd timer で書いた「cron は失敗を教えてくれない」と合わせて、二重に気づきにくい組み合わせです。

EventBridge には、スケジュール以外の使い方もあります。

・S3 にファイルが置かれたら関数を呼ぶ
・EC2 の状態が変わったら関数を呼ぶ
・アプリが自分で発行したイベントで関数を呼ぶ

「何かが起きたら動く」がイベント駆動で、これは 機能を足すたび注文APIが壊れる — システム設計深掘り でやった考え方そのものです。 Lambda は、その「動く側」を、サーバーを持たずに用意する道具です。

判断表 — Lambda を選ぶか、EC2 を選ぶか

課金の構造だけ、先に整理します。 金額は書きません。

課金の対象何で決まるか
Lambda のリクエスト数呼ばれた回数
Lambda の実行時間確保メモリ(GB) × 実行時間(秒) = GB秒
プロビジョンド同時実行待機している時間ぶん。呼ばれなくても発生する
API Gatewayリクエスト数。HTTP API と REST API で単価が違う
CloudWatch Logs出したログの量と、保存している量。保持期間が既定で無期限
データ転送外へ出るバイト数

見落としがちなのは CloudWatch Logs です。 console.log を大量に出すと、関数の実行料金より、ログの料金のほうが高くなることがあります。 保持期間は必ず設定してください。

bash
$ awsl logs put-retention-policy \
    --log-group-name /aws/lambda/apifn \
    --retention-in-days 7

そのうえで、判断です。

こういう処理選ぶもの理由
1日100回のサムネイル生成Lambda動いていない時間が圧倒的に長い
月末だけ跳ねる集計Lambda波に合わせて勝手に増える。台数を考えなくていい
Webhook の受け口Lambda + 関数URLいつ来るか分からない・API Gateway すら要らない
24時間トラフィックがあるWebアプリEC2 / コンテナ常時動かすなら EC2 のほうが安い。GB秒はずっと課金される
応答が数ミリ秒でないと困るAPIEC2 / コンテナコールドスタートを完全には消せない
15分を超えるバッチEC2 / AWS BatchLambda の上限に当たる
大量の常時接続(WebSocket)EC2 / コンテナLambda は接続を保持できない(実行が終わると消える)
DBに大量の接続が要る処理要注意同時実行数だけ接続が増える。RDS Proxy が要る

Lambda が効くのは「たまにしか動かない」「波が激しい」ものです。 「サーバーを管理したくないから全部 Lambda」は、常時トラフィックがあるなら、高くて遅い選択になります。 用途によって、単価は簡単に逆転します。


つまずいたところ

1. create-function は通るのに invoke だけが失敗した

Error: Docker not available

docker-compose.yml に /var/run/docker.sock のマウントを書き忘れていました。 LocalStack は関数を「LocalStack の中で」動かしていません。 ホストの Docker に、関数用のコンテナをもう1つ立てさせています。 「作成は API の応答を返すだけなので通り、実行だけが落ちる」という、一番わかりにくい壊れ方をします。


2. --payload が base64 だと言われて弾かれた

Invalid base64: "{"userId":"u-01"}"

AWS CLI v2 の仕様です。 --cli-binary-format raw-in-base64-out を付けます。 ネットの記事の多くは CLI v1 のまま書かれているので、そのまま真似すると必ずここで止まります。 毎回書くのが嫌なら、aws configure set cli_binary_format raw-in-base64-out で固定できます。


3. コールドスタートの原因を、AWS のせいだと思い込んでいた

「時間帯によって遅い」と思っていたので、3日ほど時刻とグラフを眺めていました。 分かったのは、BOOTED_AT をハンドラの外に置いて「環境の年齢」を返すようにしてからです。 年齢が毎回数十msに戻っていれば、環境が作り直されている。 これで1分で判定できました。 推測をやめて、判定できる値を1つ返すようにするのが、結局一番速い。


4. メモリを 128MB にしていたのは「節約」ではなく「ただ遅かった」だけだった

メモリを増やすとCPUも増える、を知りませんでした。 GB秒で計算し直したら、512MB のほうが安くて4倍速いという結果になりました。 「一番小さいのが一番安い」は、CPUを使う処理では成り立ちません。 ただし、待ち時間が支配的な処理(外部APIを叩いて待つだけ)では、メモリを増やしても速くなりません。 「CPUを使っているかどうか」で分かれます。


5. グローバル変数に利用者IDを入れていて、たまに他人の名前が出た

再現しませんでした。 同じ実行環境に、続けて別の人が当たったときだけ起きるからです。 ③のカウンタを書いて、previousUserIdSeenByThisEnvironment に前の人のIDが出たのを見て、やっと理解しました。 「Lambda は毎回きれいな状態で始まる」という思い込みが原因でした。 判定の基準は「この値が、次に来た知らない人に見えても平気か」です。


6. レイヤーの zip を node_modules/ から作ってしまった

Error: Cannot find module 'labutil'

Node.js のレイヤーは nodejs/node_modules/ から始めます。 node_modules/ から zip すると、作成も更新も成功して、実行時に初めて落ちます。 unzip -l layer.zip で先頭が nodejs/ になっているかを、毎回見るようにしました。


7. 予約済み同時実行数を「全関数に」設定して、予約していない関数が全部止まった

予約は「取り分」であると同時に「取り上げ」です。 上限1000に対して、関数5つに200ずつ予約したら、予約していない関数が使える枠が0になりました。 UnreservedConcurrentExecutions が 0 になっているのが証拠です。 AWS は最低100を未予約で残すよう要求しますが、それでも足りるとは限りません。 予約は「絶対に守りたい少数」にだけ切る、が正解でした。


8. 非同期呼び出しの失敗に、まったく気づけなかった

--invocation-type Event は 202 を返して終わりです。 中で全部失敗しても、呼んだ側には何も届きません。 「動いているつもりで1件も処理されていなかった」を1週間やりました。 送信先(Destinations)を設定していれば、失敗の理由まで飛んできます。 そして 既定の再試行は2回なので、「同じイベントで3回実行されうる」ことも、そのとき初めて知りました。


9. cron(0 9 * * ? *) が夕方に動いた

UTC でした。 日本時間の朝9時は cron(0 0 * * ? *) です。 さらに Linux の cron はフィールド5つ、EventBridge は6つで、日と曜日のどちらかを ? にする必要があります。 「cron の書き方は知っている」という思い込みが、そのまま罠になりました。


後片づけ

練習で作ったものを、全部消します。

まず、手元で起動したままの偽 Runtime API を止めます。

bash
$ jobs
$ kill %1 2>/dev/null
$ pkill -f fake-runtime-api.mjs 2>/dev/null

EventBridge のルールは、ターゲットを外してからでないと消せません。

bash
$ awsl events remove-targets --rule lab-every-5-min --ids t1 \
    --query 'FailedEntryCount' --output text
$ awsl events delete-rule --name lab-every-5-min
$ awsl events list-rules --query 'Rules[*].Name' --output text
0

最後の行が何も出なければ、ルールは消えています。 ターゲットを外さずに delete-rule すると、ValidationException で断られます。

関数URLを消します。

bash
$ awsl lambda delete-function-url-config --function-name apifn

API を消します。

bash
$ awsl apigatewayv2 delete-api --api-id $API_ID
$ awsl apigatewayv2 get-apis --query 'Items[*].ApiId' --output text

エイリアスとバージョンを消します。

bash
$ awsl lambda delete-alias --function-name thumb --name prod
$ awsl lambda delete-function --function-name thumb:2
$ awsl lambda delete-function --function-name thumb:1

delete-function に :バージョン番号 を付けると、そのバージョンだけが消えます。 付けないと関数ごと全部消えます。 本番で間違えると戻せません。

関数を全部消します。

bash
$ for F in thumb counter uselayer slow shellfn apifn; do
$   awsl lambda delete-function --function-name $F 2>/dev/null
$ done
$ awsl lambda list-functions --query 'Functions[*].FunctionName' --output text

レイヤーを消します。 バージョンごとに指定が要ります。

bash
$ awsl lambda list-layer-versions --layer-name labutil \
    --query 'LayerVersions[*].Version' --output text
1
bash
$ awsl lambda delete-layer-version --layer-name labutil --version-number 1
$ awsl lambda list-layers --query 'Layers[*].LayerName' --output text

ロググループを消します。 関数を消してもログは残ります。

bash
$ for G in $(awsl logs describe-log-groups --query 'logGroups[*].logGroupName' --output text); do
$   awsl logs delete-log-group --log-group-name $G
$ done
$ awsl logs describe-log-groups --query 'logGroups[*].logGroupName' --output text

本物の AWS でも、これは同じです。 関数を消してもロググループは残り、保持期間が無期限なら、ずっと保管料が発生します。 「関数を消したのに課金が続く」の一番多い原因がこれです。

IAM ロールを消します。

bash
$ awsl iam delete-role --role-name lab-lambda-role
$ awsl iam list-roles --query 'Roles[*].RoleName' --output text

空になったことを、まとめて確認します。

bash
$ awsl lambda list-functions --query 'Functions[*].FunctionName' --output text
$ awsl lambda list-layers --query 'Layers[*].LayerName' --output text
$ awsl events list-rules --query 'Rules[*].Name' --output text
$ awsl apigatewayv2 get-apis --query 'Items[*].ApiId' --output text

4つとも何も出なければ完了です。

LocalStack を止めます。

bash
$ cd ~/awslab/lambda
$ docker compose down -v
$ docker compose ps
NAME   IMAGE   STATUS   PORTS

-v を付けて、LocalStack の状態ボリュームも消します。

関数用に立てられたコンテナが残っていないか確認します。

bash
$ docker ps -a --filter "name=localstack" --format '{{.Names}}\t{{.Status}}'
$ docker images | grep -i lambda

ここが Lambda 特有の後片づけです。 LocalStack は関数ごとにコンテナとイメージを作るので、docker compose down だけでは残ることがあります。 LAMBDA_REMOVE_CONTAINERS=1 を最初に書いておいたのは、これを減らすためです。

残っていたら消します。

bash
$ docker container prune -f
$ docker image prune -f
$ docker system df

練習用フォルダを消します。

bash
$ cd ~
$ rm -rf ~/awslab/lambda
$ df -h ~ | tail -1

localstack/localstack:3 のイメージは残ります。 AWS の深掘りをここで終えるなら消してください。

bash
$ docker image rm localstack/localstack:3

まとめ — 理解できたこと

  • 「最初の1回だけ遅い」は、AWS が混んでいるからではない。 使い回せる実行環境が残っているかどうかの差で、間を空けると毎回作り直される
  • コールドスタートは4つに分解できる: 実行環境の確保・コードの展開・ランタイムの起動・初期化コードの実行。自分で減らせるのは後ろの2つ
  • ハンドラの外に置いたコードは、実行環境1つにつき1回しか走らない。 だから SDKクライアントとDB接続はハンドラの外。中で作ると、呼び出しのたびに接続が増える
  • 「Lambda は毎回きれいな状態で始まる」は間違い。 カウンタは増え続け、前の利用者のIDが次の呼び出しから見える。グローバル変数に利用者のデータを入れると、他人に漏れる。/tmp も同じ
  • 判定の基準は「この値が、次に来た知らない人に見えても平気か」。平気なら外、駄目なら中
  • メモリを増やすとCPUも増える。 GB秒 = 確保メモリ × 実行時間なので、速くなって結果的に安くなることがある。128MB は節約ではなく、ただ遅いだけのことがある
  • ただし、待つだけの処理ではメモリを増やしても速くならない。 CPUを使っているかどうかで分かれる
  • プロビジョンド同時実行は、待機時間に課金される。 Lambda の一番の長所を捨てる設定なので、入れる前に EC2 と比べる
  • レイヤーは nodejs/node_modules/ から zip する。 間違えても作成は成功し、実行時に Cannot find module で落ちる
  • レイヤーは5つまで、展開後の合計250MBまで。 zip の大きさではなく展開後。超えるならコンテナイメージ
  • $LATEST を本番に向けない。 保存した瞬間に本番が変わる。バージョンは不変、エイリアスは向き先を差し替えられる名前
  • エイリアスの加重で、10%だけ新バージョンに流せる。 切り戻しは加重を空にするだけで、デプロイし直さなくていい
  • 同時実行数はアカウント全体(リージョン単位)で共有。 1つの関数が食い潰すと、無関係な関数まで TooManyRequestsException で止まる
  • 予約済み同時実行数は、守ると同時に取り上げる。 全関数に配ると、予約していない関数の枠が0になる。これはバルクヘッドそのもので、仕切ったぶん積める荷物は減る
  • 非同期呼び出しは 202 を返すだけ。 失敗しても呼んだ側には何も届かない。送信先を設定しないと、失敗は黙って消える
  • 非同期は既定で2回再試行される = 同じイベントで3回実行されうる。 冪等でない処理を置いてはいけない
  • カスタムランタイムの正体は「決まったURLに HTTP で問い合わせ続けるループ」。ただし いま実務でやるならコンテナイメージのほうが現実的
  • 15分・6MB・1MB・250MB・512MB の /tmp。 上限は設計前に見る。15分を超える処理は Lambda に向かない
  • API Gateway は迷ったら HTTP API。 安くて速い。REST API を選ぶのは、APIキー・変換・WAF・プライベートAPI のどれかが要るときだけ
  • Webhook の受け口なら、API Gateway すら要らない(関数URL)。ただし --auth-type NONE は世界中から呼ばれる
  • EventBridge の cron() はフィールド6つで、時刻は UTC。 日と曜日のどちらかは ?。Linux の cron と違う
  • CloudWatch Logs の保持期間は既定で無期限。 関数を消してもログは残り、課金も残る
  • 常時動かすなら EC2 のほうが安い。 Lambda が効くのは「たまにしか動かない」「波が激しい」もの。「管理したくないから全部 Lambda」は、高くて遅い選択になる

参考リンク


次に読む

この記事は 【深掘り】AWS の 12 / 16 本目です。

記事
← 前の記事DynamoDBの設計とキー — あとから条件を足せない
→ 次の記事AWSでコンテナを動かす選択肢 — Kubernetesを選ぶ理由がない

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

roadmap.sh のどこをやっているか

AWS›AWS — Lambda
  • コールドスタートの内訳を分解する
  • 同時実行の上限はアカウント全体で共有

この記事は、上の項目を実際に手を動かして確かめる回です。

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

コメント

コメントする

目次