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在流量治理和安全防護上的能力。目前MSE Ingress可以通過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 | 兼容 | 基于 |
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匹配為正則匹配。正則表達式采用RE2語法。 |
重寫
注解 | 作用域 | 支持度 | 說明 |
nginx.ingress.kubernetes.io/rewrite-target | Ingress | 兼容 | 將Ingress定義的原Path重寫為指定目標,支持 |
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存在,則其值拼接在原有值后面。語法如下:
|
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的更多信息,請參見官方文檔。