本篇文档介绍如何在Higress上使用Ingress并借助Annotation实现高阶流量治理。

前提条件

  • 安装Higress
  • 已拥有一个Kubernetes集群，且配置了kubectl命令行工具

灰度发布

Higress提供复杂的路由处理能力，支持基于Header、Cookie以及权重的灰度发布功能。灰度发布功能可以通过设置注解来实现，为了启用灰度发布功能，需要设置注解higress.io/canary: "true"。通过不同注解可以实现不同的灰度发布功能。

说明：当多种方式同时配置时，灰度方式选择优先级为：基于Header > 基于Cookie > 基于权重（从高到低）。

基于Header灰度发布

  • 只配置higress.io/canary-by-header：基于Request Header的名称进行流量切分。当请求包含该Header并其值为always时，请求流量会被分配到灰度服务入口；其他情况时，请求流量不会分配到灰度服务。
  • 同时配置higress.io/canary-by-header和higress.io/canary-by-header-value：基于Request Header的名称和值进行流量切分。当请求中的header的名称和header的值与该配置匹配时，请求流量会被分配到灰度服务；其他情况时，请求流量不会分配到灰度服务。

Higress灰度发布时支持多个版本服务（无上限）。

  1. 请求Header为higress：always时将访问灰度服务demo-service-canary；其他情况将访问正式服务demo-service，配置如下：
  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/canary: “true”
  6.     higress.io/canary-by-header: “higress”
  7.   name: demo-canary
  8. spec:
  9.   ingressClassName: higress
  10.   rules:
  11.     - http:
  12.         paths:
  13.           - backend:
  14.               service:
  15.                 name: demo-service-canary
  16.                 port:
  17.                   number: 80
  18.             path: /hello
  19.             pathType: Exact
  20. —-
  21. apiVersion: networking.k8s.io/v1
  22. kind: Ingress
  23. metadata:
  24.   name: demo
  25. spec:
  26.   ingressClassName: higress
  27.   rules:
  28.     - http:
  29.         paths:
  30.           - backend:
  31.               service:
  32.                 name: demo-service
  33.                 port:
  34.                   number: 80
  35.             path: /hello
  36.             pathType: Exact
  1. 请求Header为higress：v1时将访问灰度服务demo-service-canary-v1；请求Header为higress：v2时将访问灰度服务demo-service-canary-v2；其他情况将访问正式服务demo-service，配置如下：
  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/canary: “true”
  6.     higress.io/canary-by-header: “higress”
  7.     higress.io/canary-by-header-value: “v1”
  8.   name: demo-canary-v1
  9. spec:
  10.   ingressClassName: higress
  11.   rules:
  12.     - http:
  13.         paths:
  14.           - backend:
  15.               service:
  16.                 name: demo-service-canary-v1
  17.                 port:
  18.                   number: 80
  19.             path: /hello
  20.             pathType: Exact
  21. —-
  22. apiVersion: networking.k8s.io/v1
  23. kind: Ingress
  24. metadata:
  25.   annotations:
  26.     higress.io/canary: “true”
  27.     higress.io/canary-by-header: “higress”
  28.     higress.io/canary-by-header-value: “v2”
  29.   name: demo-canary-v2
  30. spec:
  31.   ingressClassName: higress
  32.   rules:
  33.     - http:
  34.         paths:
  35.           - backend:
  36.               service:
  37.                 name: demo-service-canary-v2
  38.                 port:
  39.                   number: 80
  40.             path: /hello
  41.             pathType: Exact
  42. —-
  43. apiVersion: networking.k8s.io/v1
  44. kind: Ingress
  45. metadata:
  46.   name: demo
  47. spec:
  48.   ingressClassName: higress
  49.   rules:
  50.     - http:
  51.         paths:
  52.           - backend:
  53.               service:
  54.                 name: demo-service
  55.                 port:
  56.                   number: 80
  57.             path: /hello
  58.             pathType: Exact

基于Cookie灰度发布

  • higress.io/canary-by-cookie：基于Cookie的Key进行流量切分。当请求的Cookie中含有该Key且其值为always时，请求流量将被分配到灰度服务；其他情况时，请求流量将不会分配到灰度服务。

说明：基于Cookie的灰度发布不支持自定义设置Key对应的值，只能是always。

