MSE Ingress已支援Nginx Ingress核心和常用的Annotation,方便您從Nginx Ingress無縫遷移至MSE Ingress網關。此外,針對Nginx Ingress Annotation未支援的流量治理配置,MSE Ingress推出額外的Annotation來彌補Nginx Ingress的不足。本文介紹目前MSE Ingress支援的Annotation。
背景資訊
Ingress資源是Kubernetes用來管理叢集內部服務如何對外暴露的一種方式。隨著雲原生分布式應用的規模不斷擴大,官方標準定義的Ingress資源已無法滿足使用者對流量管理的訴求。各個負責應用Ingress資源的Ingress-Controller開始針對不同的情境定義適用於自身的Annotation來填補Ingress功能上的不足。其中,比較主流的Nginx Ingress到目前為止推出了100多個Annotation。
為了進一步融入K8s生態,MSE Ingress支援Nginx Ingress中比較常用且核心的Annotation,方便您從Nginx Ingress無縫遷移至MSE Ingress。此外,針對Nginx Ingress Annotation未涉及的流量治理領域,MSE Ingress推出Annotation來保持您的使用習慣。
Annotation功能概述
Kubernetes標準的Ingress只提供TLS通訊加密以及七層HTTP流量的簡單路由能力,Ingress Controller一般會通過Annotation來增強Ingress在流量治理和安全防護上的能力。
Ingress Annotation支援現狀
Nginx Ingress Annotation
為方便Nginx Ingress使用者可以無縫遷移到MSE Ingress上,MSE Ingress對Nginx Ingress Annotation進行大量的支援。支援現狀如下表所示。
Nginx Ingress Annotation | 支援總數 | 備忘 |
支援的註解 | 51 | 覆蓋90%的使用者情境。 |
不影響功能的註解 | 15 | 無需配置。 |
暫不支援的註解 | 48 | 支援中,使用情境少。 |
無法支援的註解 | 5 | 主要涉及Nginx自身的程式碼片段。 |
由於 MSE 與 Nginx 的實現不同,因此存在一定的差異。
Nginx Ingress Annotation 配置中的 Nginx變數以及程式碼片段 Snippets 無法相容。
Nginx Ingress 通過
nginx.ingress.kubernetes.io/proxy-body-size
Annotation 配置用戶端請求的 body 大小限制。如果請求的 body 超過了指定的大小限制,Nginx 會直接返回錯誤。MSE 雲原生網關採用分塊串流,無需預先佈建要求 body 的大小。在超大檔案傳輸情境中,可以在網關執行個體下的參數配置中適當調整 `DownstreamConnectionBufferLimits` 參數。
MSE Ingress Annotation
針對Nginx Ingress Annotation未涉及的治理能力,MSE Ingress推出額外的Annotation進行補充。如下資料是目前支援現狀:
MSE Ingress Annotation | 支援總數 | 備忘 |
擴充的註解 | 40 | 在Nginx基礎上增強流量治理、安全防護能力。 |
範圍含義解釋
Ingress:範圍為Ingress的Annotation的作用範圍僅限當前Ingress上定義的路由規則。
網域名稱:範圍為網域名稱的Annotation,其作用範圍為當前Ingress上出現的Host,該範圍影響其他Ingress上出現的相同Host。
服務:範圍為服務的Annotation,其作用範圍為當前Ingress上出現的Service,該範圍影響其他Ingress上出現的相同Service。
Annotation首碼
MSE Ingress支援所有Nginx Ingress的Annotation,例如nginx.ingress.kubernetes.io/xxx
的作用與mse.ingress.kubernetes.io/xxx
一致。您可以按照使用習慣使用nginx
或者mse
業務域首碼。但是MSE Ingress專屬的Annotation不可以用nginx業務域首碼來替換。
Annotation支援匯總
下文主要從流量治理和安全防護兩大模組展開說明。
流量治理
灰階發布
註解 | 範圍 | 支援度 | 說明 |
nginx.ingress.kubernetes.io/canary | Ingress | 相容 | 開啟或關閉灰階發布。 |
nginx.ingress.kubernetes.io/canary-by-header | Ingress | 相容 | 基於 |
nginx.ingress.kubernetes.io/canary-by-header-value | Ingress | 相容 | 基於 |
nginx.ingress.kubernetes.io/canary-by-header-pattern | Ingress | 相容 | 基於 |
mse.ingress.kubernetes.io/canary-by-query | Ingress | MSE擴充 | 基於 |
mse.ingress.kubernetes.io/canary-by-query-value | Ingress | MSE擴充 | 基於 |
mse.ingress.kubernetes.io/canary-by-query-pattern | Ingress | MSE擴充 | 基於 |
nginx.ingress.kubernetes.io/canary-by-cookie | Ingress | 相容 | 基於 |
mse.ingress.kubernetes.io/canary-by-cookie-value | Ingress |
| 基於 |
nginx.ingress.kubernetes.io/canary-weight | Ingress | 相容 | 基於權重和流量切分。 |
nginx.ingress.kubernetes.io/canary-weight-total | Ingress | 相容 | 權重總和。 |
多服務
註解 | 範圍 | 支援度 | 說明 |
mse.ingress.kubernetes.io/destination | Ingress | MSE拓展 | 為路由配置基於權重的服務分發。 配置文法為: 說明
|
文法樣本:
annotations:
# 60%流量到foo服務,40%流量到bar服務。
mse.ingress.kubernetes.io/destination: |
60% foo.default.svc.cluster.local:8080
40% bar.default.svc.cluster.local:9090
服務Subset
註解 | 範圍 | 支援度 | 說明 |
mse.ingress.kubernetes.io/service-subset | Ingress |
| 適用於一個Service管理多個Deployment的情境。指定ingress定義的路由轉寄到該服務下Pod集合的子集。
說明 當該服務沒有含有指定Label的Pod,流量會自動容災到該服務下的所有Pod。 |
mse.ingress.kubernetes.io/subset-labels | Ingress |
| 可選,該註解和 |
Fallback (容災)
註解 | 範圍 | 支援度 | 說明 |
nginx.ingress.kubernetes.io/default-backend | Ingress | 相容 | 容災服務。當Ingress定義的服務沒有可用節點時,請求會自動轉寄該容災服務。 |
nginx.ingress.kubernetes.io/custom-http-errors | Ingress | 相容 | 該註解和 重要 轉寄至容災服務時,請求的Path會被重寫為/,該行為與 |
正則匹配
註解 | 範圍 | 支援度 | 說明 |
nginx.ingress.kubernetes.io/use-regex | Ingress | 相容 | 正則匹配。表明Ingress定義的Path匹配為正則匹配。Regex採用RE2文法。 |
重寫
註解 | 範圍 | 支援度 | 說明 |
nginx.ingress.kubernetes.io/rewrite-target | Ingress | 相容 | 將Ingress定義的原Path重寫為指定目標,支援 |
nginx.ingress.kubernetes.io/upstream-vhost | Ingress | 相容 | 匹配Ingress定義的路由請求在轉寄給後端服務時,修改頭部Host值為指定值。 |
重新導向
Nginx和Nginx Ingress提供的功能集並不完全一致,其中Nginx具有更廣泛的功能。目前Nginx Ingress官方文檔尚未提到支援使用Nginx變數進行重新導向。儘管某些版本的Nginx Ingress可能支援Nginx變數的配置,但由於未在Nginx Ingress官方文檔中明確提及,使用這些變數可能存在相容性風險。建議避免在Nginx Ingress中使用Nginx變數。
註解 | 範圍 | 支援度 | 說明 |
nginx.ingress.kubernetes.io/ssl-redirect | Ingress | 相容 | HTTP重新導向為HTTPS。 |
nginx.ingress.kubernetes.io/force-ssl-redirect | Ingress | 相容 | HTTP重新導向為HTTPS。 |
nginx.ingress.kubernetes.io/permanent-redirect | Ingress | 相容 | 永久重新導向。 |
nginx.ingress.kubernetes.io/permanent-redirect-code | Ingress | 相容 | 永久重新導向狀態代碼。 |
nginx.ingress.kubernetes.io/temporal-redirect | Ingress | 相容 | 臨時重新導向。 |
nginx.ingress.kubernetes.io/app-root | Ingress | 相容 | 修改應用根路徑,對於訪問/的請求將會被重新導向為設定的新路徑。 |
跨域
註解 | 範圍 | 支援度 | 說明 |
nginx.ingress.kubernetes.io/enable-cors | Ingress | 相容 | 開啟或關閉跨域。 |
nginx.ingress.kubernetes.io/cors-allow-origin | Ingress | 相容 | 允許的第三方網站。 |
nginx.ingress.kubernetes.io/cors-allow-methods | Ingress | 相容 | 允許的要求方法,如GET、POST、PUT等。 |
nginx.ingress.kubernetes.io/cors-allow-headers | Ingress | 相容 | 允許的請求Header。 |
nginx.ingress.kubernetes.io/cors-expose-headers | Ingress | 相容 | 允許的暴露給瀏覽器的響應Header。 |
nginx.ingress.kubernetes.io/cors-allow-credentials | Ingress | 相容 | 是否允許攜帶憑證資訊。 |
nginx.ingress.kubernetes.io/cors-max-age | Ingress | 相容 | 預檢結果的最大緩衝時間。 |
Header控制
正式路由上定義的Header控制的註解不會作用於灰階路由。也就是說,定義在正式路由與灰階路由上的Header控制註解是互不影響並且獨立生效。利用該特性,您可以將正式路由和灰階路由的請求分別設定不同的Header操作策略。
註解 | 範圍 | 支援度 | 說明 |
mse.ingress.kubernetes.io/request-header-control-add | Ingress | MSE擴充 | 請求在轉寄給後端服務時,添加指定Header。若該Header存在,則其值拼接在原有值後面。文法如下:
|
mse.ingress.kubernetes.io/request-header-control-update | Ingress | MSE擴充 | 請求在轉寄給後端服務時,修改指定Header。若該Header存在,則其值覆蓋原有值。文法如下:
|
mse.ingress.kubernetes.io/request-header-control-remove | Ingress | MSE擴充 | 請求在轉寄給後端服務時,刪除指定Header。文法如下:
|
mse.ingress.kubernetes.io/response-header-control-add | Ingress | MSE擴充 | 請求收到後端服務響應後,在轉寄響應給用戶端之前需要添加指定Header。若該Header存在,則其值拼接在原有值後面。文法如下:
|
mse.ingress.kubernetes.io/response-header-control-update | Ingress | MSE擴充 | 請求收到後端服務響應後,在轉寄響應給用戶端之前需要修改指定Header。若該Header存在,則其值覆蓋原有值。文法如下:
|
mse.ingress.kubernetes.io/response-header-control-remove | Ingress | MSE擴充 | 請求收到後端服務響應後,在轉寄響應給用戶端之前需要刪除指定Header。文法如下:
|
逾時
註解 | 範圍 | 支援度 | 說明 |
mse.ingress.kubernetes.io/timeout | Ingress | MSE擴充 | 請求的逾時時間,單位為秒。預設未配置逾時時間。 說明 逾時設定作用在應用程式層,非傳輸層TCP。 |
重試
註解 | 範圍 | 支援度 | 說明 |
nginx.ingress.kubernetes.io/proxy-next-upstream-tries | Ingress | 相容 | 請求的最大重試次數。預設3次。 |
nginx.ingress.kubernetes.io/proxy-next-upstream-timeout | Ingress | 相容 | 請求重試的逾時時間,單位為秒。預設未配置逾時時間。 |
nginx.ingress.kubernetes.io/proxy-next-upstream | Ingress | 相容 | 請求重試條件。詳情請參見Nginx重試機制。 |
流量鏡像
註解 | 範圍 | 支援度 | 說明 |
mse.ingress.kubernetes.io/mirror-target-service | Ingress | MSE擴充 | 複製流量轉寄到指定鏡像服務。服務格式為:namespace/name:port
|
mse.ingress.kubernetes.io/mirror-percentage | Ingress |
| 複製流量的比例。可配置的值的範圍為:0~100,預設100。 |
網域名稱別名
註解 | 範圍 | 支援度 | 說明 |
nginx.ingress.kubernetes.io/server-alias | 網域名稱 |
| 定義該Ingress Spec中出現的網域名稱的別名。網域名稱別名共用源網域名稱的TLS、路由和流量治理配置。 |
單機限流(即將廢棄)
註解 | 範圍 | 支援度 | 說明 |
mse.ingress.kubernetes.io/route-limit-rpm | Ingress | MSE擴充 | 該Ingress定義的路由在每個網關執行個體上每分鐘最大請求次數。瞬時最大請求次數為該值乘以 觸發限流時,響應Body內容為
|
mse.ingress.kubernetes.io/route-limit-rps | Ingress | MSE擴充 | 該Ingress定義的路由在每個網關執行個體上每秒最大請求次數。瞬時最大請求次數為該值乘以 觸發限流時,響應Body內容為
|
mse.ingress.kubernetes.io/route-limit-burst-multiplier | Ingress | MSE擴充 | 瞬時最大請求次數的因子,預設為5。 |
全域限流量控制(推薦)
註解 | 範圍 | 支援度 | 說明 |
mse.ingress.kubernetes.io/rate-limit | Ingress |
| 該Ingress定義的路由在網關執行個體上的全域限流,即每秒最大請求數。 |
mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-code | Ingress |
| 該Ingress定義的路由觸發限流時的響應狀態代碼,預設為429。 說明 該註解與rate-limit-fallback-redirect-url互斥,即自訂響應與重新導向二選一。 |
mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body-type | Ingress |
| 該Ingress定義的路由觸發限流時的響應Body的格式,預設為text。
|
mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body | Ingress |
| 該Ingress定義的路由觸發限流時的響應Body,預設為sentinel rate limited。 |
mse.ingress.kubernetes.io/rate-limit-fallback-redirect-url | Ingress |
| 該Ingress定義的路由觸發限流時的重新導向地址。 說明 該註解與rate-limit-fallback-custom-response-code互斥,即與重新導向與自訂響應二選一。 |
全域並發控制
註解 | 範圍 | 支援度 | 說明 |
mse.ingress.kubernetes.io/concurrency-limit | Ingress |
| 該Ingress定義的路由在網關執行個體上的全域並發控制,即瞬時最大正在處理的請求數。 |
mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code | Ingress |
| 該Ingress定義的路由觸發並發控制時的響應狀態代碼,預設為429。 說明 該註解與concurrency-limit-fallback-redirect-url互斥,即自訂響應與重新導向二選一。 |
mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body-type | Ingress |
| 該Ingress定義的路由觸發並發控制時的響應Body的格式,預設為text。
|
mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body | Ingress |
| 該Ingress定義的路由在觸發並發控制時的響應Body,預設為sentinel rate limited。 |
mse.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url | Ingress |
| 該Ingress定義的路由觸發並發控制時的重新導向地址。 說明 該註解與concurrency-limit-fallback-custom-response-code互斥,即與重新導向與自訂響應二選一。 |
後端服務使用的協議
註解 | 範圍 | 支援度 | 說明 |
nginx.ingress.kubernetes.io/backend-protocol | 服務 | 部分相容,不支援AJP和FCGI。 | 指定後端服務使用的協議,預設為HTTP,支援:
|
負載平衡
註解 | 範圍 | 支援度 | 說明 |
nginx.ingress.kubernetes.io/load-balance | 服務 | 部分相容,不支援 | 後端服務的普通負載平衡演算法。預設為
|
nginx.ingress.kubernetes.io/upstream-hash-by | 服務 | 部分相容,暫不支援Nginx變數、常量的組合使用方式。 | 基於一致Hash的負載平衡演算法,MSE Ingress支援以下幾種形式:
|
服務預熱(無損上線)
註解 | 範圍 | 支援度 | 說明 |
mse.ingress.kubernetes.io/warmup | 服務 | MSE擴充 | 服務預熱時間,單位為秒。預設不開啟。 重要 服務預熱依賴於所選的負載平衡演算法,目前僅支援round_robin和least_conn。 |
Cookie親和性
註解 | 作用 | 支援度 | 說明 |
nginx.ingress.kubernetes.io/affinity | 服務 | 相容 | 親和性種類,目前只支援Cookie,預設為 |
nginx.ingress.kubernetes.io/affinity-mode | 服務 | 部分相容,暫不支援 | 親和性模式,MSE Ingress目前只支援Balanced模式,預設為 |
nginx.ingress.kubernetes.io/session-cookie-name | 服務 | 相容 | 配置指定Cookie的值作為Hash Key。 |
nginx.ingress.kubernetes.io/session-cookie-path | 服務 | 相容 | 當指定Cookie不存在,產生Cookie的Path值,預設為 |
nginx.ingress.kubernetes.io/session-cookie-max-age | 服務 | 相容 | 當指定Cookie不存在,產生Cookie的到期時間,單位為秒,預設為Session會話層級。 |
nginx.ingress.kubernetes.io/session-cookie-expires | 服務 | 相容 | 當指定Cookie不存在,產生Cookie的到期時間,單位為秒,預設為Session會話層級。 |
IP存取控制
註解 | 範圍 | 支援度 | 說明 |
nginx.ingress.kubernetes.io/whitelist-source-range | Ingress | 相容 | 指定路由上的IP白名單,支援IP地址或CIDR地址塊,以英文逗號分隔。 |
nginx.ingress.kubernetes.io/denylist-source-range | Ingress |
| 指定路由上的IP黑名單,支援IP地址或CIDR地址塊,以英文逗號分隔。 說明 該註解的優先順序高於MSE拓展的註解mse.ingress.kubernetes.io/blacklist-source-range。 |
mse.ingress.kubernetes.io/blacklist-source-range | Ingress | MSE擴充 | 指定路由上的IP黑名單,支援IP地址或CIDR地址塊,以英文逗號分隔。 |
mse.ingress.kubernetes.io/domain-whitelist-source-range | Ingress | MSE擴充 | 指定網域名稱上的IP白名單,網域名稱優先順序低於路由層級,支援IP地址或CIDR地址塊,以英文逗號分隔。 |
mse.ingress.kubernetes.io/domain-blacklist-source-range | Ingress | MSE擴充 | 指定網域名稱上的IP黑名單,網域名稱優先順序低於路由層級,支援IP地址或CIDR地址塊,以英文逗號分隔。 |
網關與後端服務之間的串連池配置
註解 | 範圍 | 支援度 | 說明 |
mse.ingress.kubernetes.io/connection-policy-tcp-max-connection | 服務 | MSE擴充 | 網關與後端服務之間可以建立串連的最大數量。 |
mse.ingress.kubernetes.io/connection-policy-tcp-max-connection-per-endpoint | 服務 | MSE擴充 | 網關與後端服務的單個節點之間可以建立串連的最大數量。 |
mse.ingress.kubernetes.io/connection-policy-http-max-request-per-connection | 服務 | MSE擴充 | 網關與後端服務之間單個串連上的最大請求數。 |
安全防護
用戶端與網關之間加密通訊
注釋 | 範圍 | 支援度 | 說明 |
mse.ingress.kubernetes.io/tls-min-protocol-version | 網域名稱 | MSE擴充 | 指定TLS的最小版本,預設值為TLSv1.0。合法值如下:
|
mse.ingress.kubernetes.io/tls-max-protocol-version | 網域名稱 | MSE擴充 | 指定TLS的最大版本,預設值為TLSv1.3。合法值如下:
|
nginx.ingress.kubernetes.io/ssl-cipher | 網域名稱 | 相容 | 指定TLS的加密套件,可以指定多個(TLS的加密套件之間使用英文冒號分隔),僅當TLS握手時採用TLSv1.0-1.2生效。 預設加密套件如下:
|
mse.ingress.kubernetes.io/auth-tls-secret | 網域名稱 | 部分相容,secret名字格式必須是:(該網域名稱認證所在的secret的名字) | 網關使用的CA認證,用於驗證MTLS握手期間,用戶端提供的認證。該註解主要應用於網關需要驗證用戶端身份的情境。 |
網關與後端服務之間通訊加密
註解 | 範圍 | 支援度 | 說明 |
nginx.ingress.kubernetes.io/proxy-ssl-secret | 服務 | 相容 | 網關使用的用戶端認證,用於後端服務對網關進行身份認證。 |
nginx.ingress.kubernetes.io/proxy-ssl-name | 服務 | 相容 | TLS握手期間使用的SNI。 |
nginx.ingress.kubernetes.io/proxy-ssl-server-name | 服務 | 相容 | 開啟或關閉TLS握手期間使用的SNI。 |
認證鑒權
Basic
註解 | 範圍 | 支援度 | 說明 |
nginx.ingress.kubernetes.io/auth-type | Ingress | 部分相容,暫只支援Basic。 | 認證類型。 |
nginx.ingress.kubernetes.io/auth-secret | Ingress | 相容 | Secret名字,格式支援 |
nginx.ingress.kubernetes.io/auth-secret-type | Ingress | 相容 | Secret內容格式。
|
nginx.ingress.kubernetes.io/auth-realm | Ingress | 相容 | 保護域。相同的保護域共用使用者名稱和密碼。 |
關於Nginx Ingress Annotation的更多資訊,請參見官方文檔。