ALB Ingress supports custom routing rules. A routing rule consists of routing conditions and actions. You can customize routing conditions to match domain names, paths, request headers, query strings, request methods, cookies, or source IP addresses. You can also specify an action to return a fixed response, redirect a request, insert a request header, delete a request header, mirror traffic, forward requests to multiple backend server groups, or rewrite a request. This topic describes how to customize routing rules for an ALB Ingress.
Prerequisites
An ALB Ingress controller of v2.5.0 or later is required. To upgrade the add-on, see Manage add-ons.
The feature to configure custom routing rules in the console is in canary release. To use this feature, submit a ticket to request access.
Routing conditions
A routing rule can have a maximum of 10 routing conditions.
The
ResponseHeaderandResponseStatusCoderouting conditions are valid only for routing rules that customize responses.
Condition types
With ALB Ingress, you configure routing conditions by using the alb.ingress.kubernetes.io/conditions.<service-name> annotation. Conditions in separate blocks are evaluated with a logical AND, while multiple values within the same block are evaluated with a logical OR. For example, two separate Header condition blocks are linked by AND, but multiple values in a single Header block are linked by OR.
Condition | Description |
Domain name | Routes requests based on their domain name. The following is an example.
|
Path | Routes requests based on their path. The following is an example.
|
Header | Routes requests based on a request header. The following is an example.
|
Query string | Routes requests based on a query string. The following is an example.
|
Request method | Routes requests based on the request method. The following is an example.
|
Cookie | Routes requests based on a cookie. The following is an example.
|
SourceIP | Routes requests based on the source IP address. The following is an example.
|
ResponseHeader | Customizes a response based on its response header. The following is an example.
|
ResponseStatusCode | Customizes a response based on its response status code. The following is an example.
|
Use case 1: Source IP and header
You can specify a maximum of five SourceIp conditions per routing rule.
The following YAML configuration demonstrates how to route traffic based on the request's source IP address, a specific header, and the request path.
Requests are routed to the gray-hello service only if they meet all of the following criteria: the source IP is from 192.168.0.0/16 or 172.16.0.0/16, the request contains a header named gray-hello with a value of value1 or value2, and the request path is /hello. All 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: 88alb.ingress.kubernetes.io/order: Specifies the priority of the Ingress. A smaller number indicates a higher priority.
Use case 2: Domain name, request method, and cookie
The following YAML configuration shows how to route traffic based on the domain name, request method, and a cookie.
Requests are routed to the service-a service only if they meet all of the following criteria: the request method is GET or HEAD, the domain name is www.hostvalue1.edu or www.hostvalue2.edu, the request contains a cookie with the key cookiekey1 and value cookievalue1, and the request path is /test. Requests that do not match are routed to the service-b service.
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: 88Use case 3: Query string, headers, and path
The following YAML configuration demonstrates how to route traffic by combining conditions for a query string and multiple headers for a specific path.
A request is routed to service-a if the request path is /pathvalue1, /pathvalue2, or /test, the key of the query string is querystringkey1 and its value is querystringvalue2, the request header must contain headerkey1 and headerkey2, the value of the headerkey1 header must be headervalue1 or headervalue2, and the value of the headerkey2 header must be headervalue3 or headervalue4. Otherwise, the request is routed to 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: 88Forwarding action
Forwarding actions
ALB Ingress lets you configure routing actions using the alb.ingress.kubernetes.io/actions.<service name> annotation. You can add actions to return fixed responses, redirect requests, insert request headers, delete request headers, mirror traffic, forward requests to multiple backend server groups, and rewrite requests. These actions give you flexible control over the routing rules for requests and responses.
The service name in the
alb.ingress.kubernetes.io/actions.<service name>annotation must match the service name specified underbackendin therulefield.In the same routing rule, terminal actions such as redirects, fixed responses, and forwarding to multiple server groups are mutually exclusive.
When you configure redirection, a fixed response, or forwarding to multiple server groups, the name of the servicePort in the
backendsection of therulefield must be use-annotation.
Inbound routing actions
Action | Description |
Fixed response | Returns a fixed response to clients. You can set the response status code, body, and content type.
|
Redirect | Redirects client requests to a different URL using an HTTP 3xx status code. Important You must specify at least one parameter in the redirect configuration other than httpCode.
|
Traffic mirroring | Copies requests and forwards them to a traffic mirroring server group. Important
|
Forwarding to multiple backend server groups | Forwards requests to multiple backend server groups. You can specify a backend server group using its ServerGroupID, or create or associate one using a combination of ServiceName and Important
|
Rewrite | Rewrites the host, path, or query string of a request. Important
For more information, see Configure rewrite. |
Insert header | Inserts a header into the request. If a header with the same name already exists, it is overwritten.
|
Remove header | Removes a specified header from the request.
|
Rate limiting | Limits the rate of requests based on the overall queries per second (QPS) and the QPS from a specific client IP address. Important
|
Outbound routing actions
Action | Description |
insert request header | Inserts a header with the specified name and value. If a header with the same name already exists, it is overwritten.
|
remove request header | Removes a specified header from the request.
|
Scenario 1: Set a fixed 503 response and content
Console
-
Log on to the ACS console. In the left navigation pane, click Clusters.
-
On the Clusters page, click the name of the target cluster. In the left navigation pane, choose Network > Ingresses.
On the Ingresses page, click Create Ingress, and in the Create Ingress dialog box, configure the Ingress.
Parameter | Description | Example |
Gateway Type | Select the gateway type, either ALB or MSE Ingress, based on your business needs. | ALB |
Name | A custom name for the Ingress. | ingress |
Ingress Class | A custom class for the Ingress. | alb |
Listener/Port | The listener port and protocol for the ALB instance, as defined in the AlbConfig. This setting specifies how the load balancer receives and processes inbound traffic. | HTTP:80 |
Rules | Click +Add Rule to add multiple routing rules.
|
|
TLS Settings | Configure TLS to enable a secure routing service.
| Disable TLS Settings. This is not required for this example. |
More |
| Disable canary release. Keep the default protocol and rewrite path. These settings are not required for this example. |
Custom Forwarding Rules | Note The feature to configure custom forwarding rules in the console is in canary release. To use this feature, submit a ticket to apply for access. Use custom forwarding rules for fine-grained management of inbound traffic. Note You can add a maximum of 10 conditions to a forwarding rule.
You can combine multiple conditions (based on domain, path, or HTTP header) and actions (such as forwarding to a backend or returning a fixed response). |
|
Annotations | You can add custom annotations by specifying a key and a value, or select or search for an annotation by its key. For more information about Ingress annotations, see ALB Ingress annotation reference. Click + Add Annotation to add multiple annotations to the Ingress. | This parameter is not required for this example. |
Labels | Specifies labels to add to the Ingress. Labels are key-value pairs that are attached to objects to specify identifying attributes. | This parameter is not required for this example. |
After you finish the configuration, click OK.
Kubectl
The following YAML defines an Ingress that returns status code 503 and the content 503 error text for requests that match its rules.
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: 301 redirect to an HTTPS port
The following code block redirects service requests to the corresponding 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": "${port}",
"protocol": "https",
"query": "${query}",
"httpCode": "301"
}
}]
spec:
ingressClassName: alb
rules:
- http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: redirect
port:
name: use-annotation # The service port name must be 'use-annotation'.Scenario 3: Add 'source: alibaba' request header
This code block overrides the request header on service requests with source: alibaba.
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
namespace: default
name: ingress
annotations:
# The referenced Service must exist in the cluster, and its name must match the one in the rule's `backend` 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: 80Scenario 4: Traffic mirroring
The following code demonstrates how to copy requests to a traffic mirroring server group.
Log on to the Application Load Balancer (ALB) console. In the left-side navigation pane, choose ALB > Server Groups and find the server group ID.
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: traffic-mirror-ingress
annotations:
# The service in the annotation must exist in the cluster, and its service name must match the one in the backend of the rule field.
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: 80Scenario 5: Forward requests to multiple backend groups
Configure in the console
-
Log on to the ACS console. In the left navigation pane, click Clusters.
-
On the Clusters page, click the name of the target cluster. In the left navigation pane, choose Network > Ingresses.
On the Ingresses page, click Create Ingress, and in the Create Ingress dialog box, configure the Ingress.
Parameter
Description
Example
Gateway Type
Select ALB or MSE Ingress as the gateway type.
ALB
Name
A custom name for the Ingress.
forward-ingress
Ingress Class
A custom class for the Ingress.
alb
Listener/Port
The listener port and protocol for the ALB instance, as defined in the AlbConfig. This setting specifies how the load balancer processes inbound traffic.
HTTP:80
Rules
Click +Add Rule to add multiple routing rules.
-
Domain Name: A custom domain name.
-
Mappings: Configure the following parameters.
-
Path: The URL path for accessing the service. In this example, this parameter is left empty to use the root path /.
-
Rule: Supports Prefix (Prefix-based Match), Exact (Exact Match), and ImplementationSpecific (Default Value).
-
Service: The target backend, which is a Kubernetes Service.
-
Port: The port that the service exposes.
-
-
An Ingress supports multiple paths under the same domain name. Click +Add to add a new path.
Domain Name: demo.domain.ingress.top
Mappings:
Path: /path
Rule: Default (Prefix match)
Service: forward
Port: 80
TLS Settings
Enable to secure the Ingress with TLS.
Domain Name: A custom domain name.
Secrets: Select a Secret. To create a Secret, perform the following steps:
To the right of Secret, click Create.
In the Create Secret dialog box, specify a Name, Cert, and Key for the Secret, and then click OK.
From the Secret drop-down list, select the Secret that you created.
Turn off TLS Settings. This is not required for this example.
More
-
Canary Release: Enable this feature to configure a canary release. You can set canary rules based on request headers, cookies, or traffic weight.
NoteYou can set only one of these conditions. If you set multiple conditions, the Ingress controller evaluates them in the order of request header, cookie, and then weight.
-
Based on Request Header: Splits traffic based on the request header. This adds the
nginx.ingress.kubernetes.io/canary-by-header,nginx.ingress.kubernetes.io/canary-by-header-value, ornginx.ingress.kubernetes.io/canary-by-header-patternannotation. -
Based on Cookie: Splits traffic based on the cookie. This adds the
nginx.ingress.kubernetes.io/canary-by-cookieannotation. -
Based on Weight: The percentage of requests (an integer from 0 to 100) to be routed to the specified service. This adds the
nginx.ingress.kubernetes.io/canary-weightannotation.
-
-
Protocol: The protocol used to communicate with the backend service. This adds the
nginx.ingress.kubernetes.io/backend-protocolannotation.HTTP, HTTPS, gRPC, and gRPCS are supported.
-
Rewrite Path: Rewrites the path in a client request before sending it to the backend service. This adds the
nginx.ingress.kubernetes.io/rewrite-targetannotation.
Turn off Canary Release. Use the default values for Protocol and Rewrite Path. These settings are not required for this example.
Custom Forwarding Rules
NoteThis feature is in canary release. To use this feature, submit a ticket to apply for access.
Turn on this switch to enable fine-grained management of inbound traffic.
NoteYou can add a maximum of 10 conditions to a forwarding rule.
From the Add Condition drop-down list, select a condition:
Domain Name:
Matches requests based on the domain name. If you specify multiple domain names, the logical relationship between them is OR. After you configure this condition, the
alb.ingress.kubernetes.io/conditions.host-exampleannotation is added.Path:
Matches requests based on the request path. If you specify multiple paths, the logical relationship between them is OR. After you configure this condition, the
alb.ingress.kubernetes.io/conditions.path-exampleannotation is added.HTTP Header:
Matches requests based on the key-value pair of a request header. For example, you can set the Key to
headernameand the Value toheadervalue1. If you specify multiple header values, the logical relationship between them is OR. After you configure this condition, thealb.ingress.kubernetes.io/conditions.http-header-exampleannotation is added.
From the Action drop-down list, select an action:
Forward To
Forwards requests to multiple backend server groups. In the Service field, select the target service. In the Port field, select the target port number. Then, configure a custom weight value.
NoteIf the cluster uses the Flannel network plugin, ClusterIP services are not supported.
If you select Forward To, path mappings are not required in the rule.
Return Fixed Response
Returns a fixed response to the client from the ALB instance. You can set the response status code, content, and content type. Configure the Response Status Code, Response Content Type (Optional), and Response Content (Optional) parameters as needed.
Response Content Type:
text/plain: Plain text content.
text/css: CSS-formatted content.
text/html: HTML-formatted content.
application/javascript: JavaScript-formatted content.
application/json: JSON-formatted content.
Forwarding Condition: Select Domain. Domain: demo.domain.ingress.top
Forwarding Action: Forward To
Service Name: tea-svc
Port: 80
Weight: 80
Add Service
Service Name: coffee-svc
Port: 80
Weight: 20
Annotations
You can add custom annotations by specifying a key and a value, or select or search for an annotation by its key. For more information about Ingress annotations, see ALB Ingress annotation reference.
Click +Add Annotation to add an unlimited number of annotations to the Ingress.
This parameter is not required for this example.
Labels
Specifies labels to add to the Ingress. Labels are key-value pairs that are attached to objects to specify identifying attributes.
This parameter is not required for this example.
-
After completing the configuration, click OK in the lower-left corner of the Create Ingress page.
Use kubectl
This YAML manifest 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 in this annotation must exist in the cluster and match the ServiceName under `backend` in the rule.
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 port name must be use-annotation.Scenario 6: Request rewrite
This code block defines an Ingress that rewrites the domain name, path, and query string of a request.
Scenario 7: Modify response headers
By default, ALB ingress routing rules apply to the inbound direction. To create routing rules for the outbound direction, set the
alb.ingress.kubernetes.io/rule-direction.<service-name>annotation to Response. The default value is Request.When creating a routing rule for the outbound direction, set the
servicePortfield iningressSpec.rules.backendtouse-annotation.
The following code block inserts the request header source: alibaba when there is a ResponseHeader match on the header response-hello with a value of either value1 or value2.
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 service port name must be use-annotation.Scenario 8: Modify response header by status code
By default, custom ALB Ingress routing rules apply to requests. To create a routing rule for responses, set the
alb.ingress.kubernetes.io/rule-direction.<Service name>annotation toResponse. By default, this annotation is set toRequest.When creating a routing rule for responses, the
servicePortin theingressSpec.rules.backendfield must beuse-annotation.
The rule in the following code block removes the response-hello request header only if 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 service port name must be use-annotation.