Customize the routing rules of an ALB Ingress in the ACK console or by configuring annotations - Container Service for Kubernetes

Application Load Balancer (ALB) Ingresses allow you to configure custom routing rules. A routing rule consists of routing conditions and actions. You can add routing conditions to match domain names, paths, request headers, query strings, request methods, cookies, or source IP addresses in requests. You can also add routing actions to return fixed responses, redirect requests, insert request headers, delete request headers, mirror traffic, forward requests to multiple backend server groups, or rewrite requests. You can customize the routing rules of an ALB Ingress in the Container Service for Kubernetes (ACK) console or by configuring the Annotations parameter in the Ingress.

Custom rule	Scenario
Routing condition	Scenario 1: Route traffic based on source IP addresses and request headers Scenario 2: Route traffic based on domain names, request methods, and cookies Scenario 3: Route traffic based on query strings, multiple request headers, and multiple paths
Routing action	Scenario 1: Return status code 503 and fixed content Scenario 2: Use 301 redirect to redirect requests to an HTTPS port Scenario 3: Insert the source: alibaba header to requests Scenario 4: Mirror traffic to a server group Scenario 5: Forward requests to multiple backend server groups Scenario 6: Rewrite requests Scenario 7: Modify the response header based on ResponseHeader Scenario 8: Modify the response header based on the response status code
Practices for configuring routing conditions and actions	Scenario 1: Configure domain name-based routing conditions and actions to route traffic to a specific Service

Prerequisites

ALB Ingress controller 2.5.0 or later is installed in your cluster. For more information, see Manage components.

Routing conditions

Important

You can add at most 10 routing conditions to one routing rule.
Routing conditions ResponseHeader and ResponseStatusCode take effect only in custom outbound routing rules.

Introduction to routing conditions

ALB Ingresses allow you to configure routing conditions in the alb.ingress.kubernetes.io/conditions.<Service name> annotation. The logical relationship among different rule blocks is AND. If multiple values are specified in a rule block, the logical relationship among the values is OR. For example, if you configure two header rule blocks, the logical relationship between the two header rule blocks is AND. If you configure multiple headers in a header rule block, the logical relationship among the headers is OR. The following table describes the routing rules that you can create for an ALB Ingress.

Routing condition	Description
Domain name	You can add this condition to route only requests that are destined for the specified domain names. Sample code: `alb.ingress.kubernetes.io/conditions.host-example: \| [{ "type": "Host", "hostConfig": { "values": [ "anno.example.com" ] } }]` type: the type of routing condition. To match requests based on domain names, set the value to Host. HostConfig: the domain names that are used to match requests. If you specify multiple domain names, the logical relationship among the domain names is OR.
Path	You can add this condition to route only requests that are sent to the specified paths. Sample code: `alb.ingress.kubernetes.io/conditions.path-example: \| [{ "type": "Path", "pathConfig": { "values": [ "/pathvalue1", "/pathvalue2" ] } }]` type: the type of routing condition. To match requests based on paths, set the value to Path. pathConfig: the paths that are used to match requests. If you specify multiple paths, the logical relationship among the paths is OR.
Header	You can add this condition to route only requests that contain the specified headers. Sample code: `alb.ingress.kubernetes.io/conditions.http-header-example: \| [{ "type": "Header", "headerConfig": { "key": "headername", "values": [ "headervalue1", "headervalue2" ] } }]` type: the type of routing condition. To match requests based on headers, set the value to Header. headerConfig: the key-value pairs that are used to match requests. The logical relationship between multiple headers is OR.
Query string	You can add this condition to route only requests that contain the specified query strings. Sample code: `alb.ingress.kubernetes.io/conditions.query-string-example: \| [{ "type": "QueryString", "queryStringConfig": { "values": [ { "key":"querystringkey1", "value":"querystringvalue2" } ] } }]` type: the type of routing condition. To match requests based on query strings, set the value to QueryString. queryStringConfig: the key-value pairs that are used to match requests. The keys and values must be 1 to 100 characters in length, and can contain lowercase letters, visible characters, asterisks (*), and question marks (?). The keys and values cannot contain space characters or the following special characters: `# [] {} \ \| <> &`. If you specify multiple query strings, the logical relationship among the query strings is OR.
Request method	You can add this condition to route only requests that use the specified request methods. Sample code: `alb.ingress.kubernetes.io/conditions.http-method-example: \| [{ "type": "Method", "methodConfig": { "values": [ "GET", "HEAD" ] } }]` type: the type of routing condition. To match requests based on request methods, set the value to Method. methodConfig: the request methods that are used to match requests. Supported methods are GET, POST, PUT, DELETE, HEAD, OPTIONS, and PATCH. If you specify multiple request methods, the logical relationship among the request methods is OR.
Cookie	You can add this condition to route only requests that contain the specified cookies. Sample code: `alb.ingress.kubernetes.io/conditions.http-cookie-example: \| [{ "type": "Cookie", "cookieConfig": { "values": [ { "key":"cookiekey1", "value":"cookievalue2" } ] } }]` type: the type of routing condition. To match requests based on cookies, set the value to Cookie. cookieConfig: the key-value pairs that are used to match requests. The keys and values must be 1 to 100 characters in length, and can contain lowercase letters, visible characters, asterisks (*), and question marks (?). The keys and values cannot contain space characters or the following special characters: `# [] {} \ \| <> &`. If you specify multiple cookies, the logical relationship among the cookies is OR.
SourceIP	You can add this condition to route only requests from the specified source IP addresses. Sample code: `alb.ingress.kubernetes.io/conditions.source-ip-example: \| [{ "type": "SourceIp", "sourceIpConfig": { "values": [ "192.168.0.0/16", "172.16.0.0/16" ] } }]` type: the type of routing condition. To match requests based on source IP addresses, set the value to SourceIP. sourceIpConfig: the source IP addresses that are used to match requests. If you specify multiple source IP addresses, the logical relationship among the source IP addresses is OR.
ResponseHeader	You can add this condition to route only responses that contain the specified response headers. Sample code: `alb.ingress.kubernetes.io/conditions.response-header-example: \| [{ "type": "ResponseHeader", "headerConfig": { "key": "headername", "values": [ "headervalue1", "headervalue2" ] } }]` type: the type of routing condition. To match responses based on response headers, set the value to ResponseHeader. headerConfig: the key-value pairs that are used to match responses. The logical relationship between multiple headers is OR.
ResponseStatusCode	You can add this condition to route only requests that return the specified status codes. Sample code: `alb.ingress.kubernetes.io/conditions.response-code-example: \| [{ "type": "ResponseStatusCode", "responseStatusCodeConfig": { "values": [ "statuscode1", "statuscode2" ] } }]` type: the type of routing condition. To match requests based on response status codes, set the value to `ResponseStatusCode`. responseStatusCodeConfig: the specified response status code. If you specify multiple response status codes, the logical relationship among the codes is OR.

