使用 Kubernetes Annotation 能够实现更丰富的七层负载均衡能力和更多样的服务路由规则。本文为您介绍 API 网关当前支持的 Nginx Ingress Annotation。
重写
| 注解 | 作用域 | 支持度 | 说明 |
|---|---|---|---|
nginx.ingress.kubernetes.io/rewrite-target | 路由（Ingress） | 兼容 | 将 Ingress 定义的原 Path 重写为指定目标，支持 Group Capture。 注意 rewrite-target 仅支持精确匹配和前缀匹配。对于前缀匹配类型，原 path 必须以 |
语法示例：
annotations: # path 重写 nginx.ingress.kubernetes.io/rewrite-target: '/new-path'
跨域
| 注解 | 作用域 | 支持度 | 说明 |
|---|---|---|---|
| nginx.ingress.kubernetes.io/enable-cors | 路由（Ingress） | 兼容 | 开启或关闭跨域。开启跨域则完全开放跨域能力，暂不支持精确控制跨域能力。 |
语法示例：
annotations: # 是否开启跨域（true 或 false），开启跨域则用户可以在浏览器上跨域访问网关 nginx.ingress.kubernetes.io/enable-cors: 'true'
负载均衡
| 注解 | 作用域 | 支持度 | 说明 |
|---|---|---|---|
nginx.ingress.kubernetes.io/load-balance | upstream | 部分兼容。 | 后端服务的普通负载均衡算法，取值：
|
语法示例：
annotations: # 网关到 upstream 的负载均衡策略，本例中网关会以轮询的负载均衡方式访问 Kubernetes Service nginx.ingress.kubernetes.io/load-balance: 'round_robin'
超时
| 注解 | 作用域 | 支持度 | 说明 |
|---|---|---|---|
| apig.ingress.kubernetes.io/timeout | Ingress | 不兼容，APIG 扩展 | 请求的超时时间，单位为秒。默认未配置超时时间。说明超时设置作用在应用层，非传输层 TCP。 |
语法示例：
annotations: # APIG 扩展的请求超时时间，单位是秒。本例中如果 30s 内 Service 没返回，则网关返回 504 timeout apig.ingress.kubernetes.io/timeout: '30'
重定向
| 注解 | 作用域 | 支持度 | 说明 |
|---|---|---|---|
| nginx.ingress.kubernetes.io/ssl-redirect | Ingress | 兼容 | HTTP 重定向为 HTTPS。 |
语法示例：
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 存在，则其值拼接在原有值后面。语法如下：
|
apig.ingress.kubernetes.io/request-header-control-update | Ingress | 不兼容，APIG 扩展 | 请求在转发给后端服务时，修改指定 Header。若该 Header 存在，则其值覆盖原有值。语法如下：
|
apig.ingress.kubernetes.io/request-header-control-remove | Ingress | 不兼容，APIG 扩展 | 请求在转发给后端服务时，删除指定 Header。语法如下：
|
apig.ingress.kubernetes.io/response-header-control-add | Ingress | 不兼容，APIG 扩展 | 请求收到后端服务响应后，在转发响应给客户端之前需要添加指定 Header。若该 Header 存在，则其值拼接在原有值后面。语法如下：
|
apig.ingress.kubernetes.io/response-header-control-update | Ingress | 不兼容，APIG 扩展 | 请求收到后端服务响应后，在转发响应给客户端之前需要修改指定 Header。若该 Header 存在，则其值覆盖原有值。语法如下：
|
apig.ingress.kubernetes.io/response-header-control-remove | Ingress | 不兼容，APIG 扩展 | 请求收到后端服务响应后，在转发响应给客户端之前需要删除指定 Header。语法如下：
|
语法示例：
用户后端服务在接收到网关转发的 http 请求时，希望能从 request header 中获取到客户端 IP、客户端 Port 等信息，从而针对客户端信息做一些业务处理。
例如，用户后端服务想通过自定义 request header：X-Real-IP、X-Real-Port 来获取客户端信息。
注意
Envoy 支持向请求和响应头部里添加动态值。用百分号（%）来分割变量名称，支持的动态值请参考 headers。
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
最终效果如下：
- 网关访问上游 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 匹配灰度发布语法示例：
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 灰度发布语法示例：
annotations: nginx.ingress.kubernetes.io/canary: 'true' # 30% 的流量发送 new-nginx 上，剩下 70% 的流量发送到原始路由中的 nginx 上 nginx.ingress.kubernetes.io/canary-weight: '30'