API Gateway のステージ変数で Lambda のエイリアスを切り替える方法 ── 1 つの API で dev と prod を分ける

概要

API Gateway と Lambda で作った API に、開発（dev）と本番（prod）の環境を用意したいとき、まず思いつくのは「環境ごとに API を作る」方法です。しかし API を 2 つ作ると、リソースやメソッドを変えるたびに両方を同じように直す必要があり、設定がずれていきます。

API Gateway には、1 つの API を複数のステージにデプロイし、ステージごとにステージ変数を持たせる仕組みがあります。Lambda 側で関数のバージョンとエイリアス（dev・prod）を用意しておき、統合先の関数名にステージ変数を使えば、同じ API のまま、ステージごとに呼ぶエイリアスを切り替えられます。

この記事では、Lambda のバージョン・エイリアスと、API Gateway のステージ・ステージ変数の関係、そしてカナリアリリースとの違いを整理します。実践では、1 つの REST API を dev と prod の 2 つのステージにデプロイし、ステージ変数で別のエイリアス（別のバージョン）が呼ばれることを確かめます。

クラウドおさる

見張り台を 2 つ建てるのではなく、1 つの見張り台に「今日の当番札」を掛け替えて使うのでござる。札（ステージ変数）を見れば、どの当番（エイリアス）を呼べばよいか分かるのでござるよ。

この記事のメリット

• Lambda のバージョン（コードと設定を固定したスナップショット）とエイリアス（バージョンを指す名前）の違いを説明できるようになる
• API Gateway のステージとステージ変数の役割が分かる
• 統合先の関数名にステージ変数を使い、1 つの API で環境を分けられるようになる
• ステージ変数での環境の分離と、カナリアリリースの違いを区別できるようになる

執筆者とキャラクター紹介

執筆者：土肥（とひ）

株式会社ジェニュインの代表であり元エンジニア。これまでオンプレミスと AWS 環境のインフラ業務を担当。AWS 認定資格の学習で得た知識を、ハンズオンとともに解説するのが得意。直近では新人の教育も行っており、これから技術を学ぶ方が納得できる解説を心がけています。基礎編・Cloud Practitioner の記事では、解説役としても登場します。

クラウドおさる

クラウドおさる

はじめましてでござる。弊猿はクラウドおさる。IT インフラが異常に発達した猿山から、雲に乗って地上の AWS を学びに降りてきたのでござる。

クラウドおさる

基礎編や Cloud Practitioner の記事では、とひさんに素朴な疑問をぶつける役でござるな。Security - Specialty などの記事では、要所でワンポイントや注意点をひとこと添えるでござる。

クラウドおさる

猿山にもデータセンターや監視当番があって、地上で起きることはだいたい猿山にも同じ仕組みがあるのでござる。例え話がつい猿山に寄るのは、弊猿の癖でござる。

技術解説

前提知識先に基礎編で手を動かしておくと、この記事がすっと入ります

Amazon API Gateway で REST API を作成しリクエストを処理するこの記事では：REST API のステージとデプロイ AWS Lambda で関数を作成しイベント駆動で実行するこの記事では：Lambda 関数を作って動かす

Lambda のバージョンとエイリアス

エイリアスを使うと、呼び出す側は 関数名:prod のようにエイリアス名で呼ぶだけでよく、新しいバージョンを出したらエイリアスの指す先を付け替えるだけで切り替えられます。

ステージとステージ変数

API Gateway の ステージ は、API のデプロイを公開する名前付きの場所で、https://{api-id}.execute-api.{region}.amazonaws.com/{ステージ名} の URL になります。1 つの API を複数のステージにデプロイできます。

ステージ変数 は、ステージごとに持てるキーと値のペアです。統合の設定などに ${stageVariables.変数名} と書いておくと、呼ばれたステージの値に置き換わります。

これで、/dev の URL で呼べば dva-stage-fn:dev、/prod の URL で呼べば dva-stage-fn:prod が呼ばれます。

呼び出しの許可はエイリアスごと

統合先にステージ変数を使うと、API Gateway はどの関数（エイリアス）を呼ぶかを実行時まで知りません。そのため、コンソールは関数への呼び出し許可を自動では追加せず、エイリアスごとに aws lambda add-permission で許可を追加するよう案内します。許可が無いエイリアスを呼ぶステージは、Internal server error（500）になります。この記事ではリソースベースポリシーに許可を足しますが、API Gateway が引き受ける IAM ロールを統合に設定して呼び出す方法もあります。

クラウドおさる

