自訂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 Gateway，叢集中的所有資源均可訪問公網。
為節點分配固定公網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狀態代碼和內容

控制台

登入Container Service管理主控台，在左側導覽列選擇叢集列表。
在叢集列表頁面，單擊目的地組群名稱，然後在左側導覽列，選擇網路 > 路由。

在路由頁面，單擊創建 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資源。

控制台

登入Container Service管理主控台，在左側導覽列選擇叢集列表。
在叢集列表頁面，單擊目的地組群名稱，然後在左側導覽列，選擇網路 > 路由。

在路由頁面，單擊創建 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`？