はじめに

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)を利用する

構成

概要

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

定義ファイル

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

デプロイ方法

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

sam build
sam deploy

構成の作成手順

###ざっくりと

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

API GatewayとOpenAPI部分の内容

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

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

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