当番札を掛け替える仕組みにすると、門番は「誰が当番か」を前もって知らぬのでござる。だから当番ごとに「門番から呼ばれてよい」許可を出しておかねばならぬ。ここを忘れると 500 で止まるでござるぞ。

カナリアリリースとの違い

dev と prod を分けたいのに、prod ステージのカナリアに dev のエイリアスをつなぐと、本番の利用者の一部が開発版を呼んでしまいます。環境の分離にはステージ変数を使います。

新卒・未経験の方へ

AWS を仕事にしたい方へ ── 新卒・未経験から

この記事を書いているのは、AWS の設計・構築を仕事にしている現役エンジニアです。運営元の株式会社ジェニュインでは、新卒・未経験の方も募集しています。異業種や文系からインフラエンジニアになり活躍しているメンバーもいます。

• ✓システム開発・WEB エンジニア / インフラ構築などの職種で、未経験から応募できます
• ✓未経験から入社した社員の声を含む社員アンケートを掲載
• ✓応募フォームから 1 分で応募できます

採用ページを見る

実践

ハンズオンガイド7 ステップ画面 4 枚

コンソールの横に開いて、チェックしながら進めましょう。

ガイドを開く

別タブで開きます。チェックはこのブラウザに保存されます。

用意済みの Lambda 関数 dva-stage-fn（呼ばれたエイリアス・バージョン・環境変数 BUILD の値を返す）にバージョンとエイリアスを作り、1 つの REST API の dev と prod のステージから、ステージ変数で別のエイリアスを呼びます。

前提条件

• リージョン: ap-northeast-1（東京）
• 以下のリソースが作成済みであること

まだ用意していない場合は、「作り方の参考」の記事の手順で作れます。リソース名は、この記事の名前に読み替えてください。

作成するリソース一覧

手順 1: バージョンとエイリアスを作る

AWS マネジメントコンソールにログインし、リージョンが ap-northeast-1（東京）であることを確認します。上部の検索バーに Lambda と入力し、「Lambda」を選択して dva-stage-fn を開きます。

「バージョン」タブで「新しいバージョンを発行」をクリックし、説明に release-1.0 と入力して「発行」をクリックします。バージョン 1 ができます。

関数の画面に戻り、「設定」タブ →「環境変数」で「編集」をクリックし、BUILD の値を dev-2.0 に変えて保存します。もう一度「バージョン」タブで「新しいバージョンを発行」をクリックし、説明に dev-2.0 と入力して発行します。バージョン 2 ができます。

「エイリアス」タブで「エイリアスを作成」をクリックし、名前 prod・バージョン 1 で作成します。同じように、名前 dev・バージョン 2 のエイリアスを作成します。

手順 2: REST API を作り、統合先にステージ変数を使う

上部の検索バーに API Gateway と入力し、「API Gateway」を選択します。「API を作成」→「REST API」の「構築」をクリックし、「新しい API」で API 名に dva-stage-api と入力して「API を作成」をクリックします。

「リソースを作成」でリソース名 stage-info のリソースを作ります。/stage-info を選択して「メソッドを作成」をクリックし、以下を設定します。

• メソッドタイプ: GET
• 統合タイプ: 「Lambda 関数」
• Lambda プロキシ統合: オン（デフォルトはオフなので、トグルをオンにします）
• Lambda 関数: arn:aws:lambda:ap-northeast-1:<アカウントID>:function:dva-stage-fn:${stageVariables.lambdaAlias}

Lambda 関数にステージ変数を入れると、入力欄の下に「Lambda 関数をステージ変数として定義しました」という警告が表示されます。「許可の追加コマンド」を開くと、API Gateway に呼び出しの許可を追加するための aws lambda add-permission のコマンドが確認できます。「メソッドを作成」をクリックします。

手順 3: エイリアスごとに呼び出しの許可を追加する

コンソール上部の CloudShell のアイコンから CloudShell を開き、表示されたコマンドの ${stageVariables.lambdaAlias} の部分を dev と prod に置き換えて、2 回実行します。<api-id> は API の一覧の「ID」で確認できます。

ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
for ALIAS in dev prod; do
  aws lambda add-permission \
    --function-name "arn:aws:lambda:ap-northeast-1:$ACCOUNT:function:dva-stage-fn:$ALIAS" \
    --source-arn "arn:aws:execute-api:ap-northeast-1:$ACCOUNT:<api-id>/*/GET/stage-info" \
    --principal apigateway.amazonaws.com \
    --statement-id "apigw-$ALIAS" \
    --action lambda:InvokeFunction
