自定义ALB Ingress的转发规则

ALB Ingress支持通过自定义转发规则扩展Kubernetes原生Ingress的功能，例如指定请求头、查询字符串、请求方法、Cookie、源IP等，也可以自定义转发动作，例如配置固定响应、重定向、流量镜像等功能。部分自定义转发规则支持通过控制台配置。

工作原理

ALB 自定义转发规则主要由转发条件与转发动作两部分组成，支持在请求或响应阶段进行精细化流量控制：

转发条件：通过 alb.ingress.kubernetes.io/conditions.<service_name> 注解配置。该条件通过名称关联后端 Service，并应用于 Ingress 中指向该 Service 的所有路径。只有满足条件的流量才会被执行相应操作，且条件支持在请求或响应双向进行匹配。
转发动作：通过 alb.ingress.kubernetes.io/actions.<service_name> 注解配置。用于定义 ALB 实例在处理请求或返回响应时的具体行为（如转发或重定向）。
作用方向：自定义转发规则支持在请求或响应方向配置，使用 alb.ingress.kubernetes.io/rule-direction.<service_name> 明确规则的作用方向：
- 请求方向：客户端请求经ALB Ingress转发到Service。
- 响应方向：Service的响应经ALB Ingress转发回客户端。
- 当在同一方向同时配置了条件与动作时，仅符合转发条件的请求或响应才会触发相应的转发动作。

重要

由于alb.ingress.kubernetes.io/rule-direction.<service_name>作用于当前 Ingress 资源内的所有配置，请将不同方向（请求/响应）的转发规则拆分到不同的 Ingress 资源中配置。配置示例，请参见场景七：基于ResponseHeader对响应头进行修改。

准备工作

安装组件

安装ALB Ingress Controller组件，或确保已安装的组件为v2.5.0及以上版本。

创建示例服务

创建并将下方示例复制到echoserver.yaml，执行kubectl apply -f echoserver.yaml创建示例Deployment和Service。该示例使用了echoserver镜像，会自动返回收到的请求内容，可以用于验证ALB自定义转发规则的效果。

重要

本文示例使用的镜像为公网镜像，拉取时集群或节点需具备公网访问能力：

为集群开启访问公网的能力（推荐）：为集群所在的VPC创建公网NAT网关，集群中的所有资源均可访问公网。
为节点分配固定公网IP：拥有公网IP的节点可拉取公网镜像，但需要为部署工作负载的每个节点都分配公网IP。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: echoserver
  labels:
    app: echoserver
spec:
  replicas: 2
  selector:
    matchLabels:
      app: echoserver
  template:
    metadata:
      labels:
        app: echoserver
    spec:
      containers:
      - name: echoserver
        image: openkruise-registry.cn-shanghai.cr.aliyuncs.com/openkruise/demo:1.10.2
        imagePullPolicy: IfNotPresent
        ports:
        - containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: echoserver
  labels:
    app: echoserver
spec:
  type: ClusterIP
  ports:
  - port: 80
    targetPort: 8080
    protocol: TCP
    name: http
  selector:
    app: echoserver

配置转发条件

重要

通过ACK控制台创建Ingress并设置路径转发条件后，为满足格式需求，Ingress中会自动添加两条路径为/created-by-<ALB-ID>的转发规则。

场景一：基于SourceIp和请求头的转发

重要

同一条转发规则的自定义条件设置的SourceIp数量限制为5个。

下方示例中，当请求的客户端IP、请求头和路径符合配置时，才会被转发到后端Service。

创建并将下方示例复制到sourceip-header.yaml，执行kubectl apply -f sourceip-header.yaml创建Ingress。

客户端IP：匹配192.168.0.0/16或10.0.0.0/8。
请求头：包含headername:headervalue1或headername:headervalue2。
路径：使用/echo。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/conditions.echoserver: | # echoserver需与spec.rules中配置的后端Service名称对应一致。
     [{
       "type": "Header",
       "headerConfig": {
         "key": "headername",
         "values": [
           "headervalue1",
           "headervalue2"
         ]
       }
     },
     {
      "type": "SourceIp",
      "sourceIpConfig": {
        "values": [
          "192.168.0.0/16",
          "10.0.0.0/8"
         ]
       }
     }]
  name: sourceip-header-ingress
spec:
  ingressClassName: alb
  rules:
  - http:
      paths:
      - path: /echo
        pathType: ImplementationSpecific
        backend:
          service:
            name: echoserver
            port:
              number: 80

效果验证

将下方命令中的ALB_ENDPOINT替换为ALB实例端点后执行，请求中手动添加了请求头：

请确保发送请求的客户端IP处于SourceIp列表中。

curl -H "headername:headervalue1" -s ALB_ENDPOINT/echo | grep -A 16 "Request Information"

预期输出：

Request Information:
	client_address=::ffff:10.0.2.93
	method=GET
	real path=/echo # 匹配转发条件的path
	query=
	request_version=1.1
	request_scheme=http
	request_uri=http://alb-jyoefh22rkje******.******-**.alb.aliyuncsslbintl.com:8080/echo