Scenario 1: Route traffic based on source IP addresses and request headers

Important

You can add at most five source IP addresses to the custom conditions for one routing rule.

The following code block is used to route packets based on source IP addresses, request headers, and paths.

In the following code block, the source IP addresses are set to 192.168.0.0/16 and 172.16.0.0/16, the header key is set to gray-hello, the header values are set to value1 and value2, and the path is set to /hello. Only requests whose source IP addresses, headers, and paths match all of the preceding conditions are routed to the gray-hello Service. Other requests are routed to other Services.

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: the priority of the Ingress. A smaller value indicates a higher priority.

Scenario 2: Route traffic based on domain names, request methods, and cookies

The following code block is used to route packets based on domain names, request methods, and cookies.

In the following code block, the request methods are set to GET and HEAD, the domain names are set to example.com and *.edu, the key of the cookie is set to cookiekey1, the value of the cookie is set to cookievalue1, and the path is set to /test. Only requests whose domain names, request methods, cookies, and paths match all of the preceding conditions are routed to the gray-hello Service. Other requests are routed to the service-b Service.

Note

Domain name-based forwarding rules support matching wildcard domain names.

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": [
              "example.com",
              "*.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

Scenario 3: Route traffic based on query strings, multiple request headers, and multiple paths

The following code block is used to route packets based on query strings, multiple request headers, and multiple paths.

In the following code block, the paths are set to /pathvalue1, /pathvalue2, and /test, the query string key is set to querystringkey1, and the query string value is set to querystringvalue2. In addition, the code block specifies that the request must contain headerkey1 and headerkey2. The header value for headerkey1 must be headervalue1 or headervalue2, and the header value for headervalue2 must be headervalue3 or headervalue4. Only requests whose query strings, request headers, and paths match all of the preceding conditions are routed to the service-a Service. Other requests are routed to the service-b Service.

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

Routing actions

Introduction to routing actions

ALB Ingresses allow you to configure routing actions for inbound and outbound routing rules in the alb.ingress.kubernetes.io/actions.<Service name> annotation. You can add routing actions to return fixed responses, redirect requests, insert request headers, delete request headers, mirror traffic, forward requests to multiple backend server groups, or rewrite requests. ALB Ingresses allow you to define different routing actions to process requests and responses on demand.

Important

The Service name in the alb.ingress.kubernetes.io/actions.<Service name> annotation must be the same as the Service name specified in backend in the rule field.
In the same routing rule, you cannot add multiple termination actions at the same time. For example, you cannot add routing actions to return fixed responses, redirect requests, or forward requests to multiple backend server groups at the same time.

