MSE Ingress支援哪些Annotation - Container Service for Kubernetes

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在流量治理和安全防護上的能力。

Annotation支援現狀

Nginx Annotation

為方便Nginx Ingress使用者可以無縫遷移到MSE Ingress上，MSE Ingress對Nginx Ingress Annotation進行大量的支援。支援現狀如下表所示。

Nginx Annotation	支援總數	備忘
支援的註解	51	覆蓋90%的使用者情境。
不影響功能的註解	15	無需配置。
暫不支援的註解	48	支援中，使用情境少。
無法支援的註解	5	主要涉及Nginx自身的程式碼片段。

MSE Annotation

針對Nginx Ingress Annotation未涉及的治理能力，MSE Ingress推出額外的Annotation進行補充。如下資料是目前支援現狀：

MSE 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	相容	基於`Request Header Key`流量切分。
nginx.ingress.kubernetes.io/canary-by-header-value	Ingress	相容	基於`Request Header Value`流量切分，Value為精確匹配。
nginx.ingress.kubernetes.io/canary-by-header-pattern	Ingress	相容	基於`Request Header Value`流量切分，Value為正則匹配。
mse.ingress.kubernetes.io/canary-by-query	Ingress	MSE擴充	基於`URL Query Parameter`流量切分。
mse.ingress.kubernetes.io/canary-by-query-value	Ingress	MSE擴充	基於`URL Query Parameter`流量切分，Value為精確匹配。
mse.ingress.kubernetes.io/canary-by-query-pattern	Ingress	MSE擴充	基於`URL Query Parameter`流量切分，Value為正則匹配。
nginx.ingress.kubernetes.io/canary-by-cookie	Ingress	相容	基於`Request Cookie Key`流量切分。
mse.ingress.kubernetes.io/canary-by-cookie-value	Ingress	MSE擴充要求網關版本1.2.30	基於`Request Cookie Value`流量切分，Value為精確匹配。
nginx.ingress.kubernetes.io/canary-weight	Ingress	相容	基於權重和流量切分。
nginx.ingress.kubernetes.io/canary-weight-total	Ingress	相容	權重總和。

多服務

註解

範圍

支援度

說明

mse.ingress.kubernetes.io/destination

Ingress

MSE拓展

為路由配置基於權重的服務分發。

配置文法為：{weight}% {serviceName}.{serviceNamespace}.svc.cluster.local:{port}。

說明

配置該註解後，該Ingress上所有路由規則的目標服務修改為該註解指定的服務。
如果該註解的配置文法不符合要求，則會被忽略。Ingress上所有路由規則的目標服務不會被修改。

文法樣本：

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

MSE拓展
要求網關版本1.2.25

適用於一個Service管理多個Deployment的情境。指定ingress定義的路由轉寄到該服務下Pod集合的子集。

當subset-labels註解未配置時，該註解的配置值的含義如下：
- 當配置為""或者base時，請求會被轉寄到Label中含有opensergo.io/canary: ""或不含有任何opensergo.io/canary為首碼的Label Key的Pod集合，即標籤上打了空標和未打標的Pod集合。
- 當配置為其他值，請求會被轉寄到Label中含有opensergo.io/canary-{該值}: "該值"的Pod集合。比如當配置為gray，請求會被轉寄到Label中含有opensergo.io/canary-gray: gray的Pod集合。
當subset-labels註解配置時，請求僅會轉寄Label中含有subset-labels註解定義的Key:Value的Pod集合。

說明

當該服務沒有含有指定Label的Pod，流量會自動容災到該服務下的所有Pod。

mse.ingress.kubernetes.io/subset-labels

Ingress

MSE拓展
要求網關版本1.2.25

可選，該註解和service-subset一起工作，用於明確配置含有哪些Label的Pod屬於同一Subset。

Fallback （容災）

註解	範圍	支援度	說明
nginx.ingress.kubernetes.io/default-backend	Ingress	相容	容災服務。當Ingress定義的服務沒有可用節點時，請求會自動轉寄該容災服務。
nginx.ingress.kubernetes.io/custom-http-errors	Ingress	相容	該註解和`default-backend`一起工作。當後端服務返回指定HTTP響應碼，原始請求會被再次轉寄至容災服務。重要轉寄至容災服務時，請求的Path會被重寫為/，該行為與`ingress-nginx`保持一致

正則匹配

註解	範圍	支援度	說明
nginx.ingress.kubernetes.io/use-regex	Ingress	相容	正則匹配。表明Ingress定義的Path匹配為正則匹配。Regex採用RE2文法。

重寫

註解	範圍	支援度	說明
nginx.ingress.kubernetes.io/rewrite-target	Ingress	相容	將Ingress定義的原Path重寫為指定目標，支援`Group Capture`。
nginx.ingress.kubernetes.io/upstream-vhost	Ingress	相容	匹配Ingress定義的路由請求在轉寄給後端服務時，修改頭部Host值為指定值。

重新導向

