前書き

Terraform で API Gateway を構築する際に、aws_apigatewayv2_api というリソースの存在を知った。今回は備忘録も兼ねて、aws_apigatewayv2_api を使用した API Gateway の構築手順を記載する。

API Gateway の概要

Amazon API Gateway は、REST や HTTP 、WebSocket の API を作成・公開・管理するための AWS のマネージドサービス。サーバを自分で用意せずに、API の受付口を AWS 上に作成できる。このリソースは、 クライアントとバックエンドサービスの間に立つ入口（ゲートウェイ） として動作する。ブラウザ、モバイルアプリ、外部システムなどからのリクエストを受け取り、適切な処理先へ転送する。

前提条件

Terraformを動作させる環境が存在する
AWSの認証は、AWS-Vaultの設定方法を参考に設定している
Terraformのバージョンが v1.50 以上
本記事では、下記の初期状態から構築を行う

構築手順

　構築構成は、Lambda などのバックエンドリソースは使用せず、API Gateway から外部の HTTP サービスへ通信できることを確認する。

servicesフォルダー内の構築内容

API Gateway のリソースは直接定義せず、モジュールとして定義した API Gateway を呼び出すだけの役割とする。

main.tf

# API Gateway
module "api_gateway" {
  source = "../modules/api_gateway"

  name_prefix = local.name_prefix
}

variables.tf

locals {
  name_prefix = "api-gateway-v2"
}

API Gatewayの構築内容

以下の構成で構築をした。ビジネスロジックやレスポンス加工は一切行わない。

HTTP API（API Gateway V2）を使用
すべての HTTP メソッドを受け付ける
ルーティングは最小限とし、疎通確認に特化
API Gateway が通信できるかどうかのみを検証対象とする

integration_uriの注意点

api_gateway.tf

# API Gateway v2 (HTTP API)
resource "aws_apigatewayv2_api" "api_connectivity_test" {
  name          = "${var.name_prefix}-test"
  protocol_type = "HTTP"
}

# ステージを作成する
resource "aws_apigatewayv2_stage" "api_connectivity_test_prod" {
  api_id      = aws_apigatewayv2_api.api_connectivity_test.id
  name        = "prod"
  auto_deploy = true
}

# API Gateway から外部 HTTP（httpbin）へプロキシ転送する統合を定義する
resource "aws_apigatewayv2_integration" "api_connectivity_test_httpbin" {
  api_id             = aws_apigatewayv2_api.api_connectivity_test.id
  integration_type   = "HTTP_PROXY"
  integration_method = "ANY"
  integration_uri    = "https://httpbin.org/anything"

  payload_format_version = "1.0"
  timeout_milliseconds   = 29000
}

# GET /test へのリクエストを外部 HTTP プロキシ統合へルーティングする
resource "aws_apigatewayv2_route" "api_connectivity_test_get" {
  api_id    = aws_apigatewayv2_api.api_connectivity_test.id
  route_key = "ANY /test"
  target    = "integrations/${aws_apigatewayv2_integration.api_connectivity_test_httpbin.id}"
}

`api_gateway.tf`内で使用したメソッドの説明

項目	説明
`protocol_type`	作成する API の通信方式を指定する。`HTTP` または `WEBSOCKET` を指定する
`auto_deploy`	ルートや統合の変更を行った際に、ステージへ自動でデプロイするかを指定する。`true` は自動デプロイ、`false` は手動デプロイとなる
`integration_type`	API Gateway がリクエストをどの方式で統合先へ転送するかを指定する
`integration_method`	統合先へ転送する際に使用する HTTP メソッドを指定する。`GET`、`POST`、`PUT`、`DELETE`、`PATCH`、`HEAD`、`OPTIONS`、`ANY` を指定できる。
`payload_format_version`	API Gateway から統合先へ送信するリクエストペイロードの形式を指定する・1.0 は multiValueHeaders などを含む従来の形式・2.0 は HTTP API 向けに構造が整理され、ヘッダーやクエリが簡素化され、Lambda 側の実装が容易になる形式
`timeout_milliseconds`	API Gateway が統合先からのレスポンスを待つ最大時間をミリ秒単位で指定する
`route_key`	HTTP メソッドとパスを組み合わせてルーティング条件を指定する。`GET /test` や `ANY /test` のように「メソッドパス」の形式で記述する。
`target`	ルートに一致したリクエストを、どの統合（integration）へ転送するかを指定する

Terraform で使用する変数 name_prefix を宣言
name_prefix は、API Gateway などのリソース名の先頭に付与する共通の接頭辞として使用する

variables.tf

variable "name_prefix" { type = string }

疎通確認を行うため、API のエンドポイント URL を output として定義する
出力された URL に対して curl などでリクエストを送信することで、API Gateway 経由で外部 HTTP サービスと通信できているかを確認できる

output.tf

# 疎通確認用の API エンドポイント URL を出力する
output "api_connectivity_test_invoke_url" {
  value = "${aws_apigatewayv2_api.api_connectivity_test.api_endpoint}/${aws_apigatewayv2_stage.api_connectivity_test_prod.name}"
}

terraform console を実行し、module.api_gateway.api_connectivity_test_invoke_urlを叩くことで、エンドポイントの取得が可能となる。

terraform console
> module.api_gateway.api_connectivity_test_invoke_url

疎通テスト用のコマンド

GET

curl -i "https://**********.execute-api.ap-northeast-1.amazonaws.com/prod/test?ping=get"

POST

curl -i -X POST "https://**********.execute-api.ap-northeast-1.amazonaws.com/prod/test" \
  -H "Content-Type: application/json" \
  -d '{"message":"post test"}'

PUT

curl -i -X PUT "https://**********.execute-api.ap-northeast-1.amazonaws.com/prod/test" \
  -H "Content-Type: application/json" \
  -d '{"message":"put test"}'

DELETE

curl -i -X DELETE "https://**********.execute-api.ap-northeast-1.amazonaws.com/prod/test"

GitHub

参考資料

感想

　今回は、Terraform の aws_apigatewayv2_api を使用して API Gateway を構築しました。旧来の構成で API Gateway を構築した経験は何度かありますが、HTTP API（V2）を用いた新しい構成での構築は今回が初めてでした。

実際に触ってみると、設定項目が大幅に減っており、非常に構築しやすいと感じました。また、ルーティングや統合の設定も分かりやすく、疎通確認用途であれば最小限の構成で実装できる点が印象的でした。

今後 API Gateway を新規で作成する際は、特別な理由がない限り、積極的にaws_apigatewayv2_api を使用していこうと思います。