请求的Cookie为demo=always时将访问灰度服务demo-service-canary；其他情况将访问正式服务demo-service。配置如下：

  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/canary: “true”
  6.     higress.io/canary-by-cookie: “demo”
  7.   name: demo-canary
  8. spec:
  9.   ingressClassName: higress
  10.   rules:
  11.     - http:
  12.         paths:
  13.           - backend:
  14.               service:
  15.                 name: demo-service-canary
  16.                 port:
  17.                   number: 80
  18.             path: /hello
  19.             pathType: Exact
  20. —-
  21. apiVersion: networking.k8s.io/v1
  22. kind: Ingress
  23. metadata:
  24.   name: demo
  25. spec:
  26.   ingressClassName: higress
  27.   rules:
  28.     - http:
  29.         paths:
  30.           - backend:
  31.               service:
  32.                 name: demo-service
  33.                 port:
  34.                   number: 80
  35.             path: /hello
  36.             pathType: Exact

基于权重灰度发布

  • higress.io/canary-weight：设置请求到指定服务的百分比（值为0~100的整数）
  • higress.io/canary-weight-total：设置权重总和，默认为100

配置灰度服务demo-service-canary-v1的权重为30%，配置灰度服务demo-service-canary-v2的权重为20%，配置正式服务demo-service的权重为50%。

  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/canary: “true”
  6.     higress.io/canary-weight: “30”
  7.   name: demo-canary-v1
  8. spec:
  9.   ingressClassName: higress
  10.   rules:
  11.     - http:
  12.         paths:
  13.           - backend:
  14.               service:
  15.                 name: demo-service-canary-v1
  16.                 port:
  17.                   number: 80
  18.             path: /hello
  19.             pathType: Exact
  20. —-
  21. apiVersion: networking.k8s.io/v1
  22. kind: Ingress
  23. metadata:
  24.   annotations:
  25.     higress.io/canary: “true”
  26.     higress.io/canary-weight: “20”
  27.   name: demo-canary-v2
  28. spec:
  29.   ingressClassName: higress
  30.   rules:
  31.     - http:
  32.         paths:
  33.           - backend:
  34.               service:
  35.                 name: demo-service-canary-v2
  36.                 port:
  37.                   number: 80
  38.             path: /hello
  39.             pathType: Exact
  40. —-
  41. apiVersion: networking.k8s.io/v1
  42. kind: Ingress
  43. metadata:
  44.   name: demo
  45. spec:
  46.   ingressClassName: higress
  47.   rules:
  48.     - http:
  49.         paths:
  50.           - backend:
  51.               service:
  52.                 name: demo-service
  53.                 port:
  54.                   number: 80
  55.             path: /hello
  56.             pathType: Exact

跨域

跨域资源共享CORS（Cross-Origin Resource Sharing）是指允许Web应用服务器进行跨域访问控制，从而实现跨域数据安全传输。

  • higress.io/enable-cors：“true” or “false”。开启或关闭跨域。
  • higress.io/cors-allow-origin：允许的第三方站点，支持泛域名，逗号分隔；支持通配符*。默认值为*，即允许所有第三方站点。
  • higress.io/cors-allow-methods：允许的请求方法，如GET、POST，逗号分隔；支持通配符*。默认值为GET, PUT, POST, DELETE, PATCH, OPTIONS。
  • higress.io/cors-allow-headers：允许的请求头部，逗号分隔；支持通配符*。默认值为DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization。
  • higress.io/cors-expose-headers：允许的响应头部，逗号分隔。
  • higress.io/cors-allow-credentials：“true” or “false”。是否允许携带凭证信息。默认允许。
  • higress.io/cors-max-age：预检结果的最大缓存时间，单位为秒；默认值为1728000。

跨域请求被限制为只能来自example.com域的请求，并且HTTP方法只能是GET和POST，允许的请求头部为X-Foo-Bar，不允许携带凭证信息。

  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/enable-cors: “true”
  6.     higress.io/cors-allow-origin: “example.com”
  7.     higress.io/cors-allow-methods: “GET,POST”
  8.     higress.io/cors-allow-headers: “X-Foo-Bar”
  9.     higress.io/cors-allow-credentials: “false”
  10.   name: demo
  11. spec:
  12.   ingressClassName: higress
  13.   rules:
  14.     - http:
  15.         paths:
  16.           - backend:
  17.               service:
  18.                 name: demo-service
  19.                 port:
  20.                   number: 80
  21.             path: /hello
  22.             pathType: Exact