註解	範圍	支援度	說明
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存在，則其值拼接在原有值後面。文法如下：單個Header：Key Value。多個Header：使用YAML特殊符號`\|` ，使每對Key Value單獨處於一行。
mse.ingress.kubernetes.io/request-header-control-update	Ingress	MSE擴充	請求在轉寄給後端服務時，修改指定Header。若該Header存在，則其值覆蓋原有值。文法如下：單個Header：Key Value。多個Header：使用YAML特殊符號`\|` ，使每對Key Value單獨處於一行。
mse.ingress.kubernetes.io/request-header-control-remove	Ingress	MSE擴充	請求在轉寄給後端服務時，刪除指定Header。文法如下：單個Header：Key。多個Header：使用英文逗號分隔。
mse.ingress.kubernetes.io/response-header-control-add	Ingress	MSE擴充	請求收到後端服務響應後，在轉寄響應給用戶端之前需要添加指定Header。若該Header存在，則其值拼接在原有值後面。文法如下：單個Header：`Key Value`。多個Header：使用YAML特殊符號`\|` ，使每對Key Value單獨處於一行。
mse.ingress.kubernetes.io/response-header-control-update	Ingress	MSE擴充	請求收到後端服務響應後，在轉寄響應給用戶端之前需要修改指定Header。若該Header存在，則其值覆蓋原有值。文法如下：單個Header：`Key Value`。多個Header：使用YAML特殊符號`\|` ，使每對Key Value單獨處於一行。
mse.ingress.kubernetes.io/response-header-control-remove	Ingress	MSE擴充	請求收到後端服務響應後，在轉寄響應給用戶端之前需要刪除指定Header。文法如下：單個Header：Key。多個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

namespace: K8s Service所在的命名空間，可選，預設為Ingress所在的命名空間。
name：K8s Service的名稱，必選。
port：待轉寄至K8s Service的連接埠，可選，預設為第一個連接埠。

mse.ingress.kubernetes.io/mirror-percentage

Ingress

MSE擴充
要求網關版本1.2.32

複製流量的比例。可配置的值的範圍為：0~100，預設100。

網域名稱別名

註解	範圍	支援度	說明
nginx.ingress.kubernetes.io/server-alias	網域名稱	部分相容（僅支援精確網域名稱和泛網域名稱）要求網關版本1.2.30	定義該Ingress Spec中出現的網域名稱的別名。網域名稱別名共用源網域名稱的TLS、路由和流量治理配置。

單機限流（即將廢棄）

註解	範圍	支援度	說明
mse.ingress.kubernetes.io/route-limit-rpm	Ingress	MSE擴充	該Ingress定義的路由在每個網關執行個體上每分鐘最大請求次數。瞬時最大請求次數為該值乘以`limit-burst-multiplier`。觸發限流時，響應Body內容為`local_rate_limited`，響應狀態代碼說明：網關版本小於1.2.23：狀態代碼為503。網關版本1.2.23及以上：狀態代碼為429。
mse.ingress.kubernetes.io/route-limit-rps	Ingress	MSE擴充	該Ingress定義的路由在每個網關執行個體上每秒最大請求次數。瞬時最大請求次數為該值乘以`limit-burst-multiplier`。觸發限流時，響應Body內容為`local_rate_limited`，響應狀態代碼說明：網關版本小於1.2.23：狀態代碼為503。網關版本1.2.23及以上：狀態代碼為429。
mse.ingress.kubernetes.io/route-limit-burst-multiplier	Ingress	MSE擴充	瞬時最大請求次數的因子，預設為5。

全域限流量控制（推薦）

註解	範圍	支援度	說明
mse.ingress.kubernetes.io/rate-limit	Ingress	MSE拓展要求網關版本1.2.25	該Ingress定義的路由在網關執行個體上的全域限流，即每秒最大請求數。
mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-code	Ingress	MSE拓展要求網關版本1.2.25	該Ingress定義的路由觸發限流時的響應狀態代碼，預設為429。說明該註解與rate-limit-fallback-redirect-url互斥，即自訂響應與重新導向二選一。
mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body-type	Ingress	MSE拓展要求網關版本1.2.25	該Ingress定義的路由觸發限流時的響應Body的格式，預設為text。配置為text時：響應的Content-Type的值為text/plain; charset=UTF-8 配置為json時：響應的Content-Type的值為application/json; charset=UTF-8
mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body	Ingress	MSE拓展要求網關版本1.2.25	該Ingress定義的路由觸發限流時的響應Body，預設為sentinel rate limited。
mse.ingress.kubernetes.io/rate-limit-fallback-redirect-url	Ingress	MSE拓展要求網關版本1.2.25	該Ingress定義的路由觸發限流時的重新導向地址。說明該註解與rate-limit-fallback-custom-response-code互斥，即與重新導向與自訂響應二選一。

全域並發控制

