先日、API Gatewayの設定をCloudFormationテンプレートで更新した際、テンプレート上では変更が反映されているのに、実際のAPIの動作に変更が適用されていないという問題に遭遇しました。調査した結果、API Gatewayのデプロイメント設定に関する理解不足でした。この記事では、同じ問題で時間を浪費しないための知見を共有します。

根本的な原因：API Gatewayの2段階デプロイ

CloudFormationでAWS::ApiGateway::RestApiリソースを定義した場合、テンプレートの変更だけでは自動デプロイされないようです。

※HTTP APIでは自動デプロイ可能ですが、RestAPIでは自動デプロイは出来ないようです。(2025/7現在）

（ここでいう「デプロイ」は、CloudFormationスタックがデプロイされることではなく、API Gatewayがデプロイされることを指しています。）
その為、CloudFormationテンプレートでは正しくスタックの更新がされているにも関わらず、API Gatewayリソースは変更が有効化されておらず、上手くいかないということが発生します・・。

API Gatewayの設定変更は「ソースコードの編集」、デプロイは「ビルド&デプロイ」のような関係です。コードを変更してもデプロイしなければ変更は反映されません。

なぜ自動デプロイできないのか？

CloudFormationを使っている中でこのようなことが発生したのはAPI Gatewayのみであったため、少し調べてみました。

API Gatewayの「デプロイ」の考え方

API Gatewayでは、「ステージ」「デプロイ」という設定が存在しています。
ステージは、同じAPIを使用しながらも各環境ごとにエンドポイントなどの設定を簡単に変えられるようにするための設定です。
デプロイは、各APIの設定のスナップショットを取っておくようなもので、バージョン管理のようなイメージです。

APIは影響があった場合に前断面へ戻したりなどする場面が多いため作られた設定なのかな、と思います。

変更が反映されるようにするためのデプロイメント定義の例

CloudFormationテンプレートでAPI Gatewayのデプロイ定義を記載する際は以下のように記載していると思いますが、他のAPI Gatewayの修正を加えた際に、必ずCloudFormationテンプレートのDeployment定義の物理名を変更するようにしましょう。

DeploymentVer1: #ここを毎度変える！！
  Type: AWS::ApiGateway::Deployment
  Properties:
    StageName: "prod"

CloudFormationは、「テンプレートの物理名ごとに各リソースを確認し、変更があれば更新を掛ける」という仕組みでリソースを作成・更新しています。
その為、Deployment定義を更新しないと、StageやAPI Gatewayリソースポリシーは変更したのに、変更内容が有効化されていない！ということが発生します。

他にも、Deployment定義にタイムスタンプなどをいれることで毎度CloudFormationテンプレートをデプロイ時に別のスタックが作られ、更新を掛けることが出来る、などもあるようですね。

CloudFormationテンプレートでデプロイする場合は、ソースコードの変更だけしてリソースを更新したくない場合はないと思うので、自動でAPIのデプロイも出来たらいいのに・・と思いますが、HTTPAPIは可能なようですので、RESTAPIももう少し機能のアップデートがされるのを待ちたいと思います。