Request Headers:
	accept=*/*
	headername=headervalue1 # 匹配转发条件的请求头
	host=alb-jyoefh22rkje******.******-**.alb.aliyuncsslbintl.com
	remoteip=140.205.***.***
	user-agent=curl/8.4.0
	x-forwarded-for=140.205.***.*** # 匹配转发条件的客户端IP

场景二：基于域名、请求方法和Cookie的转发

下方示例中，当请求使用的域名、请求方法、Cookie和路径符合配置时，才会被转发到后端Service。

创建并将下方示例复制到host-method.yaml，执行kubectl apply -f host-method.yaml创建Ingress。

域名：使用demo.alb.ingress.top，在spec.rules中配置。
请求方法：使用PUT或HEAD。
Cookie：包含cookiekey1=cookievalue1。
路径：使用/echo。

域名转发条件支持泛域名（例如*.com）匹配。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/conditions.echoserver: | # echoserver需与spec.rules中配置的后端Service名称对应一致。
     [{
       "type": "Cookie",
       "cookieConfig": {
         "values": [
           {
             "key":"cookiekey1",
             "value":"cookievalue1"
           }
        ]
       }
      },
      {
       "type": "Method",
       "methodConfig": {
         "values": [
           "PUT",
           "HEAD"
         ]
       }
      }]
  name: host-method-ingress
spec:
  ingressClassName: alb
  rules:
  - host: demo.alb.ingress.top
    http:
      paths:
      - path: /echo
        pathType: ImplementationSpecific
        backend:
          service:
            name: echoserver
            port:
              number: 80

效果验证

将下方命令中的ALB_ENDPOINT替换为ALB实例端点后执行，请求中手动添加了域名、请求方法和Cookie：

curl -H "Host:demo.alb.ingress.top" -X PUT -b "cookiekey1=cookievalue1" -s ALB_ENDPOINT/echo | grep -A 16 "Request Information"

预期输出：

Request Information:
	client_address=::ffff:10.0.3.249
	method=PUT # 匹配转发条件的请求方法
	real path=/echo # 匹配转发条件的path
	query=
	request_version=1.1
	request_scheme=http
	request_uri=http://demo.alb.ingress.top:8080/echo

Request Headers:
	accept=*/*
	cookie=cookiekey1=cookievalue1 # 匹配转发条件的Cookie值
	host=demo.alb.ingress.top # 匹配转发条件的域名
	remoteip=140.205.***.***
	user-agent=curl/8.4.0
	x-forwarded-for=140.205.***.***

场景三：基于查询字符串、多个请求头的转发

下方示例中，当请求查询字符串、请求头和路径符合配置时，才会被转发到后端Service。

创建并将下方示例复制到querystring.yaml，执行kubectl apply -f querystring.yaml创建Ingress。

查询字符串：使用querystringkey1=querystringvalue2。
请求头：包含headerkey1:headervalue1或headerkey1:headervalue2，同时包含headerkey2:headervalue3或headerkey2:headervalue4。
路径：使用/echo。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/conditions.echoserver: | # echoserver需与spec.rules中配置的后端Service名称对应一致。
    [{
      "type": "QueryString",
      "queryStringConfig": {
        "values": [
          {
            "key":"querystringkey1",
            "value":"querystringvalue2"
          }
        ]
      }
    },
    {
      "type": "Header",
      "headerConfig": {
        "key":"headerkey1",
        "values": [
          "headervalue1",
          "headervalue2"
        ]
      }
    },
    {
      "type": "Header",
      "headerConfig": {
        "key":"headerkey2",
        "values": [
          "headervalue3",
          "headervalue4"
        ]
      }
    }]
  name: querystring-ingress
spec:
  ingressClassName: alb
  rules:
  - http:
      paths:
      - path: /echo
        pathType: ImplementationSpecific
        backend:
          service:
            name: echoserver
            port:
              number: 80

效果验证

将下方命令中的ALB_ENDPOINT替换为ALB实例端点后执行，请求中手动添加了查询字符串、请求头：

curl -H "headerkey1:headervalue1" -H "headerkey2:headervalue4" -s "ALB_ENDPOINT/echo?querystringkey1=querystringvalue2" | grep -A 16 "Request Information"

预期输出：

Request Information:
	client_address=::ffff:10.0.3.249
	method=GET
	real path=/echo?querystringkey1=querystringvalue2 # 匹配转发条件的path
	query=querystringkey1=querystringvalue2 # 匹配转发条件的查询字符串
	request_version=1.1
	request_scheme=http
	request_uri=http://alb-jyoefh22rkje******.******-**.alb.aliyuncsslbintl.com/echo?querystringkey1=querystringvalue2