When you add routing actions to return fixed responses, redirect requests, or forward requests to multiple backend server groups, the name of the Service port specified in backend in the rule field must be use-annotation.

Routing actions for inbound routing rules

Routing action	Description
Return fixed responses	You can configure the ALB Ingress to return fixed content to clients. You can specify the status code, content, and type of content that are returned to clients. Sample code: `alb.ingress.kubernetes.io/actions.response-503: \| [{ "type": "FixedResponse", "FixedResponseConfig": { "contentType": "text/plain", "httpCode": "503", "content": "503 error text" } }]` type: the type of routing action. To return fixed responses, set the value to FixedResponse. contentType: the type of content to be returned. httpCode: the status code to be returned. content: the content to be returned.
Redirect requests	You can use the HTTP 3XX status codes to redirect requests to other Service addresses. Sample code: Important You cannot keep the default settings for all redirect parameters at the same time, excluding httpCode. `alb.ingress.kubernetes.io/actions.redirect: \| [{ "type": "Redirect", "RedirectConfig": { "host": "${host}", "path": "${path}", "port": "443", "protocol": "${protocol}", "query": "${query}", "httpCode": "301" } }]` type: the type of routing action. To redirect requests, set the value to Redirect. host: the domain name to which requests are redirected. path: the path to which requests are redirected. port: the port to which requests are redirected. protocol: the protocol of the redirected requests. query: the query string of the redirected requests. httpCode: the status code of the redirected requests.
Mirror traffic	You can specify the ID of a server group to mirror traffic to the specified server group. Sample code: Important The traffic mirroring action can be used together only with the actions that are used to forward requests, write headers, delete headers, and throttle traffic. This action is mutually exclusive with the actions that are used to rewrite requests, return fixed responses, and redirect requests. You can use only the ServerGroupID parameter to specify the server group to which traffic is mirrored. `alb.ingress.kubernetes.io/actions.traffic-mirror: \| [{ "type": "TrafficMirror", "TrafficMirrorConfig": { "TargetType" : "ForwardGroupMirror", "MirrorGroupConfig": { "ServerGroupTuples" : [{ "ServerGroupID": "sgp-2auud2fxj1r46*****" }] } } }]` type: the type of action. To mirror traffic, set the value to TrafficMirror. TargetType: the type of destination to which traffic is mirrored. Set the value to ForwardGroupMirror to mirror traffic to the specified server group. ServerGroupID: the ID of the server group to which traffic is mirrored.
Forward requests to multiple backend server groups	To forward requests to multiple backend server groups, you need to set the ServerGroupID field to specify server group IDs or set the ServiceName and ServicePort fields to create or associate server groups. You can also specify the weight of each backend server group and enable session persistence for the server groups. Important You can associate at most five backend server groups with a standard ALB instance. If you set the ServerGroupID, ServiceName, and ServicePort fields at the same time to associate backend server groups, the ServerGroupID field takes precedence. After you enable session persistence, the ALB Ingress forwards the requests that belong to the same session to the same backend server group. `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 }] "ServerGroupStickySession": { "Enabled": true, "Timeout": 80 } } }]` type: the type of action. To forward requests to multiple backend server groups, set the value to ForwardGroup. ForwardConfig: the configurations of the backend server groups. Requests are forwarded to multiple server groups based on their weights. ServerGroupId: the ID of the server group. ServiceName: the name of the Service that is exposed by using the ALB instance. ServicePort: the Service port. Weight: the weight of the server group. Enabled: enables session persistence for the server groups. Timeout: the timeout period of session persistence.
Rewrite requests	After you configure a rewrite rule for an ALB instance, the domain names, paths, and query strings of requests are rewritten. Sample code: Important The rewrite action conflicts with the `rewrite-target` annotation. Do not specify the rewrite-target annotation when you configure the rewrite action. You cannot add routing actions to rewrite requests and return fixed responses at the same time. You cannot add routing actions to rewrite requests and redirect requests at the same time. `alb.ingress.kubernetes.io/actions.rewrite: \| [{ "type": "Rewrite", "RewriteConfig": { "Host": "demo.domain.ingress.top", "Path": "/test", "Query": "querystring" } }]` type: the type of action. To rewrite requests, set the value to Rewrite. RewriteConfig: the configurations of the rewrite rule. Host: rewrites the matched domain name. Path: rewrites the matched path. Query: rewrites the matched query string. For more information about rewrite rules, see Configure rewrite rules.
Insert request headers	You can specify the names and values of header fields to overwrite the existing header variables in requests. Sample code: `alb.ingress.kubernetes.io/actions.insert-header: \| [{ "type": "InsertHeader", "InsertHeaderConfig": { "key": "key", "value": "value", "valueType": "UserDefined" } }]` type: the type of routing action. To insert request headers, set the value to InsertHeader. key: the name of the header field to be inserted. value: the value of the header field to be inserted. valueType: the type of value.
Delete request headers	You can delete the keys and values of request headers. Sample code: `alb.ingress.kubernetes.io/actions.remove-header: \| [{ "type": "RemoveHeader", "RemoveHeaderConfig": { "key": "key" } }]` `type`: the type of routing action. To delete request headers, set the value to `RemoveHeader`. `key`: the name of the header field to be deleted.
QPS throttling	When you configure forwarding rules for an ALB instance, you can set the global request rate limit and a request rate limit based on a client IP address. Sample code: Important The queries per second (QPS) throttling action must be used with the action of forwarding requests to server groups. If the X-Forwarded-For header contains multiple IP addresses, such as X-Forwarded-For: <client-ip-address>, <proxy1>, <proxy2>, ..., the leftmost address is the client IP address. If you want to configure a request rate limit based on the client IP address, you need to turn on the switch for retrieving client IP addresses on the listener details page. This way, you can use the X-Forwarded-For header to preserve client IP addresses. For more information, see XForwardedForConfig. `annotations: alb.ingress.kubernetes.io/actions.traffic-limit: \| [{ "type": "TrafficLimit", "TrafficLimitConfig": { "QPS": "1000", "QPSPerIp": "100" } }]` `type`: the type of routing action. In this example, the value is set to `TrafficLimit`, which indicates rate limiting. `QPS`: the global request rate limit, which indicates the maximum number of requests that can be processed per second. Valid values: 1 to 1000000. When the request rate exceeds the specified value, new connection requests are rejected and the client receives an HTTP status code 503. `QPSPerIp`: the request rate limit based on a client IP address. Valid values: 1 to 1000000. If both `QPS` (global rate limit) and `QPSPerIp` (rate limit based on a client IP address) are set, the value of QPSPerIp must be smaller than that of QPS. When the request rate exceeds the specified value, new connection requests are rejected and the client receives an HTTP status code 503.

