NCP 将分别为具有 TLS 规范和不具有 TLS 规范的 Ingress 各创建一个第 7 层负载均衡器。您还可以创建 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 将被注释为出现错误。例如,如果创建两个具有相同 hostpath 的 Ingress,其中一个 Ingress 为 TLS,另一个为非 TLS,并且 kubernetes.io/ingress.allow-httpfalse,则两个规则将在不同的虚拟服务器上创建,并且不会相互冲突。但是,如果 kubernetes.io/ingress.allow-httptrue,则稍后应用的 Ingress 将被注释为出现错误。有关详细信息,请参见下面的“错误”部分。
  • 每个集群只支持一个具有默认后端的 Ingress。不匹配任何 Ingress 规则的流量将被转发到默认后端。
  • 如果存在多个具有默认后端的 Ingress,则只会配置第一个输入。其他 Ingress 将被注释为出现错误。有关详细信息,请参见下面的“错误”部分。
  • 规则将按以下顺序应用:
    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 Ingress 具有默认后端,建议您将该默认后端设置为同时响应 HTTP 和 HTTPS 请求,原因如下:
    • 如果存在主机与请求中的主机相匹配的 TLS Ingress(在 Kubernetes/TKGI 用例的集群中,或在与 Project Pacific 用例相同的命名空间中),则负载均衡器将终止 TLS 并将 HTTP 请求发送到默认后端服务器。
    • 如果不存在主机与请求中的主机相匹配的 TLS Ingress(在 Kubernetes/TKGI 用例的集群中,或在与 Project Pacific 用例相同的命名空间中),则负载均衡器将重新加密 HTTPS 请求并将其发送到后端服务器。
  • 支持 IngressClass 资源。
  • 支持 pathType 属性。
  • 支持 JWT(JSON Web 令牌)客户端身份验证。此功能需要使用 NSX-T Data Center 3.0.0 或更高版本。
从 Kubernetes 1.18 开始, kubernetes.io/ingress.class 注释已弃用,并替换为 IngressClass 资源。要将 NSX-T 指定为 IngressClass 资源中的 Ingress 控制器,请将控制器参数设置为 k8s.io/nsx。例如:
kind: IngressClass
metadata:
  name: nsx-lb
  annotations:
    ingressclass.kubernetes.io/is-default-class: true
spec:
  controller: k8s.io/nsx
要指定第三方 Ingress 控制器,需要将控制器参数设置为 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 指示负责此 Ingress 的 Ingress 控制器 nsx、nginx 等 nsx 2.5 和更高版本
nsx/loadbalancer 将 Ingress 放置在专用负载均衡器上 LoadBalancer CRD 的名称 无默认值 2.5.1 和更高版本
(NCP 3.1 及更低版本)ncp/whitelist-source-range

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

通过请求源 IP 限制 Ingress 访问权限 以逗号分隔的 CIDR、IP 地址或 IP 范围列表。 无默认值 3.0.0 和更高版本
ncp/ssl-mode 为 Ingress 中的所有规则选择 SSL 模式 offload、reencrypt、passthrough offload 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 和更高版本
有关注释的详细信息:
  • 路径正则表达式匹配
    • 对于 NCP 2.5.0 及更低版本

      在 NCP 2.5.0 及更低版本中,将使用正则表达式字符“.”和“*”自动启用所有子路径匹配。例如,路径 /coffee/.* 与后跟零个、一个或多个字符的 /coffee/ 匹配,例如与 /coffee//coffee/a/coffee/b 匹配,但不与 /coffee/coffeecup/coffeecup/a 匹配。

      Ingress 规范示例:
      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 启用或禁用 Ingress path(而不是 host)参数的正则表达式匹配。如果将该注释设置为 false,将通过执行 equals 匹配来执行精确路径匹配。如果将该注释设置为 true,将通过向路径添加字符串开头字符 (^) 和字符串结尾字符 ($) 来执行正则表达式匹配,以便整个请求 URI 与模式相匹配。请注意,使用 OR 运算符 (|) 时,请始终使用圆括号指定范围,以使 ^ 和 $ 应用于所有操作数。例如, path: /(tea|coffee|milk)。Ingress 规范示例:
      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 或更高版本之前更新 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 的示例:
    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 虚拟服务器创建规则。请注意,仅当 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(在 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
    • 此注释适用于 Ingress 中的所有规则,并且负载均衡器将在为这些规则选定的 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 客户端身份验证:
    • 要为 Ingress 下的所有规则启用 JWT 客户端身份验证,需要同时为 ncp/jwt-algncp/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 名称。

错误

错误作为注释添加到 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-algncp/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 规则未指定 hostpath。此类 Ingress 规则具有与 Ingress 默认后端相同的功能。请改用 Ingress 默认后端。
    • Ingress 具有无法正确处理的 JWL 注释。例如:
      • 缺少 ncp/jwt-algncp/jwt-secret
      • ncp/jwt-alg 配置的算法不受支持。
      • ncp/jwt-algncp/jwt-secret 配置了其他 HTTP 启用注释或 SSL 直通。