Request Headers:
	accept=*/*
	headerkey1=headervalue1 # 匹配转发条件的请求头
	headerkey2=headervalue4 # 匹配转发条件的请求头
	host=alb-jyoefh22rkje******.******-**.alb.aliyuncsslbintl.com
	remoteip=140.205.***.***
	user-agent=curl/8.4.0
	x-forwarded-for=140.205.***.***

转发条件配置说明

重要

多个转发条件共用时的生效逻辑，请参见多个同类型的转发条件会同时生效吗？

转发条件	描述
域名	匹配请求域名，使用了该域名的请求才会被转发到后端Service。域名转发条件支持泛域名（例如`*.com`）匹配。 `alb.ingress.kubernetes.io/conditions.service-name: \| # service-name需与spec.rules中配置的后端Service名称对应一致。 [{ "type": "Host", "hostConfig": { "values": [ "anno.example.com" ] } }]` `type`：转发条件的匹配类型。`Host`表示匹配域名。 `hostConfig`：匹配的具体域名。如果设置了多个域名，则域名之间是或的关系。重要与Ingress原生配置`spec.rules.host`效果相同，同时配置时，两个域名之间是或的关系。请勿配置相同内容，否则会导致The param is duplicated问题。
路径	匹配请求路径，使用了该路径的请求才会被转发到后端Service。 `alb.ingress.kubernetes.io/conditions.service-name: \| # service-name需与spec.rules中配置的后端Service名称对应一致。 [{ "type": "Path", "pathConfig": { "values": [ "/pathvalue1", "/pathvalue2" ] } }]` `type`：转发条件的匹配类型。`Path`表示匹配请求路径。 `pathConfig`：匹配的具体路径。如果设置了多个路径，则路径之间是或的关系。重要与Ingress原生配置`spec.rules.http.paths.path`效果相同，同时配置时，两个路径之间是或的关系。请勿配置相同内容，否则会导致The param is duplicated问题。
Header	匹配请求头，请求头中包含特定内容的请求才会被转发到后端Service。 `alb.ingress.kubernetes.io/conditions.service-name: \| # service-name需与spec.rules中配置的后端Service名称对应一致。 [{ "type": "Header", "headerConfig": { "key": "headername", "values": [ "headervalue1", "headervalue2" ] } }]` `type`：转发条件的匹配类型。`Header`表示匹配请求头。 `headerConfig`：请求头中需要包含的键值对。如果设置了多个值，则各值之间是或的关系。使用场景与示例请参见场景一：基于SourceIp和请求头的转发。
查询字符串	匹配查询字符串，只有使用特定查询字符串的请求才会被转发到后端Service。 `alb.ingress.kubernetes.io/conditions.service-name: \| # service-name需与spec.rules中配置的后端Service名称对应一致。 [{ "type": "QueryString", "queryStringConfig": { "values": [ { "key":"querystringkey1", "value":"querystringvalue2" } ] } }]` `type`：转发条件的匹配类型。`QueryString`表示匹配请求的查询字符串。 `queryStringConfig`：查询字符串的键值对。如果设置了多个查询字符串，则查询字符串之间是或的关系。键字符长度取值为[1,100]，值字符长度取值为1～128个字符，支持小写字母、可见字符和通配符星号（*）和英文半角问号（?），不支持空格和`#[]{}\\|<>&`。使用场景与示例请参见场景三：基于查询字符串、多个请求头的转发。
请求方法	匹配请求方法，只有使用特定方法的请求才会被转发到后端Service。 `alb.ingress.kubernetes.io/conditions.service-name: \| # service-name需与spec.rules中配置的后端Service名称对应一致。 [{ "type": "Method", "methodConfig": { "values": [ "GET", "HEAD" ] } }]` `type`：转发条件的匹配类型。`Method`表示匹配请求方法。 `methodConfig`：具体的请求方法，支持GET、POST、PUT、DELETE、HEAD、OPTIONS和PATCH。如果设置了多个请求方法，则请求方法之间是或的关系。使用场景与示例请参见场景二：基于域名、请求方法和Cookie的转发。
Cookie	匹配Cookie，只有包含正确的Cookie的请求才会被转发到后端Service。 `alb.ingress.kubernetes.io/conditions.service-name: \| # service-name需与spec.rules中配置的后端Service名称对应一致。 [{ "type": "Cookie", "cookieConfig": { "values": [ { "key":"cookiekey1", "value":"cookievalue2" } ] } }]` `type`：转发条件的匹配类型。`Cookie`表示匹配Cookie。 `cookieConfig`：Cookie的键值对。如果设置了多个Cookie，则Cookie之间是或的关系。键字符长度取值为[1,100]，值字符长度取值为[1,100]，支持小写字母、可见字符和通配符星号（*）和英文半角问号（?），不支持空格和`#[]{}\\|<>&`。使用场景与示例请参见场景二：基于域名、请求方法和Cookie的转发。
SourceIp	匹配请求源IP，只有客户端源IP在列表中的请求才会被转发到后端Service。 `alb.ingress.kubernetes.io/conditions.service-name: \| # service-name需与spec.rules中配置的后端Service名称对应一致。 [{ "type": "SourceIp", "sourceIpConfig": { "values": [ "192.168.0.0/16", "172.16.0.0/16" ] } }]` `type`：转发条件的匹配类型。`SourceIp`表示匹配请求的源IP。 `sourceIpConfig`：请求的IP地址。如果设置了多个请求IP，则请求IP之间是或的关系。使用场景与示例请参见场景一：基于SourceIp和请求头的转发。重要单个转发条件内的SourceIp数量限制为5个。
ResponseHeader	匹配响应头，只对携带正确响应头的响应执行转发动作。请注意与响应方向转发动作及响应方向转发规则注解`alb.ingress.kubernetes.io/rule-direction.<service-name>: Response`配合使用。 `alb.ingress.kubernetes.io/conditions.service-name: \| # service-name需与spec.rules中配置的后端Service名称对应一致。 [{ "type": "ResponseHeader", "responseHeaderConfig": { "key": "responseHeader", "values": [ "headervalue1", "headervalue2" ] } }]` `type`：转发条件的匹配类型。`ResponseHeader`表示匹配响应头。 `responseHeaderConfig`：响应头中需要包含的键值对。如果设置了多个值，则各值之间是或的关系。使用场景与示例请参见场景七：基于ResponseHeader对响应头进行修改。
ResponseStatusCode	匹配响应状态码，只有返回正确的状态码才能访问服务。请注意与响应方向转发动作及响应方向转发规则注解`alb.ingress.kubernetes.io/rule-direction.<service-name>: Response`配合使用。 `alb.ingress.kubernetes.io/conditions.service-name: \| # service-name需与spec.rules中配置的后端Service名称对应一致。 [{ "type": "ResponseStatusCode", "responseStatusCodeConfig": { "values": [ "statuscode1", "statuscode2" ] } }]` `type`：转发条件的匹配类型。`ResponseStatusCode`表示匹配响应状态码。 `responseStatusCodeConfig`：具体的响应状态码。如果设置了多个响应状态码，则响应状态码之间是或的关系。使用场景与示例请参见场景八：基于响应状态码对响应头进行修改。

配置转发动作

场景一：设置固定响应503状态码和内容

控制台

登录容器服务管理控制台，在左侧导航栏选择集群列表。
在集群列表页面，单击目标集群名称，然后在左侧导航栏，选择网络 > 路由。

在路由页面，单击创建 Ingress，根据下方配置创建Ingress。

配置项	值
网关类型	ALB Ingress
名称	fixed-ingress
IngressClass	alb
规则	删除路径映射。
自定义转发规则	开启自定义转发规则。转发条件：选择路径，填入/echo。转发动作：选择返回固定响应。响应状态码：503 响应正文类型（可选）：text/plain 响应正文（可选）：503 error text 其余选项保持默认。

配置完成后，单击确定。

kubectl

下方示例中的Ingress会在接收到请求时，返回HTTP 503状态码和503 error text。

创建并将下方示例复制到fixed-response.yaml，执行kubectl apply -f fixed-response.yaml创建Ingress。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  namespace: default
  name: fixed-ingress
  annotations:
    alb.ingress.kubernetes.io/actions.echoserver: | # echoserver需与spec.rules中配置的后端Service名称对应一致。
      [{
          "type": "FixedResponse",
          "FixedResponseConfig": {
              "contentType": "text/plain",
              "httpCode": "503",
              "content": "503 error text"
          }
      }]
spec:
  ingressClassName: alb
  rules:
  - http:
      paths:
      - path: /echo
        pathType: Prefix
        backend:
          service:
            name: echoserver
            port:
              name: use-annotation # servicePort的名称必须为use-annotation。

效果验证

将下方命令中的ALB_ENDPOINT替换为ALB实例端点后执行：

curl -si ALB_ENDPOINT/echo | grep "HTTP/"

预期输出：

503 error text

场景二：使用301重定向到HTTPS端口

重定向

下方示例中的Ingress会在接收到请求时，通过HTTP 301将请求重定向到新域名的443端口。

如果重定向后的域名会被解析到ALB实例端点，可使用此方法将ALB Ingress的HTTP端口重定向到HTTPS端口。

创建并将下方示例复制到redirect.yaml，执行kubectl apply -f redirect.yaml创建Ingress。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  namespace: default
  name: redirect-ingress
  annotations:
    alb.ingress.kubernetes.io/actions.echoserver: | # echoserver需与spec.rules中配置的后端Service名称对应一致。
      [{
          "type": "Redirect",
          "RedirectConfig": {
              "host": "www.alibabacloud.com",
              "path": "/en",
              "port": "443",
              "protocol": "https",
              "query": "_p_lc=1",
              "httpCode": "301"
          }
      }]
spec:
  ingressClassName: alb
  rules:
  - http:
      paths:
      - path: /echo
        pathType: Prefix
        backend:
          service:
            name: echoserver
            port:
              name: use-annotation # servicePort的名称必须为use-annotation。

效果验证

将下方命令中的ALB_ENDPOINT替换为ALB实例端点后执行：

curl -LIs ALB_ENDPOINT/echo | grep "HTTP"

预期输出如下，请求被重定向到新的域名。

HTTP/1.1 301 Moved Permanently
Via: HTTP/1.1 SLB.208
HTTP/2 200

多Service重定向

下方示例中的Ingress同时对多个Service进行重定向。

参见创建示例服务新建一个名为echoserver2的Service。
创建并将下方示例复制到multi-redirect.yaml，执行kubectl apply -f multi-redirect.yaml创建Ingress。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  namespace: default
  name: multi-redirect-ingress
  annotations:
    alb.ingress.kubernetes.io/actions.echoserver: | # echoserver需与spec.rules中配置的后端Service名称对应一致。
      [{
          "type": "Redirect",
          "RedirectConfig": {
              "host": "www.alibabacloud.com",
              "path": "/en",
              "port": "443",
              "protocol": "https",
              "query": "_p_lc=1",
              "httpCode": "301"
          }
      }]
    alb.ingress.kubernetes.io/actions.echoserver2: | # echoserver2需与spec.rules中配置的后端Service名称对应一致。
      [{
          "type": "Redirect",
          "RedirectConfig": {
              "host": "www.alibabacloud.com",
              "path": "/en",
              "port": "443",
              "protocol": "https",
              "query": "_p_lc=1",
              "httpCode": "301"
          }
      }]
spec:
  ingressClassName: alb
  rules:
  - http:
      paths:
      - path: /echo
        pathType: Prefix
        backend:
          service:
            name: echoserver
            port:
              name: use-annotation # servicePort的名称必须为use-annotation。
      - path: /echo2
        pathType: Prefix
        backend:
          service:
            name: echoserver2
            port:
              name: use-annotation # servicePort的名称必须为use-annotation。

效果验证

将下方命令中的ALB_ENDPOINT替换为ALB实例端点后执行：

curl -LIs ALB_ENDPOINT/echo | grep "HTTP" ;
curl -LIs ALB_ENDPOINT/echo2 | grep "HTTP"

预期输出如下，向两个Service的请求都被重定向到新的域名。

HTTP/1.1 301 Moved Permanently
Via: HTTP/1.1 SLB.208
HTTP/2 200
HTTP/1.1 301 Moved Permanently
Via: HTTP/1.1 SLB.208
HTTP/2 200

场景三：插入自定义请求头

下方示例中的Ingress会在接收到请求时，在请求头中插入source:alibaba。

创建并将下方示例复制到insert-header.yaml，执行kubectl apply -f insert-header.yaml创建Ingress。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  namespace: default
  name: insert-header-ingress
  annotations:
    alb.ingress.kubernetes.io/actions.echoserver: | # echoserver需与spec.rules中配置的后端Service名称对应一致
      [{
          "type": "InsertHeader",
          "InsertHeaderConfig": {
              "key": "source",
              "value": "alibaba",
              "valueType": "UserDefined"
          }
      }]
spec:
  ingressClassName: alb
  rules:
  - http:
      paths:
      - path: /echo
        pathType: Prefix
        backend:
          service:
            name: echoserver
            port:
              number: 80

效果验证

将下方命令中的ALB_ENDPOINT替换为ALB实例端点后执行：

curl -s ALB_ENDPOINT/echo | grep -A 6 "Request Headers"

预期输出：

Request Headers:
	accept=*/*
	host=alb-jyoefh22rkjeerxmcg.us-west-1.alb.aliyuncsslbintl.com
	remoteip=140.205.***.***
	source=alibaba # 自定义请求头
	user-agent=curl/8.4.0
	x-forwarded-for=140.205.***.***