Routing actions for outbound routing rules

Routing action

Description

Insert request headers

You can specify the names and values of header fields to overwrite the existing header variables in requests. Sample code:

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

type: the type of routing action. To insert request headers, set the value to InsertHeader.
key: the name of the header field to be inserted.
value: the value of the header field to be inserted.
valueType: the type of value.

Delete request headers

You can delete the keys and values of request headers. Sample code:

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

type: the type of routing action. To delete request headers, set the value to RemoveHeader.

key: the name of the header field to be deleted.

Scenario 1: Return status code 503 and fixed content

Use the ACK console

Log on to the ACK console. In the left-side navigation pane, click Clusters.
On the Clusters page, find the cluster that you want to manage and click its name. In the left-side pane, choose Network > Ingresses.

On the Ingresses page, click Create Ingress. In the Create Ingress dialog box, configure the parameters.

Parameter	Description	Example
Gateway Type	You can select ALB, MSE Cloud-native Gateway, or Nginx based on your requirements. For more information about the differences among the three gateway types, see Comparison among NGINX Ingresses, ALB Ingresses, and MSE Ingresses.	ALB
Name	Specify the name of the Ingress.	ingress
Ingress Class	Specify the IngressClass associated with the Ingress.	alb
Rules	Click +Add Rule to add an Ingress rule. Domain Name: Specify a custom domain name. Mappings: Specify the following parameters: Path: Specify the URL path of the backend Service. In this example, the root path / is used. Rule: You can select Prefix (Prefix-based Match), Exact (Exact Match), or ImplementationSpecific (Default Value). Service: Select the backend Service. Port: Specify the Service port that you want to expose. You can configure multiple paths for a domain name. Click + Add to add a path.	Domain Name: Leave this parameter empty. Mappings: Path: /. Rule: Prefix (Prefix-based Match) is selected by default. Service: response-503. Port: 80.
TLS Settings	Specifies whether to enable TLS authentication. You can enable TLS authentication for the Ingress. Domain Name: the custom domain name. Secret: Select the Secret that you want to use. To create a Secret, perform the following steps: Click Create to the right of the Secret field. In the Create Secret dialog box, configure the Name, Cert, and Key parameters. Then, click OK. Select the Secret that you created from the Secret drop-down list. You can click + Add to add more TLS certificates. For more information about Ingress configurations, see Advanced NGINX Ingress configurations.	Turn off TLS Settings. In this example, you do not need to configure a TLS certificate.
More	Canary Release: Enable canary releases. You can configure canary release rules based on request headers, cookies, and weights. Description You can configure canary release rules based on only one of the following elements: request headers, cookies, and weights. You can also configure canary release rules based on request headers, cookies, and weights at the same time. In this case, request headers, cookies, and weights take effect in descending order of precedence. Based on Request Header: Distribute traffic based on request headers by adding the `nginx.ingress.kubernetes.io/canary-by-header`, `nginx.ingress.kubernetes.io/canary-by-header-value`, or `nginx.ingress.kubernetes.io/canary-by-header-pattern` annotation. Based on Cookie: Distribute traffic based on cookies by adding the `nginx.ingress.kubernetes.io/canary-by-cookie` annotation. Based on Weight: Distribute traffic based on Service weights (integers from 0 to 100) by adding the `nginx.ingress.kubernetes.io/canary-weight` annotation. Protocol: Select the protocol used by the backend Service by adding the `nginx.ingress.kubernetes.io/backend-protocol` annotation. HTTP, HTTPS, gRPC, and gRPCS are supported. Rewrite Path: Add the `nginx.ingress.kubernetes.io/rewrite-target` annotation to rewrite the paths in client requests before the requests are forwarded to the backend Service.	Turn off Canary Release. Use the default values of the Protocol and Rewrite Path parameters. In this example, you do not need to configure these parameters.
Custom Forwarding Rules	You can enable custom forwarding rules to manage inbound traffic in a fine-grained manner. Note You can add up to 10 conditions to a forwarding rule. The following condition types are available in the Add Condition drop-down list: Domain Name: Specifies that only requests that contain the specified domain names are routed. The logical relationship between multiple domain names is OR. After you specify the domain names, the system adds the `alb.ingress.kubernetes.io/conditions.host-example` annotation. Path: Specifies that only requests that contain the specified one or more paths are routed. Multiple paths are treated with an OR relationship. After you specify the paths, the system adds the `alb.ingress.kubernetes.io/conditions.path-example` annotation. HTTP Header: Specifies that only requests that contain the specified HTTP headers are routed. Each HTTP request header is a key-value pair. For example, you can set the key to `headername` and the value to `headervalue1`. If you specify multiple header values, the logical relationship among the header values is OR. After you specify the headers, the system adds the `alb.ingress.kubernetes.io/conditions.http-header-example` annotation. The following actions are available in the Action drop-down list: Return Fixed Response Specifies that fixed content is returned to clients by the ALB instance. You can specify the status code, content, and type of content that are returned to clients. Configure the Response Status Code, Response Content Type (Optional), and Response Content (Optional) parameters based on your business requirements. Valid values of the Response Content Type parameter: text/plain: indicates that the content is in plaintext. text/css: indicates that the content is in the XML format. text/html: indicates that the content is in the HTML format. application/javascript: indicates that the content is in the JavaScript format. application/json: indicates that the content is in the JSON format.	In the Add Condition drop-down list, Path is selected by default. In the Action drop-down list, Return Fixed Response is selected. Response Status Code: 503. Response Content Type (Optional): text/plain. Response Content (Optional): error.
Annotations	You can enter custom annotation names and values. You can also select or search for annotations by name from the drop-down list. For more information about Ingress annotations, see ALB Ingress GlobalConfiguration dictionary. Click +Add Annotation to add an annotation. ACK does not limit the number of Ingress annotations that you can add.	In this example, you do not need to configure annotations.
Labels	You can add labels to describe the characteristics of the Ingress. Click +Add Label to add a label. ACK does not limit the number of Ingress labels that you can add.	In this example, you do not need to configure labels.

