通过Ingress Annotation实现高阶流量治理

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

前提条件

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

灰度发布

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

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

只配置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灰度发布时支持多个版本服务（无上限）。

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

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/canary: "true"
    higress.io/canary-by-header: "higress"
  name: demo-canary
spec:
  ingressClassName: higress
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service-canary
                port:
                  number: 80
            path: /hello
            pathType: Exact
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo
spec:
  ingressClassName: higress
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /hello
            pathType: Exact

请求Header为higress：v1时将访问灰度服务demo-service-canary-v1；请求Header为higress：v2时将访问灰度服务demo-service-canary-v2；其他情况将访问正式服务demo-service，配置如下：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/canary: "true"
    higress.io/canary-by-header: "higress"
    higress.io/canary-by-header-value: "v1"
  name: demo-canary-v1
spec:
  ingressClassName: higress
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service-canary-v1
                port:
                  number: 80
            path: /hello
            pathType: Exact
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/canary: "true"
    higress.io/canary-by-header: "higress"
    higress.io/canary-by-header-value: "v2"
  name: demo-canary-v2
spec:
  ingressClassName: higress
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service-canary-v2
                port:
                  number: 80
            path: /hello
            pathType: Exact
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo
spec:
  ingressClassName: higress
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /hello
            pathType: Exact

基于Cookie灰度发布

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

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

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

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/canary: "true"
    higress.io/canary-by-cookie: "demo"
  name: demo-canary
spec:
  ingressClassName: higress
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service-canary
                port:
                  number: 80
            path: /hello
            pathType: Exact
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo
spec:
  ingressClassName: higress
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /hello
            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%。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/canary: "true"
    higress.io/canary-weight: "30"
  name: demo-canary-v1
spec:
  ingressClassName: higress
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service-canary-v1
                port:
                  number: 80
            path: /hello
            pathType: Exact
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/canary: "true"
    higress.io/canary-weight: "20"
  name: demo-canary-v2
spec:
  ingressClassName: higress
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service-canary-v2
                port:
                  number: 80
            path: /hello
            pathType: Exact
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo
spec:
  ingressClassName: higress
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /hello
            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，不允许携带凭证信息。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/enable-cors: "true"
    higress.io/cors-allow-origin: "example.com"
    higress.io/cors-allow-methods: "GET,POST"
    higress.io/cors-allow-headers: "X-Foo-Bar"
    higress.io/cors-allow-credentials: "false"
  name: demo
spec:
  ingressClassName: higress
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /hello
            pathType: Exact

Rewrite重写Path和Host

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

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

Rewrite重写Path

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

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/rewrite-target: "/dev"
  name: demo
spec:
  ingressClassName: higress
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

将请求example.com/v1/app在转发至后端服务之前，去掉Path前缀/v1

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/rewrite-target: "/$2"
  name: demo
spec:
  ingressClassName: higress
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /v1(/|$)(.*)
            pathType: ImplementationSpecific

将请求example.com/v1/app在转发至后端服务之前，将Path前缀/v1更改为/v2

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/rewrite-target: "/v2/$2"
  name: demo
spec:
  ingressClassName: higress
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /v1(/|$)(.*)
            pathType: ImplementationSpecific

Rewrite重写Host

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

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/upstream-vhost: "test.com"
  name: demo
spec:
  ingressClassName: higress
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            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。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/ssl-redirect: "true"
  name: demo
spec:
  ingressClassName: higress
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            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。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/permanent-redirect: "http://example.com/app"
  name: demo
spec:
  ingressClassName: higress
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

临时重定向

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

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

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/temporal-redirect: "http://example.com/app"
  name: demo
spec:
  ingressClassName: higress
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

通过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：逗号分隔

对于请求example.com/test添加两个Header，foo: bar和test: true。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/request-header-control-add: |
      foo bar
      test true
  name: demo
spec:
  ingressClassName: higress
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

Header控制可以结合灰度发布，对灰度流量进行染色。请求Header为higress：v1时将访问灰度服务demo-service-canary-v1，并添加Header，stage: gray；其他情况将访问正式服务demo-service，并添加Header，stage: production。配置如下：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/canary: "true"
    higress.io/canary-by-header: "higress"
    higress.io/canary-by-header-value: "v1"
    higress.io/request-header-control-add: "stage gray"
  name: demo-canary-v1