场景四：流量镜像至服务器组

配置流量镜像，使ALB Ingress在接收请求时，同时将请求复制发送到另一个服务器组。

登录应用型负载均衡ALB控制台，在左侧导航栏选择应用型负载均衡 ALB > 服务器组，在服务器组页面获取服务器组ID。

创建并将下方示例复制到traffic-mirror.yaml，执行kubectl apply -f traffic-mirror.yaml创建Ingress。

下方示例中的Ingress会在接收到请求时，同时将请求发送到sgp-2auud2fxj1r46*****服务器组。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: traffic-mirror-ingress
  annotations:
    alb.ingress.kubernetes.io/actions.echoserver: | # echoserver需与spec.rules中配置的后端Service名称对应一致
       [{
           "type": "TrafficMirror",
           "TrafficMirrorConfig": {
              "TargetType" : "ForwardGroupMirror",
              "MirrorGroupConfig": {
                  "ServerGroupTuples" : [{
                      "ServerGroupID": "sgp-2auud2fxj1r46*****"
                  }]
              }
           }
       }]
spec:
  ingressClassName: alb
  rules:
  - host: demo.domain.ingress.top
    http:
      paths:
      - path: /echo
        pathType: Prefix
        backend:
          service:
            name: echoserver
            port:
              number: 80