Rewrite重写Path和Host

在请求转发给目标后端服务之前，重写可以修改原始请求的路径（Path）和主机域（Host)。

  • higress.io/rewrite-target：重写Path，支持捕获组（Capture Group)。
  • higress.io/upstream-vhost：重写Host。

Rewrite重写Path

  1. 将请求example.com/test在转发至后端服务之前，重写为example.com/dev
  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/rewrite-target: “/dev”
  6.   name: demo
  7. spec:
  8.   ingressClassName: higress
  9.   rules:
  10.     - host: example.com
  11.       http:
  12.         paths:
  13.           - backend:
  14.               service:
  15.                 name: demo-service
  16.                 port:
  17.                   number: 80
  18.             path: /test
  19.             pathType: Exact
  1. 将请求example.com/v1/app在转发至后端服务之前，去掉Path前缀/v1
  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/rewrite-target: “/$2”
  6.   name: demo
  7. spec:
  8.   ingressClassName: higress
  9.   rules:
  10.     - host: example.com
  11.       http:
  12.         paths:
  13.           - backend:
  14.               service:
  15.                 name: demo-service
  16.                 port:
  17.                   number: 80
  18.             path: /v1(/|$)(.*)
  19.             pathType: ImplementationSpecific
  1. 将请求example.com/v1/app在转发至后端服务之前，将Path前缀/v1更改为/v2
  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/rewrite-target: “/v2/$2”
  6.   name: demo
  7. spec:
  8.   ingressClassName: higress
  9.   rules:
  10.     - host: example.com
  11.       http:
  12.         paths:
  13.           - backend:
  14.               service:
  15.                 name: demo-service
  16.                 port:
  17.                   number: 80
  18.             path: /v1(/|$)(.*)
  19.             pathType: ImplementationSpecific

Rewrite重写Host

将请求example.com/test在转发至后端服务之前，重写为test.com/test

  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/upstream-vhost: “test.com”
  6.   name: demo
  7. spec:
  8.   ingressClassName: higress
  9.   rules:
  10.     - host: example.com
  11.       http:
  12.         paths:
  13.           - backend:
  14.               service:
  15.                 name: demo-service
  16.                 port:
  17.                   number: 80
  18.             path: /test
  19.             pathType: Exact

重定向

通过重定向可以将原始客户端请求更改为目标请求。

配置HTTP重定向至HTTPS

  • higress.io/ssl-redirect：HTTP重定向到HTTPS
  • higress.io/force-ssl-redirect: HTTP重定向到HTTPS

说明：Higress对于以上两个注解不区分对待，都是强制将HTTP重定向到HTTPS。

将请求http://example.com/test重定向为https://example.com/test。

  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/ssl-redirect: “true”
  6.   name: demo
  7. spec:
  8.   ingressClassName: higress
  9.   rules:
  10.     - host: example.com
  11.       http:
  12.         paths:
  13.           - backend:
  14.               service:
  15.                 name: demo-service
  16.                 port:
  17.                   number: 80
  18.             path: /test
  19.             pathType: Exact

永久重定向

  • higress.io/permanent-redirect：永久重定向的目标url，必须包含scheme（http or https)。
  • higress.io/permanent-redirect-code：永久重定向的HTTP状态码，默认为301。

将请求http://example.com/test永久重定向为http://example.com/app。

  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/permanent-redirect: “http://example.com/app“
  6.   name: demo
  7. spec:
  8.   ingressClassName: higress
  9.   rules:
  10.     - host: example.com
  11.       http:
  12.         paths:
  13.           - backend:
  14.               service:
  15.                 name: demo-service
  16.                 port:
  17.                   number: 80
  18.             path: /test
  19.             pathType: Exact

临时重定向

  • higress.io/temporal-redirect：临时重定向的目标url，必须包含scheme（http or https)。

将请求http://example.com/test临时重定向为http://example.com/app。

  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/temporal-redirect: “http://example.com/app“
  6.   name: demo
  7. spec:
  8.   ingressClassName: higress
  9.   rules:
  10.     - host: example.com
  11.       http:
  12.         paths:
  13.           - backend:
  14.               service:
  15.                 name: demo-service
  16.                 port:
  17.                   number: 80
  18.             path: /test
  19.             pathType: Exact

Header控制

通过Header控制，您可以在转发请求到后端服务之前对请求Header进行增删改，在收到响应转发给客户端时对响应Header进行增删改。

