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 一樣。設定步驟有以下:

  1. 申請 SSL Certificate - ACM
  2. 建立 Custom Domain Names - API Gateway
  3. 設定 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 已經有關聯,就會無法建立。

建立的過程,會設定以下:

  1. Domain Name
  2. 指定 SSL Certificate, 確認已經在 us-east-1 完成
  3. 指定 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 上,他的位址規則大概是這樣:

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

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

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

延伸閱讀

參考資料


Comments