场景五：挂载多个后端服务

接收到请求时，按自定义权重将请求转发到多个后端Service。

参见创建示例服务新建一个名为echoserver2的Service。

创建Ingress资源。

控制台

登录容器服务管理控制台，在左侧导航栏选择集群列表。
在集群列表页面，单击目标集群名称，然后在左侧导航栏，选择网络 > 路由。

在路由页面，单击创建 Ingress，根据下方配置创建Ingress。

配置项	值
网关类型	ALB Ingress
名称	forward-ingress
IngressClass	alb
规则	删除路径映射。
自定义转发规则	开启自定义转发规则。转发条件：域名：demo.alb.ingress.top 路径：/echo 转发动作：选择转发至。服务名称：echoserver 端口：80 服务名称：echoserver2 端口：80 其余选项保持默认。

配置完成后，单击确定。

kubectl

创建并将下方示例复制到forward.yaml，执行kubectl apply -f forward.yaml创建Ingress。

下方示例中的Ingress会在接收到请求时，按80:20的权重转发到echoserver和echoserver2。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: forward-ingress
  annotations:
    alb.ingress.kubernetes.io/actions.echoserver: | # echoserver需与spec.rules中配置的后端Service名称对应一致
       [{
           "type": "ForwardGroup",
           "ForwardConfig": {
             "ServerGroups" : [{
               "ServiceName": "echoserver",
               "Weight": 80,
               "ServicePort": 80
             },
             {
               "ServiceName": "echoserver2",
               "Weight": 20,
               "ServicePort": 80
             }]
           }
       }]
spec:
  ingressClassName: alb
  rules:
  - host: demo.alb.ingress.top
    http:
      paths:
      - path: /echo
        pathType: Prefix
        backend:
          service:
            name: echoserver
            port:
              name: use-annotation # 必须使用use-annotation。

场景六：重写请求配置信息

ALB Ingress支持通过自定义转发规则修改请求的域名、路径和查询参数，弥补了使用Rewrite重写无法修改域名的局限，适用于URL简化、对客户端无感的重写、隐藏后端技术实现等场景。

创建并将下方示例复制到rewrite.yaml，执行kubectl apply -f rewrite.yaml创建Ingress。

下方示例中，客户端使用的URLhttps://example.com/api/echo被重写为https://example.org/echo。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  namespace: default
  name: rewrite-ingress
  annotations:
    alb.ingress.kubernetes.io/actions.echoserver: | # echoserver需与spec.rules中配置的后端Service名称对应一致
       [{
           "type": "Rewrite",
           "RewriteConfig": {
               "host": "example.org", 
               "path": "/echo", 
               "query": "${query}"
           }
       }]
spec:
  ingressClassName: alb
  rules:
  - host: example.com
    http:
      paths:
      - path: /api/echo
        pathType: ImplementationSpecific
        backend:
          service:
            name: echoserver
            port: 
              number: 80

效果验证

将下方命令中的ALB_ENDPOINT替换为ALB实例端点后执行：

curl -H "Host:example.com" -s "ALB_ENDPOINT/api/echo?querystring=request" | grep -A 7 "Request Information"

预期输出：

Request Information:
	client_address=::ffff:10.0.2.93
	method=GET
	real path=/echo?querystring=request
	query=querystring=request
	request_version=1.1
	request_scheme=http
	request_uri=http://example.org:8080/echo?querystring=request # 域名和路径都被重写