done

ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
for ALIAS in dev prod; do
  aws lambda add-permission \
    --function-name "arn:aws:lambda:ap-northeast-1:$ACCOUNT:function:dva-stage-fn:$ALIAS" \
    --source-arn "arn:aws:execute-api:ap-northeast-1:$ACCOUNT:<api-id>/*/GET/stage-info" \
    --principal apigateway.amazonaws.com \
    --statement-id "apigw-$ALIAS" \
    --action lambda:InvokeFunction
done

手順 4: 2 つのステージにデプロイし、ステージ変数を設定する

API Gateway のコンソールに戻り、「API をデプロイ」をクリックします。ステージで「新しいステージ」を選び、ステージ名に dev と入力して「デプロイ」をクリックします。

dev ステージの画面で「ステージ変数」タブを選択し、「ステージ変数を管理」→「ステージ変数を追加」で、名前 lambdaAlias・値 dev を追加して保存します。

同じように「API をデプロイ」で新しいステージ prod にデプロイし、ステージ変数 lambdaAlias = prod を追加します。ステージ変数は保存してから反映されるまで少しかかるので、次の手順は 30 秒ほど待ってから試します（反映前に呼ぶと、エイリアスが空のまま関数名の検証エラーが返ります）。

手順 5: ステージごとに呼び出して確かめる

CloudShell で、2 つのステージの URL を呼び出します。

curl -s https://<api-id>.execute-api.ap-northeast-1.amazonaws.com/dev/stage-info; echo
curl -s https://<api-id>.execute-api.ap-northeast-1.amazonaws.com/prod/stage-info; echo

curl -s https://<api-id>.execute-api.ap-northeast-1.amazonaws.com/dev/stage-info; echo
curl -s https://<api-id>.execute-api.ap-northeast-1.amazonaws.com/prod/stage-info; echo

/dev は {"alias": "dev", "version": "2", "build": "dev-2.0", "stage": "dev"}、/prod は {"alias": "prod", "version": "1", "build": "release-1.0", "stage": "prod"} を返します。API は 1 つのまま、ステージ変数によって別のエイリアス・バージョンが呼ばれています。

クラウドおさる

見張り台は 1 つ、当番札だけが 2 枚。dev の札では開発版、prod の札では本番版が呼ばれたでござる。本番を新しいバージョンにするときも、prod エイリアスの指す先を付け替えるだけでよいのでござるな。

まとめ

• Lambda のバージョンはコードと設定（環境変数を含む）を固定したスナップショット、エイリアスはバージョンを指す名前で、指す先を付け替えられる
• ステージ変数は ${stageVariables.変数名} で参照し、ステージごとに別の値になる
• 統合先の関数名にステージ変数を使うと、同じ API のまま、ステージごとに別のエイリアスを呼べる
• その場合、呼び出しの許可はエイリアスごとに aws lambda add-permission で追加する（API Gateway が引き受ける IAM ロールを使う方法もある）。許可が無いと 500 になる
• カナリアリリースは同じステージ内で一部のトラフィックを流す仕組みで、環境の分離ではない

参照先

• API Gateway で REST API のステージをセットアップする – Amazon API Gateway
• API Gateway で REST API のステージ変数を使用する – Amazon API Gateway
• Lambda 関数のバージョンを管理する – AWS Lambda
• Lambda 関数のエイリアスの作成 – AWS Lambda
• API Gateway の Canary リリースデプロイの設定 – Amazon API Gateway
• I defined my Lambda integration in API Gateway using a stage variable. Why do I get an “Internal server error” and a 500 status code when I invoke the API method? – AWS re:Post

キャリア相談

独学の先に、AWS の仕事がある ── ジュニアおさるのキャリア相談

CLF には受かったけれど、次に何をすればいいのか分からない。独学で AWS を学ぶジュニアおさるの相談に、株式会社ジェニュイン代表の土肥が答えています。

• ✓資格はゴールか、CLF の次に何から手を付けるか
• ✓EC2 の次に作ってみる構成と、IaC・コスト管理
• ✓実務経験ゼロでも、面接で話せる「これまで」の作り方

相談を読む

新卒・未経験の方へ

AWS を仕事にしたい方へ ── 新卒・未経験から

この記事を書いているのは、AWS の設計・構築を仕事にしている現役エンジニアです。運営元の株式会社ジェニュインでは、新卒・未経験の方も募集しています。異業種や文系からインフラエンジニアになり活躍しているメンバーもいます。

• ✓システム開発・WEB エンジニア / インフラ構築などの職種で、未経験から応募できます
• ✓未経験から入社した社員の声を含む社員アンケートを掲載
• ✓応募フォームから 1 分で応募できます

採用ページを見る