请求Header控制

  • higress.io/request-header-control-add：请求在转发给后端服务时，添加指定Header。若该Header存在，则其值拼接在原有值后面。语法如下：
    • 单个Header：Key Value
    • 多个Header：使用yaml特殊符号 |，每对Key Value单独处于一行
  • higress.io/request-header-control-update：请求在转发给后端服务时，修改指定Header。若该header存在，则其值覆盖原有值。语法如下：
    • 单个Header：Key Value
    • 多个Header：使用yaml特殊符号 |，每对Key Value单独处于一行
  • higress.io/request-header-control-remove：请求在转发给后端服务时，删除指定Header。语法如下：
    • 单个Header：Key
    • 多个Header：逗号分隔
  1. 对于请求example.com/test添加两个Header，foo: bar和test: true。
  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/request-header-control-add: |
  6.       foo bar
  7.       test true
  8.   name: demo
  9. spec:
  10.   ingressClassName: higress
  11.   rules:
  12.     - host: example.com
  13.       http:
  14.         paths:
  15.           - backend:
  16.               service:
  17.                 name: demo-service
  18.                 port:
  19.                   number: 80
  20.             path: /test
  21.             pathType: Exact
  1. Header控制可以结合灰度发布，对灰度流量进行染色。请求Header为higress：v1时将访问灰度服务demo-service-canary-v1，并添加Header，stage: gray；其他情况将访问正式服务demo-service，并添加Header，stage: production。配置如下：
  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/canary: “true”
  6.     higress.io/canary-by-header: “higress”
  7.     higress.io/canary-by-header-value: “v1”
  8.     higress.io/request-header-control-add: “stage gray”
  9.   name: demo-canary-v1
  10. spec:
  11.   ingressClassName: higress
  12.   rules:
  13.     - http:
  14.         paths:
  15.           - backend:
  16.               service:
  17.                 name: demo-service-canary-v1
  18.                 port:
  19.                   number: 80
  20.             path: /hello
  21.             pathType: Exact
  22. —-
  23. apiVersion: networking.k8s.io/v1
  24. kind: Ingress
  25. metadata:
  26.   annotations:
  27.     higress.io/request-header-control-add: “stage production”
  28.   name: demo
  29. spec:
  30.   ingressClassName: higress
  31.   rules:
  32.     - http:
  33.         paths:
  34.           - backend:
  35.               service:
  36.                 name: demo-service
  37.                 port:
  38.                   number: 80
  39.             path: /hello
  40.             pathType: Exact

响应Header控制

  • higress.io/response-header-control-add：请求在收到后端服务响应之后并且转发响应给客户端之前，添加指定Header。若该Header存在，则其值拼接在原有值后面。语法如下：
    • 单个Header：Key Value
    • 多个Header：使用yaml特殊符号 |，每对Key Value单独处于一行
  • higress.io/response-header-control-update：请求在收到后端服务响应之后并且转发响应给客户端之前，修改指定Header。若该header存在，则其值覆盖原有值。语法如下：
    • 单个Header：Key Value
    • 多个Header：使用yaml特殊符号 |，每对Key Value单独处于一行
  • higress.io/response-header-control-remove：请求在收到后端服务响应之后并且转发响应给客户端之前，删除指定Header。语法如下：
    • 单个Header：Key
    • 多个Header：逗号分隔

对于请求example.com/test的响应删除Header：req-cost-time。

  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/response-header-control-remove: “req-cost-time”
  6.   name: demo
  7. spec:
  8.   ingressClassName: higress
  9.   rules:
  10.     - host: example.com
  11.       http:
  12.         paths:
  13.           - backend:
  14.               service:
  15.                 name: demo-service
  16.                 port:
  17.                   number: 80
  18.             path: /test
  19.             pathType: Exact

重试

Higress提供路由级别的重试设置，可以为出错的请求调用自动进行重试。您可以按需设置重试条件，例如建立连接失败，或者后端服务不可用以及对指定HTTP状态码的响应等进行请求重试。

  • higress.io/proxy-next-upstream-tries：请求的最大重试次数。默认3次。
  • higress.io/proxy-next-upstream-timeout：请求重试的超时时间，单位秒。默认未配置超时时间。
  • higress.io/proxy-next-upstream：请求重试条件，逗号分隔；默认值为”error,timeout”。合法值如下：
    • error：建立连接失败，请求出错5xx。
    • timeout：建立连接超时，请求出错5xx。
    • invalid_header：请求出错5xx。
    • http_xxx：针对具体响应状态码的情况进行重试。例如http_502，http_403。
    • non_idempotent：对于非幂等请求出错时进行重试。默认情况下，Higress针对非幂等POST、PATCH请求出错时不会进行重试，配置non_idempotent可以开启重试。
    • off：关闭重试。