场景七：基于ResponseHeader对响应头进行修改

下方示例中的Ingress对响应头进行了修改。当响应头中包含Content-Type: text/plain，在响应头中插入source: alibaba。

创建并将下方示例复制到response-header.yaml，执行kubectl apply -f response-header.yaml创建Ingress。

重要

创建响应方向的转发规则时，需要将注解项 alb.ingress.kubernetes.io/rule-direction.<service-name> 配置为Response（该注解项默认配置为Request）。
单独配置响应方向的转发规则无法完成请求方向的转发，下方示例中同时配置了一个请求方向的Ingress。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: response-header-ingress
  annotations:
    alb.ingress.kubernetes.io/rule-direction.echoserver: Response # 响应方向的转发规则需配合response-header: Response一起使用。
    alb.ingress.kubernetes.io/conditions.echoserver: | # 配合响应方向的转发条件一起使用，只有符合转发条件的响应才会被插入自定义响应头。
     [{
         "type": "ResponseHeader",
         "responseHeaderConfig": {
            "key": "Content-Type",
            "values": [
               "text/plain"
            ]
         }
     }]
    alb.ingress.kubernetes.io/actions.echoserver: | # 插入自定义响应头
     [{
         "type": "InsertHeader",
         "InsertHeaderConfig": {
             "key": "source",
             "value": "alibaba",
             "valueType": "UserDefined"
         }
     }]
spec:
  ingressClassName: alb
  rules:
  - http:
      paths:
      - path: /echo
        pathType: ImplementationSpecific
        backend:
          service:
            name: echoserver
            port:
              name: use-annotation # 必须配置为use-annotation。

---
# 请求方向的Ingress
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: request-ingress
spec:
  ingressClassName: alb
  rules:
  - http:
      paths:
      - path: /echo
        pathType: ImplementationSpecific
        backend:
          service:
            name: echoserver
            port:
              number: 80

效果验证

将下方命令中的ALB_ENDPOINT替换为ALB实例端点后执行：

curl -sI ALB_ENDPOINT/echo | grep "source"

预期输出：

source: alibaba

场景八：基于响应状态码对响应头进行修改

下方示例中的Ingress对响应头进行了修改。当响应的状态码为200或300时，从响应头中移除Content-Type。

创建并将下方示例复制到response-code.yaml，执行kubectl apply -f response-code.yaml创建Ingress。

重要

创建响应方向的转发规则时，需要将注解项 alb.ingress.kubernetes.io/rule-direction.<service-name> 配置为Response（该注解项默认配置为Request）。
单独配置响应方向的转发规则无法完成请求方向的转发，下方示例中同时配置了一个请求方向的Ingress。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    alb.ingress.kubernetes.io/rule-direction.echoserver: Response # 响应方向的转发规则需配合response-header: Response一起使用
    alb.ingress.kubernetes.io/conditions.echoserver: | # 配合响应方向的转发条件一起使用，只有符合转发条件的响应才会被移除响应头。
     [{
       "type": "ResponseStatusCode",
       "responseStatusCodeConfig": {
         "values": [
             "200",
             "300"
         ]
       }
     }]
    alb.ingress.kubernetes.io/actions.echoserver: | # 移除自定义响应头
     [{
         "type": "RemoveHeader",
         "RemoveHeaderConfig": {
             "key": "Content-Type"
         }
     }]
  name: response-code-ingress
spec:
  ingressClassName: alb
  rules:
  - http:
      paths:
      - path: /echo
        pathType: ImplementationSpecific
        backend:
          service:
            name: echoserver
            port:
              name: use-annotation # 必须配置为use-annotation。
              
---
# 请求方向的Ingress
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: request-ingress
spec:
  ingressClassName: alb
  rules:
  - http:
      paths:
      - path: /echo
        pathType: ImplementationSpecific
        backend:
          service:
            name: echoserver
            port:
              number: 80

效果验证

将下方命令中的ALB_ENDPOINT替换为ALB实例端点后执行：

curl -sI ALB_ENDPOINT/echo

预期输出：

HTTP/1.1 200 OK
Date: Thu, 29 Jan 2026 09:46:20 GMT
Connection: keep-alive
Vary: Accept-Encoding
# Content-Type: text/plain header被移除

转发动作配置说明

请求方向

