自定义ALB Ingress的转发规则 - 容器服务 Kubernetes 版 ACK

ALB Ingress支持自定义转发规则。转发规则包含转发条件和转发动作。您可以自定义转发条件，指定请求的域名、路径、请求头、查询字符串、请求方法、Cookie、源IP等。您也可以自定义转发动作，配置固定响应、重定向、插入请求头、删除请求头、流量镜像、转发至后端多服务器组和重写。本文介绍如何自定义ALB Ingress的转发规则。

前提条件

已安装ALB Ingress Controller组件，且组件为v2.5.0及以上版本。具体操作，请参见管理组件。

转发条件

重要

转发规则的条件条目上限为10个，一旦达到规定数量上限，您将无法再添加更多的条件。
转发条件ResponseHeader和ResponseStatusCode仅在自定义响应方向转发规则中有效。

转发条件介绍

ALB Ingress支持在alb.ingress.kubernetes.io/conditions.<Service的名称>注解中配置转发条件。不同的路由规则块是与的关系，同一个路由规则块中的值是或的关系，例如，如果是两个不同的Header规则块，那这两个规则块是与的关系，但是同一个Header规则块中设置的值是或的关系。详细的路由规则说明如下。

转发条件	描述
域名	匹配请求域名，只有正确的域名的请求才能访问服务。示例如下。 `alb.ingress.kubernetes.io/conditions.host-example: \| [{ "type": "Host", "hostConfig": { "values": [ "anno.example.com" ] } }]` type：匹配类型。设置为Host，表示匹配域名。 HostConfig：匹配的具体域名。如果设置了多个域名，则域名之间是或的关系。
路径	匹配请求路径，只有正确的路径的请求才能访问服务。示例如下。 `alb.ingress.kubernetes.io/conditions.path-example: \| [{ "type": "Path", "pathConfig": { "values": [ "/pathvalue1", "/pathvalue2" ] } }]` type：匹配类型。设置为Path，表示匹配请求路径。 pathConfig：匹配的具体路径。如果设置了多个路径，则路径之间是或的关系。
Header	匹配请求Header，只有正确的Header的请求才能访问服务。示例如下。 `alb.ingress.kubernetes.io/conditions.http-header-example: \| [{ "type": "Header", "headerConfig": { "key": "headername", "values": [ "headervalue1" "headervalue2" ] } }]` type：匹配类型。设置为Header，表示匹配请求头中的Header。 headerConfig：Header的键值对。如果设置了多个Header值，则Header之间是或的关系。
查询字符串	匹配查询字符串，只有包含正确的查询字符串的请求才能访问服务。示例如下。 `alb.ingress.kubernetes.io/conditions.query-string-example: \| [{ "type": "QueryString", "queryStringConfig": { "values": [ { "key":"querystringkey1", "value":"querystringvalue2" } ] } }]` type：匹配类型。设置为QueryString，表示匹配请求的查询字符串。 queryStringConfig：查询字符串的键值对。键字符长度取值为[1,100]，值字符长度取值为[1,100]，支持小写字母、可见字符和通配符星号（*）和英文半角问号（?），不支持空格和`#[]{}\\|<>&`。如果设置了多个查询字符串，则查询字符串之间是或的关系。
请求方法	匹配请求方法，只有正确的请求方法的请求才能访问服务。示例如下。 `alb.ingress.kubernetes.io/conditions.http-method-example: \| [{ "type": "Method", "methodConfig": { "values": [ "GET", "HEAD" ] } }]` type：匹配类型。设置为Method，表示匹配请求方法。 methodConfig：具体的请求方法，支持GET、POST、PUT、DELETE、HEAD、OPTIONS和PATCH。如果设置了多个请求方法，则请求方法之间是或的关系。
Cookie	匹配Cookie，只有包含正确的Cookie的请求才能访问服务。示例如下。 `alb.ingress.kubernetes.io/conditions.http-cookie-example: \| [{ "type": "Cookie", "cookieConfig": { "values": [ { "key":"cookiekey1", "value":"cookievalue2" } ] } }]` type：匹配类型。设置为Cookie，表示匹配Cookie。 cookieConfig：Cookie的键值对。键字符长度取值为[1,100]，值字符长度取值为[1,100]，支持小写字母、可见字符和通配符星号（*）和英文半角问号（?），不支持空格和`#[]{}\\|<>&`。如果设置了多个Cookie，则Cookie之间是或的关系。
SourceIP	匹配请求源IP，只有正确的源IP的请求才能访问服务。示例如下。 `alb.ingress.kubernetes.io/conditions.source-ip-example: \| [{ "type": "SourceIp", "sourceIpConfig": { "values": [ "192.168.0.0/16", "172.16.0.0/16" ] } }]` type：匹配类型。设置为SourceIP，表示匹配请求的源IP。 sourceIpConfig：请求的IP地址。如果设置了多个请求IP，则请求IP之间是或的关系。
ResponseHeader	匹配响应Header，只对携带正确Header的响应执行转发动作。示例如下。 `alb.ingress.kubernetes.io/conditions.response-header-example: \| [{ "type": "ReponseHeader", "headerConfig": { "key": "headername", "values": [ "headervalue1" "headervalue2" ] } }]` type：匹配类型。设置为ResponseHeader，表示匹配响应头中的Header。 headerConfig：Header的键值对。如果设置了多个Header值，则Header之间是或的关系。
ResponseStatusCode	匹配响应状态码，只有返回正确的状态码才能访问服务。示例如下。 `alb.ingress.kubernetes.io/conditions.response-code-example: \| [{ "type": "ResponseStatusCode", "responseStatusCodeConfig": { "values": [ "statuscode1", "statuscode2" ] } }]` type：匹配类型。设置为`ResponseStatusCode`，表示匹配响应状态码。 responseStatusCodeConfig：具体的响应状态码。如果设置了多个响应状态码，则响应状态码之间是或的关系。

