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，則稍後套用的入口將會註解上相關的錯誤。如需詳細資訊，請參閱以下的「錯誤」小節。
  • 每個叢集僅支援具有預設後端的單一入口。不符合任何入口規則的流量將會轉送至預設後端。
  • 如果有多個入口具有預設後端，則僅設定第一個入口。其他入口將標註為錯誤。如需詳細資訊，請參閱以下的「錯誤」小節。
  • 這些規則會依下列順序套用：
    1. 同時指定 host 和 path 的規則。
      1. 含有 Exact pathType 的規則。
      2. 含有 Prefix pathType 的規則。
      3. 含有 Regex pathType 的規則。
    2. 指定了 host 或 path 的規則。
      1. 含有 Exact pathType 的規則。
      2. 含有 Prefix pathType 的規則。
      3. 含有 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 新增至入口規則。
  • 主機名稱萬用字元
    指定主機名稱時，您可以指定確切的名稱 (如 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 或更新版本。
從 Kubernetes 1.18 開始， kubernetes.io/ingress.class 註解已棄用並取代為 IngressClass 資源。若要將 NSX 指定為 IngressClass 資源中的入口控制器，請將控制器參數設定為 k8s.io/nsx。例如： 
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: nsx-lb
  annotations:
    ingressclass.kubernetes.io/is-default-class: true
spec:
  controller: k8s.io/nsx
若要指定第三方入口控制器，請將控制器參數設定為 k8s.io/<controller name>。例如： 
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 資源不得同時使用。

如果您手動設定 Endpoints 物件，請務必設定 targetRef 參數。此值應為後端網繭的 UID。例如： 
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
...

功能註解

下表列出 NCP 支援的註解：
註解 說明 支援的值 預設值
kubernetes.io/ingress.allow-http 除了 HTTPS，還會啟用 HTTP 要求 true、false true
ncp/use-regex 啟用路徑模式比對 true、false false
ingress.kubernetes.io/rewrite-target 傳入要求的重寫路徑
  • 以「/」開頭的路徑
  • 在規則運算式中針對群組擷取的編號預留位置路徑，例如，/$1
 無預設值
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 之前更新入口
      僅當您的入口需要使用字元「.」和「*」的進行所有子路徑比對時，才需要此選項。
      1. 更新入口以包含註解 ncp/use-regex: true。
      2. 對於所有子路徑比對，如果您具有 /coffee/* 或 /* 之類的路徑，請將其變更為 /coffee/.* 和 /.*。

        /coffee/.* 將比對 /coffee/、/coffee/a、/coffee/b、/coffee/a/b，依此類推。/.* 將比對 /coffee、/tea、/coffee/a，依此類推。省略路徑會產生與 path: /.* 相同的行為。

  • 在下列 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，警告索引鍵為 ncp/warning.loadbalancer。可能的錯誤和警告如下：
  • 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 傳遞。