NCP 將針對含 TLS 規格的入口和不含 TLS 規格的入口,分別建立一個第 7 層負載平衡器。您也可以建立 CRD (CustomResourceDefinitions) 來處理入口調整。
- 所有入口將取得單一 IP 位址。
- 會從 ncp.ini 的 [nsx_v3] 區段中的 external_ip_pools 選項所指定的外部 IP 集區,為入口資源配置 IP 位址。負載平衡器將在此 IP 位址及 HTTP 和 HTTPS 連接埠 (80 和 443) 上公開。
- 會從 ncp.ini 的 [nsx_v3] 區段中的 external_ip_pools_lb 選項所指定的外部 IP 集區,為入口資源配置 IP 位址。如果 external_ip_pools_lb 選項不存在,則會使用 external_ip_pools 所指定的集區。負載平衡器將在此 IP 位址及 HTTP 和 HTTPS 連接埠 (80 和 443) 上公開。
- 您可以透過變更組態並重新啟動 NCP,變更為不同的 IP 集區。
- 您可以指定 TLS 的預設憑證。如需產生憑證並將憑證掛接到 NCP 網繭中的相關資訊,請參閱以下內容。
- 不含 TLS 規格的入口將主控於 HTTP 虛擬伺服器 (連接埠 80) 之上。
- 含 TLS 規格的入口將主控於 HTTPS 虛擬伺服器 (連接埠 443) 之上。負載平衡器將充當 SSL 伺服器,並且會終止用戶端 SSL 連線。
- 支援透過新增或移除 TLS 區段來修改入口。從入口規格中移除 tls 金鑰時,入口規則將從 HTTPS 虛擬伺服器 (連接埠 443) 傳輸至 HTTP 虛擬伺服器 (連接埠 80)。同樣地,將 tls 金鑰新增至入口規格時,入口規則將從 HTTP 虛擬伺服器 (連接埠 80) 傳輸至 HTTPS 虛擬伺服器 (連接埠 443)。
- 如果單一叢集的入口定義中有重複規則,則僅套用第一個規則。具有重複規則的其他入口將註解上相關的錯誤。例如,如果您建立具有相同 host 和 path 的兩個入口,其中一個入口為 TLS,而另一個入口為非 TLS,並且 kubernetes.io/ingress.allow-http 為 false,則這兩個規則將在不同的虛擬伺服器上建立,並且彼此不會衝突。但是,如果 kubernetes.io/ingress.allow-http 為 true,則稍後套用的入口將會註解上相關的錯誤。如需詳細資訊,請參閱以下的「錯誤」小節。
- 每個叢集僅支援具有預設後端的單一入口。不符合任何入口規則的流量將會轉送至預設後端。
- 如果有多個入口具有預設後端,則僅設定第一個入口。其他入口將標註為錯誤。如需詳細資訊,請參閱以下的「錯誤」小節。
- 這些規則會依下列順序套用:
- 同時指定 host 和 path 的規則。
- 含有 Exact pathType 的規則。
- 含有 Prefix pathType 的規則。
- 含有 Regex pathType 的規則。
- 指定了 host 或 path 的規則。
- 含有 Exact pathType 的規則。
- 含有 Prefix pathType 的規則。
- 含有 Regex pathType 的規則。
附註:如果有多個路徑符合要求,系統會將優先順序指定給最長的相符路徑。
關於 pathType:- 從 Kubernetes 1.19 開始,pathType 是必要的。
- 如果設定了 use-regex,則僅當 pathType 為 ImplementationSpecific 時才會生效。
- 如果未設定 use-regex,則 ImplementationSpecific 會視為與 Exact 相同。pathType 優先於其他 NCP 註解。
- 具有不同 pathType 的兩個相符路徑可以並存。
- 對於 Prefix 類型,/foo 將比對 /foo/、/foo/bar 而非 /foo 或 /foobar。若要比對 /foo,請將 Exact 路徑 /foo 新增至入口規則。
- 同時指定 host 和 path 的規則。
- 主機名稱萬用字元
指定主機名稱時,您可以指定確切的名稱 (如 abc.example.com),也可以使用萬用字元,如 *.example.com。請注意,萬用字元將比對一或多個 DNS 標籤。如果指定 *.example.com,下表將顯示比對結果。
主機標頭 比對結果 abc.example.com 相符 abc.def.example.com 相符 example.com 無相符項目 - (如果使用原則模式,則此為適用)。如果使用預設後端建立 TLS 入口,建議您將預設後端設定為同時回應 HTTP 和 HTTPS 要求,因為:
- 如果有 TLS 入口 (在 Kubernetes/TKGI 使用案例的叢集中,或 Project Pacific 使用案例的相同命名空間中),且其主機與要求中的主機相符,則負載平衡器將會終止 TLS,並將 HTTP 要求傳送至預設後端伺服器。
- 如果沒有 TLS 入口 (在 Kubernetes/TKGI 使用案例的叢集中,或 Project Pacific 使用案例的相同命名空間中),而其主機與要求中的主機相符,則負載平衡器將會重新加密,並將 HTTPS 要求傳送至後端伺服器。
- 支援 IngressClass 資源。
- 支援 pathType 屬性。
- 支援 JWT (JSON Web Token) 用戶端驗證。此功能需要 NSX 3.0.0 或更新版本。
apiVersion: networking.k8s.io/v1 kind: IngressClass metadata: name: nsx-lb annotations: ingressclass.kubernetes.io/is-default-class: true spec: controller: k8s.io/nsx
apiVersion: networking.k8s.io/v1 kind: IngressClass metadata: name: nginx-lb annotations: ingressclass.kubernetes.io/is-default-class: false spec: controller: k8s.io/ingress-nginx
若要將 IngressClass 設定為叢集的預設值,請將註解 ingressclass.kubernetes.io/is-default-class 設定為 true。請參閱上述範例。
kubernetes.io/ingress.class 註解和 IngressClass 資源不得同時使用。
apiVersion: networking.k8s.io/v1 kind: Endpoints metadata: name: tea-svc subsets: - addresses: - ip: 172.26.0.2 targetRef: uid: 4378e0ae-5837-49c6-a0b2-178dced8eb1e ...
功能註解
註解 | 說明 | 支援的值 | 預設值 |
---|---|---|---|
kubernetes.io/ingress.allow-http | 除了 HTTPS,還會啟用 HTTP 要求 | true、false | true |
ncp/use-regex | 啟用路徑模式比對 | true、false | false |
ingress.kubernetes.io/rewrite-target | 傳入要求的重寫路徑 |
|
無預設值 |
ncp/http-redirect | 將 HTTP 要求重新導向至 HTTPS | true、false | false |
kubernetes.io/ingress.class | 指出哪個入口控制器負責此入口 | nsx、nginx 等 | nsx |
nsx/loadbalancer | 將入口置於專用的負載平衡器上 | 負載平衡器 CRD 的名稱 | 無預設值 |
ncp/allowed-source-range | 依要求來源 IP 限制入口存取 | 以逗點分隔的 CIDR、IP 位址或 IP 範圍的清單。 | 無預設值 |
ncp/ssl-mode | 針對入口中的所有規則選取 SSL 模式 | 卸載、重新加密、傳遞 | 卸載 |
ncp/jwt-alg | 決定用於驗證 JWT 簽章的演算法。啟用要與 ncp/jwt-secret 搭配設定的 JWT 用戶端驗證。 | HS256、RS256 | 無預設值 |
ncp/jwt-secret | 指定包含用於簽章驗證之 JWT 密碼或公開金鑰的 Kubernetes 密碼名稱。啟用要與 ncp/jwt-alg 搭配設定的 JWT 用戶端驗證。 | Kubernetes 密碼的名稱 | 無預設值 |
ncp/jwt-token | 要在 HTTP 要求中搜尋 JWT 的其他位置。 | _arg_<param_name>、_cookie_<cookie_name> | 無預設值 |
ncp/jwt-realm | 指定驗證失敗時傳回 401 的領域標頭。 | 指出領域的字串 | 入口規則的主機名稱 |
ncp/jwt-preserve | 成功驗證後保留 JWT 並傳遞至後端的選項。 | true、false | true |
ncp/connection_multiplexing_enabled | 啟用 TCP 多工處理。 | true、false | false |
ncp/connection_multiplexing_number | 如果啟用了 TCP 多工處理,則此選項指定可用的閒置 TCP 連線數。 | 0 - 2147483647 | 6 |
- 路徑 Regex (規則運算式) 比對
- 您可以將使用註解 ncp/use-regex 的入口 path (但不是 host) 參數的規則運算式比對啟用或停用。如果設定為 false,則會透過執行 equals 比對來執行精確路徑比對。如果設定為 true,則會透過將字串字元開頭 (^) 和字串字元結尾 ($) 新增至路徑來執行規則運算式比對,使得整個要求 URI 符合模式。請注意,使用 OR 運算子 (|) 時,一律使用括弧指定範圍,使得 ^ 和 $ 適用於所有運算元。例如,
path: /(tea|coffee|milk)
。入口規格範例:apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: cafe-ingress annotations: kubernetes.io/ingress.class: "nsx" #/tea/cup will be served by tea-svc:80 ncp/use-regex: "True" spec: rules: - host: cafe.example.com http: paths: # for this tea and coffee NCP will configure regex rule - path: /tea/(.*) pathType: ImplementationSpecific backend: service: name: tea-svc port: number: 80 - path: /coffee/(.*) pathType: ImplementationSpecific backend: service: name: coffee-svc port: number: 80 # for juice and alcohol NCP will configure Exact and Prefix rules - path: /juice pathType: Exact backend: service: name: juice-svc port: number: 80 - path: /alcohol pathType: Prefix backend: service: name: bar number: 80
- 在升級 NCP 之前更新入口
僅當您的入口需要使用字元「.」和「*」的進行所有子路徑比對時,才需要此選項。
- 更新入口以包含註解 ncp/use-regex: true。
- 對於所有子路徑比對,如果您具有 /coffee/* 或 /* 之類的路徑,請將其變更為 /coffee/.* 和 /.*。
/coffee/.* 將比對 /coffee/、/coffee/a、/coffee/b、/coffee/a/b,依此類推。/.* 將比對 /coffee、/tea、/coffee/a,依此類推。省略路徑會產生與 path: /.* 相同的行為。
- 您可以將使用註解 ncp/use-regex 的入口 path (但不是 host) 參數的規則運算式比對啟用或停用。如果設定為 false,則會透過執行 equals 比對來執行精確路徑比對。如果設定為 true,則會透過將字串字元開頭 (^) 和字串字元結尾 ($) 新增至路徑來執行規則運算式比對,使得整個要求 URI 符合模式。請注意,使用 OR 運算子 (|) 時,一律使用括弧指定範圍,使得 ^ 和 $ 適用於所有運算元。例如,
- 在下列 ingress.kubernetes.io/rewrite-target 註解範例中,路徑 /tea 和 /coffee 將重寫為 /,然後再將 URL 傳送至後端服務。
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: cafe-ingress annotations: ingress.kubernetes.io/rewrite-target: / spec: rules: - host: cafe.example.com http: paths: - path: /tea pathType: ImplementationSpecific backend: service: name: tea-svc port: number: 80 - path: /coffee pathType: ImplementationSpecific backend: service: name: coffee-svc port: number: 80
如果使用規則運算式來指定 path,則所擷取的群組會以 $1、$2 (依此類推) 的編號預留位置格式儲存。這些預留位置可用作 ingress.kubernetes.io/rewrite-target 註解中的參數。不支援已命名的擷取群組和命名的預留位置。例如,apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: cafe-ingress annotations: kubernetes.io/ingress.class: "nsx" ncp/use-regex: "true" #/tea/cup will be rewritten to /cup before sending request to endpoint ingress.kubernetes.io/rewrite-target: /$1 spec: rules: - host: cafe.example.com http: paths: - path: /tea/(.*) pathType: ImplementationSpecific backend: service: name: tea-svc port: number: 80 - path: /coffee/(.*) pathType: ImplementationSpecific backend: service: name: coffee-svc port: number: 80
- 關於註解 kubernetes.io/ingress.allow-http:
- 如果註解設定為 false,則會為 HTTPS 虛擬伺服器建立規則。
- 如果註解設定為 true 或遺失,則會同時為 HTTP 和 HTTPS 虛擬伺服器建立規則。請注意,只有在入口規格中存在 TLS 區段時才會建立 HTTPS 規則。
- 關於註解 ncp/http-redirect:
- 如果註解設定為 false,則不會將對 HTTP 虛擬伺服器的傳入 HTTP 流量 (連接埠 80) 重新導向至 HTTPS 虛擬伺服器。
- 如果註解設定為 true,則會將對 HTTP 虛擬伺服器的傳入 HTTP 流量 (連接埠 80) 重新導向至 HTTPS 虛擬伺服器 (連接埠 443)。
此註解僅在 TLS 區段存在時有效。此註解優先於 kubernetes.io/ingress.allow-http。設定為 true 時,無論 kubernetes.io/ingress.allow-http 的設定方式如何,都會將符合的 HTTP 流量導向 HTTPS。
- 關於註解 kubernetes.io/ingress.class:
- 如果值為 nsx,則此入口將由 NCP 進行處理。如果指定任何其他值,NCP 將忽略該入口。如需詳細資訊,請參閱第三方入口控制器。
- 如需有關註解 nsx/loadbalancer 的詳細資訊,請參閱用來處理入口調整的負載平衡器 CRD。
- 關於註解 ncp/allowed-source-range:
- 僅在原則模式下受支援。
- 設定時,僅當傳入要求的來源 IP 包含在此註解中時,才會予以接受。否則,將會捨棄流量。
- 您可以指定 CIDR、IP 位址和 IP 範圍的組合。例如,1.1.1.1/24、2.2.2.2、3.3.3.3-4.4.4.4。
- YAML 範例:
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: cafe-ingress annotations: kubernetes.io/ingress.class: "nsx" #Source IP addresses allowed to access ingress URL ncp/allowed-source-range: "192.168.128.0/17, 192.168.64.0-192.168.64.255, 192.168.16.32" spec: tls: - hosts: - cafe.example.com rules: - host: cafe.example.com http: paths: - path: /tea pathType: ImplementationSpecific backend: service: name: tea-svc port: number: 80 - path: /coffee pathType: ImplementationSpecific backend: service: name: coffee-svc port: number: 80
- 關於註解 ncp/ssl-mode:
- 僅在原則模式下受支援。
- 此註解適用於入口中的所有規則,且負載平衡器將在選取的 SSL 模式下針對這些規則運作。
如果 ncp/ssl-mode 設定為 reencrypt 或 passthrough,則 kubernetes.io/ingress.allow-http 必須設定為 False。如果已設定 ingress.kubernetes.io/rewrite-target、ncp/use-regex 或 ncp/allowed-source-range 註解,則無法將此註解設定為 passthrough。
如果 ncp/ssl-mode 設定為 passthrough,則不支援 rules 規格中的 path 屬性。
- 關於 JWT 用戶端驗證:
- 若要為入口下方的所有規則啟用 JWT 用戶端驗證,則需要將 ncp/jwt-alg 和 ncp/jwt-secret 設為有效的值。啟用時,只有在承載有效的 JSON Web Token 時,才會將傳入 HTTP 流量傳遞至後端。否則,流量將遭到拒絕,且具有 401 狀態。
- 此功能與下列註解不相容:
- kubernetes.io/ingress.allow-http: true
- ncp/http-redirect: true
- ncp/ssl-mode: passthrough
- ncp/jwt-alg:
- 支援的對稱演算法:HS256
- 支援的非對稱演算法:RS256
- ncp/jwt-secret:
- 對稱金鑰或公用憑證必須在 Kubernetes 密碼中進行設定,且在與入口相同的命名空間下方具有此註解中指定的名稱。
- 對於對稱演算法,密碼必須儲存在 jwt.key 欄位中。
- 對於非對稱演算法,公用憑證必須儲存在 tls.crt 欄位中。
- 如果對稱密碼或公開憑證未儲存在上述位置中,或如果儲存在密碼中的資料無效,則會停用 JWT 用戶端驗證。
- ncp/jwt-token:
- 只能在此註解中設定一個項目。
- _arg_<param_name>:針對以 URI 參數形式傳入的 JWT。指定包含 JWT 的參數名稱。
- _cookie_<cookie_name>:針對以 Cookie 形式傳入的 JWT。指定包含 JWT 的 Cookie 名稱。
- 關於 ncp/connection_multiplxing_enabled 與 ncp/connection_multiplxing_number 註解:
- TCP 多工處理不能與 HTTP NTLM 共存。在 NSX 中,如果將啟用了 TCP 多工處理的負載平衡器集區繫結至啟用了 NTLM 的第 7 層伺服器,則 NTLM 組態將優先於 TCP 多工處理。
- YAML 範例:
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: cafe-ingress annotations: ncp/connection_multiplexing_enabled: "true" ncp/connection_multiplexing_number: 100 spec: tls: - hosts: - cafe.example.com rules: - host: cafe.example.com http: paths: - path: /tea backend: service: name: tea-svc port: number: 80 - path: /coffee backend: service: name: coffee-svc port: number: 80
錯誤
- ncp/error.loadbalancer: DEFAULT_BACKEND_IN_USE
這個錯誤指示具有預設後端的入口已存在。入口將處於非作用中狀態。如果發生下列情況,即會發生此錯誤:(1) 此入口適用於 HTTP,而具有預設後端、適用於 HTTP 的另一個入口存在。(2) 此入口適用於 HTTPS,而具有預設後端、適用於 HTTPS 的另一個入口存在;或 (3) 此入口適用於 HTTP 和 HTTPS,而具有預設後端、適用於 HTTP 和 HTTPS 的另一個入口存在。若要修正錯誤,請刪除入口,然後重新建立具有正確規格的入口。
- ncp/warning.loadbalancer: SECRET_NOT_FOUND
此錯誤指出入口規格中指定的密碼不存在,或者 ncp/jwt-alg 和 ncp/jwt-secret 已加上註解,但在與入口相同的命名空間下方找不到密碼。入口將部分處於作用中狀態。若要修正錯誤,請建立遺失的密碼。請注意,註解中一旦出現警告,在入口資源的生命週期內將不會予以清除。
- ncp/warning.loadbalancer: INVALID_INGRESS
此錯誤指出下列條件之一為 true。入口將處於非作用中狀態。若要修正錯誤,請刪除入口,然後重新建立具有正確規格的入口。
- 入口規則與相同 Kubernetes 叢集中的另一個入口規則衝突。僅針對具有相同比對策略 (也就是相同 ncp/use-regex 註解值) 的入口判斷衝突。
- 將 kubernetes.io/ingress.allow-http 註解設為 false,且入口沒有 TLS 區段。
- 將 ncp/http-redirect 註解設為 true,且入口沒有 TLS 區段。
- 入口規則未指定 host 和 path。此類入口規則具有與入口預設後端相同的功能。請改用入口預設後端。
- 入口具有無法正確處理的 JWL 註解。例如:
- ncp/jwt-alg 或 ncp/jwt-secret 遺失。
- ncp/jwt-alg 設定了不受支援的演算法。
- ncp/jwt-alg 和 ncp/jwt-secret 已設定為使用其他 HTTP 啟用註解或使用 SSL 傳遞。