Ingress

NCP 将分别为具有 TLS 规范和不具有 TLS 规范的 Ingress 各创建一个 L7 负载均衡器。您还可以创建 CRD (CustomResourceDefinition) 来处理 Ingress 缩放。

请注意以下事项：

• 所有 Ingress 都将获得单个 IP 地址。
• 从 ncp.ini 的 [nsx_v3] 部分中的 external_ip_pools 选项指定的外部 IP 池为 Ingress 资源分配 IP 地址。将在此 IP 地址以及 HTTP 端口 80 和 HTTPS 端口 443 上公开负载均衡器。
• 从 ncp.ini 的 [nsx_v3] 部分中的 external_ip_pools_lb 选项指定的外部 IP 池为 Ingress 资源分配 IP 地址。如果 external_ip_pools_lb 选项不存在，则使用 external_ip_pools 指定的池。将在此 IP 地址以及 HTTP 端口 80 和 HTTPS 端口 443 上公开负载均衡器。
• 可以通过更改配置并重新启动 NCP 来更改为不同的 IP 池。
• 可以为 TLS 指定默认证书。有关生成证书并将证书挂载到 NCP pod 的信息，请参见下文。
• 将在 HTTP 虚拟服务器（端口 80）上托管不具有 TLS 规范的 Ingress。
• 将在 HTTPS 虚拟服务器（端口 443）上托管具有 TLS 规范的 Ingress。负载均衡器将充当 SSL 服务器并终止客户端 SSL 连接。
• 支持通过添加或移除 TLS 部分来修改 Ingress。从 Ingress 规范中移除 tls 密钥后，Ingress 规则将从 HTTPS 虚拟服务器（端口 443）传输到 HTTP 虚拟服务器（端口 80）。同样，将 tls 密钥添加到 Ingress 规范后，Ingress 规则将从 HTTP 虚拟服务器（端口 80）传输到 HTTPS 虚拟服务器（端口 443）。
• 如果单个集群的 Ingress 定义中存在重复的规则，则只会应用第一个规则。具有重复规则的其他 Ingress 将被注释为出现错误。例如，如果创建两个具有相同 host 和 path 的 Ingress，其中一个 Ingress 为 TLS，另一个为非 TLS，并且 kubernetes.io/ingress.allow-http 为 false，则两个规则将在不同的虚拟服务器上创建，并且不会相互冲突。但是，如果 kubernetes.io/ingress.allow-http 为 true，则稍后应用的 Ingress 将被注释为出现错误。有关详细信息，请参见下面的“错误”部分。
• 每个集群只支持一个具有默认后端的 Ingress。不匹配任何 Ingress 规则的流量将被转发到默认后端。
• 如果存在多个具有默认后端的 Ingress，则只会配置第一个输入。其他 Ingress 将被注释为出现错误。有关详细信息，请参见下面的“错误”部分。
• 规则将按以下顺序应用：
  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，则仅当 ImplementationSpecific 为 pathType 时才会生效。
  • 如果未设置 use-regex，则 ImplementationSpecific 会视为与 Exact 相同。pathType 优先于其他 NCP 注释。
  • 具有不同 pathType 的两个匹配路径可以共存。
  • 对于 Prefix 类型，/foo 将匹配 /foo/、/foo/bar，但不匹配 /foo 或 /foobar。要匹配 /foo，请将 Exact 路径 /foo 添加到 Ingress 规则中。
• 主机名通配符
  指定主机名时，您可以指定确切的名称（如 abc.example.com），也可以使用通配符，如 *.example.com。请注意，通配符将与一个或多个 DNS 标签匹配。如果指定 *.example.com，下表将显示匹配结果。

  主机标头	匹配结果
  abc.example.com	匹配
  abc.def.example.com	匹配
  example.com	无匹配项

• （如果您使用策略模式，则此内容适用。）如果创建的 TLS Ingress 具有默认后端，建议您将该默认后端设置为同时响应 HTTP 和 HTTPS 请求，原因如下：
  • 如果存在主机与请求中的主机相匹配的 TLS Ingress（在 Kubernetes/TKGI 用例的集群中，或在与 Project Pacific 用例相同的命名空间中），则负载均衡器将终止 TLS 并将 HTTP 请求发送到默认后端服务器。
  • 如果不存在主机与请求中的主机相匹配的 TLS Ingress（在 Kubernetes/TKGI 用例的集群中，或在与 Project Pacific 用例相同的命名空间中），则负载均衡器将重新加密 HTTPS 请求并将其发送到后端服务器。
• 支持 IngressClass 资源。
• 支持 pathType 属性。
• 支持 JWT（JSON Web 令牌）客户端身份验证。此功能需要 NSX 3.0.0 或更高版本。

从 Kubernetes 1.18 开始， kubernetes.io/ingress.class 注释已弃用，并替换为 IngressClass 资源。要将 NSX 指定为 IngressClass 资源中的 Ingress 控制器，请将控制器参数设置为 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

