使用 Kubernetes Annotation 能够实现更丰富的七层负载均衡能力和更多样的服务路由规则。本文为您介绍 API 网关当前支持的 Nginx Ingress Annotation。 ## 重写 |注解 |作用域 |支持度 |说明 | |---|---|---|---| |nginx.ingress.kubernetes.io/rewrite\-target |路由（Ingress） |兼容 |将 Ingress 定义的原 Path 重写为指定目标，支持 Group Capture。|\ | | | |:::warning|\ | | | |rewrite\-target 仅支持精确匹配和前缀匹配。对于前缀匹配类型，原 path 必须以`/`结尾，否则可能同步失败。|\ | | | ||\ | | | |:::| 语法示例： ```yaml annotations: # path 重写 nginx.ingress.kubernetes.io/rewrite-target: '/new-path' ``` ## 跨域 |注解 |作用域 |支持度 |说明 | |---|---|---|---| |nginx.ingress.kubernetes.io/enable\-cors |路由（Ingress） |兼容 |开启或关闭跨域。开启跨域则完全开放跨域能力，暂不支持精确控制跨域能力。 | 语法示例： ```yaml annotations: # 是否开启跨域（true 或 false），开启跨域则用户可以在浏览器上跨域访问网关 nginx.ingress.kubernetes.io/enable-cors: 'true' ``` ## 负载均衡 |注解 |作用域 |支持度 |说明 | |---|---|---|---| |nginx.ingress.kubernetes.io/load\-balance |upstream |部分兼容。|后端服务的普通负载均衡算法，取值：|\ | | |不支持 ewma 算法。若配置为 EWMA 算法，会回退到 round_robin 算法。 ||\ | | | |* round_robin：（默认）基于轮询的负载均衡。|\ | | | |* least_conn：基于最小请求数的负载均衡。|\ | | | |* random：基于随机的负载均衡。 | 语法示例： ```yaml annotations: # 网关到 upstream 的负载均衡策略，本例中网关会以轮询的负载均衡方式访问 Kubernetes Service nginx.ingress.kubernetes.io/load-balance: 'round_robin' ``` ## 超时 |注解 |作用域 |支持度 |说明 | |---|---|---|---| |apig.ingress.kubernetes.io/timeout |Ingress |不兼容，APIG 扩展 |请求的超时时间，单位为秒。默认未配置超时时间。说明超时设置作用在应用层，非传输层 TCP。 | 语法示例： ```yaml annotations: # APIG 扩展的请求超时时间，单位是秒。本例中如果 30s 内 Service 没返回，则网关返回 504 timeout apig.ingress.kubernetes.io/timeout: '30' ``` ## 重定向 |注解 |作用域 |支持度 |说明 | |---|---|---|---| |nginx.ingress.kubernetes.io/ssl\-redirect |Ingress |兼容 |HTTP 重定向为 HTTPS。 | 语法示例： ```yaml annotations: # 是否开启重定向（true 或 false），开启后如果客户端通过 HTTP 访问，则网关会重定向成 HTTPS nginx.ingress.kubernetes.io/ssl-redirect: 'true' ``` ## Header 操作 |注解 |作用域 |支持度 |说明 | |---|---|---|---| |apig.ingress.kubernetes.io/request\-header\-control\-add |Ingress |不兼容，APIG 扩展 |请求在转发给后端服务时，添加指定 Header。若该 Header 存在，则其值拼接在原有值后面。语法如下：|\ | | | ||\ | | | |* 单个 Header：`Key Value`。|\ | | | |* 多个 Header：使用 YAML 特殊符号`\|` ，使每对 Key Value 单独处于一行。 | |apig.ingress.kubernetes.io/request\-header\-control\-update |Ingress |不兼容，APIG 扩展 |请求在转发给后端服务时，修改指定 Header。若该 Header 存在，则其值覆盖原有值。语法如下：|\ | | | ||\ | | | |* 单个 Header：`Key Value`。|\ | | | |* 多个 Header：使用 YAML 特殊符号`\|` ，使每对 Key Value 单独处于一行。 | |apig.ingress.kubernetes.io/request\-header\-control\-remove |Ingress |不兼容，APIG 扩展 |请求在转发给后端服务时，删除指定 Header。语法如下：|\ | | | ||\ | | | |* 单个 Header：`Key`。|\ | | | |* 多个 Header：使用英文逗号分隔。 | |apig.ingress.kubernetes.io/response\-header\-control\-add |Ingress |不兼容，APIG 扩展 |请求收到后端服务响应后，在转发响应给客户端之前需要添加指定 Header。若该 Header 存在，则其值拼接在原有值后面。语法如下：|\ | | | ||\ | | | |* 单个 Header：`Key Value`。|\ | | | |* 多个 Header：使用 YAML 特殊符号`\|` ，使每对 Key Value 单独处于一行。 | |apig.ingress.kubernetes.io/response\-header\-control\-update |Ingress |不兼容，APIG 扩展 |请求收到后端服务响应后，在转发响应给客户端之前需要修改指定 Header。若该 Header 存在，则其值覆盖原有值。语法如下：|\ | | | ||\ | | | |* 单个 Header：`Key Value`。|\ | | | |* 多个 Header：使用 YAML 特殊符号`\|` ，使每对 Key Value 单独处于一行。 | |apig.ingress.kubernetes.io/response\-header\-control\-remove |Ingress |不兼容，APIG 扩展 |请求收到后端服务响应后，在转发响应给客户端之前需要删除指定 Header。语法如下：|\ | | | ||\ | | | |* 单个 Header：`Key`。|\ | | | |* 多个 Header：使用英文逗号分隔。 | 语法示例：用户后端服务在接收到网关转发的 http 请求时，希望能从 request header 中获取到客户端 IP、客户端 Port 等信息，从而针对客户端信息做一些业务处理。例如，用户后端服务想通过自定义 request header：X\-Real\-IP、X\-Real\-Port 来获取客户端信息。 :::warning Envoy 支持向请求和响应头部里添加动态值。用百分号（%）来分割变量名称，支持的动态值请参考 [headers](https://cloudnative.to/envoy/configuration/http/http_conn_man/headers.html)。 ::: ```yaml annotations: # 添加 request header，value 的值支持 envoy 动态值 apig.ingress.kubernetes.io/request-header-control-add: |- x-Real-IP %DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT% X-Real-Port %DOWNSTREAM_REMOTE_PORT% apig.ingress.kubernetes.io/request-header-control-update: |- aaa bb&*!b ccc ddd apig.ingress.kubernetes.io/request-header-control-remove: |- age ``` 最终效果如下： ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_33d718310fe262f38136a0e514dc1ca1.png =959x) * 网关访问上游 upstream 时，追加两个 request header： * x\-Real\-IP=客户端 IP * X\-Real\-Port=客户端 Port * 网关访问上游 upstream 时，覆写两个 request header： * aaa=bb&\*!b * ccc=ddd * 网关访问上游 upstream 时，移除了一个request header：header key是age ## 灰度发布 |注解 |作用域 |支持度 |说明 | |---|---|---|---| |nginx.ingress.kubernetes.io/canary |Ingress |兼容 |开启或关闭灰度发布。 | |nginx.ingress.kubernetes.io/canary\-by\-header |Ingress |兼容 |基于`Request Header Key`分流到不同 Kubernetes Service 上。 | |nginx.ingress.kubernetes.io/canary\-by\-header\-value |Ingress |兼容 |基于`Request Header Value`分流到不同 Kubernetes Service 上，Value 为精确匹配。 | |nginx.ingress.kubernetes.io/canary\-weight |Ingress |兼容 |基于权重分流到不同 Kubernetes Service 上。 | |nginx.ingress.kubernetes.io/canary\-weight\-total |Ingress |兼容 |权重总和。 | 按 Header 匹配灰度发布语法示例： ```yaml annotations: nginx.ingress.kubernetes.io/canary: 'true' # headers 中包含 foo=bar 时，才会发送到 new-ngnix 上，不带此 header 时，发送到原始路由 nginx 上 nginx.ingress.kubernetes.io/canary-by-header: foo nginx.ingress.kubernetes.io/canary-by-header-value: bar ``` 按 weight 灰度发布语法示例： ```yaml annotations: nginx.ingress.kubernetes.io/canary: 'true' # 30% 的流量发送 new-nginx 上，剩下 70% 的流量发送到原始路由中的 nginx 上 nginx.ingress.kubernetes.io/canary-weight: '30' ```