API Gateway - Custom Domain Names

API Gateway 是直接面對使用者的，所以除了 API 本身的描述，面對 Client 的 Endpoint / URL Path 的規劃也很重要，相對應的就會帶出 DNS、SSL、CDN … 等議題，而這些問題，通常上線後都才會注意到。但實際上規劃的不好，不只門面不好看，同時也會造成開發、測試、管理、溝通 … 等成本。

本文整理如何使用 Amazon API Gateway 和 AWS 的 Certificate Manager (ACM)、Route53 設定 Custom Domain Name，還有更重要的是規劃完整的 Service 與 Endpoint 要注意的事情。

Configure the Custom Domain Names

這個功能是 Amazon API Gateway 後來提供的，早期是要自己把 SSL Public / Private Cert、Chain 放進去，根 ELB 一樣。設定步驟有以下：

申請 SSL Certificate - ACM
建立 Custom Domain Names - API Gateway
設定 DNS - Route53

Setup SSL Certificate using ACM

切換 Region 到 US East (N. Virginia) 申請適當的名稱，像是是 api.abc.com、或者 *.api.abc.com 。

注意：一定要到 us-east-1 申請，等一下的 Custom Domain Name 才可以使用。

Configure Custom Domain Names in API Gateway

到 API Gateway -> Custom Domain Names，新增一筆資料。

注意： Domain Name 不能跟其他 region 重複，如果在其他 region 或者 CloudFront 已經有關聯，就會無法建立。

建立的過程，會設定以下：

Domain Name
指定 SSL Certificate, 確認已經在 us-east-1 完成
指定 Base Path Mappings，可以關聯到不同的 API，規劃後述。

完成配置後，因為會同步建立 CloudFront，所以會花一點時間建立 (約 30 分)，最後產生 CloudFront 的 DNS，先複製這個名稱。

好了之後，就可以到 Route53 設定 DNS。

Base Path Mappings

Base Path Mappings 跟 API 的和 Domain Name 的對應有關係，同時也牽涉到未來如何給予客戶的位置有關係。後面將我的規劃當例子說明。

Planning

基本的 Domain Name 設定跟 API Gateway 綁定並不難，比較重要的還是怎麼 規劃，規劃得不好，很容易造成溝通成本，還有未來管理的問題。

Domain Names 與環境的規則

規劃 Domain Name 用以不同的用途，需要考量 Product Line 的概念、環境 … 等，底下以環境為優先考量：

Production: 正式環境
- api.abc.com: 主要 API Domain Name，通常是核心產品
- abc.com: 主要入口 Index
Sandbox: 給客戶試用的，以 sandbox.abc.com 為根節點，也是內部確認問題的環境。
- api.sandbox.abc.com: 主要 Domain Name for Production
Beta: 內部的測試環境，上線前的確認版
- api.beta.abc.com

如果有不同產品線，或者事業部，那就要另外規劃不同的 Domain Name，類似這樣規劃：

Product Line1
- Index: https://{product1}.abc.com
- API: https://api.{product1}.abc.com
Product Line2
- Index: https://{product2}.abc.com
- API: https://api.{product2}.abc.com

或者買另一個 Domain Name，取新的名字，像是 kkbox / kktv / kkticket …，他們就是買不同的名稱，同屬一個集團。

BU1
- Index: https://{BU1}.com
- API: https://api.{BU1}.com
BU2
- Index: https://{BU2}.com
- API: https://api.{BU2}.com

底下舉例另一個產品的代號叫 Mixo，以此作為 Domain Name。他由很多 服務 or Microservices 組成，那麼名稱規則是這樣：api.mixo.abc.com/{ServiceName}，如下：

Production：
- Index: https://mixo.abc.com
- API: https://api.mixo.abc.com
Sandbox：
- Index ：https://sandbox.mixo.abc.com
- API: https://api.sandbox.mixo.abc.com
Beta：
- Index ：https://beta.mixo.abc.com
- API: https://api.beta.mixo.abc.com
Lab{N}：測試環境
- Index ：https://lab{N}.mixo.abc.com
- API: https://api.lab{N}.mixo.abc.com

Mixo 名稱源自於調式音階的 調五 Mixolydian 的前置詞，詳細參閱我的音樂 Blog 介紹：調式概念。實務上 代號 只是內部使用，不適合當作對外的名稱。

服務 (Services or Micorservices) 的規劃

一個產品底下可能會切很多服務，以下是電子商務常見的服務類型：

Mixo-Pay: 付款
Mixo-Category: 商品頁
Mixo-Member: 會員
Mixo-Order: 訂單

上述名稱，會對應到 API Gateway 的每一個 API，如下圖：

然後透過 Custom Domain 的 Mapping，規劃如下：

Production 環境的規劃：

https://api.abc.com/pay: 付款
https://api.abc.com/category: 商品頁
https://api.abc.com/member: 會員
https://api.abc.com/order: 訂單

下圖是 Amazon API Gateway 的設定方式：

Beta 環境的規劃，對應到 API 的 beta Stage

https://api.beta.abc.com/pay: 付款
https://api.beta.abc.com/category: 商品頁
https://api.beta.abc.com/member: 會員
https://api.beta.abc.com/order: 訂單

下圖是 Amazon API Gateway 的設定方式：

這樣的規劃，好處在於 Domain Name 都是同一個，然後每個 Service 都使用同樣的規範，理解之後，可以減少很多溝通成本。

規劃的邏輯就是：不同的環境使用不同的 Domain Name，然後對應不同的 Stage 作為匹配。

這些規劃，跟 Microservices 的導入也有關係，沒規劃好，整個開發流程，包含環境、溝通、路徑，一定會是一團亂。影響的將會是很恐怖的溝通成本與部署紊亂。

結論

本文紀錄 Custom Domain Name 在 Amazon API Gateway 的設定方式，還有在實際的產品如何規劃與使用，跟一開始介紹以 Domain 的概念不一樣，主要是因為取決於產品、與公司的組織有關係。

另外 URL Path 的規劃，可以參考 AWS 自身服務的規劃，像是 API Gateway 就不是放在 Domain Name 上，他的位址規則大概是這樣：

https://{AWS_REGION}.console.aws.amazon.com/{ServiceName}
https://us-west-1.console.aws.amazon.com/api-gateway

所以不難想像， AWS 新服務 (e.g., EKS) 出現時，也是透過 API Gateway 擋在前面，然後以此延伸。

規劃的同時，參考別人怎麼做，從模仿中學習。

接下來要介紹的是如何跟 VPC 內部既有的服務整合與串接。

API Gateway - Custom Domain Names

Configure the Custom Domain Names

Setup SSL Certificate using ACM

Configure Custom Domain Names in API Gateway

Base Path Mappings

Planning

Domain Names 與環境的規則

服務 (Services or Micorservices) 的規劃

結論

延伸閱讀

系列文章

參考資料

Comments

About

著作

演講

Facebook

AWS Certifications