APIG 支持通过注解（Annotation）实现更加丰富的路由能力配置。本文主要介绍使用 Annotation 配置 APIG 的主要场景和配置方法。

配置灰度发布

APIG 支持通过 Annotation 配置灰度发布，允许基于 Header 或服务权重实现流量切分。示例和说明如下：

apiVersion: networking.k8s.io/v1​
kind: Ingress​
metadata:​
  name: apig-ingress # 路由规则的名称​
  namespace: default  # 路由规则所属的命名空间​
  annotations:​
    ingress.vke.volcengine.com/apig-instance-name: "apig-instance-demo" # 指定 APIGInstance 资源名称​
    nginx.ingress.kubernetes.io/canary: "true" # 是否开启灰度发布功能，取值：true（开启）、false（关闭）​
    nginx.ingress.kubernetes.io/canary-by-header: "Region" # 基于 Header 的流量切分策略​
    nginx.ingress.kubernetes.io/canary-by-header-value: "beijing" # Header 中包含指定 Header 且值为 beijing时，将请求进行转发​
    nginx.ingress.kubernetes.io/canary-weight: "25" # 基于服务权重的流量切分策略​
    nginx.ingress.kubernetes.io/canary-weight-total: "100" # 服务总权重​
spec:​
  ingressClassName: apig​
  rules:​
    - host: example.com  # 需要对外提供访问的域名​
      http:​
        paths:​
        - pathType: Prefix # 路径匹配规则。取值：Exact（精确匹配）、Prefix（前缀匹配）、Regex（正则匹配）​
          path: / # 请求匹配的路径​
          backend:​
            service:​
              name: service-demo # 需要对接的服务名称​
              port: ​
                number: 80 # 需要对接服务的端口号​

Annotation 说明如下表所示。

字段	类型	描述	默认值
nginx.ingress.kubernetes.io/canary	String	启用灰度发布功能。取值： true：开启灰度发布功能。 false：关闭灰度发布功能。	无
nginx.ingress.kubernetes.io/canary-by-header	String	基于 Header 实现灰度发布，将请求流量分配到灰度服务入口。	无
nginx.ingress.kubernetes.io/canary-by-header-value	String	当请求中的 Header 值与该配置匹配时，请求流量会被分配到灰度服务入口。	无
nginx.ingress.kubernetes.io/canary-weight	String	基于权重实现灰度发布，流量会根据权重占比随机路由到灰度服务入口。	无
nginx.ingress.kubernetes.io/canary-weight-total	String	配置基于权重切分流量时的权重总和。	100

配置重写

APIG 支持通过 Annotation 配置重写，示例和说明如下：

Annotation 说明如下表所示。

字段	类型	描述	默认值
nginx.ingress.kubernetes.io/rewrite-target	String	APIG 实例的 Path 重写。支持将 Ingress 定义的原 Path 重写为指定目标，支持 Group Capture。注意 rewrite-target 支持精确匹配和前缀匹配。如果原path中的路径以/结尾，则rewrite-target中的路径也需要以/结尾。如果原path中的路径不是以/结尾，则rewrite-target中的路径也不能以/结尾。	无

配置跨域

APIG 支持通过 Annotation 配置跨域，示例和说明如下：

Annotation 说明如下表所示。

字段	类型	描述	默认值
nginx.ingress.kubernetes.io/enable-cors	String	开启或关闭跨域。取值： true：开启跨域。 false：关闭跨域。	无

配置负载均衡

APIG 支持通过 Annotation 配置负载均衡算法，示例和说明如下：

Annotation 说明如下表所示。

字段	类型	描述	默认值
nginx.ingress.kubernetes.io/load-balance	String	配置负载均衡算法，取值： round_robin：基于轮询的负载均衡。 least_conn：基于最小请求数的负载均衡。 random：基于随机的负载均衡。说明暂不支持 ewma 算法。若配置为 ewma 算法，系统会自动回退到 round_robin 算法。	round_robin

配置超时

APIG 支持通过 Annotation 配置超时时间，示例和说明如下：

Annotation 说明如下表所示。

字段	类型	描述	默认值
apig.ingress.kubernetes.io/timeout	Integer	APIG 扩展的请求超时时间，单位为秒。例如设置为 30 时，表示如果 30 秒内上游 Service 没返回，则网关就返回504 timeout错误信息。	30

配置重定向

APIG 支持通过 Annotation 配置 HTTP 重定向到 HTTPS，示例和说明如下：

Annotation 说明如下表所示。

字段	类型	描述	默认值
nginx.ingress.kubernetes.io/ssl-redirect	String	是否将 HTTP 请求重定向至 HTTPS。取值： true：开启将 HTTP 请求重定向至 HTTPS。 false：关闭将 HTTP 请求重定向至 HTTPS。	无

配置重试

APIG 支持通过 Annotation 配置重试，示例和说明如下：

Annotation 说明如下表所示。

