Amazon API GatewayのHTTP APIをOpen APIを利用して定義してみた (1/2)

はじめに

AWS ドキュメントを見ながら、Amazon API GatewayのHTTP APIをOpenAPIを利用して定義する機会があったので、メモとして残します。当記事は手順を簡単に解説し、別記事にて、実際のサンプルを提示したいと思います。

サマリ

• Open APIを利用したAPI定義が可能
• 定義は別ファイルに外部化することも可能
• 外部化したファイルに対してもパラメータや他のスタックのExportした値、擬似変数が利用可能

今回試した設定のもとになる要件

• HTTP APIを採用する
• APIは数十のパスが想定され、メンテナンスが発生しやすい
• 統合先としては、VPC Linkを利用してプライベートなVPCのALBと、AWS Lambda関数がある
• mTLS接続をする。つまり、ためにカスタムドメインとトラストストアの構成,ACMの証明書が必要
• アクセスログを出力する
• いくつかのパスはIAMによる認可が必要
• CORS設定が必要
• DeployはSAM(Serverless Application Model)を利用する

構成

概要

1. デフォルトVPCを利用。
2. Stack1：ALBやバケットなど周辺リソースを作成
3. Stack2: API やVPC Link、Logsなどを作成

定義ファイル

1. Stack1用のyaml(SAMテンプレート）
2. Stack2用のyaml(SAMテンプレート）
3. Stack2から参照するOpenAPI定義(yaml)

デプロイ方法

以下のコマンドでビルド& デプロイ

sam build
sam deploy

構成の作成手順

ざっくりと

1. まず、APIのバックエンドは前述の通りInternal なALB( Internet FacingしないALB)を利用するため、VPC１つ、Subnet2つ(ALBはサブネットが二つ必要）が必要だった。これは、一から作らず、既存のVPC/Subnetを利用することにして手抜きした。（しかもインターネットからアクセス可能なサブネットを利用）.
2. 続いて、ALBやALBに必要なSecurityGroup、HTTP APIの統合先として指定するALBのListenerをCFnで作成(Stack1)。その際、OutputsでHTTP ListenerやVPC/SubnetをExportとし別スタックで利用できるように作成。
3. mTLSで必要になるルートCAの証明書、中間CAの証明書を格納するためのS3バケットを作成(Stack1)し、Bucket名をOutputsでExport
4. mTLS用の証明書(ルートCAの証明書、中間CA証明書、クライアント証明書)をコマンドで手作業で発行した。Stack1でExportし、Importできるように構成
5. ACMを利用してGUIでAPI Gatewayで利用するためのサーバ証明書を発行、Stack1でExport（別にExportしなくてもよいが気分的にやってみました）
6. API GatewayからバックエンドのInternalなALBに接続をするために、VPC Linkと Security Groupを作成(Stack2)
7. パスが未定義な状態のAPI Gatewayを定義(Stack2)
8. デプロイされたAPI Gatewayにダミーでパスを手動で１つ登録し、OpenAPI 定義をYaml形式でExport
9. ExportしたOpenAPIのYAMLを利用してPaths等を定義
10. Stack2のUpdate

API GatewayとOpenAPI部分の内容

1. API Gatewayのスタックで定義したもの
   1. API Gatewayが利用するIAM ROle
   2. API Gatewayのアクセスログ出力先のCloudWatch Logグループ
   3. API定義
      1. OpenAPIを定義したファイルのパス指定
      2. Access Logの設定
      3. 警告発生時は失敗にする設定
      4. Domainの設定
      5. Domain Mappingの設定
2. Open APIを定義
   1. Pathsの定義
      1. HTTP Method
      2. Path
      3. Auth
      4. Parameter Mappings
      5. Integration(ALB/Lambda)
   2. CORS
   3. Security

API Gatewayの定義をしてからOpen APIの定義をExportし、ExportされたYAMLに対して必要な定義をした方法を選択したのは、APIGatewayのOpenAPI定義について熟練者ではない私にとっては、API Gatewayで定義したものがどういう形でExportされるのか確認し、それを参考に定義するのが速く、正確な方法だと理解したためである。いちから書ける人はダミーのパス登録やExportは不要だが、簡単な方法なので構造を把握するという意味で試すとよい。

次回は実際のコマンドやテンプレートを掲載する予定