设置example/test请求的最大重试次数为2，重试超时时间为5s，只有在响应状态码为502才重试，并且开启非幂等重试。

  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/proxy-next-upstream-tries: “2”
  6.     higress.io/proxy-next-upstream-timeout: “5”
  7.     higress.io/proxy-next-upstream: “http_502,non_idempotent”
  8.   name: demo
  9. spec:
  10.   ingressClassName: higress
  11.   rules:
  12.     - host: example.com
  13.       http:
  14.         paths:
  15.           - backend:
  16.               service:
  17.                 name: demo-service
  18.                 port:
  19.                   number: 80
  20.             path: /test
  21.             pathType: Exact

超时

Higress提供路由级别的超时设置，与nginx ingress不同，没有区分连接/读写超时，而是面向的接口处理总延时进行配置，在未进行配置时默认不限制，例如后端未返回应答，网关将无限等待。

设置超时时间为5s：

  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/timeout: “5”
  6.   name: demo
  7. spec:
  8.   ingressClassName: higress
  9.   rules:
  10.     - host: example.com
  11.       http:
  12.         paths:
  13.           - backend:
  14.               service:
  15.                 name: demo-service
  16.                 port:
  17.                   number: 80
  18.             path: /test
  19.             pathType: Exact

单机限流

提示 Higress商业版具备全局限流能力，详情查看商业版文档中全局限流一节的介绍

支持针对路由级别的单机限流策略，在设定的时间周期内，限制每个网关副本匹配在某个路由上的请求数量不大于阈值。该限流是针对单机级别，即配置的阈值在每个网关实例进行流控。

  • higress.io/route-limit-rpm：该Ingress定义的路由在每个网关实例上每分钟最大请求次数。瞬时最大请求次数为该值乘以limit-burst-multiplier。
  • higress.io/route-limit-rps：该Ingress定义的路由在每个网关实例上每秒最大请求次数。瞬时最大请求次数为该值乘以limit-burst-multiplier。
  • higress.io/route-limit-burst-multiplier：瞬时最大请求次数的因子，默认为5。

例如：

限制example.com/test的请求每分钟最大请求数为100，瞬时请求数200。配置如下：

  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/route-limit-rpm: “100”
  6.     higress.io/route-limit-burst-multiplier: “2”
  7.   name: demo
  8. spec:
  9.   ingressClassName: mse
  10.   rules:
  11.     - host: example.com
  12.       http:
  13.         paths:
  14.           - backend:
  15.               service:
  16.                 name: demo-service
  17.                 port:
  18.                   number: 80
  19.             path: /test
  20.             pathType: Exact

限制example.com/test的请求每秒最大请求数为10，瞬时请求数50。配置如下：

  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/route-limit-rps: “10”
  6.     # 默认为5
  7.     # higress.io/route-limit-burst-multiplier: “5”
  8.   name: demo
  9. spec:
  10.   ingressClassName: mse
  11.   rules:
  12.     - host: example.com
  13.       http:
  14.         paths:
  15.           - backend:
  16.               service:
  17.                 name: demo-service
  18.                 port:
  19.                   number: 80
  20.             path: /test
  21.             pathType: Exact

配置后端服务协议：HTTPS或GRPC

Higress默认使用HTTP协议转发请求到后端业务容器。当您的业务容器为HTTPS协议时，可以通过使用注解higress.io/backend-protocol: "HTTPS"；当您的业务容器为GRPC服务时，可以通过使用注解higress.io/backend-protocol: "GRPC"。

