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)。
  • 如果單一叢集的入口定義中有重複規則,則僅套用第一個規則。具有重複規則的其他入口將註解上相關的錯誤。例如,如果您建立具有相同 hostpath 的兩個入口,其中一個入口為 TLS,而另一個入口為非 TLS,並且 kubernetes.io/ingress.allow-httpfalse,則這兩個規則將在不同的虛擬伺服器上建立,並且彼此不會衝突。但是,如果 kubernetes.io/ingress.allow-httptrue,則稍後套用的入口將會註解上相關的錯誤。如需詳細資訊,請參閱以下的「錯誤」小節。
  • 每個叢集僅支援具有預設後端的單一入口。不符合任何入口規則的流量將會轉送至預設後端。
  • 如果有多個入口具有預設後端,則僅設定第一個入口。其他入口將標註為錯誤。如需詳細資訊,請參閱以下的「錯誤」小節。
  • 這些規則會依下列順序套用:
    1. 同時指定 hostpath 的規則。
      1. 含有 Exact pathType 的規則。
      2. 含有 Prefix pathType 的規則。
      3. 含有 Regex pathType 的規則。
    2. 指定了 hostpath 的規則。
      1. 含有 Exact pathType 的規則。
      2. 含有 Prefix pathType 的規則。
      3. 含有 Regex pathType 的規則。

    附註:如果有多個路徑符合要求,系統會將優先順序指定給最長的相符路徑。

    關於 pathType
    • ImplementationSpecific 會被視為與 Exact 相同。
    • 具有不同 pathType 的兩個相符路徑可以並存。
    • 對於 Prefix 類型,/foo 將比對 /foo//foo/bar 而非 /foo 或 /foobar。若要比對 /foo,請將 Exact 路徑 /foo 新增至入口規則。
  • (如果使用原則模式,則此為適用)。如果使用預設後端建立 TLS 入口,建議您將預設後端設定為同時回應 HTTP 和 HTTPS 要求,因為:
    • 如果有 TLS 入口 (在 Kubernetes/TKGI 使用案例的叢集中,或 Project Pacific 使用案例的相同命名空間中),且其主機與要求中的主機相符,則負載平衡器將會終止 TLS,並將 HTTP 要求傳送至預設後端伺服器。
    • 如果沒有 TLS 入口 (在 Kubernetes/TKGI 使用案例的叢集中,或 Project Pacific 使用案例的相同命名空間中),而其主機與要求中的主機相符,則負載平衡器將會重新加密,並將 HTTPS 要求傳送至後端伺服器。
  • 支援 IngressClass 資源。
  • 支援 pathType 屬性。
  • 支援 JWT (JSON Web Token) 用戶端驗證。此功能需要 NSX-T Data Center 3.0.0 或更新版本。
從 Kubernetes 1.18 開始, kubernetes.io/ingress.class 註解已過時並取代為 IngressClass 資源。若要將 NSX-T 指定為 IngressClass 資源中的入口控制器,請將控制器參數設定為 k8s.io/nsx。例如:
kind: IngressClass
metadata:
  name: nsx-lb
  annotations:
    ingressclass.kubernetes.io/is-default-class: true
spec:
  controller: k8s.io/nsx
若要指定第三方入口控制器,請將控制器參數設定為 k8s.io/<controller name>。例如:
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 資源不得同時使用。

功能註解

下表列出 NCP 支援的註解:
註解 說明 支援的值 預設值 NCP 版本
kubernetes.io/ingress.allow-http 除了 HTTPS,還會啟用 HTTP 要求 true、false true 2.5 及更新版本
ncp/use-regex 啟用路徑模式比對 true、false false 2.5.1 及更新版本
ingress.kubernetes.io/rewrite-target 傳入要求的重寫路徑
  • (NCP 2.5 及更新版本) 以「/」開頭的路徑
  • (NCP 2.5.1 及更新版本和 NSX-T 2.5.1 及更新版本) 在規則運算式中針對群組擷取的編號預留位置路徑,例如,/$1