字段	类型	描述	默认值
nginx.ingress.kubernetes.io/proxy-next-upstream	String	配置重试条件，取值： error：连接后端服务时出错（例如服务不可用、端口不通等）。 timeout：连接、读写超时。 http_503：后端服务返回 503 错误（服务不可用）。 http_502：后端服务返回 502 错误（网关错误）。 http_504：后端服务返回 504 错误（网关超时） invalid_header：后端响应头非法。 off：关闭重试。说明支持同时配置多个重试条件，多个条件之间使用空格分割。例如nginx.ingress.kubernetes.io/proxy-next-upstream: "error timeout"。	无
nginx.ingress.kubernetes.io/retriable-status-codes	String	配置重试的 HTTP 错误码。例如429、500、502 等。说明支持同时配置多个重试的 HTTP 错误码，多个错误码之间使用英文逗号,分割。例如nginx.ingress.kubernetes.io/retriable-status-codes: "429,500,502,503,504"。	无
nginx.ingress.kubernetes.io/proxy-next-upstream-tries	String	配置重试请求的最大次数，正整数形式。该配置包含第一次请求，因此当配置为 1 时，表示禁止重试。	无
nginx.ingress.kubernetes.io/proxy-next-upstream-timeout	String	配置所有重试请求的总超时时间，超时就立刻停止重试并返回错误。整数形式，单位为秒。配置为 0 时表示不限制重试时间。	0

配置 Header

APIG 支持通过 Annotation 配置 Header。允许在接收请求或响应后，添加、修改或删除指定 Header。示例和说明如下：

Annotation 说明如下表所示。

字段	类型	描述	默认值
apig.ingress.kubernetes.io/request-header-control-add	String	请求在转发给后端服务时，添加指定 Header。若该 Header 存在，则其值拼接在原有值后面。语法如下：单个 Header：Key Value。多个 Header：使用 YAML 特殊符号\| ，使每对 Key Value 单独处于一行。	无
apig.ingress.kubernetes.io/request-header-control-update	String	请求在转发给后端服务时，修改指定 Header。若该 Header 存在，则其值覆盖原有值。语法如下：单个 Header：Key Value。多个 Header：使用 YAML 特殊符号\| ，使每对 Key Value 单独处于一行。	无
apig.ingress.kubernetes.io/request-header-control-remove	String	请求在转发给后端服务时，删除指定 Header。语法如下：单个 Header：Key Value。多个 Header：使用 YAML 特殊符号\| ，使每对 Key Value 单独处于一行。	无
apig.ingress.kubernetes.io/response-header-control-add	String	请求收到后端服务响应后，在转发响应给客户端之前需要添加指定 Header。若该 Header 存在，则其值拼接在原有值后面。语法如下：单个 Header：Key Value。多个 Header：使用 YAML 特殊符号\| ，使每对 Key Value 单独处于一行。	无
apig.ingress.kubernetes.io/response-header-control-update	String	请求收到后端服务响应后，在转发响应给客户端之前需要修改指定 Header。若该 Header 存在，则其值覆盖原有值。语法如下：单个 Header：Key Value。多个 Header：使用 YAML 特殊符号\| ，使每对 Key Value 单独处于一行。	无
apig.ingress.kubernetes.io/response-header-control-remove	String	请求收到后端服务响应后，在转发响应给客户端之前需要删除指定 Header。语法如下：单个 Header：Key Value。多个 Header：使用 YAML 特殊符号\| ，使每对 Key Value 单独处于一行。	无

配置举例

某用户后端服务，在接收到 APIG 转发的 HTTP 请求时，希望能从 Request Header 中获取到客户端 IP、客户端 Port 等信息，从而针对客户端信息做一些业务处理。例如，用户后端服务想通过自定义 Request Header：X-Real-IP、X-Real-Port 来获取客户端信息。

预期结果如下：

网关访问上游 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。

配置会话亲和性

APIG 支持通过 Annotation 配置会话亲和性，示例和说明如下：

Annotation 说明如下表所示。

字段	类型	描述	默认值
nginx.ingress.kubernetes.io/affinity	String	配置会话亲和性，允许同一个客户端的请求始终转发到同一个后端服务。当前仅支持设置为cookie，即基于 Cookie 的会话亲和。	cookie
nginx.ingress.kubernetes.io/session-cookie-name	String	配置会话亲和的 Cookie 名称。	无
nginx.ingress.kubernetes.io/session-cookie-path	String	配置会话亲和 Cookie 的字段路径。仅当客户端访问这个路径时，浏览器才会携带指定的 Cookie，从而实现会话亲和。	/
nginx.ingress.kubernetes.io/session-cookie-max-age	String	配置会话亲和 Cookie 超时时间，单位为秒，默认为 Session 会话级别。	无
nginx.ingress.kubernetes.io/session-cookie-expires	String	配置会话亲和 Cookie 超时时间，单位为秒，默认为 Session 会话级别。说明该参数兼容性较强，兼容 IE 等旧浏览器。	无

配置后端服务使用的协议

APIG 支持通过 Annotation 配置后端服务使用的协议，示例和说明如下：

Annotation 说明如下表所示。

字段	类型	描述	默认值
nginx.ingress.kubernetes.io/backend-protocol	String	配置后端服务使用的协议，支持 HTTP、HTTP2 和 gRPC。	HTTP

API 网关