说明：相比Nginx Ingress的优势，如果您的后端服务所属的K8s Service资源中关于Port Name的定义为grpc或http2，您无需配置注解higress.io/backend-protocol: “GRPC”，Higress会自动使用GRPC或者HTTP2。

  1. 请求example.com/test转发至后端服务使用HTTPS协议。
  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/backend-protocol: “HTTPS”
  6.   name: demo
  7. spec:
  8.   ingressClassName: higress
  9.   rules:
  10.     - host: example.com
  11.       http:
  12.         paths:
  13.           - backend:
  14.               service:
  15.                 name: demo-service
  16.                 port:
  17.                   number: 80
  18.             path: /
  19.             pathType: Exact
  1. 请求example/grpcbin.GRPCBin转发至后端服务使用GRPC协议。
  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/backend-protocol: “GRPC”
  6.   name: demo
  7. spec:
  8.   ingressClassName: higress
  9.   rules:
  10.     - host: example.com
  11.       http:
  12.         paths:
  13.           - backend:
  14.               service:
  15.                 name: demo-service
  16.                 port:
  17.                   number: 80
  18.             path: /grpcbin.GRPCBin
  19.             pathType: Prefix

配置后端服务的负载均衡算法

负载均衡决定着网关在转发请求至后端服务时如何选择节点。

普通负载均衡算法

  • higress.io/load-balance：后端服务的普通负载均衡算法。默认为round_robin。合法值如下：
    • round_robin：基于轮询的负载均衡。
    • least_conn：基于最小请求数的负载均衡。
    • random：基于随机的负载均衡。

设置后端服务demo-service的负载均衡算法为least_conn。

  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/load-balance: “least_conn”
  6.   name: demo
  7. spec:
  8.   ingressClassName: higress
  9.   rules:
  10.     - host: example.com
  11.       http:
  12.         paths:
  13.           - backend:
  14.               service:
  15.                 name: demo-service
  16.                 port:
  17.                   number: 80
  18.             path: /order
  19.             pathType: Exact

基于一致性Hash的负载均衡算法

基于一致性Hash的负载均衡算法具备请求亲和性，具有相同特征的请求会始终负载到相同节点上。Higress支持基于部分Nginx 变量、请求Header和请求路径参数作为Hash Key。

  • higress.io/upstream-hash-by：基于一致Hash的负载均衡算法。Higress支持以下几种形式：
    • 支持配置部分nginx变量：
      • $request_uri：请求的Path（包括路径参数）作为Hash Key
      • $host：请求的Host作为Hash Key
      • $remote_addr：请求的客户端IP作为Hash Key
    • 基于请求header的一致性Hash。您只需配置为$http_headerName。
    • 基于请求路径参数的一致性Hash。您只需配置为$arg_varName。
  1. 基于请求的客户端IP作为Hash Key，同一个客户端IP的请求始终负载到同一个节点。
  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/upstream-hash-by: “$remote_addr”
  6.   name: demo
  7. spec:
  8.   ingressClassName: higress
  9.   rules:
  10.     - host: example.com
  11.       http:
  12.         paths:
  13.           - backend:
  14.               service:
  15.                 name: demo-service
  16.                 port:
  17.                   number: 80
  18.             path: /test
  19.             pathType: Exact
  1. 基于请求Header x-stage作为Hash key，带有x-stage头部的请求且值相同的请求始终负载到同一个节点。
  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/upstream-hash-by: “$http_x-stage”
  6.   name: demo
  7. spec:
  8.   ingressClassName: higress
  9.   rules:
  10.     - host: example.com
  11.       http:
  12.         paths:
  13.           - backend:
  14.               service:
  15.                 name: demo-service
  16.                 port:
  17.                   number: 80
  18.             path: /test
  19.             pathType: Exact
  1. 基于请求路径参数 x-stage作为Hash key，带有路径参数x-stage的请求且值相同的请求始终负载到同一个节点。
  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/upstream-hash-by: “$arg_x-stage”
  6.   name: demo
  7. spec:
  8.   ingressClassName: higress
  9.   rules:
  10.     - host: example.com
  11.       http:
  12.         paths:
  13.           - backend:
  14.               service:
  15.                 name: demo-service
  16.                 port:
  17.                   number: 80
  18.             path: /test
  19.             pathType: Exact

Cookie亲和性 （会话保持）

具备相同的Cookie的请求会被网关始终负载到同一个节点，并且如果第一次访问携带Cookie，Higress会在第一次响应时为客户端生成一个Cookie，用来保证后续的请求被网关始终负载到相同节点。

  • higress.io/affinity：亲和性种类，目前只支持cookie，默认为cookie。
  • higress.io/affinity-mode：亲和性模式，Higress目前只支持balanced模式，默认为balanced模式。
  • higress.io/session-cookie-name：配置指定Cookie的值作为Hash Key，默认为INGRESSCOOKIE
  • higress.io/session-cookie-path：当指定Cookie不存在，生成的Cookie的Path值，默认为/
  • higress.io/session-cookie-max-age：当指定Cookie不存在，生成的Cookie的过期时间，单位为秒，默认为Session会话级别。
  • higress.io/session-cookie-expires：当指定Cookie不存在，生成的Cookie的过期时间，单位为秒，默认为Session会话级别。

