Documentation
Home Page Server Load Balancer Application Load Balancer Listeners and Forwarding Rules Forwarding rules for domain and path matching

Forwarding rules for domain and path matching

Updated at:
Copy as MD
Product

This topic provides examples of how to configure ALB forwarding rules, covering domain name and path matching, rewrite, and redirect.

Configuration examples

Scenario 1: Redirect HTTP to HTTPS

Redirect HTTP requests to HTTPS to ensure data is encrypted in transit. You can achieve this by adding a forwarding rule to the HTTP listener (port 80).

Parameter

Description

Add Condition

Set Path to Exact Match and Wildcard and enter /*.

Action

Select Redirect.

  • Protocol: Select HTTPS.

  • Domain Name: ${host}

  • Port: Enter the port of the existing HTTPS listener, such as 443.

  • Path: ${path}

  • Search: ${query}

  • Status Code: Select 301.

Result: When a user accesses http://www.example.com/page, the browser automatically redirects to https://www.example.com/page.

Configure this rule on the HTTP listener (port 80). Also, ensure that an HTTPS listener (port 443) has been created and is associated with a valid SSL certificate. For complete prerequisites and procedures, see Use ALB to redirect HTTP requests to HTTPS.

Scenario 2: Route traffic by path

For a single domain, you can forward requests with different paths to different server groups. For example, you can forward API requests and static asset requests to separate backends.

Rule 1: Forward requests for /api/* to the API server group.

Parameter

Description

Add Condition

Set Path to Exact Match and Wildcard and enter /api/*.

Action

Select Forward, and then select the API server group.

Rule 2: Forward requests for /static/* to the static asset server group.

Parameter

Description

Add Condition

Set Path to Exact Match and Wildcard and enter /static/*.

Action

Select Forward, and then select the static asset server group.

ALB evaluates forwarding rules sequentially based on their priority numbers. Place more specific path rules (with lower priority numbers) before broader ones to prevent them from being matched by a wildcard rule first. For example, the rule for /api/v2/* should have a lower priority number than the rule for /api/*.

Scenario 3: Forward multiple domains

Host multiple domains on a single ALB instance and forward requests for each domain to its respective backend server group.

Rule 1: Forward requests for www.example.com to the web server group.

Parameter

Description

Add Condition

Set Domain Name to Exact Match and Wildcard and enter www.example.com.

Action

Select Forward, and then select the web server group.

Rule 2: Forward requests for api.example.com to the API server group.

Parameter

Description

Add Condition

Set Domain Name to Exact Match and Wildcard and enter api.example.com.

Action

Select Forward, and then select the API server group.

Scenario 4: Strip a path prefix before forwarding

Strip a specific prefix from a request path before forwarding the request to a backend, while still capturing multi-level paths after the prefix. For example, when ALB forwards requests for www.example.com/api/aaa/bbb/..., you need to remove the /api part from the path while still capturing subsequent multi-level paths like /aaa/bbb/....

A rewrite replaces the path internally within ALB; the URL in the client's browser address bar does not change. A redirect returns a new URL to the client, and the browser's address bar updates to the new URL. Use rewrite if only the backend needs to receive the path without the prefix. Use redirect if the client must be aware of the URL change.

Rewrite

Parameter

Description

Add Condition

Domain Name

Set to Exact Match and Wildcard and enter www.example.com.

Path

Set to Regular Expression Match | Case Insensitive and enter ^/api/(.*).

Action

Rewrite

  • Domain Name: ${host}

  • Path: /${1}

  • Search: ${query}

Forward

Select the target server group.

Redirect

Parameter

Description

Add Condition

Domain Name

Set to Exact Match and Wildcard and enter www.example.com.

Path

Set to Regular Expression Match | Case Insensitive and enter ^/api/(.*).

Action

Redirect

  • Protocol: ${protocol}

  • Domain Name: ${host}

  • Port: ${port}

  • Path: /${1}

  • Search: ${query}

  • Status Code: Select 301.

Result: For a request to www.example.com/api/aaa/bbb/..., the backend server receives the path /aaa/bbb/....

Scenario 5: Redirect bare domain to www

Redirect requests from a bare domain (such as example.com) to www.example.com. This unifies the entry point for better SEO and easier management.

Parameter

Description

Add Condition

Set Domain Name to Exact Match and Wildcard and enter example.com.

Action

Select Redirect.

  • Protocol: ${protocol}

  • Domain Name: Enter www.example.com.

  • Port: ${port}

  • Path: ${path}

  • Search: ${query}

  • Status Code: Select 301.

Result: When a user accesses example.com, the browser automatically redirects to www.example.com. The protocol and port remain unchanged.

If you also need to redirect HTTP requests to HTTPS, combine this configuration with Scenario 1.

Scenario 6: Match a wildcard domain

Use a wildcard domain to match all subdomains and forward their requests to the same server group.

Parameter

Description

Add Condition

Set Domain Name to Exact Match and Wildcard and enter *.example.com.

Action

Select Forward, and then select the target server group.

Result: Requests to all matching subdomains, such as a.example.com, b.example.com, and tenant1.example.com, are forwarded to the same server group.

To forward a specific subdomain to a different server group, create a rule for that exact domain and give it a lower priority number than the wildcard rule. ALB evaluates rules based on their priority number, not by the specificity of the domain match.

Scenario 7: Canary release by HTTP header

Use an HTTP header to implement a canary release. This forwards requests with a specific header to the new version server group, while other requests are forwarded to the current version server group.

Rule 1 (Canary rule, higher priority): Forward requests containing the X-Canary: true header to the new version server group.

Parameter

Description

Add Condition

Select HTTP Header, set the key to X-Canary, and set the value to true.

Action

Select Forward, and then select the new version server group.

Rule 2 (Default rule, lower priority): Requests without the canary header are forwarded to the current version server group. This can be implemented using the listener's default forwarding rule.

Result: When a client request includes the X-Canary: true header, traffic is forwarded to the new version server group. Requests without this header are forwarded to the current version server group.

To ensure canary traffic is matched first, the canary rule must have a lower priority number (indicating higher priority) than the default rule. For information about canary release methods based on cookies and server group weights, see Use ALB to implement a canary release.

Domain matching in forwarding rules

ALB evaluates forwarding rules by their priority number, from lowest to highest, and stops at the first rule that matches. Rules are not automatically sorted by domain specificity. This behavior is different from CLB, which automatically prioritizes rules based on specificity (for example, exact match > narrower wildcard > broader wildcard).

For example, consider a listener with the following two rules:

Priority number

Match condition

Rule 1 (Priority: 1)

Domain = *.example.com → Forward to server group A

Rule 2 (Priority: 2)

Domain = www.example.com → Forward to server group B

A request to www.example.com matches Rule 1 (the wildcard rule), not Rule 2 (the exact match rule), because Rule 1 has a lower priority number.

Best practice: To ensure a more specific rule is evaluated first, assign it a lower priority number than a less specific rule. For example, set the rule for www.example.com to Priority 1 and the rule for *.example.com to Priority 2.

Match type

Description

Exact match and wildcard match

  • Match description

    • Exact match: The requested domain name must be identical to the one specified in the rule.

    • Wildcard match: The requested domain name must match the wildcard pattern specified in the rule.

  • Requirements

    The domain name must be 3 to 256 characters long and can contain only letters, digits, and the following special characters: .-?=~_+\^*!$&|()[]. You can use asterisks (*) and question marks (?) as wildcards.

  • Example

    Requested domain name: www.example.com

    • Exact match: Matches if the rule is set to www.example.com.

    • Wildcard match: Matches if the rule is set to *.example.com or www.example.*.

Regular expression match

  • Match description

    The requested domain name must match the regular expression specified in the rule.

  • Requirements

    The domain name must be 3 to 256 characters long and can contain only letters, digits, and the following special characters: .-?=~_+\^*!$&|()[].

  • Example

    Requested domain name: www.example.com

    Matches if the rule is set to the regular expression ^www.example.com$. This match is case-insensitive.

Forwarding rule path matching

The path matching rules of ALB are different from those of Nginx. ALB does not support the longest prefix match principle. For example, Nginx uses the longest prefix match method for a common configuration such as location /api. To achieve the same effect in ALB, you must use a wildcard. You can configure the path as /api/* (a combination of an exact match and a wildcard).

If a listener has rules for both /api/* and /api/v2/*, you must place the /api/v2/* rule before the /api/* rule by assigning it a lower rule number. Otherwise, the /api/* rule will match all requests first.

Match type

Description

Exact and wildcard match

  • Match description

    • Exact match: The requested path must be identical to the path specified in the rule.

    • Wildcard match: The requested path must match the wildcard pattern specified in the rule.

  • Input requirements

    The path must start with a forward slash (/), and must contain only letters, digits, and the following special characters: $-_.+/&~@:. Asterisks (*) and question marks (?) serve as wildcards.

  • Example

    Request path: /example/text

    • Exact match: A request matches if the rule is configured with the path /example/text.

    • Wildcard match: A request matches if the rule is configured with the path /example/*.

Regular expression match

  • Match description

    The requested path must match the regular expression specified in the rule.

  • Input requirements

    The regular expression must contain only letters, digits, and the following special characters: .-_/=?~^*$:()[]+|.

  • Example

    Request path: /api/v2/Users

    • Case-sensitive: A request matches if the regular expression is set to ^/api/(.*)/Users$.

    • Case-insensitive: A request matches if the regular expression is set to ^/api/(.*)/users$.

Advanced path configuration for rewrites and redirects

If you use a regular expression to define a path in a forwarding condition, you can use regular expression substitution in the path of a rewrite or redirect action.

  • Notes

    • The number of capture groups, defined by parentheses( ), in the regular expression of the forwarding condition must match the number of ${n} variables in the rewrite or redirect path of the forwarding action.

    • The rewrite or redirect path in the forwarding action must include one or more of${1}, ${2}, and${3}. Do not replace these variables with other characters.

    • In a rewrite or redirect path, use the$ character only to reference the following variables: ${host}, ${path}, ${port}, ${protocol}, and regular expression capture group variables such as${1}, ${2}, and${3}. No other variables are supported.

  • How it works

    1. Path matching: A client sends a request that matches the regular expression in a forwarding rule.

    2. Extraction and substitution: The system extracts content from the first three capture groups, defined by parentheses( ), and saves it to the${1}, ${2}, and${3} variables. These variables are then used for substitution in the rewrite or redirect path of the forwarding action.

    3. Path construction: The system replaces the${1}, ${2}, and${3} variables with their captured values and constructs the final path for the rewrite or redirect.

    No.

    Step

    Example

    1

    Configure the forwarding condition and forwarding action for a forwarding rule.

    • Path in the forwarding condition: /app/(.*)/(.*)/settings

    • Path for rewrite or redirect action: /${1}/${2}

    2

    A client sends a request that matches the path.

    • Request path from the client: /app/users/profile/settings

    • Matched path in the forwarding condition: /app/(.*)/(.*)/settings

    3

    Extract and substitute values.

    The system extractsusers andprofile from the two(.*) capture groups in the forwarding condition path and saves the values to the ${1} and ${2} variables for the forwarding action.

    • ${1} is replaced withusers.

    • ${2} is replaced withprofile.

    4

    Construct the path.

    Path received by the backend server: /users/profile

  • Configuration examples

    When adding forwarding rules in the console, refer to the preceding notes and workflow description.

    Example 1: Set the forwarding action to Rewrite and Forward

    This example shows how to rewrite the path /app/users/profile/settings to /users/profile and then forward the request to a backend server. The regular expression /app/(.*)/(.*)/settings uses two capture groups to extract users and profile. The rewritten path then uses /${1}/${2} to construct the final path.

    Parameter

    Description

    Add Condition

    Path

    Select Regular Expression Match | Case Insensitive and enter the regular expression /app/(.*)/(.*)/settings.

    For example, if a client requests the path /app/users/profile/settings, the rule is matched. The capture groups extract users and profile, which are saved to the ${1} and ${2} variables respectively.

    Action

    Rewrite

    • Domain Name: ${host}

    • Path: /${1}/${2}

    • Search: ${query}

    The Search is the part of a URL that follows the question mark. For example, for the URL www.example.com/test/test1?x=1, the Search is x=1.

    Forward

    Select the target server group from the server group list.

    Example 2: Set the forwarding action to redirect

    The following example redirects the path /app/users/profile/settings to /users/profile. Unlike Example 1, this redirect returns a 301 status code, and the URL in the browser's address bar changes.

    Parameter

    Description

    Add Condition

    Path

    Select Regular Expression Match | Case Insensitive and enter the regular expression /app/(.*)/(.*)/settings.

    For example, if a client requests the path /app/users/profile/settings, the rule is matched. The capture groups extract users and profile, which are saved to the ${1} and ${2} variables respectively.

    Action

    Redirect

    • Protocol: ${protocol}

    • Domain Name: ${host}

    • Port: ${port}

    • Path: /${1}/${2}

    • Search: ${query}

    • Status Code: 301

FAQ

Rewrite a domain name only

To rewrite the requested domain name to another while keeping the path and query string unchanged, configure the rule as follows:

  • Add Condition: Set the domain name to the original domain name, such as old.example.com.

  • Action: Select rewrite. Set the domain name to the new domain name (such as new.example.com), the path to ${path}, and the query to ${query}. Also, configure Forward to specify a server group.

Add a prefix to a path

To add a prefix to a path (for example, rewriting /users/list to /v2/users/list), configure the rule as follows:

  • Add Condition: Set the path to match the regular expression ^/(.*).

  • Action: Select rewrite and set the path to /v2/${1}. Also, configure Forward to specify a server group.

After you configure the rule, ALB rewrites a request for /users/list to /v2/users/list and forwards it to the backend server.

Remove a path prefix

See Use case 4: Forward requests after stripping a path prefix in this topic. This use case provides a complete configuration example for removing a prefix, such as /api/*, by using a regular expression match with a rewrite or redirect action.

Troubleshoot forwarding rule matching and routing

If your forwarding rules do not route requests as expected, use the following troubleshooting steps:

  1. Check the rule priority: ALB evaluates rules in ascending order of their priority number and stops at the first match. If a broader rule has a lower priority number (and is therefore evaluated first), a more specific rule with a higher priority number will not be matched.

  2. Check the match type: Ensure you use the correct match type (exact match, wildcard, or regular expression). For example, an exact match for /api does not match /api/users. To match both, you must use a wildcard, such as /api/*.

  3. Check multiple conditions: When configuring multiple conditions for a single forwarding rule, conditions of different types are combined with an AND operator, while multiple values for the same condition type are combined with an OR operator. For more information, see Configure listener forwarding rules.

  4. Check the access logs: Use the host and request_uri fields in the ALB access log to verify that the request details received by ALB match your expectations.

Rewrite versus redirect

Item

Rewrite

Redirect

Browser address bar

Unchanged (transparent to the user)

Changes to the new URL

How it works

ALB rewrites the request path internally and then forwards the request to the backend server. The entire process completes in a single request.

ALB returns a 3xx status code, and the browser initiates a second request to the new URL.

Use cases

Internal path adjustments, such as stripping prefixes or adding version numbers.

HTTP-to-HTTPS redirects, bare-domain-to-www redirects, and legacy URL migrations.

Requires "Forward to"

Yes. A rewrite action must be configured with a "Forward to" action that specifies a server group.

No. A redirect action is standalone.

Related documents

For instructions on configuring listener forwarding rules for an ALB, see Configure listener forwarding rules.

Previous：Listener forwarding rulesNext：Implement canary release