场景一：基于SourceIP和Header实现流量分发

重要

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

以下代码块定义了仅当请求的IP、Header和路径符合配置时，才能实现目标流量分发。

即当请求源IP为192.168.0.0/16或172.16.0.0/16中的IP地址，请求Header中包含gray-hello，值必须为value1或value2，请求路径为/hello，请求才能路由到gray-hello服务，否则将路由到其他服务。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
   alb.ingress.kubernetes.io/order: "1"
   alb.ingress.kubernetes.io/conditions.gray-hello: |
     [{
       "type": "Header",
       "headerConfig": {
          "key":"gray-hello",
           "values": [
              "value1",
              "value2"
           ]
       }
      },
      {
         "type": "SourceIp",
         "sourceIpConfig": {
           "values": [
             "192.168.0.0/16",
             "172.16.0.0/16"
           ]
         }
     }]
  name: gray-hello
spec:
  ingressClassName: alb
  rules:
   - http:
      paths:
      - path: /hello
        pathType: ImplementationSpecific
        backend:
          service:
            name: gray-hello
            port:
              number: 88

alb.ingress.kubernetes.io/order：标识Ingress的优先级，数字越小，优先级越高。

场景二：基于域名、请求方法、Cookie实现流量分发

以下代码块定义了仅当请求的域名、请求方法和Cookie符合配置时，才能实现目标流量分发。

即当请求方法为GET或HEAD，请求域名为www.hostvalue1.edu或www.hostvalue2.edu，请求Cookie的键为cookiekey1，值为cookievalue1，请求路径为/test，请求才能路由到service-a服务，否则将路由到service-b服务。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
   alb.ingress.kubernetes.io/conditions.service-a: |
     [{
       "type": "Cookie",
       "cookieConfig": {
         "values": [
           {
             "key":"cookiekey1",
             "value":"cookievalue1"
           }
        ]
       }
      },
      {
       "type": "Method",
       "methodConfig": {
         "values": [
           "GET",
           "HEAD"
         ]
       }
      },
     {
       "type": "Host",
       "hostConfig": {
           "values": [
              "www.hostvalue1.edu",
              "www.hostvalue2.edu"
           ]
       }
      }]
  name: ingress-example
spec:
  ingressClassName: alb
  rules:
   - http:
      paths:
      - path: /test
        pathType: ImplementationSpecific
        backend:
          service:
            name: service-a
            port:
              number: 88
      - path: /test
        pathType: ImplementationSpecific
        backend:
          service:
            name: service-b
            port:
              number: 88

场景三：基于查询字符串、多个Header、多个路径实现流量分发

以下代码块定义了仅当请求的查询字符串、Header、路径符合配置时，才能实现目标流量分发。