spec:
  ingressClassName: higress
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service-canary-v1
                port:
                  number: 80
            path: /hello
            pathType: Exact
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/request-header-control-add: "stage production"
  name: demo
spec:
  ingressClassName: higress
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /hello
            pathType: Exact

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。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/response-header-control-remove: "req-cost-time"
  name: demo
spec:
  ingressClassName: higress
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            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才重试，并且开启非幂等重试。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/proxy-next-upstream-tries: "2"
    higress.io/proxy-next-upstream-timeout: "5"
    higress.io/proxy-next-upstream: "http_502,non_idempotent"
  name: demo
spec:
  ingressClassName: higress
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

超时

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

设置超时时间为5s：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/timeout: "5"
  name: demo
spec:
  ingressClassName: higress
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            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。配置如下：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/route-limit-rpm: "100"
    higress.io/route-limit-burst-multiplier: "2"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

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

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/route-limit-rps: "10"
    # 默认为5
    # higress.io/route-limit-burst-multiplier: "5"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            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。

请求example.com/test转发至后端服务使用HTTPS协议。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/backend-protocol: "HTTPS"
  name: demo
spec:
  ingressClassName: higress
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /
            pathType: Exact

请求example/grpcbin.GRPCBin转发至后端服务使用GRPC协议。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/backend-protocol: "GRPC"
  name: demo
spec:
  ingressClassName: higress
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /grpcbin.GRPCBin
            pathType: Prefix

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

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

普通负载均衡算法

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

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

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/load-balance: "least_conn"
  name: demo
spec:
  ingressClassName: higress
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /order
            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。

基于请求的客户端IP作为Hash Key，同一个客户端IP的请求始终负载到同一个节点。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/upstream-hash-by: "$remote_addr"
  name: demo
spec:
  ingressClassName: higress
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

基于请求Header x-stage作为Hash key，带有x-stage头部的请求且值相同的请求始终负载到同一个节点。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/upstream-hash-by: "$http_x-stage"
  name: demo
spec:
  ingressClassName: higress
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

基于请求路径参数 x-stage作为Hash key，带有路径参数x-stage的请求且值相同的请求始终负载到同一个节点。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/upstream-hash-by: "$arg_x-stage"
  name: demo
spec:
  ingressClassName: higress
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            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作为过期时间。

开启Cookie亲和性，利用Higress的默认配置，即Cookie的名字为INGRESSCOOKIE，Path为/，Cookie的生命周期为Session会话级别。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/affinity: "cookie"
  name: demo
spec:
  ingressClassName: higress
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

开启Cookie亲和性，Cookie的名字为test，Path为/，Cookie的过期时间为10s。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/affinity: "cookie"
    higress.io/session-cookie-name: "test"
    higress.io/session-cookie-max-age: "10"
  name: demo
spec:
  ingressClassName: higress
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

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

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

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

例如:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    # 这里的要求是必须以域名上配置证书secret名称后缀加上-cacert
    higress.io/auth-tls-secret: tls-secret-cacert
  name: bar
  namespace: default
spec:
  ingressClassName: higress
  rules:
  - host: bar.com
    http:
      paths:
      - backend:
          service:
            name: bar-service
            port:
              number: 5678
        path: /
        pathType: Prefix
  tls:
  - hosts:
    - bar.com
    secretName: tls-secret
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: foo
  namespace: default
spec:
  ingressClassName: higress
  rules:
  - host: foo.com
    http:
      paths:
      - backend:
          service:
            name: foo-service
            port:
              number: 5678
        path: /
        pathType: Prefix
  tls:
  - hosts:
    - foo.com
    secretName: tls-secret

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

