← AWSサービスの内部原理 コース
45. デプロイは不変スナップショット、ステージはポインタ — ステージ変数とカナリア
API Gatewayのデプロイ・ステージ・ステージ変数・カナリアリリースは、「不変のスナップショット」と「それを指すポインタ」という一つのモデルで全部つながります。
① デプロイ=不変スナップショット(gitのコミット)
API定義を編集ルート・メソッド・統合・オーソライザー・リソースポリシー
保存しただけでは呼び出せない『デプロイ』を作成=その時点の定義を凍結
デプロイ v1不変スナップショット
デプロイ v2不変スナップショット
デプロイ v3不変スナップショット
= gitのコミット- 一度作ったデプロイは中身が変わらない。編集を続けても既存のデプロイは書き換わらず、作り直すたびに別のスナップショットが増える
- だからAWSは『APIを更新したら必ず再デプロイが必要』と明記——変更を反映するには新しいスナップショットを作るしかない
API定義は編集・保存しただけでは呼べない。呼べるようにするには『デプロイ』=その時点の定義をまるごと凍結した不変スナップショットを作る。
② ステージ=デプロイを指すポインタ(gitのブランチ)
クライアント…/{stageName} を呼ぶ
URLのステージ名で参照を解決
devステージ
testステージ
prodステージ
『デプロイへの名前付き参照』(AWS)いま指しているスナップショットが呼ばれる
デプロイ v3test と prod が同時に参照してもよい
testで検証した版へprodを向け直す=昇格- 既定ドメインのURL: https://{restapi-id}.execute-api.{region}.amazonaws.com/{stageName} — ホスト名とステージ名がベースURLを決める
- ポインタなので付け替え自由。同じ一つのスナップショットを複数ステージから同時参照もできる
ステージ(dev・prod・betaなど)はデプロイを指す名前付きポインタで、gitのブランチと同型。prodにアクセスする=prodが今指すスナップショットを呼ぶこと。
③ ステージ変数=同じ定義を実行時に別の実体へ写す
同一の不変スナップショット統合先は ${stageVariables.functionName} のプレースホルダ
具体的な統合先を直書きしない実行時にステージのステージ変数の値を差し替え
prod ステージfunctionName = 本番関数名
beta ステージfunctionName = beta関数名
本番の Lambda 関数
beta 用の Lambda 関数
- ステージ変数はステージに紐づく key-value で『環境変数のように振る舞う』(AWS)——設定をコードの外に出す考え方の再登場
- HTTP統合なら http://${stageVariables.url} のようにホスト部分にも書ける
- 関数名を切り替える場合、その関数を呼ぶ権限(lambda:add-permission)は自分で設定する
- 認証情報など機微データの置き場ではない。そうした値は Lambda オーソライザーの出力で渡すのが正しい設計
まったく同じ不変スナップショットが、ステージごとのkey-value(ステージ変数)の差し替えで、実行時に別々の実体へ写される。
④ カナリアリリース=一つのステージに二つのデプロイ
到着したリクエストprod ステージ宛
percentTraffic の割合でランダムに振り分け
本番リリース大部分(例: 95%)
カナリア(新版)小さな割合(例: 5%)
確率的な分割そのものcanarySettings で設定
deploymentIdカナリアが指すデプロイ
percentTraffic0.0〜100.0
stageVariableOverrides本番のステージ変数を上書き
useStageCacheキャッシュ利用の有無
- 有効化した直後は、ステージもカナリアも同じデプロイを指している
- 選択がランダムかつ小さいので、全ユーザーが常に新版のバグに晒されず、特定の一人が毎回影響を受け続けることもない
- カナリアが有効な間、そのステージは別の非カナリアデプロイに関連付けられない(無効化して設定を外すまで固定)
カナリアは、一つのステージに本番リリースと新版という二つのデプロイをぶら下げ、リクエストを設定した割合でランダムに振り分ける仕組み。
⑤ 観測と分離 — 専用ログ・別集計メトリクス・キャッシュ
カナリアへのリクエスト
実行ログは両方に記録
本番ステージのロググループ
/Canary 専用ロググループ…/{rest-api-id}/{stage-name}/Canary
メトリクスもカナリア分を別集計キャッシュの扱い
別デプロイを指すとき別々のキャッシュキー→それぞれ対応する結果
同じデプロイを指すとき単一のキャッシュキー→同じ応答
- アクセスログも同様に /Canary サフィックス付きのログへ分離される
- カナリア専用のステージ変数オーバーライド・専用ログ・分離キャッシュで、新版を安全に観測できる
カナリアは単なるトラフィック分割ではなく、検証に必要な観測と分離(専用ログ・別集計・キャッシュキー)まで用意されている。
⑥ 昇格=ポインタの向きを確定させて古い版を切り離す
本番リリース指す先: 旧デプロイ
カナリア指す先: 新デプロイ(メトリクスが基準を満たした)
昇格: カナリアが指していたデプロイを本番リリースに引き上げ
本番リリース指す先: 新デプロイ
カナリア無効化
古い版を切り離す- 一貫して、変わらないのはスナップショット(不変データ)、動かしているのはそれを指すポインタ
昇格とは、カナリアが指すデプロイを本番リリースへ引き上げてカナリアを無効化する操作——つまりポインタの向きを確定させること。