转发动作	描述
固定响应	向客户端返回固定内容的响应。 `alb.ingress.kubernetes.io/actions.service-name: \| # service-name必须与spec.rules中配置的后端Service名称对应一致。 [{ "type": "FixedResponse", "FixedResponseConfig": { "contentType": "text/plain", "httpCode": "503", "content": "503 error text" } }]` `type`：转发动作类型，`FixedResponse`表示配置固定响应。 `contentType`：响应正文类型。 `httpCode`：响应状态码，仅支持`2XX`、`4XX`、`5XX`数字型字符串。 `content`：响应正文。重要 `backend.service.port.name`必须设置为`use-annotation`。固定响应的场景示例，请参见场景一：设置固定响应503状态码和内容。
重定向	通过HTTP 3xx状态码重定向到其他地址访问服务。 `alb.ingress.kubernetes.io/actions.service-name: \| # service-name必须与spec.rules中配置的后端Service名称对应一致。 [{ "type": "Redirect", "RedirectConfig": { "host": "${host}", "path": "/test", "port": "443", "protocol": "https", "query": "querystring", "httpCode": "301" } }]` `type`：转发动作类型，`Redirect`表示配置重定向。 `host`：跳转的域名。 `path`：跳转的路径。 `port`：跳转的端口。 `protocol`：跳转的协议。 `query`：跳转的查询字符串。 `httpCode`：跳转后的状态码，取值：`301`、`302`、`303`、`307`或`308`。重要 `host`、`path`、`port`、`protocol`、`query`是特殊参数，可配置为使用原请求中的默认值，但需至少有一项配置为非默认值。以`host`为例，设置为`${host}`、空置（`"host": ""`）、不填写此项时，都表明使用原请求中的值。 `backend.service.port.name`必须设置为`use-annotation`。重定向的场景示例，请参见场景二：使用301重定向到HTTPS端口
流量镜像	设置流量镜像转发服务器组ID，将复制请求转发至流量镜像服务器组。 `alb.ingress.kubernetes.io/actions.service-name: \| # service-name必须与spec.rules中配置的后端Service名称对应一致。 [{ "type": "TrafficMirror", "TrafficMirrorConfig": { "TargetType" : "ForwardGroupMirror", "MirrorGroupConfig": { "ServerGroupTuples" : [{ "ServerGroupID": "sgp-2auud2fxj1r46*****" }] } } }]` `type`：转发动作类型，`TrafficMirror`表示配置流量镜像功能。 `TargetType`：镜像的目标类型，当前只支持ForwardGroupMirror类型，即镜像请求至服务器组。 `ServerGroupID`：流量镜像服务器组ID。重要流量镜像转发动作只能和转发、写入请求头、删除请求头、流量限速共存，不能和重写、固定响应、重定向共存。流量镜像服务器组只支持通过`ServerGroupID`挂载。流量镜像的场景示例，请参见场景四：流量镜像至服务器组。
转发至后端多服务器组	在ALB后端挂载多个服务器组，通过设置各服务器组间的权重来控制流量分发比例。支持通过`ServerGroupID`指定后端挂载的服务器组，或通过`ServiceName+ServicePort`创建并挂载服务器组。 alb.ingress.kubernetes.io/actions.service-name: \| # service-name必须与spec.rules中配置的后端Service名称对应一致。 [{ "type": "ForwardGroup", "ForwardConfig": { "ServerGroups" : [{ "ServiceName": "tea-svc", "Weight": 30, "ServicePort": 80 }, { "ServiceName": "coffee-svc", "Weight": 20, "ServicePort": 80 }, { "ServerGroupID": "sgp-71aexb9y93ypo***", "Weight": 20 }, { "ServerGroupID": "sgp-slygpbvm2cydo***", "Weight": 30 }], "ServerGroupStickySession": { "Enabled": true, "Timeout": 80 } } }] `type`：转发动作类型，`ForwardGroup`表示配置转发至后端多服务器组。 `ForwardConfig`：后端转发服务器组具体参数。如果设置了多个服务器组，请求按照权重转发至各服务器组。 `ServerGroupID`：服务器组ID。 `ServiceName`：服务的名称。 `ServicePort`：服务的端口。 `Weight`：请求转发至各服务器组权重，取值范围：[1, 100]。 `Enabled`：是否开启服务器组间会话保持。 `Timeout`：服务器组间会话保持超时时间，单位：秒。取值范围：[1, 86400]。重要标准版ALB实例最多挂载5个服务器组或Service。如果同时通过`ServerGroupID`与`ServiceName+ServicePort`挂载服务器组，`ServerGroupID`优先级更高。开启服务器组间会话保持后，ALB Ingress会将属于同一会话的请求转发到同一后端。 `backend.service.port.name`必须设置为`use-annotation`。支持开启服务器组间会话保持功能（需确保所有添加的服务器组开启了会话保持功能）。转发至多服务器组的场景示例，请参见场景五：挂载多个后端服务。
重写	在接到客户端请求后，修改请求的域名、路径和查询字符串等配置后再转发到后端Service。 `alb.ingress.kubernetes.io/actions.service-name: \| # service-name必须与spec.rules中配置的后端Service名称对应一致。 [{ "type": "Rewrite", "RewriteConfig": { "host": "demo.domain.ingress.top", "path": "/test", "query": "querystring" } }]` `type`：转发动作类型，设置为`Rewrite`使用重写。 `host`：重写后请求使用的域名。 `path`：重写后请求使用的路径。 `query`：重写后请求的查询字符串。重要重写转发动作与注解项`rewrite-target`冲突，不可以重复。重写目前不可与固定响应和重定向转发动作共用。 `host`、`path`、`query`是特殊参数，可配置为使用原请求中的默认值，但需至少有一项配置为非默认值。以`host`为例，设置为`${host}`、空置（`"host": ""`）、不填写此项时，都表明使用原请求中的值。重写的场景示例，请参见场景六：重写请求配置信息。
插入请求头	设置头字段名称和头字段内容，覆盖请求中的配置。 `alb.ingress.kubernetes.io/actions.service-name: \| # service-name必须与spec.rules中配置的后端Service名称对应一致。 [{ "type": "InsertHeader", "InsertHeaderConfig": { "key": "key", "value": "value", "valueType": "UserDefined" } }]` `type`：转发动作类型，`InsertHeader`表示配置插入请求头。 `key`：插入的头字段名称。 `value`：插入的头字段内容。 `valueType`：头字段内容类型。插入请求头的场景示例，请参见场景三：插入自定义请求头。
删除请求头	删除请求头内容。 `alb.ingress.kubernetes.io/actions.service-name: \| # service-name必须与spec.rules中配置的后端Service名称对应一致。 [{ "type": "RemoveHeader", "RemoveHeaderConfig": { "key": "key" } }]` `type`：转发动作类型，设置为`RemoveHeader`，表示配置删除请求头。 `key`：去除的头字段名称。
QPS限速	配置总请求速率限制和基于客户端源IP的请求速率限制。 `annotations: alb.ingress.kubernetes.io/actions.service-name: \| # service-name必须与spec.rules中配置的后端Service名称对应一致。 [{ "type": "TrafficLimit", "TrafficLimitConfig": { "QPS": "1000", "QPSPerIp": "100" } }]` `type`：转发动作的类型，`TrafficLimit`表示QPS限速配置。 `QPS`：总体请求速率限制，即每秒可以处理的请求次数，取值范围是[1,1000000]。当请求速率超出设置的规格后，超出部分的新建连接请求将被拒绝，并且客户端将收到HTTP状态码503。 `QPSPerIp`：表示基于每个客户端源IP的请求速率限制，取值范围是[1,1000000]。当同时设置了`QPS`（总体限速）和`QPSPerIp`（基于客户端源IP的限速）时，后者的值必须小于前者。当请求速率超出了设置的规格后，超出部分的请求将被拒绝，并且客户端将收到HTTP状态码503。重要 QPS限速转发动作需要和转发至服务器组同时使用。当X-Forwarded-For请求标头中包含多个IP地址时，例如X-Forwarded-For: <client-ip-address>, <proxy1>, <proxy2>, …，最左边的地址是真实客户端IP，如果您需要使用基于客户端源IP限速功能，您需要在监听打开查找真实客户端源IP开关，以便ALB从X-Forwarded-For头字段中查找真实客户端源IP。更多信息，请参见XForwardedForConfig。