註解	範圍	支援度	說明
mse.ingress.kubernetes.io/concurrency-limit	Ingress	MSE拓展要求網關版本1.2.25	該Ingress定義的路由在網關執行個體上的全域並發控制，即瞬時最大正在處理的請求數。
mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code	Ingress	MSE拓展要求網關版本1.2.25	該Ingress定義的路由觸發並發控制時的響應狀態代碼，預設為429。說明該註解與concurrency-limit-fallback-redirect-url互斥，即自訂響應與重新導向二選一。
mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body-type	Ingress	MSE拓展要求網關版本1.2.25	該Ingress定義的路由觸發並發控制時的響應Body的格式，預設為text。配置為text時：響應的Content-Type的值為text/plain; charset=UTF-8 配置為json時：響應的Content-Type的值為application/json; charset=UTF-8
mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body	Ingress	MSE拓展要求網關版本1.2.25	該Ingress定義的路由觸發並發控制時的響應Body，預設為sentinel rate limited。
mse.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url	Ingress	MSE拓展要求網關版本1.2.25	該Ingress定義的路由觸發並發控制時的重新導向地址。說明該註解與concurrency-limit-fallback-custom-response-code互斥，即與重新導向與自訂響應二選一。

後端服務使用的協議

註解

範圍

支援度

說明

nginx.ingress.kubernetes.io/backend-protocol

服務

部分相容，不支援AJP和FCGI。

指定後端服務使用的協議，預設為HTTP，支援：

HTTP
HTTP2
HTTPS
gRPC
gRPCS

負載平衡

註解

範圍

支援度

說明

nginx.ingress.kubernetes.io/load-balance

服務

部分相容，不支援ewma演算法。若配置為EWMA演算法，會回退到round_robin演算法。

後端服務的普通負載平衡演算法。預設為round_robin。合法值如下：

round_robin：基於輪詢的負載平衡。
least_conn：基於最小請求數的負載平衡。
random：基於隨機的負載平衡。

nginx.ingress.kubernetes.io/upstream-hash-by

服務

部分相容，暫不支援Nginx變數、常量的組合使用方式。

基於一致Hash的負載平衡演算法，MSE Ingress支援以下幾種形式：

MSE Ingress支援配置部分Nginx變數：
- $request_uri：請求的Path（包括路徑參數）作為Hash Key。
- $host：請求的Host作為Hash Key。
- $remote_addr：請求的用戶端IP作為Hash Key。
基於請求Header的一致性Hash。您只需配置為$http_headerName。
基於請求路徑參數的一致性Hash。您只需配置為$arg_varName。

服務預熱（無損上線）

註解	範圍	支援度	說明
mse.ingress.kubernetes.io/warmup	服務	MSE擴充	服務預熱時間，單位為秒。預設不開啟。重要服務預熱依賴於所選的負載平衡演算法，目前僅支援round_robin和least_conn。

Cookie親和性

註解	作用	支援度	說明
nginx.ingress.kubernetes.io/affinity	服務	相容	親和性種類，目前只支援Cookie，預設為`cookie`
nginx.ingress.kubernetes.io/affinity-mode	服務	部分相容，暫不支援`persistent`模式。	親和性模式，MSE Ingress目前只支援Balanced模式，預設為`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	相容要求網關版本1.2.31	指定路由上的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。合法值如下： TLSv1.0 TLSv1.1 TLSv1.2 TLSv1.3
mse.ingress.kubernetes.io/tls-max-protocol-version	網域名稱	MSE擴充	指定TLS的最大版本，預設值為TLSv1.3。合法值如下： TLSv1.0 TLSv1.1 TLSv1.2 TLSv1.3
nginx.ingress.kubernetes.io/ssl-cipher	網域名稱	相容	指定TLS的加密套件，可以指定多個（TLS的加密套件之間使用英文冒號分隔），僅當TLS握手時採用TLSv1.0-1.2生效。預設加密套件如下： ECDHE-ECDSA-AES128-GCM-SHA256 ECDHE-RSA-AES128-GCM-SHA256 ECDHE-ECDSA-AES128-SHA ECDHE-RSA-AES128-SHA AES128-GCM-SHA256 AES128-SHA ECDHE-ECDSA-AES256-GCM-SHA384 ECDHE-RSA-AES256-GCM-SHA384 ECDHE-ECDSA-AES256-SHA ECDHE-RSA-AES256-SHA AES256-GCM-SHA384 AES256-SHA
mse.ingress.kubernetes.io/auth-tls-secret	網域名稱	部分相容，secret名字格式必須是：（該網域名稱認證所在的secret的名字）`-cacert`	網關使用的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名字，格式支援`<namespace>/<name>`，包含被授予能夠訪問該Ingress上定義的路由的存取權限的使用者名稱和密碼。
nginx.ingress.kubernetes.io/auth-secret-type	Ingress	相容	Secret內容格式。 `auth-file`：Data的Key為auth，Value為使用者名稱和密碼，多帳號斷行符號分隔。 `auth-map`：Data的Key為使用者名稱，Value為密碼。
nginx.ingress.kubernetes.io/auth-realm	Ingress	相容	保護域。相同的保護域共用使用者名稱和密碼。

關於Nginx-Ingress Annotation的更多資訊，請參見官方文檔。