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. This topic describes how to customize the routing rules of an ALB Ingress.
Prerequisites
ALB Ingress controller 2.5.0 or later is installed in your cluster. For more information, see Manage components.
Routing conditions
You can add at most 10 routing conditions to one routing rule.
Routing conditions ResponseHeader and ResponseStatusCode only take effect in custom outbound routing rules.
Introduction to routing conditions
ALB Ingresses allow you to configure routing conditions in the annotation alb.ingress.kubernetes.io/conditions.<Service name>. The logical relation among different rule blocks is AND. If multiple values are specified in a rule block, the logical relation among the values is OR. For example, if you configure two header rule blocks, the logical relation between the two header rule blocks is AND. If you configure multiple headers in a header rule block, the logical relation 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:
|
URL | You can add this condition to route only requests that are sent to the specified paths. Sample code:
|
Header | You can add this condition to route only requests that contain the specified headers. Sample code:
|
Query string | You can add this condition to route only requests that contain the specified query strings. Sample code:
|
Request method | You can add this condition to route only requests that use the specified request methods. Sample code:
|
Cookie | You can add this condition to route only requests that contain the specified cookies. Sample code:
|
SourceIP | You can add this condition to route only requests from the specified source IP addresses. Sample code:
|
ResponseHeader | You can add this condition to route only responses that contain the specified response headers. Sample code:
|
ResponseStatusCode | You can add this condition to route only requests that return specified status codes. Sample code:
|
Scenario 1: Route traffic based on source IP addresses and request headers
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: 88alb.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 www.hostvalue1.edu and www.hostvalue2.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.
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: 88Scenario 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: 88Routing actions
Introduction to routing actions
ALB Ingresses allow you to configure routing actions for inbound and outbound routing rules in the annotation alb.ingress.kubernetes.io/actions.<Service name>. 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.
The Service name in the annotation
alb.ingress.kubernetes.io/actions.<Service name>must be the same as the Service name specified inbackendin therulefield.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 servicePort specified in
backendin therulefield 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:
|
Redirect requests | You can use the HTTP 3XX status codes to redirect requests to other Service addresses. Sample code: Note You cannot keep the default settings for all redirect parameters at the same time, excluding httpCode.
|
Mirror traffic | You can specify the ID of a server group to mirror traffic to the specified server group. Sample code: Note
|
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. Sample code: Note
|
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: Note
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:
|
Delete request headers | You can delete the keys and values of request headers. Sample code:
|
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:
|
Delete request headers | You can delete the keys and values of request headers. Sample code:
|
Scenario 1: Return status code 503 and fixed content
The following code block is used to return status code 503 and the specified 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-annotationScenario 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": "${port}",
"protocol": "https",
"query": "${query}",
"httpCode": "301"
}
}]
spec:
ingressClassName: alb
rules:
- http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: redirect
port:
name: use-annotationScenario 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:
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: Mirror traffic to a server group
The following code block is used to mirror traffic to a specified server group:
Log on to the Server Load Balancer (SLB) console. In the left-side navigation pane, choose . 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:
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 server groups
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:
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-annotationScenario 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:
port: 80Scenario 7: Modify the response header based on ResponseHeader
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
servicePortin theingressSpec.rules.backendfield must beuse-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-annotationScenario 8: Modify the response header based on the response status code
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
servicePortin theingressSpec.rules.backendfield must beuse-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