無預設值 請參閱「支援的值」一欄
ncp/http-redirect 將 HTTP 要求重新導向至 HTTPS true、false false 2.5.1 及更新版本
kubernetes.io/ingress.class 指出哪個入口控制器負責此入口 nsx、nginx 等 nsx 2.5 及更新版本
nsx/loadbalancer 將入口置於專用的負載平衡器上 負載平衡器 CRD 的名稱 無預設值 2.5.1 及更新版本
(NCP 3.1 及更早版本) ncp/whitelist-source-range

(NCP 3.1.1 及更新版本) ncp/allowed-source-range

依要求來源 IP 限制入口存取 以逗點分隔的 CIDR、IP 位址或 IP 範圍的清單。 無預設值 3.0.0 及更新版本
ncp/ssl-mode 針對入口中的所有規則選取 SSL 模式 卸載、重新加密、傳遞 卸載 3.0.1 及更新版本
ncp/jwt-alg 決定用於驗證 JWT 簽章的演算法。啟用要與 ncp/jwt-secret 搭配設定的 JWT 用戶端驗證。 HS256、RS256 無預設值 3.0.2 及更新版本
ncp/jwt-secret 指定包含用於簽章驗證之 JWT 密碼或公開金鑰的 Kubernetes 密碼名稱。啟用要與 ncp/jwt-alg 搭配設定的 JWT 用戶端驗證。 Kubernetes 密碼的名稱 無預設值 3.0.2 及更新版本
ncp/jwt-token 要在 HTTP 要求中搜尋 JWT 的其他位置。 _arg_<param_name>、_cookie_<cookie_name> 無預設值 3.0.2 及更新版本
ncp/jwt-realm 指定驗證失敗時傳回 401 的領域標頭。 指出領域的字串 入口規則的主機名稱 3.0.2 及更新版本
ncp/jwt-preserve 成功驗證後保留 JWT 並傳遞至後端的選項。 true、false true 3.0.2 及更新版本
有關註解的詳細資料:
  • 路徑 Regex (規則運算式) 比對
    • 針對 NCP 2.5.0 和更早版本

      在 NCP 2.5.0 和更早版本中,會使用規則運算式字元「.」和「*」自動啟用所有子路徑比對。例如,路徑 /coffee/.* 會比對後面不跟字元或後跟一或多個字元的 /coffee/,例如 /coffee//coffee/a/coffee/b,而非 /coffee/coffeecup/coffeecup/a

      入口規格範例:
      kind: Ingress
      metadata:
        name: cafe-ingress
      spec:
        rules:
        - http:
            paths:
            - path: /coffee/.*    #Matches /coffee/, /coffee/a but NOT /coffee, /coffeecup, etc.
              backend:
                serviceName: coffee-svc
                servicePort: 80
    • 針對 NCP 2.5.1 及更新版本
      您可以將使用註解 ncp/use-regex 的入口 path (但不是 host) 參數的規則運算式比對啟用或停用。如果設定為 false,則會透過執行 equals 比對來執行精確路徑比對。如果設定為 true,則會透過將字串字元開頭 (^) 和字串字元結尾 ($) 新增至路徑來執行規則運算式比對,使得整個要求 URI 符合模式。請注意,使用 OR 運算子 (|) 時,一律使用括弧指定範圍,使得 ^ 和 $ 適用於所有運算元。例如, path: /(tea|coffee|milk)。入口規格範例:
      kind: Ingress
      metadata:
        name: cafe-ingress
        annotations:
          kubernetes.io/ingress.class: "nsx"
          ncp/use-regex: "true"
      spec:
        rules:
        - host: cafe.example.com
          http:
            paths:
            - path: /tea/.*
              backend:
                serviceName: tea-svc
                servicePort: 80
    • 在將 NCP 升級至 2.5.1 及更新版本之前更新入口
      僅當您的入口需要使用字元「.」和「*」的進行所有子路徑比對時,才需要此選項。
      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 的範例:
    kind: Ingress
    metadata:
      name: cafe-ingress
      annotations:
        ingress.kubernetes.io/rewrite-target: /
    spec:
      rules:
      - host: cafe.example.com
        http:
          paths:
          - path: /tea
            backend:
              serviceName: tea-svc
              servicePort: 80
          - path: /coffee
            backend:
              serviceName: coffee-svc
              servicePort: 80

    路徑 /tea/coffee 將重寫為 /,然後再將 URL 傳送至後端服務。

    從 NCP 2.5.1 和 NSX-T 2.5.1 開始,如果使用規則運算式指定 path,則所擷取的群組會以 $1、$2 (依此類推) 的編號預留位置格式儲存。這些預留位置可用作 ingress.kubernetes.io/rewrite-target 註解中的參數。不支援已命名的擷取群組和命名的預留位置。例如,
    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/(.*)
            backend:
              serviceName: tea-svc
              servicePort: 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 (在 NCP 3.1 及更早版本中,此註解名為 ncp/whitelist-source-range):
    • 設定時,僅當傳入要求的來源 IP 包含在此註解中時,才會予以接受。否則,將會捨棄流量。
    • 您可以指定 CIDR、IP 位址和 IP 範圍的組合。例如,1.1.1.1/24、2.2.2.2、3.3.3.3-4.4.4.4。
    • 範例 YAML:
      kind: Ingress
      metadata:
        name: cafe-ingress
        annotations:
          kubernetes.io/ingress.class: "nsx"
          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
              backend:
                serviceName: tea-svc
                servicePort: 80
  • 關於註解 ncp/ssl-mode
    • 此註解適用於入口中的所有規則,且負載平衡器將在選取的 SSL 模式下針對這些規則運作。

      附註:如果 ncp/ssl-mode 設定為 reencryptpassthrough,則 kubernetes.io/ingress.allow-http 必須設定為 False。如果已設定 ingress.kubernetes.io/rewrite-targetncp/use-regexncp/allowed-source-range 註解,則無法將此註解設定為 passthrough。(請注意,在 NCP 3.1 及更早版本中,ncp/allowed-source-range 名為 ncp/whitelist-source-range)。

  • 關於 JWT 用戶端驗證:
    • 若要為入口下方的所有規則啟用 JWT 用戶端驗證,則需要將 ncp/jwt-algncp/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/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-algncp/jwt-secret 已加上註解,但在與入口相同的命名空間下方找不到密碼。入口將部分處於作用中狀態。若要修正錯誤,請建立遺失的密碼。請注意,註解中一旦出現警告,在入口資源的生命週期內將不會予以清除。

  • ncp/warning.loadbalancer: INVALID_INGRESS
    此錯誤指出下列條件之一為 true。入口將處於非作用中狀態。若要修正錯誤,請刪除入口,然後重新建立具有正確規格的入口。
    • 入口規則與相同 Kubernetes 叢集中的另一個入口規則衝突。僅針對具有相同比對策略 (也就是相同 ncp/use-regex 註解值) 的入口判斷衝突。
    • kubernetes.io/ingress.allow-http 註解設為 false,且入口沒有 TLS 區段。
    • ncp/http-redirect 註解設為 true,且入口沒有 TLS 區段。
    • 入口規則未指定 hostpath。此類入口規則具有與入口預設後端相同的功能。請改用入口預設後端。
    • 入口具有無法正確處理的 JWL 註解。例如:
      • ncp/jwt-algncp/jwt-secret 遺失。
      • ncp/jwt-alg 設定了不受支援的演算法。
      • ncp/jwt-algncp/jwt-secret 已設定為使用其他 HTTP 啟用註解或使用 SSL 傳遞。