说明：max-age和expires都可以用来指定cookie过期时间。当session-cookie-max-age和session-cookie-expires同时配置时，Higress优先选取session-cookie-max-age作为过期时间。

  1. 开启Cookie亲和性，利用Higress的默认配置，即Cookie的名字为INGRESSCOOKIE，Path为/，Cookie的生命周期为Session会话级别。
  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/affinity: “cookie”
  6.   name: demo
  7. spec:
  8.   ingressClassName: higress
  9.   rules:
  10.     - host: example.com
  11.       http:
  12.         paths:
  13.           - backend:
  14.               service:
  15.                 name: demo-service
  16.                 port:
  17.                   number: 80
  18.             path: /test
  19.             pathType: Exact
  1. 开启Cookie亲和性，Cookie的名字为test，Path为/，Cookie的过期时间为10s。
  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/affinity: “cookie”
  6.     higress.io/session-cookie-name: “test”
  7.     higress.io/session-cookie-max-age: “10”
  8.   name: demo
  9. spec:
  10.   ingressClassName: higress
  11.   rules:
  12.     - host: example.com
  13.       http:
  14.         paths:
  15.           - backend:
  16.               service:
  17.                 name: demo-service
  18.                 port:
  19.                   number: 80
  20.             path: /test
  21.             pathType: Exact

网关与客户端双向认证(MTLS)

当开启HTTPS时，网关与客户端默认是基于单向TLS认证，可以通过下面注解开启双向TLS认证，即让服务端同时校验客户端的合法性。

  • higress.io/auth-tls-secret: 网关使用的CA证书，用于验证MTLS握手期间，客户端提供的证书。该注解主要应用于网关需要验证客户端身份的场景。secret名字格式必须是：(该域名证书所在的secret的名字)-cacert

例如:

  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     # 这里的要求是必须以域名上配置证书secret名称后缀加上-cacert
  6.     higress.io/auth-tls-secret: tls-secret-cacert
  7.   name: bar
  8.   namespace: default
  9. spec:
  10.   ingressClassName: higress
  11.   rules:
  12.   - host: bar.com
  13.     http:
  14.       paths:
  15.       - backend:
  16.           service:
  17.             name: bar-service
  18.             port:
  19.               number: 5678
  20.         path: /
  21.         pathType: Prefix
  22.   tls:
  23.   - hosts:
  24.     - bar.com
  25.     secretName: tls-secret
  26. —-
  27. apiVersion: networking.k8s.io/v1
  28. kind: Ingress
  29. metadata:
  30.   name: foo
  31.   namespace: default
  32. spec:
  33.   ingressClassName: higress
  34.   rules:
  35.   - host: foo.com
  36.     http:
  37.       paths:
  38.       - backend:
  39.           service:
  40.             name: foo-service
  41.             port:
  42.               number: 5678
  43.         path: /
  44.         pathType: Prefix
  45.   tls:
  46.   - hosts:
  47.     - foo.com
  48.     secretName: tls-secret

