使用 Annotation 配置 APIG Ingress--容器服务-火山引擎

文档中心

立即注册

导航

使用 Annotation 配置 APIG Ingress

最近更新时间：2024.08.14 17:08:58首次发布时间：2024.08.14 17:08:58

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

注意

注解的内容需要严格区分大小写。

配置灰度发布

APIG Ingress 支持通过 Annotation 配置灰度发布，允许基于 Header 或服务权重实现流量切分。详情请参见使用 APIG Ingress 实现灰度发布和蓝绿发布。

配置重写

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

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/rewrite-target: /test # 配置重写，将原 Path 重写为指定路径
spec:
  ingressClassName: apig
  rules:
    - host: example.com  # 需要对外提供访问的域名
      http:
        paths:
        - pathType: Prefix # 路径匹配规则，默认为 Prefix（前缀匹配）
          path: / # 请求匹配的路径
          backend:
            service:
              name: service-demo # 需要对接的服务名称
              port: 
                number: 80 # 需要对接服务的端口号

Annotation 说明如下表所示。

字段	类型	描述	默认值
nginx.ingress.kubernetes.io/rewrite-target	String	APIG 实例的 Path 重写。支持将 Ingress 定义的原 Path 重写为指定目标，支持 Group Capture。注意 rewrite-target 仅支持精确匹配和前缀匹配。对于前缀匹配类型，原 Path 必须以`/`结尾，否则可能同步失败。	无

配置跨域

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

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/enable-cors: true # 配置开启或关闭跨域
spec:
  ingressClassName: apig
  rules:
    - host: example.com  # 需要对外提供访问的域名
      http:
        paths:
        - pathType: Prefix # 路径匹配规则，默认为 Prefix（前缀匹配）
          path: / # 请求匹配的路径
          backend:
            service:
              name: service-demo # 需要对接的服务名称
              port: 
                number: 80 # 需要对接服务的端口号

Annotation 说明如下表所示。

字段	类型	描述	默认值
nginx.ingress.kubernetes.io/enable-cors	Boolean	开启或关闭跨域。开启跨域则完全开放跨域能力，暂不支持精确控制跨域能力。取值： true：开启跨域。 false：关闭跨域。	无

字段

类型

描述

默认值

nginx.ingress.kubernetes.io/enable-cors

Boolean

开启或关闭跨域。开启跨域则完全开放跨域能力，暂不支持精确控制跨域能力。取值：

true：开启跨域。
false：关闭跨域。

无

配置负载均衡

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

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/load-balance: round_robin # 配置负载均衡算法
spec:
  ingressClassName: apig
  rules:
    - host: example.com  # 需要对外提供访问的域名
      http:
        paths:
        - pathType: Prefix # 路径匹配规则，默认为 Prefix（前缀匹配）
          path: / # 请求匹配的路径
          backend:
            service:
              name: service-demo # 需要对接的服务名称
              port: 
                number: 80 # 需要对接服务的端口号

Annotation 说明如下表所示。

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

字段

类型

描述

默认值

nginx.ingress.kubernetes.io/load-balance

String

配置负载均衡算法，取值：

round_robin：基于轮询的负载均衡。
least_conn：基于最小请求数的负载均衡。
random：基于随机的负载均衡。

说明

暂不支持 ewma 算法。若配置为 ewma 算法，系统会自动回退到 round_robin 算法。

round_robin

配置超时

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

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 资源名称
    apig.ingress.kubernetes.io/timeout: 30 # APIG 扩展的请求超时时间，单位为秒
spec:
  ingressClassName: apig
  rules:
    - host: example.com  # 需要对外提供访问的域名
      http:
        paths:
        - pathType: Prefix # 路径匹配规则，默认为 Prefix（前缀匹配）
          path: / # 请求匹配的路径
          backend:
            service:
              name: service-demo # 需要对接的服务名称
              port: 
                number: 80 # 需要对接服务的端口号

Annotation 说明如下表所示。

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

配置 HTTP 重定向

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

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/ssl-redirect: true # 开启 HTTP 重定向到 HTTPS
spec:
  ingressClassName: apig
  rules:
    - host: example.com  # 需要对外提供访问的域名
      http:
        paths:
        - pathType: Prefix # 路径匹配规则，默认为 Prefix（前缀匹配）
          path: / # 请求匹配的路径
          backend:
            service:
              name: service-demo # 需要对接的服务名称
              port: 
                number: 80 # 需要对接服务的端口号

Annotation 说明如下表所示。

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

字段

类型

描述

默认值

nginx.ingress.kubernetes.io/ssl-redirect

Boolean

是否将 HTTP 请求重定向至 HTTPS。取值：

true：开启将 HTTP 请求重定向至 HTTPS。
false：关闭将 HTTP 请求重定向至 HTTPS。

无

APIG Ingress 支持通过 Annotation 配置 Header。允许在接收请求或响应后，添加、修改或删除指定 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 资源名称
    apig.ingress.kubernetes.io/request-header-control-add: key value # 请求在转发给后端服务时，添加指定 Header
    apig.ingress.kubernetes.io/request-header-control-update: key value # 请求在转发给后端服务时，修改指定 Header
    apig.ingress.kubernetes.io/request-header-control-remove: key value # 请求在转发给后端服务时，删除指定 Header
    apig.ingress.kubernetes.io/response-header-control-add: key value # 请求收到后端服务响应后，在转发响应给客户端之前需要添加指定 Header
    apig.ingress.kubernetes.io/response-header-control-update: key value # 请求收到后端服务响应后，在转发响应给客户端之前需要修改指定 Header
    apig.ingress.kubernetes.io/response-header-control-remove: key value # 请求收到后端服务响应后，在转发响应给客户端之前需要删除指定 Header
spec:
  ingressClassName: apig
  rules:
    - host: example.com  # 需要对外提供访问的域名
      http:
        paths:
        - pathType: Prefix # 路径匹配规则，默认为 Prefix（前缀匹配）
          path: / # 请求匹配的路径
          backend:
            service:
              name: service-demo # 需要对接的服务名称
              port: 
                number: 80 # 需要对接服务的端口号

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 来获取客户端信息。

说明

Envoy 支持向请求和响应头部里添加动态值。用百分号（%）来分割变量名称，支持的动态值请参考官方文档。

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。

alt