After the configuration is complete, click OK.

kubectl

The following code block is used to return the status code 503 and 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 # The name of the Service port must be use-annotation.

Scenario 2: Use 301 redirect to redirect requests to an HTTPS port

The following code block is used to redirect requests to an HTTPS port:

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": "443",
              "protocol": "https",
              "query": "${query}",
              "httpCode": "301"
          }
      }]
spec:
  ingressClassName: alb
  rules:
    - http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: redirect
                port:
                  name: use-annotation # The name of the Service port must be use-annotation.

Scenario 3: Insert the source: alibaba header to requests

The following code block is used to overwrite the existing header in requests with the source: alibaba header:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  namespace: default
  name: ingress
  annotations:
  # The Service specified in the annotation must be an existing Service in the cluster, and the Service name must be the same as the Service name specified in the backend parameter of the rule field. 
    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

Scenario 4: Mirror traffic to a server group

The following code block is used to mirror traffic to the specified server group:

Log on to the Server Load Balancer (SLB) console. In the left-side navigation pane, choose ALB > Server Groups. On the Server Groups page, you can view the ID of the server group. 服务器组

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: traffic-mirror-ingress
  annotations:
  # mirror-svc must be one of the backend services specified below.
  # ALB Ingress will mirror the traffic forwarded to mirror-svc to the backend server specified in the ServerGroupID field.
  # If multiple Services need to configure traffic mirroring, add an annotation for each Service.
   alb.ingress.kubernetes.io/actions.mirror-svc: |
       [{
           "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: mirror-svc
            port:
              number: 80

Scenario 5: Forward requests to multiple backend server groups

Use the ACK console

Log on to the ACK console. In the left-side navigation pane, click Clusters.
On the Clusters page, find the cluster that you want to manage and click its name. In the left-side pane, choose Network > Ingresses.

On the Ingresses page, click Create Ingress. In the Create Ingress dialog box, configure the parameters.

Parameter	Description	Example
Gateway Type	You can select ALB, MSE Cloud-native Gateway, or Nginx based on your requirements. For more information about the differences among the three gateway types, see Comparison among NGINX Ingresses, ALB Ingresses, and MSE Ingresses.	ALB
Name	Specify the name of the Ingress.	forward-ingress
Ingress Class	Specify the IngressClass associated with the Ingress.	alb
Rules	Click +Add Rule to add an Ingress rule. Domain Name: Specify a custom domain name. Mappings: Specify the following parameters: Path: Specify the URL path of the backend Service. In this example, the root path / is used. Rule: You can select Prefix (Prefix-based Match), Exact (Exact Match), or ImplementationSpecific (Default Value). Service: Select the backend Service. Port: Specify the Service port that you want to expose. You can configure multiple paths for a domain name. Click + Add to add a path.	Domain Name: demo.domain.ingress.top. Mappings: Path: /path. Rule: Prefix (Prefix-based Match) is selected by default. Service: forward. Port: 80.
TLS Settings	Specifies whether to enable TLS authentication. You can enable TLS authentication for the Ingress. Domain Name: the custom domain name. Secret: Select the Secret that you want to use. To create a Secret, perform the following steps: Click Create to the right of the Secret field. In the Create Secret dialog box, configure the Name, Cert, and Key parameters. Then, click OK. Select the Secret that you created from the Secret drop-down list.	Turn off TLS Settings. In this example, you do not need to configure a TLS certificate.
More	Canary Release: Enable canary releases. You can configure canary release rules based on request headers, cookies, and weights. Description You can configure canary release rules based on only one of the following elements: request headers, cookies, and weights. You can also configure canary release rules based on request headers, cookies, and weights at the same time. In this case, request headers, cookies, and weights take effect in descending order of precedence. Based on Request Header: Distribute traffic based on request headers by adding the `nginx.ingress.kubernetes.io/canary-by-header`, `nginx.ingress.kubernetes.io/canary-by-header-value`, or `nginx.ingress.kubernetes.io/canary-by-header-pattern` annotation. Based on Cookie: Distribute traffic based on cookies by adding the `nginx.ingress.kubernetes.io/canary-by-cookie` annotation. Based on Weight: Distribute traffic based on Service weights (integers from 0 to 100) by adding the `nginx.ingress.kubernetes.io/canary-weight` annotation. Protocol: Select the protocol used by the backend Service by adding the `nginx.ingress.kubernetes.io/backend-protocol` annotation. HTTP, HTTPS, gRPC, and gRPCS are supported. Rewrite Path: Add the `nginx.ingress.kubernetes.io/rewrite-target` annotation to rewrite the paths in client requests before the requests are forwarded to the backend Service.	Turn off Canary Release. Use the default values of the Protocol and Rewrite Path parameters. In this example, you do not need to configure these parameters.
Custom Forwarding Rules	You can enable custom forwarding rules to manage inbound traffic in a fine-grained manner. Note You can add up to 10 conditions to a forwarding rule. The following condition types are available in the Add Condition drop-down list: Domain Name: Specifies that only requests that contain the specified domain names are routed. The logical relationship between multiple domain names is OR. After you specify the domain names, the system adds the `alb.ingress.kubernetes.io/conditions.host-example` annotation. Path: Specifies that only requests that contain the specified one or more paths are routed. Multiple paths are treated with an OR relationship. After you specify the paths, the system adds the `alb.ingress.kubernetes.io/conditions.path-example` annotation. HTTP Header: Specifies that only requests that contain the specified HTTP headers are routed. Each HTTP request header is a key-value pair. For example, you can set the key to `headername` and the value to `headervalue1`. If you specify multiple header values, the logical relationship among the header values is OR. After you specify the headers, the system adds the `alb.ingress.kubernetes.io/conditions.http-header-example` annotation. The following actions are available in the Action drop-down list: Forward To Forwards the inbound traffic to multiple backend server groups. Select the Service that you want to access from the Service Name drop-down list. Select the port used to connect to the Service from the Port drop-down list. Specify a custom weight for each backend server group. Note If the cluster uses the Flannel component, the ClusterIP Service is not supported. If you select Forward To from the Action drop-down list, you do not need to configure the Mappings parameter for the rule.	In the Add Condition drop-down list, Domain Name is selected. Domain Name: demo.domain.ingress.top In the Action drop-down list, Forward To is selected. Service: tea-svc. Port: 80. Weight: 80. Add a Service Service: coffee-svc. Port: 80. Weight: 20.
Annotations	You can enter custom annotation names and values. You can also select or search for annotations by name from the drop-down list. For more information about Ingress annotations, see ALB Ingress GlobalConfiguration dictionary. Click +Add Annotation to add an annotation. ACK does not limit the number of Ingress annotations that you can add.	In this example, you do not need to configure annotations.
Labels	You can add labels to describe the characteristics of the Ingress. Click +Add Label to add a label. ACK does not limit the number of Ingress labels that you can add.	In this example, you do not need to configure labels.

After the configurations are complete, click OK in the lower-left corner of the Create Ingress panel.

kubectl

The following code block defines an Ingress that forwards requests to multiple Services in the cluster:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: forward-ingress
  annotations:
  # The Service specified in the annotation must be an existing Service in the cluster, and the Service name must be the same as the Service name specified in backend of the rule field. 
    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 # The name of the Service port must be use-annotation.

Scenario 6: Rewrite requests

The following code block defines an Ingress that rewrites the domain names, paths, and query strings of requests.

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: 80

Scenario 7: Modify the response header based on ResponseHeader

Important

By default, custom routing rules take effect in the inbound direction. To enable custom routing rules to take effect in the outbound direction, set the annotation alb.ingress.kubernetes.io/rule-direction.<Service name> to Response. The annotation is set to Request by default.
When you create a custom outbound routing rule, the name of the Service port in the ingressSpec.rules.backend field must be use-annotation.

The following code block defines that when a response header is matched (the header contains response-hello and the value must be value1 or value2), a new request header source: alibaba will be inserted into the header.

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 # The name of the Service port must be use-annotation.

Scenario 8: Modify the response header based on the response status code

Important

By default, custom routing rules take effect in the inbound direction. To enable custom routing rules to take effect in the outbound direction, set the annotation alb.ingress.kubernetes.io/rule-direction.<Service name> to Response. The annotation is set to Request by default.
When you create a custom outbound routing rule, the name of the Service port in the ingressSpec.rules.backend field must be use-annotation.

The following code block defines that the request header is removed (response-hello is removed from the request header) only when the response status code is 200 or 300.

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 # The name of the Service port must be use-annotation.

Practices for configuring routing conditions and actions

Scenario 1: Configure domain name-based routing conditions and actions to route traffic to a specific Service

This section describes how to configure domain name-based routing conditions and actions in the ACK console to route traffic to a specific Service.

Note

Before you create ALB Ingresses, perform the following steps to deploy a backend Service and create an AlbConfig and an IngressClass.

Log on to the ACK console. In the left-side navigation pane, click Clusters.
On the Clusters page, find the cluster that you want to manage and click its name. In the left-side pane, choose Network > Ingresses.

On the Ingresses page, click Create Ingress. In the Create Ingress dialog box, configure the parameters.

Parameter	Description	Example
Gateway Type	You can select ALB, MSE Cloud-native Gateway, or Nginx based on your requirements. For more information about the differences among the three gateway types, see Comparison among NGINX Ingresses, ALB Ingresses, and MSE Ingresses.	ALB
Name	The name of the Ingress.	alb_ingress
Ingress Class	Specify the IngressClass associated with the Ingress.	alb
Rules	Click +Add Rule to add an Ingress rule. Domain Name: Specify a custom domain name. Mappings: Specify the following parameters: Path: Specify the URL path of the backend Service. In this example, the root path / is used. Rule: You can select Prefix (Prefix-based Match), Exact (Exact Match), or ImplementationSpecific (Default Value). Service: Select the backend Service. Port: Specify the Service port that you want to expose. You can configure multiple paths for a domain name. Click + Add to add a path.	Domain Name: .example.com. Mappings: Path: /tes Rule: ImplementationSpecific. This is the default value. Service: tea-svc. Port*: 80.
TLS Settings	Specifies whether to enable TLS authentication. You can enable TLS authentication for the Ingress. Domain Name: the custom domain name. Secret: Select the Secret that you want to use. To create a Secret, perform the following steps: Click Create to the right of the Secret field. In the Create Secret dialog box, configure the Name, Cert, and Key parameters. Then, click OK. Select the Secret that you created from the Secret drop-down list. You can click + Add to add more TLS certificates. For more information, see Use an ALB Ingress to configure certificates for an HTTPS listener.	Turn off TLS Settings. In this example, you do not need to configure a TLS certificate.
More	Canary Release: Enable canary releases. You can configure canary release rules based on request headers, cookies, and weights. Description You can configure canary release rules based on only one of the following elements: request headers, cookies, and weights. You can also configure canary release rules based on request headers, cookies, and weights at the same time. In this case, request headers, cookies, and weights take effect in descending order of precedence. Based on Request Header: Distribute traffic based on request headers by adding the `nginx.ingress.kubernetes.io/canary-by-header`, `nginx.ingress.kubernetes.io/canary-by-header-value`, or `nginx.ingress.kubernetes.io/canary-by-header-pattern` annotation. Based on Cookie: Distribute traffic based on cookies by adding the `nginx.ingress.kubernetes.io/canary-by-cookie` annotation. Based on Weight: Distribute traffic based on Service weights (integers from 0 to 100) by adding the `nginx.ingress.kubernetes.io/canary-weight` annotation. Protocol: Select the protocol used by the backend Service by adding the `nginx.ingress.kubernetes.io/backend-protocol` annotation. HTTP, HTTPS, gRPC, and gRPCS are supported. Rewrite Path: Add the `nginx.ingress.kubernetes.io/rewrite-target` annotation to rewrite the paths in client requests before the requests are forwarded to the backend Service.	Turn off Canary Release. Use the default values of the Protocol and Rewrite Path parameters. In this example, you do not need to configure these parameters.
Custom Forwarding Rules	You can enable custom forwarding rules to manage inbound traffic in a fine-grained manner. Note You can add up to 10 conditions to a forwarding rule. The following condition types are available in the Add Condition drop-down list: Domain name: Specifies that only requests that contain the specified domain names are routed. The logical relationship between multiple domain names is OR. After you specify the domain names, the system adds the `alb.ingress.kubernetes.io/conditions.host-example` annotation. Path: Specifies that only requests that contain the specified one or more paths are routed. Multiple paths are treated with an OR relationship. After you specify the paths, the system adds the `alb.ingress.kubernetes.io/conditions.path-example` annotation. Important After you configure the forwarding conditions, Ingress will automatically add a forwarding rule for the path `/created-by-<ALB-ID>`. HTTP Header: Specifies that only requests that contain the specified HTTP headers are routed. Each HTTP request header is a key-value pair. For example, you can set the key to `headername` and the value to `headervalue1`. If you specify multiple header values, the logical relationship among the header values is OR. After you specify the headers, the system adds the `alb.ingress.kubernetes.io/conditions.http-header-example` annotation. The following actions are available in the Action drop-down list: Forward To Forwards the inbound traffic to multiple backend server groups. Select the Service that you want to access from the Service Name drop-down list. Select the port used to connect to the Service from the Port drop-down list. Specify a custom weight for each backend server group. Note If you use the Flannel component for the cluster, the ClusterIP Service is not supported. If you select Forward To from the Action drop-down list, you do not need to configure the Mappings parameter for the rule.	In the Add Condition drop-down list, Domain Name, Path, and HTTP Header are selected. Domain Name: example.com. You can click + Add Host to add a domain name, such as test.com. In the Action drop-down list, Forward To is selected. Service: tea-svc. Port: 80. Weight: 100.
Annotations	You can enter custom annotation names and values. You can also select or search for annotations by name from the drop-down list. For more information about Ingress annotations, see Annotations. Click +Add Annotation to add an annotation. ACK does not limit the number of Ingress annotations that you can add.	In this example, you do not need to configure annotations.
Labels	You can add labels to describe the characteristics of the Ingress. Click +Add Label to add a label. ACK does not limit the number of Ingress labels that you can add.	In this example, you do not need to configure labels.

After the configurations are complete, click OK in the lower-left corner of the Create Ingress panel.
Verify that the Ingress is created.
1. In the left-side pane, choose Network > Ingresses. The Ingress named cafe-ingress is displayed on the Ingresses page.
2. In the Endpoint column of cafe-ingress, view the endpoint.

Container Service for Kubernetes:Customize the routing rules of an ALB Ingress in the ACK console or by configuring annotations

Table of contents

Prerequisites

Routing conditions

Introduction to routing conditions

Scenario 1: Route traffic based on source IP addresses and request headers

Scenario 2: Route traffic based on domain names, request methods, and cookies

Scenario 3: Route traffic based on query strings, multiple request headers, and multiple paths

Routing actions

Introduction to routing actions

Routing actions for inbound routing rules

Routing actions for outbound routing rules

Scenario 1: Return status code 503 and fixed content

Use the ACK console

kubectl

Scenario 2: Use 301 redirect to redirect requests to an HTTPS port

Scenario 3: Insert the source: alibaba header to requests

Scenario 4: Mirror traffic to a server group

Scenario 5: Forward requests to multiple backend server groups

Use the ACK console

kubectl

Scenario 6: Rewrite requests

Scenario 7: Modify the response header based on ResponseHeader

Scenario 8: Modify the response header based on the response status code

Practices for configuring routing conditions and actions

Scenario 1: Configure domain name-based routing conditions and actions to route traffic to a specific Service