响应方向

转发动作

描述

插入响应头

设置头字段名称和头字段内容，覆盖响应中的配置。

alb.ingress.kubernetes.io/rule-direction.response-header: Response # 响应方向的转发规则需配合response-header: Response一起使用。
alb.ingress.kubernetes.io/actions.service-name: | # service-name必须与spec.rules中配置的后端Service名称对应一致。
  [{
      "type": "InsertHeader",
      "InsertHeaderConfig": {
          "key": "key",
          "value": "value",
          "valueType": "UserDefined"
      }
  }]

type：转发动作类型，InsertHeader表示配置插入响应头。
key：插入的头字段名称。
value：插入的头字段内容。
valueType：头字段内容类型。

在响应方向修改响应头的场景示例，请参见场景七：基于ResponseHeader对响应头进行修改、场景八：基于响应状态码对响应头进行修改。

删除响应头

删除响应头内容。

alb.ingress.kubernetes.io/rule-direction.response-header: Response # 响应方向的转发规则需配合response-header: Response一起使用。
alb.ingress.kubernetes.io/actions.service-name: | # service-name必须与spec.rules中配置的后端Service名称对应一致。
     [{
         "type": "RemoveHeader",
         "RemoveHeaderConfig": {
             "key": "key"
         }
     }]

type：转发动作类型，设置为RemoveHeader，表示配置删除响应头。

key：去除的头字段名称。

配额与限制

对单个Service的转发规则中，转发条件上限为10个，包含通过spec.rules指定的域名和Path。
在同一条转发规则中，未使用限速时，只能使用重定向、固定响应、转发至多服务器组等其中一种终结类型的转发动作。使用限速时，可使用限速+转发至+固定响应/重定向。
配置重定向、固定响应、转发至多服务器组时，backend.service.port.name必须设置为use-annotation。

常见问题

多个同类型的转发条件会同时生效吗？

不同的路由规则块之间是与（AND）的关系，同一个路由规则块中的值是或（OR）的关系。以Header类型的转发条件为例：

两个不同的Header规则块之间是与的关系，请求头需同时匹配headervalue1与headervalue2才会被转发。

alb.ingress.kubernetes.io/conditions.service-name: |
  [{
    "type": "Header",
    "headerConfig": {
      "key": "headername",
      "values": [
        "headervalue1"
      ]
     }
  },
  {
    "type": "Header",
    "headerConfig": {
      "key": "headername",
      "values": [
        "headervalue2"
      ]
     }
  }]

同一个Header规则块中设置的值是或的关系，请求头只需匹配headervalue1或headervalue2其中之一。

alb.ingress.kubernetes.io/conditions.service-name: |
  [{
    "type": "Header",
    "headerConfig": {
      "key": "headername",
      "values": [
        "headervalue1",
        "headervalue2"
      ]
     }
  }]

为什么会提示`The param of Rules.1.RuleConditions.2.HostConfig.Values.2 is duplicated`？

如果在转发条件中配置了Host条件，同时在spec.rules的host中指定了相同的域名时，会导致Ingress配置失败，请选择其中之一配置域名。

工作原理

准备工作

安装组件

创建示例服务

配置转发条件

场景一：基于SourceIp和请求头的转发

效果验证

场景二：基于域名、请求方法和Cookie的转发

效果验证

场景三：基于查询字符串、多个请求头的转发

效果验证

转发条件配置说明

配置转发动作

场景一：设置固定响应503状态码和内容

控制台

kubectl

效果验证

场景二：使用301重定向到HTTPS端口

重定向

效果验证

多Service重定向

效果验证

场景三：插入自定义请求头

效果验证

场景四：流量镜像至服务器组

场景五：挂载多个后端服务

控制台

kubectl

场景六：重写请求配置信息

效果验证

场景七：基于ResponseHeader对响应头进行修改

效果验证

场景八：基于响应状态码对响应头进行修改

效果验证

转发动作配置说明

请求方向

响应方向

配额与限制

常见问题

多个同类型的转发条件会同时生效吗？

为什么会提示The param of Rules.1.RuleConditions.2.HostConfig.Values.2 is duplicated？

为什么会提示`The param of Rules.1.RuleConditions.2.HostConfig.Values.2 is duplicated`？