Apigatewayのカスタムドメインとは何か・何故必要か
Apigatewayのカスタムドメイン概要
AWS API Gateway を使うと、デフォルトでは
https://{apiId}.execute-api.{region}.amazonaws.com/{stage}/…
という execute-api ドメイン 付き URL が自動払い出しされます。
しかし実運用では下記のようなニーズがあります。
- サービスのブランディング: api.example.com など覚えやすい URL を使いたい
- HTTPS 証明書の名義: 独自ドメインに合わせた証明書を返したい
- パス構成: /prod /v1 を隠蔽してシンプルにしたい
これを実現する仕組みが API Gateway のカスタムドメイン です。
カスタムドメインを利用すれば
https://api.example.com/users
のように 独自ドメイン + 任意のパス で呼び出せます。
Apigatewayのexecute-apiドメインとは何か
API Gateway が自動発行するデフォルトエンドポイントです。
https://abc12345.execute-api.ap-northeast-1.amazonaws.com/prod
- 固定 IP は無く、CloudFront のディストリビューションが裏側で動いている
- HTTPS で返される証明書は
*.execute-api.ap-northeast-1.amazonaws.comなどの ワイルドカード証明書
エイリアスレコードとは（Aレコード・Cレコード違い）
| レコード種別 | 変換対象 | 主な用途 | ルートドメイン (example.com) に使えるか |
|---|---|---|---|
| A レコード | ドメイン ▶ IPアドレス | 静的ウェブサーバ、EC2 など | ✅ |
| CNAME レコード | ドメイン ▶ 別ドメイン名 |
www → ルートへ転送など |
❌（RFCで禁止） |
| Alias レコード (Route 53 独自) | ドメイン ▶ AWS サービスのドメイン名 | ALB, CloudFront, API Gateway など | ✅ |
エイリアスレコードにexecute-apiを紐づけるだけだとエラーになる？
処理の遷移は下記です
api.example.com -> Alias -> abc12345.execute-api.ap-northeast-1.amazonaws.com
この場合、ブラウザでNET::ERR_CERT_COMMON_NAME_INVALIDなど 証明書不一致エラー を返します。
証明書って何？
HTTPS では、サーバーと通信する際にSSL/TLS証明書を使って安全性を担保します。
たとえば、ブラウザが https://api.example.com にアクセスすると、こうチェックされます：
- サーバーが「このドメイン用の証明書」を持っているか
- その証明書が信頼できる認証局（CA）から発行されているか
- 証明書の「CN（Common Name）」や「SAN（Subject Alternative Name）」 にapi.example.com が含まれているか
証明書エラーが起きる原因
仮に次のように設定したとします：
api.example.com → Alias → abc12345.execute-api.ap-northeast-1.amazonaws.com
この場合、アクセスは api.example.com ですが、実際に証明書を持ってるのは execute-api.ap-northeast-1.amazonaws.com です。
abc12345.execute-api.ap-northeast-1.amazonaws.com が返す証明書には、api.example.com が含まれていないです。（execute-api.ap-northeast-1.amazonaws.comは、api.example.comの証明書を知りません。）
カスタムドメインの必要性
① 見た目が整った URL を提供できる
デフォルトだと https://abc12345.execute-api.ap-northeast-1.amazonaws.com/prod/ のような長くて無機質なURLになるが、https://api.example.com ならわかりやすく信頼感もある
② 独自ドメイン用のHTTPS証明書が使える
execute-api ドメインだと AWS の汎用証明書になる。api.example.com に対してはそのドメインに合った証明書が必要で、それはカスタムドメインでしか対応できない
③ ステージ名（/prodなど）を隠せる／整理できる
https://api.example.com/users のようにアクセスさせつつ、内部的には /prod/users にルーティングできる（ベースパスマッピング機能）
④ マルチバージョン／マルチステージ対応がしやすい
/v1, /v2 のようにベースパスを分けることで、複数のAPIステージを1つのドメインで柔軟に管理できる
Discussion