即当请求路径是/pathvalue1、/pathvalue2或/test，查询字符串的键为querystringkey1，值为querystringvalue2，请求Header中必须包含headerkey1和headerkey2，请求Header中包含headerkey1，值必须为headervalue1或headervalue2，请求Header包含headerkey2，值必须为headervalue3或headervalue4，才能路由到service-a服务，否则将路由到service-b服务。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
   alb.ingress.kubernetes.io/conditions.service-a: |
     [{
       "type": "Path",
       "pathConfig": {
           "values": [
              "/pathvalue1",
              "/pathvalue2"
           ]
       }
      },
      {
       "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: ingress-example
spec:
  ingressClassName: alb
  rules:
   - http:
      paths:
      - path: /test
        pathType: ImplementationSpecific
        backend:
          service:
            name: service-a
            port:
              number: 88
      - path: /test
        pathType: ImplementationSpecific
        backend:
          service:
            name: service-b
            port:
              number: 88

转发动作

转发动作介绍

ALB Ingress支持使用alb.ingress.kubernetes.io/actions.<服务名称>注解配置请求方向和响应方向的转发动作。支持固定响应、重定向、插入请求头、删除请求头、流量镜像、转发至后端多服务器组和重写。通过定义这些转发动作，您可以在ALB Ingress中灵活地管理请求和响应的转发规则。

重要

alb.ingress.kubernetes.io/actions.<服务名称>注解中的服务名称必须和rule字段backend下的服务名称一致。
在同一条转发规则中，重定向、固定响应、转发至多服务器组等终结类型的转发动作不能同时使用。

配置重定向、固定响应、转发至多服务器组时，rule字段backend下的servicePort的名称必须为use-annotation。

请求方向的转发动作

转发动作	描述
固定响应	设置通过ALB给客户端返回固定响应内容，可以设置响应状态码，正文内容和正文类型。示例如下。 `alb.ingress.kubernetes.io/actions.response-503: \| [{ "type": "FixedResponse", "FixedResponseConfig": { "contentType": "text/plain", "httpCode": "503", "content": "503 error text" } }]` type：转发动作类型，设置为FixedResponse，表示配置固定响应。 contentType：响应正文类型。 httpCode：响应状态码。 content：响应正文。
重定向	通过HTTP 3xx状态码，指导客户端跳转到其他地址访问服务。示例如下。重要除了httpCode，重定向的其他参数不能都设置为默认值。 `alb.ingress.kubernetes.io/actions.redirect: \| [{ "type": "Redirect", "RedirectConfig": { "host": "${host}", "path": "${path}", "port": "${port}", "protocol": "${protocol}", "query": "${query}", "httpCode": "301" } }]` type：转发动作类型，设置为Redirect，表示配置重定向。 host：跳转的域名 path：跳转的路径。 port：跳转的端口 protocol：跳转的协议 query：跳转的查询字符串。 httpCode：状态码。
流量镜像	设置流量镜像转发服务器组ID，将复制请求转发至流量镜像服务器组。示例如下。重要流量镜像转发动作只能和转发、写入Header、删除Header、流量限速共存，不能和重写、固定响应、重定向共存。流量镜像服务器组只支持通过ServerGroupID挂载。 `alb.ingress.kubernetes.io/actions.traffic-mirror: \| [{ "type": "TrafficMirror", "TrafficMirrorConfig": { "TargetType" : "ForwardGroupMirror", "MirrorGroupConfig": { "ServerGroupTuples" : [{ "ServerGroupID": "sgp-2auud2fxj1r46*****" }] } } }]` type：转发动作类型，设置为TrafficMirror，表示配置流量镜像功能。 TargetType：镜像的目标类型，当前只支持ForwardGroupMirror类型，即镜像请求至服务器组。 ServerGroupID：流量镜像服务器组ID。
转发至后端多服务器组	设置将ALB请求转发至后端多个服务器组，可以通过ServerGroupID指定后端挂载的服务器组，也可以通过ServiceName+ServicePort创建或挂载服务器组。可以设置请求转发至各后端服务器组的权重。示例如下。重要标准版ALB实例最多挂载5个服务器组。如果同时通过ServerGroupID与ServiceName+ServicePort挂载服务器组，优先根据ServerGroupID匹配后端服务器组。 `alb.ingress.kubernetes.io/actions.forward: \| [{ "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 }] } }]` type：转发动作类型，设置为ForwardGroup，表示配置转发至后端多服务器组。 ForwardConfig：后端转发服务器组具体参数。如果设置了多个服务器组，请求按照权重转发至各服务器组。 ServerGroupID：服务器组ID。 ServiceName：服务的名称。 ServicePort：服务的端口。 Weight：请求转发至各服务器组权重。
重写	设置ALB支持重写，将覆盖请求的域名、路径和字符串。示例如下。重要重写转发动作与注解项`rewrite-target`冲突，不可以重复。重写目前不可与固定响应和重定向转发动作共用。 `alb.ingress.kubernetes.io/actions.rewrite: \| [{ "type": "Rewrite", "RewriteConfig": { "Host": "demo.domain.ingress.top", "Path": "/test", "Query": "querystring" } }]` type：转发动作类型，设置为Rewrite时，表示当前ALB支持Rewrite重写。 RewriteConfig：重写的具体参数。 Host：重写匹配的具体域名。 Path：重写匹配的具体路径。 Query：重写匹配的具体字符串。更多Rewrite重写规则，请参见支持Rewrite重写。
插入请求头	设置头字段名称和头字段内容，将覆盖请求中已有的头变量。示例如下。 `alb.ingress.kubernetes.io/actions.insert-header: \| [{ "type": "InsertHeader", "InsertHeaderConfig": { "key": "key", "value": "value", "valueType": "UserDefined" } }]` type：转发动作类型，设置为InsertHeader，表示配置插入请求头。 key：请求头的字段名称。 value：请求头的字段内容。 valueType：值类型。
删除请求头	删除头字段名称和头字段内容。示例如下。 `alb.ingress.kubernetes.io/actions.remove-header: \| [{ "type": "RemoveHeader", "RemoveHeaderConfig": { "key": "key" } }]` `type`：转发动作类型，设置为`RemoveHeader`，表示配置删除请求头。 `key`：请求头的字段名称。

响应方向的转发动作

转发动作

描述

插入请求头

设置头字段名称和头字段内容，将覆盖请求中已有的头变量。示例如下。

alb.ingress.kubernetes.io/actions.insert-header: |
  [{
      "type": "InsertHeader",
      "InsertHeaderConfig": {
          "key": "key",
          "value": "value",
          "valueType": "UserDefined"
      }
  }]

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

删除请求头

删除头字段名称和头字段内容。示例如下。

alb.ingress.kubernetes.io/actions.remove-header: |
     [{
         "type": "RemoveHeader",
         "RemoveHeaderConfig": {
             "key": "key"
         }
     }]

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

key：请求头的字段名称。

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

以下代码块定义了请求服务时，将返回503状态码和503 error text。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  namespace: default
  name: ingress
  annotations:
    alb.ingress.kubernetes.io/actions.response-503: |
      [{
          "type": "FixedResponse",
          "FixedResponseConfig": {
              "contentType": "text/plain",
              "httpCode": "503",
              "content": "503 error text"
          }
      }]
spec:
  ingressClassName: alb
  rules:
    - http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: response-503
                port:
                  name: use-annotation

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

以下代码块定义了请求服务时，将重定向到服务的HTTPS端口。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  namespace: default
  name: ingress
  annotations:
    alb.ingress.kubernetes.io/actions.redirect: |
      [{
          "type": "Redirect",
          "RedirectConfig": {
              "host": "${host}",
              "path": "${path}",
              "port": "${port}",
              "protocol": "https",
              "query": "${query}",
              "httpCode": "301"
          }
      }]
spec:
  ingressClassName: alb
  rules:
    - http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: redirect
                port:
                  name: use-annotation

场景三：插入source: alibaba请求头

以下代码块定义了请求服务时，将使用source: alibaba覆盖原有请求头。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  namespace: default
  name: ingress
  annotations:
    alb.ingress.kubernetes.io/actions.insert-header: |
      [{
          "type": "InsertHeader",
          "InsertHeaderConfig": {
              "key": "source",
              "value": "alibaba",
              "valueType": "UserDefined"
          }
      }]
spec:
  ingressClassName: alb
  rules:
    - http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: insert-header
                port:
                  number: 80

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

以下代码块定义了请求服务时，将复制请求至流量镜像服务器组。

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

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: traffic-mirror-ingress
  annotations:
   alb.ingress.kubernetes.io/actions.traffic-mirror: |
       [{
           "type": "TrafficMirror",
           "TrafficMirrorConfig": {
              "TargetType" : "ForwardGroupMirror",
              "MirrorGroupConfig": {
                  "ServerGroupTuples" : [{
                      "ServerGroupID": "sgp-2auud2fxj1r46*****"
                  }]
              }
           }
       }]
spec:
  ingressClassName: alb
  rules:
   - host: demo.domain.ingress.top
     http:
      paths:
      - path: /test
        pathType: Prefix
        backend:
          service:
            name: traffic-mirror
            port:
              number: 80

场景五：请求转发至多个后端服务器组

以下代码块定义了请求服务时，将请求转发至集群内多个服务。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: forward-ingress
  annotations:
    alb.ingress.kubernetes.io/actions.forward: |
       [{
           "type": "ForwardGroup",
           "ForwardConfig": {
             "ServerGroups" : [{
               "ServiceName": "tea-svc",
               "Weight": 80,
               "ServicePort": 80
             },
             {
               "ServiceName": "coffee-svc",
               "Weight": 20,
               "ServicePort": 80
             }]
           }
       }]
spec:
  ingressClassName: alb
  rules:
   - host: demo.domain.ingress.top
     http:
      paths:
      - path: /path
        pathType: Prefix
        backend:
          service:
            name: forward
            port:
              name: use-annotation

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

以下代码块定义了请求服务时，重写请求的域名、路径和字符串。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  namespace: default
  name: rewrite-ingress
  annotations:
    alb.ingress.kubernetes.io/actions.rewrite: |
       [{
           "type": "Rewrite",
           "RewriteConfig": {
               "Host": "demo.domain.ingress.top",
               "Path": "/test",
               "Query": "queryString"
           }
       }]
spec:
  ingressClassName: alb
  rules:
    - http:
        paths:
          - path: /path
            pathType: Prefix
            backend:
              service:
                name: rewrite
                port:
                  port: 80

场景七：基于ResponseHeader对响应方向的请求头进行修改

重要

自定义的ALB ingress转发规则在默认情况下为请求方向，如果您希望创建响应方向的转发规则，则需要将注解项 alb.ingress.kubernetes.io/rule-direction.<Service的名称> 配置为Response（该注解项默认配置为Request）。
当创建响应方向的转发规则时，ingressSpec.rules.backend字段下的servicePort的名称必须为use-annotation。

以下代码块定义了当匹配到ResponseHeader时，即Header中包含response-hello，值必须为value1或value2，那么将在Header中插入新的请求头source: alibaba。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
   alb.ingress.kubernetes.io/rule-direction.response-header: Response
   alb.ingress.kubernetes.io/conditions.response-header: |
     [{
         "type": "ResponseHeader",
         "responseHeaderConfig": {
            "key": "response-hello",
            "values": [
               "value1",
               "value2"
            ]
         }
     }]
   alb.ingress.kubernetes.io/actions.response-header: |
     [{
         "type": "InsertHeader",
         "InsertHeaderConfig": {
             "key": "source",
             "value": "alibaba",
             "valueType": "UserDefined"
         }
     }]
  name: response-header
spec:
  ingressClassName: alb
  rules:
   - http:
      paths:
      - path: /
        pathType: ImplementationSpecific
        backend:
          service:
            name: response-header
            port:
              name: use-annotation

场景八：基于响应状态码对响应方向的请求头进行修改

重要

自定义的ALB ingress转发规则在默认情况为请求方向，如果您希望创建响应方向的转发规则，则需要将注解项 alb.ingress.kubernetes.io/rule-direction.<Service的名称> 配置为Response（该注解项默认配置为Request）。
当创建响应方向的转发规则时，ingressSpec.rules.backend字段下的servicePort的名称必须为use-annotation。

以下代码块定义了仅当响应状态码为200或300时，才会对请求头执行移除操作（将response-hello从请求Header中移除）。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
   alb.ingress.kubernetes.io/rule-direction.response-hello: Response
   alb.ingress.kubernetes.io/conditions.response-hello: |
     [{
       "type": "ResponseStatusCode",
       "responseStatusCodeConfig": {
         "values": [
             "200",
             "300"
         ]
       }
     }]
   alb.ingress.kubernetes.io/actions.response-hello: |
     [{
         "type": "RemoveHeader",
         "RemoveHeaderConfig": {
             "key": "response-hello"
         }
     }]
  name: response-hello
spec:
  ingressClassName: alb
  rules:
   - http:
      paths:
      - path: /*
        pathType: ImplementationSpecific
        backend:
          service:
            name: response-hello
            port:
              name: use-annotation