apiVersion: v1
data:
  cacert: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURDekNDQWZPZ0F3SUJBZ0lVQ0tMSGM5SFhBbEFYNUdFR2dHVk1zVXhzUFhBd0RRWUpLb1pJaHZjTkFRRUwKQlFBd0ZURVRNQkVHQTFVRUF3d0tSWGhoYlhCc1pTQkRRVEFlRncweU16RXlNakl3T1RNek1ESmFGdzB5TkRFeQpNakV3T1RNek1ESmFNQlV4RXpBUkJnTlZCQU1NQ2tWNFlXMXdiR1VnUTBFd2dnRWlNQTBHQ1NxR1NJYjNEUUVCCkFRVUFBNElCRHdBd2dnRUtBb0lCQVFDaW1jaWQ4VWx4VzA4a1RTcmc1UnAzTlMvSmFMQWt3bVZzeWdEanc0TUEKSjh6Q2FWWHFmU2xpbCtTRFdLcllRYUtPQ1JRWjlWdXBwODl4UnRJTkpUVmlBZUpHYzh6SDY2Sy82aUZJZ2N4ZQplczVaaDdqQXdENzZ4eEtMUjJPbkRSb0xpVlFVOGxkekVNclVHRytCOXJ1TzFsNjkxNlRjQ0dqS3VGUklQNzJCCjlJcEI0ekxZUUNLWldmZ1cxVmU0alpYTUZ0MVhUc0dWdkhCaEt0MSt5eXMrNnc3WndxMW43NysxdXcya2dmM3cKaXNCbXBzTlRPVVJSZzVvdEdYVUUxaGl3dC9KeW9PQkt1YmVyY2dwd05OYzAvNHZ6eWRHMm83UFFpTHcyallPbwppbFptYUZzVXEyclU4S0hCdWlSbVkyTXlOWEU2R0liY29sVGZRQWM2NE5EWEFnTUJBQUdqVXpCUk1CMEdBMVVkCkRnUVdCQlNOZC9vYTkyemFGWFNaRVJoRXJMSElqRE8zYWpBZkJnTlZIU01FR0RBV2dCU05kL29hOTJ6YUZYU1oKRVJoRXJMSElqRE8zYWpBUEJnTlZIUk1CQWY4RUJUQURBUUgvTUEwR0NTcUdTSWIzRFFFQkN3VUFBNElCQVFBTwpjMDNIYWFDRHhhR0phdzlrYkJxMW1DbUVvR3pWZ0loYkhveTQ0Q0IxbGpnS0xOWHo2bnZ5bDVCdWRzWXJkT1lXCmJMMEJGdGxLbWRqeUFHemtnOThGSkpVNExTVFM1ZDNySlBkQU1lcXFOQ2R5NVh0c2l2VDlIbzh5QVBiUGFmZlkKTmozN29JVEQrdXhQbTNVMGhOTU5YSGdGdnJ4bGV6U2MyOHFWL1VxVDBWcnNJR3IyblNiaEYrR3g1WS92aTZocQp5RTJsYWJXdDQ3VlBYcTNFL2lHRWhTSmFndTdhN2xBSDhYWWlqMUtCMkU4bjlERy80R2ZDMEVpTnNXbUpzWVNjCk9tdXlmRGpXaHQ2LzlUVkh4YkNZMzZGQ08vOTcraThqUGhxVlkxRlJzUG5WRUtiRXBNemdXb3Y0UXNKeHoxS3gKdHN2eHlVRnJsaU5wUk1OQmVEODIKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=
kind: Secret
metadata:
  name: tls-secret-cacert
  namespace: default
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。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.io/proxy-ssl-secret: "default/gateway-cert"
  name: demo
spec:
  ingressClassName: higress
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

通过Ingress Annotation实现高阶流量治理

前提条件

灰度发布

基于Header灰度发布

基于Cookie灰度发布

基于权重灰度发布

跨域

Rewrite重写Path和Host

Rewrite重写Path

Rewrite重写Host

重定向

配置HTTP重定向至HTTPS

永久重定向

临时重定向

Header控制

请求Header控制

响应Header控制

重试

超时

单机限流

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

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

普通负载均衡算法

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

Cookie亲和性（会话保持）

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

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

通过Ingress Annotation实现高阶流量治理

前提条件

灰度发布

基于Header灰度发布

基于Cookie灰度发布

基于权重灰度发布

跨域

Rewrite重写Path和Host

Rewrite重写Path

Rewrite重写Host

重定向

配置HTTP重定向至HTTPS

永久重定向

临时重定向

Header控制

请求Header控制

响应Header控制

重试

超时

单机限流

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

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

普通负载均衡算法

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

Cookie亲和性 （会话保持）

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

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

Cookie亲和性（会话保持）