tls-secret-cacert 这个 secret 的内容中必须有 cacert 这个key，例如：

  1. apiVersion: v1
  2. data:
  3.   cacert: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURDekNDQWZPZ0F3SUJBZ0lVQ0tMSGM5SFhBbEFYNUdFR2dHVk1zVXhzUFhBd0RRWUpLb1pJaHZjTkFRRUwKQlFBd0ZURVRNQkVHQTFVRUF3d0tSWGhoYlhCc1pTQkRRVEFlRncweU16RXlNakl3T1RNek1ESmFGdzB5TkRFeQpNakV3T1RNek1ESmFNQlV4RXpBUkJnTlZCQU1NQ2tWNFlXMXdiR1VnUTBFd2dnRWlNQTBHQ1NxR1NJYjNEUUVCCkFRVUFBNElCRHdBd2dnRUtBb0lCQVFDaW1jaWQ4VWx4VzA4a1RTcmc1UnAzTlMvSmFMQWt3bVZzeWdEanc0TUEKSjh6Q2FWWHFmU2xpbCtTRFdLcllRYUtPQ1JRWjlWdXBwODl4UnRJTkpUVmlBZUpHYzh6SDY2Sy82aUZJZ2N4ZQplczVaaDdqQXdENzZ4eEtMUjJPbkRSb0xpVlFVOGxkekVNclVHRytCOXJ1TzFsNjkxNlRjQ0dqS3VGUklQNzJCCjlJcEI0ekxZUUNLWldmZ1cxVmU0alpYTUZ0MVhUc0dWdkhCaEt0MSt5eXMrNnc3WndxMW43NysxdXcya2dmM3cKaXNCbXBzTlRPVVJSZzVvdEdYVUUxaGl3dC9KeW9PQkt1YmVyY2dwd05OYzAvNHZ6eWRHMm83UFFpTHcyallPbwppbFptYUZzVXEyclU4S0hCdWlSbVkyTXlOWEU2R0liY29sVGZRQWM2NE5EWEFnTUJBQUdqVXpCUk1CMEdBMVVkCkRnUVdCQlNOZC9vYTkyemFGWFNaRVJoRXJMSElqRE8zYWpBZkJnTlZIU01FR0RBV2dCU05kL29hOTJ6YUZYU1oKRVJoRXJMSElqRE8zYWpBUEJnTlZIUk1CQWY4RUJUQURBUUgvTUEwR0NTcUdTSWIzRFFFQkN3VUFBNElCQVFBTwpjMDNIYWFDRHhhR0phdzlrYkJxMW1DbUVvR3pWZ0loYkhveTQ0Q0IxbGpnS0xOWHo2bnZ5bDVCdWRzWXJkT1lXCmJMMEJGdGxLbWRqeUFHemtnOThGSkpVNExTVFM1ZDNySlBkQU1lcXFOQ2R5NVh0c2l2VDlIbzh5QVBiUGFmZlkKTmozN29JVEQrdXhQbTNVMGhOTU5YSGdGdnJ4bGV6U2MyOHFWL1VxVDBWcnNJR3IyblNiaEYrR3g1WS92aTZocQp5RTJsYWJXdDQ3VlBYcTNFL2lHRWhTSmFndTdhN2xBSDhYWWlqMUtCMkU4bjlERy80R2ZDMEVpTnNXbUpzWVNjCk9tdXlmRGpXaHQ2LzlUVkh4YkNZMzZGQ08vOTcraThqUGhxVlkxRlJzUG5WRUtiRXBNemdXb3Y0UXNKeHoxS3gKdHN2eHlVRnJsaU5wUk1OQmVEODIKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=
  4. kind: Secret
  5. metadata:
  6.   name: tls-secret-cacert
  7.   namespace: default
  8. type: Opaque

网关与后端服务双向认证（MTLS)

默认情况下，Higress默认使用HTTP协议转发请求到后端业务容器。你可以通过使用注解higress.io/backend-protocol: "HTTPS"配置Higress访问后端服务使用HTTPS协议，但这是单向TLS，也就是说只有Higress会验证后端服务提供的证书，且一般后端服务使用的证书需要是权威CA签发的。另一种更安全的模式是零信任，网关会验证后端服务的证书是否合法，同样后端服务也会验证网关提供的证书是否合法，这就是MTLS，网关与后端服务进行双向认证。

  • higress.io/proxy-ssl-secret：网关使用的客户端证书，用于后端服务对网关进行身份认证，格式为 secretNamespace/secretName。
  • higress.io/proxy-ssl-name：TLS握手期间使用的SNI。
  • higress.io/proxy-ssl-server-name：on or off。开启或关闭TLS握手期间使用SNI。

网关与后端服务进行双向认证，网关使用的secret name为gateway-cert，命名空间为default。

  1. apiVersion: networking.k8s.io/v1
  2. kind: Ingress
  3. metadata:
  4.   annotations:
  5.     higress.io/proxy-ssl-secret: “default/gateway-cert”
  6.   name: demo
  7. spec:
  8.   ingressClassName: higress
  9.   rules:
  10.     - host: example.com
  11.       http:
  12.         paths:
  13.           - backend:
  14.               service:
  15.                 name: demo-service
  16.                 port:
  17.                   number: 80
  18.             path: /test
  19.             pathType: Exact