要指定第三方 Ingress 控制器，需要将控制器参数设置为 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 参数。该值应该是后端 Pod 的 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	指示负责此 Ingress 的 Ingress 控制器	nsx、nginx 等	nsx
nsx/loadbalancer	将 Ingress 放置在专用负载均衡器上	LoadBalancer CRD 的名称	无默认值
ncp/allowed-source-range	通过请求源 IP 限制 Ingress 访问权限	以逗号分隔的 CIDR、IP 地址或 IP 范围列表。	无默认值
ncp/ssl-mode	为 Ingress 中的所有规则选择 SSL 模式	offload、reencrypt、passthrough	offload
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 的领域标头。	表示领域的字符串	Ingress 规则的主机名
ncp/jwt-preserve	用于在身份验证成功后保留 JWT 并传递到后端的选项。	true、false	true
ncp/connection_multiplexing_enabled	启用 TCP 多路复用。	true、false	false
ncp/connection_multiplexing_number	如果启用了 TCP 多路复用，则此选项指定可用的空闲 TCP 连接数。	0 - 2147483647	6

有关注释的详细信息：

• 路径正则表达式匹配
  • 您可以使用注释 ncp/use-regex 启用或禁用 Ingress path（而不是 host）参数的正则表达式匹配。如果将该注释设置为 false，将通过执行 equals 匹配来执行精确路径匹配。如果将该注释设置为 true，将通过向路径添加字符串开头字符 (^) 和字符串结尾字符 ($) 来执行正则表达式匹配，以便整个请求 URI 与模式相匹配。请注意，使用 OR 运算符 (|) 时，请始终使用圆括号指定范围，以使 ^ 和 $ 应用于所有操作数。例如，path: /(tea|coffee|milk)。Ingress 规范示例：

    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 之前更新 Ingress
    仅当您的 Ingress 要求使用字符“.”和“*”进行所有子路径匹配时，才需要这样做。

    1. 更新 Ingress 以包含注释 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 注释示例中，在将 URL 发送到后端服务之前，路径 /tea 和 /coffee 将重写为 /。

  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 虚拟服务器创建规则。请注意，仅当 Ingress 规范中存在 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 处理此 Ingress。如果指定了任何其他值，则 NCP 将忽略此 Ingress。有关详细信息，请参见第三方 Ingress 控制器。
• 有关注释 nsx/loadbalancer 的详细信息，请参见用于处理 Ingress 缩放的 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：
  • 仅在策略模式下受支持。
  • 此注释适用于 Ingress 中的所有规则，并且负载均衡器将在为这些规则选定的 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 客户端身份验证：
  • 要为 Ingress 下的所有规则启用 JWT 客户端身份验证，需要同时为 ncp/jwt-alg 和 ncp/jwt-secret 设置有效的值。如果启用，则只有在具有有效的 JSON Web 令牌时，才会将入站 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 密钥中配置，并且在此注释中指定的名称必须与 Ingress 位于相同的命名空间中。
    • 对于对称算法，必须将密钥存储在 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 的 L7 服务器，则 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

错误

错误作为注释添加到 Ingress 资源中。错误键为 ncp/error.loadbalancer，警告键为 ncp/warning.loadbalancer。可能的错误和警告包括：

• ncp/error.loadbalancer: DEFAULT_BACKEND_IN_USE

  该错误表示具有默认后端的 Ingress 已存在。Ingress 将处于非活动状态。如果发生以下几种情况，则会出现此错误：(1) 此 Ingress 用于 HTTP，并且存在另一个用于 HTTP 且具有默认后端的 Ingress；(2) 此 Ingress 用于 HTTPS，并且存在另一个用于 HTTPS 且具有默认后端的 Ingress；或 (3) 此 Ingress 用于 HTTP 和 HTTPS，并且存在另一个用于 HTTP 和 HTTPS 且具有默认后端的 Ingress。要解决此错误，请删除 Ingress 并使用正确的规范重新创建。

• ncp/warning.loadbalancer: SECRET_NOT_FOUND

  该错误表示 Ingress 规范中指定的密钥不存在，或者已为 ncp/jwt-alg 和 ncp/jwt-secret 添加注释，但在与 Ingress 所在的相同命名空间下找不到密钥。Ingress 将部分处于活动状态。要解决此错误，请创建缺少的密钥。请注意，警告出现在注释中后，不会在 Ingress 资源的生命周期内将其清除。

• ncp/warning.loadbalancer: INVALID_INGRESS
  此错误表示以下条件之一成立。Ingress 将处于非活动状态。要解决此错误，请删除 Ingress 并使用正确的规范重新创建。

  • Ingress 规则与同一 Kubernetes 集群中的另一 Ingress 规则冲突。仅为具有相同匹配策略（即 ncp/use-regex 注释值相同）的 Ingress 确定冲突。
  • kubernetes.io/ingress.allow-http 注释设置为 false，且 Ingress 没有 TLS 部分。
  • ncp/http-redirect 注释设置为 true，且 Ingress 没有 TLS 部分。
  • Ingress 规则未指定 host 和 path。此类 Ingress 规则具有与 Ingress 默认后端相同的功能。请改用 Ingress 默认后端。
  • Ingress 具有无法正确处理的 JWL 注释。例如：
    • 缺少 ncp/jwt-alg 或 ncp/jwt-secret。
    • 为 ncp/jwt-alg 配置的算法不受支持。
    • ncp/jwt-alg 和 ncp/jwt-secret 配置了其他 HTTP 启用注释或 SSL 直通。