DocsICP FilingConsole
Documentation

CreateRule

Updated at:
Copy as MD
Product
My Favorites

Creates a forwarding rule for a listener.

Operation description

When calling this operation to create a forwarding rule, note the following:

  • When you configure the Redirect action, you must set at least one parameter other than HttpCode to a non-default value.

  • If you specify a Rewrite action together with other actions in a forwarding rule, you must also specify a ForwardGroup action.

  • The CreateRule operation is asynchronous. After you send a request, the system returns a request ID and runs the creation task in the background. The forwarding rule is not created immediately. To query its status, call the ListRules operation:

    • If a forwarding rule is in the Provisioning state, the rule is being created.

    • If a forwarding rule is in the Available state, the rule has been created successfully.

  • A forwarding rule has the following limits for conditions (RuleConditions) and actions (RuleActions):

    • Conditions: 5 for a basic Application Load Balancer (ALB) instance, 10 for a standard ALB instance, and 10 for a WAF-enabled ALB instance.

    • Actions: 3 for a basic ALB instance, 5 for a standard ALB instance, and 5 for a WAF-enabled ALB instance.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

  • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

  • API: The API that you can call to perform the action.

  • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

  • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

    • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

    • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

  • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

  • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

alb:CreateRule

create

*LoadBalancer

acs:alb:{#regionId}:{#accountId}:loadbalancer/{#loadbalancerId}

*ServerGroup

acs:alb:{#regionId}:{#accountId}:servergroup/{#servergroupId}

 None None

Request parameters

Parameter

Type

Required

Description

Example
ListenerId

string

Yes

The ID of the listener.

lsn-l16uo9y******
ClientToken

string

No

The client token used to ensure request idempotence.

The client must generate a unique token for each request. The token can contain only ASCII characters.

Note

If you do not specify this parameter, the system uses the RequestId of the API request as the ClientToken. Each API request has a unique RequestId.

5A2CFF0E-5718-45B5-9D4D-70B******
DryRun

boolean

No

Specifies whether to perform a dry run. Valid values:

  • true: Performs a dry run. The system checks for potential issues, such as required parameters, request format, and service limits, without creating the forwarding rule. If the check fails, the system returns an error. If the check passes, the system returns the DryRunOperation error code.

  • false (default): Sends a normal request. If the check passes, the system performs the operation and returns an HTTP 2xx status code.

false
Priority

integer

Yes

The priority of the rule. Valid values: 1 to 10000. A smaller value indicates a higher priority.

Note

The priority of each forwarding rule within the same listener must be unique.

10
Direction

string

No

The direction in which the forwarding rule is applied. Valid values:

  • Request (default): The rule matches and processes requests sent from the client to the ALB instance.

  • Response: The rule matches and processes responses returned from server groups to the ALB instance.

Note

Basic ALB instances do not support the Response type.

Request
RuleActions

array<object>

Yes

A list of actions for the forwarding rule.

array<object>

Yes

The actions of the forwarding rule.

FixedResponseConfig

object

No

The fixed response configuration.

Content

string

No

The content of the fixed response. The content can be up to 1 KB in size and can contain only ASCII characters.

dssacav
ContentType

string

No

The content type of the fixed response.

Valid values: text/plain, text/css, text/html, application/javascript, or application/json.

text/plain
HttpCode

string

No

The HTTP response status code. Valid values are strings that represent 2xx, 4xx, and 5xx status codes, where x is any digit.

200
ForwardGroupConfig

object

No

The configuration for forwarding requests to one or more server groups.

ServerGroupTuples

array<object>

No

The server groups to which requests are forwarded. You can specify up to five server groups.

object

No

The configuration for a server group.

ServerGroupId

string

No

The ID of the server group.

sgp-k86c1ov501id6p****
Weight

integer

No

The weight of the server group. A server group with a higher weight receives more requests. Valid values: 0 to 100.

  • If you specify only one server group, the default weight is 100.

  • If you specify more than one server group, you must specify a weight for each group.

100
ServerGroupStickySession

object

No

The session persistence configuration.

Enabled

boolean

No

Specifies whether to enable session persistence. Valid values:

  • true: Enables session persistence.

  • false (default): Disables session persistence.

false
Timeout

integer

No

The timeout period, in seconds. Valid values: 1 to 86400. Default: 1000.

100
InsertHeaderConfig

object

No

The header insertion configuration.

Key

string

No

The name of the header to be inserted. The name must be 1 to 40 characters in length and can contain letters, digits, underscores (_), and hyphens (-). Header names must be unique within this action.

Note

The following header names are not allowed (case-insensitive): slb-id, slb-ip, x-forwarded-for, x-forwarded-proto, x-forwarded-eip, x-forwarded-port, x-forwarded-client-srcport, connection, upgrade, content-length, transfer-encoding, keep-alive, te, host, cookie, remoteip, authority, and x-forwarded-host.

key
Value

string

No

The value of the header to be inserted.

  • If ValueType is set to SystemDefined, you can set the value to one of the following:

    • ClientSrcPort: The source port of the client.

    • ClientSrcIp: The source IP address of the client.

    • Protocol: The request protocol (HTTP or HTTPS).

    • SLBId: The ID of the ALB instance.

    • SLBPort: The listener port of the ALB instance.

  • If ValueType is set to UserDefined, you can specify a custom header value. The value must be 1 to 128 characters in length and can contain printable characters with an ASCII value in the range of ch >= 32 && ch < 127. You can use asterisks (*) and question marks (?) as wildcards. The value cannot contain double quotation marks ("), start or end with a space, or end with a backslash (\).

  • If ValueType is set to ReferenceHeader, you can reference a request header. The value must be 1 to 128 characters in length and can contain lowercase letters, digits, hyphens (-), and underscores (_).

UserDefined
ValueType

string

No

The type of the header value. Valid values:

  • UserDefined: A user-defined header value.

  • ReferenceHeader: A value that is referenced from a request header.

  • SystemDefined: A system-defined header value.

UserDefined
Order

integer

Yes

The execution order of the action. Valid values: 1 to 50000. Actions are executed in ascending order of this value. Each action must have a unique order value.

1
RedirectConfig

object

No

The redirect configuration.

Note

You must specify a non-default value for at least one of the following parameters: Host, Path, Port, Protocol, or Query.

Host

string

No

The host to which requests are redirected. Valid values:

  • ${host} (default): This value cannot be used with other characters.

  • Other values must meet the following requirements:

    • The host must be 3 to 128 characters in length and can contain lowercase letters, digits, hyphens (-), periods (.), asterisks (*), equal signs (=), tildes (~), underscores (_), plus signs (+), backslashes (\), carets (^), exclamation points (!), dollar signs ($), ampersands (&), vertical bars (|), parentheses (()), square brackets ([]), and question marks (?).

    • The host must contain at least one period (.) and cannot start or end with a period (.).

    • The rightmost domain label can contain only letters and wildcards, and cannot contain digits or hyphens (-). The leftmost domain label can be an asterisk (*).

    • A domain label cannot start or end with a hyphen (-).

    • You can use asterisks (*) and question marks (?) as wildcards anywhere in a domain label.

${host}
HttpCode

string

No

The redirect type. Valid values: 301, 302, 303, 307, or 308.

301
Path

string

No

The path to which requests are redirected. Valid values:

  • ${path} (default): You can reference ${host}, ${protocol}, and ${port}. Each variable can be used only once. These variables can be used together or combined with strings that are in the valid value range.

  • Other values must meet the following requirements:

    • The path must be 1 to 128 characters in length, case-sensitive, and can contain asterisks (*) and question marks (?) as wildcards.

    • The path must start with a forward slash (/). It can contain letters, digits, and the following special characters: $-_.+/&~@:'*?. It cannot contain “%#;!()[]^,”\". It can also contain asterisks (*) and question marks (?) as wildcards.

/test
Port

string

No

The port to which requests are redirected.

  • ${port} (default): This value cannot be used with other characters.

  • Other values: 1 to 63335.

10
Protocol

string

No

The protocol to which requests are redirected. Valid values:

  • ${protocol} (default): This value must be used as-is and cannot be modified or used with other characters.

  • HTTP

  • HTTPS

Note

  • HTTPS listeners can redirect requests only over HTTPS.

  • HTTP listeners can redirect requests over HTTP or HTTPS.

HTTP
Query

string

No

The query string to which requests are redirected.

  • ${query} (default): You can reference ${host}, ${protocol}, and ${port}. Each variable can be used only once. These variables can be used together or combined with strings that are in the valid value range.

  • Other values must meet the following requirements:

    • The value must be 1 to 128 characters in length.

    • It can contain printable characters but cannot contain spaces or the following special characters: #[]{}\|<>". Letters must be lowercase.

${query}
RewriteConfig

object

No

The rewrite configuration.

Note

If a forwarding rule contains a Rewrite action, it must also contain a ForwardGroup action.

Host

string

No

The destination host for the internal redirect. Valid values:

  • ${host} (default): This value cannot be used with other characters.

  • Other values must meet the following requirements:

    • The host must be 3 to 128 characters in length and can contain lowercase letters, digits, hyphens (-), periods (.), asterisks (*), equal signs (=), tildes (~), underscores (_), plus signs (+), backslashes (\), carets (^), exclamation points (!), dollar signs ($), ampersands (&), vertical bars (|), parentheses (()), square brackets ([]), and question marks (?).

    • The host must contain at least one period (.) and cannot start or end with a period (.).

    • The rightmost domain label can contain only letters and wildcards, and cannot contain digits or hyphens (-). The leftmost domain label can be an asterisk (*).

    • A domain label cannot start or end with a hyphen (-). You can use asterisks (*) and question marks (?) as wildcards anywhere in a domain label.

www.example.com
Path

string

No

The path for the internal redirect. Valid values:

  • ${path} (default): You can reference ${host}, ${protocol}, and ${port}. Each variable can be used only once. These variables can be used together or combined with strings that are in the valid value range.

  • Other values must meet the following requirements:

    • The path must be 1 to 128 characters in length, case-sensitive, and can contain asterisks (*) and question marks (?) as wildcards.

    • The path must start with a forward slash (/). It can contain letters, digits, and the following special characters: $-_.+/&~@:'*?. It cannot contain “%#;!()[]^,”\". It can also contain asterisks (*) and question marks (?) as wildcards.

/tsdf
Query

string

No

The query string for the internal redirect.

  • ${query} (default): You can reference ${host}, ${protocol}, and ${port}. Each variable can be used only once. These variables can be used together or combined with strings that are in the valid value range.

  • Other values must meet the following requirements:

    • The value must be 1 to 128 characters in length.

    • It can contain printable characters but cannot contain spaces or the following special characters: #[]{}\|<>". Letters must be lowercase.

${query}
Type

string

Yes

The type of the action. Valid values:

  • ForwardGroup: Forwards requests to multiple server groups.

  • Redirect: Redirects a request.

  • FixedResponse: Returns a fixed response.

  • Rewrite: Rewrites a request.

  • InsertHeader: Inserts a header.

  • RemoveHeader: Removes a header.

  • TrafficLimit: Throttles traffic.

  • TrafficMirror: Mirrors traffic.

  • Cors: Enables cross-origin resource sharing (CORS).

Note

A forwarding rule must contain one of the following actions: ForwardGroup, Redirect, or FixedResponse. This terminating action must be the last one executed in the rule.

ForwardGroup
TrafficLimitConfig

object

No

The traffic throttling configuration.

QPS

integer

No

The number of queries per second (QPS). Valid values: 1 to 1000000.

100
PerIpQps

integer

No

The number of QPS for each source IP address. Valid values: 1 to 1000000.

Note

If you also configure QPS, the value of PerIpQps must be smaller than the value of QPS.

80
TrafficMirrorConfig

object

No

The traffic mirroring configuration.

TargetType

string

No

The type of the destination to which traffic is mirrored. Valid values:

  • ForwardGroupMirror: Mirrors traffic to a server group.

ForwardGroupMirror
MirrorGroupConfig

object

No

The server groups to which traffic is mirrored.

ServerGroupTuples

array<object>

No

The server groups to which traffic is mirrored.

object

No

The server groups to which traffic is mirrored.

ServerGroupId

string

No

The ID of the server group.

sgp-00mkgijak0w4qgz9****
RemoveHeaderConfig

object

No

The header removal configuration.

Key

string

No

The name of the header to be removed. The name must be 1 to 40 characters in length and can contain letters, digits, underscores (_), and hyphens (-). Header names cannot be duplicated in RemoveHeaderConfig.

  • For requests (Direction is Request): The following header names are not allowed (case-insensitive): slb-id, slb-ip, x-forwarded-for, x-forwarded-proto, x-forwarded-eip, x-forwarded-port, x-forwarded-client-srcport, connection, upgrade, content-length, transfer-encoding, keep-alive, te, host, cookie, remoteip, authority, and x-forwarded-host.

  • For responses (Direction is Response): The following header names are not allowed (case-insensitive): connection, upgrade, content-length, and transfer-encoding.

test
CorsConfig

object

No

The cross-origin resource sharing (CORS) configuration.

AllowOrigin

array

No

The list of allowed origins. You can specify a single value of *, or one or more specific values.

  • A specific value must start with http:// or https://, followed by a valid domain or a wildcard domain. (Example: http://*.test.abc.example.com)

  • A value can either omit the port or specify a port in the range of 1 to 65535.

string

No

The allowed origin.

http://example.com
AllowMethods

array

No

The allowed HTTP methods for CORS requests.

string

No

The allowed HTTP method for CORS requests. Valid values:

  • GET

  • POST

  • PUT

  • DELETE

  • HEAD

  • OPTIONS

  • PATCH

GET
AllowHeaders

array

No

The list of allowed headers for CORS.

string

No

The allowed header. You can specify a single value of * or a specific header name. The name can be up to 32 characters in length and can contain letters, digits, underscores (_), and hyphens (-). Underscores (_) and hyphens (-) cannot be the first or last character.

test_123
ExposeHeaders

array

No

The list of allowed exposed headers.

string

No

The allowed exposed header. You can specify a single value of * or a specific header name. The name can be up to 32 characters in length and can contain letters, digits, underscores (_), and hyphens (-). Underscores (_) and hyphens (-) cannot be the first or last character.

test_123
AllowCredentials

string

No

Specifies whether to allow requests to carry credentials. Valid values:

  • on: Allows requests to carry credentials.

  • off: Disables carrying credentials in requests.

on
MaxAge

integer

No

The maximum time, in seconds, that a preflight request can be cached by the browser.

Valid values: -1 to 172800.

1000
RuleConditions

array<object>

Yes

A list of conditions for the forwarding rule.

array<object>

Yes

A condition for the forwarding rule.

CookieConfig

object

No

The cookie configuration.

Values

array<object>

No

A list of cookie values.

object

No

A cookie key-value pair.

Key

string

No

The key of the cookie.

  • It must be 1 to 100 characters in length.

  • It can contain printable characters, asterisks (*), and question marks (?). Letters must be lowercase.

  • It cannot contain spaces or the following special characters: ;#[]{}\|<>&".

test
Value

string

No

The value of the cookie.

  • It must be 1 to 100 characters in length.

  • It can contain printable characters, asterisks (*), and question marks (?). Letters must be lowercase.

  • It cannot contain spaces or the following special characters: ;#[]{}\|<>&".

test
HeaderConfig

object

No

The header configuration.

Key

string

No

The key of the header.

  • It must be 1 to 40 characters in length.

  • It can contain letters, digits, hyphens (-), and underscores (_).

  • The Cookie and Host headers are not supported.

Port
Values

array

No

A list of header values.

string

No

An HTTP header value. Header values for the same key must be unique within the condition.

  • It must be 1 to 128 characters in length.

  • It can contain printable characters with an ASCII value in the range of ch >= 32 && ch < 127, asterisks (*), and question marks (?). It cannot contain double quotation marks (").

  • It cannot start or end with a space, or end with a backslash (\).

5006
HostConfig

object

No

The host configuration.

Values

array

No

A list of hostnames.

string

No

The hostname.

  • The hostname must be 3 to 128 characters in length and can contain lowercase letters, digits, hyphens (-), periods (.), asterisks (*), equal signs (=), tildes (~), underscores (_), plus signs (+), backslashes (\), carets (^), exclamation points (!), dollar signs ($), ampersands (&), vertical bars (|), parentheses (()), square brackets ([]), and question marks (?).

  • The hostname must contain at least one period (.) and cannot start or end with a period (.).

  • The rightmost domain label can contain only letters and wildcards, and cannot contain digits or hyphens (-). The leftmost domain label can be an asterisk (*).

  • A domain label cannot start or end with a hyphen (-). You can use asterisks (*) and question marks (?) as wildcards anywhere in a domain label.

  • For exact matches and wildcards, the first character cannot be a tilde (~).

  • For regular expression matches (case-insensitive), the first character cannot be an asterisk (*).

www.example.edu
MethodConfig

object

No

The request method configuration.

Values

array

No

A list of request methods.

string

No

A request method.

Valid values: HEAD, GET, POST, OPTIONS, PUT, PATCH, and DELETE.

PUT
PathConfig

object

No

The path configuration.

Values

array

No

A list of paths.

string

No

A path.

  • The path must be 1 to 128 characters in length, case-sensitive, and can contain asterisks (*) and question marks (?) as wildcards.

  • For non-regular expressions, the path must start with a forward slash (/) and can contain letters, digits, and the following special characters: $-_.+/&~@:'*?. It cannot contain “%#;!()[]^,”\".

  • For regular expressions, the path must start with ~ and can contain letters, digits, and the following special characters: .-_/=?~^*$:()[]+|.

/test
QueryStringConfig

object

No

The query string configuration.

Values

array<object>

No

A list of query strings.

object

No

A query string.

Key

string

No

The key of the query string.

  • It must be 1 to 100 characters in length.

  • It can contain printable characters, asterisks (*), and question marks (?). Letters must be lowercase. It cannot contain spaces or the following special characters: #[]{}\|<>&".

test
Value

string

No

The value of the query string.

  • It must be 1 to 128 characters in length.

  • It can contain printable characters, asterisks (*), and question marks (?). It cannot contain spaces or the following special characters: #[]{}\|<>&". Letters must be lowercase.

test
ResponseStatusCodeConfig

object

No

The response status code configuration.

Values

array

No

A list of response status codes.

string

No

A response status code.

test
ResponseHeaderConfig

object

No

The header condition configuration.

Key

string

No

The key of the header.

  • It must be 1 to 40 characters in length.

  • It can contain letters, digits, hyphens (-), and underscores (_).

  • The Cookie and Host headers are not supported.

test
Values

array

No

A list of header values.

string

No

A header value.

  • It must be 1 to 128 characters in length.

  • It can contain printable characters with an ASCII value in the range of ch >= 32 && ch < 127, lowercase letters, asterisks (*), and question marks (?). It cannot contain double quotation marks (").

  • It cannot start or end with a space, or end with a backslash (\).

50006
Type

string

Yes

The forwarding rule type. Valid values:

  • Host: host.

  • Path: path.

  • Header: An HTTP header.

  • QueryString: The query string.

  • Method: The request method.

  • Cookie: Cookie.

  • SourceIp: The source IP address.

  • ResponseHeader: The response HTTP header.

  • ResponseStatusCode: The response status code.

Host
SourceIpConfig

object

No

The configuration for matching service traffic based on the source IP. This is required and takes effect when Type is set to SourceIP.

Values

array

No

A service traffic matching list based on the source IP.

string

No

Add one or more IP addresses or IP address ranges.

192.168.0.0/32
RuleName

string

Yes

The name of the forwarding rule.

  • The length must be 2 to 128 English or Chinese characters.

  • The name must start with a letter, a Chinese character, or a number, and can contain numbers, periods (.), underscores (_), hyphens (-), and spaces.

rule-doc
Tag

array<object>

No

Tag list.

object

No

Tag structure.

Key

string

No

The tag key can be up to 128 characters in length and cannot start with aliyun or acs: or contain http:// or https://.

env
Value

string

No

The value cannot exceed 128 characters, start with aliyun or acs:, or contain http:// or https://.

product

Response elements

Element

Type

Description

Example

object

The response body.

JobId

string

The ID of the asynchronous task.

72dcd26b-f12d-4c27-b3af-18f6aed5****
RequestId

string

The request ID.

365F4154-92F6-4AE4-92F8-7FF34B540750
RuleId

string

The ID of the forwarding rule.

rule-a3x3pg1yohq3lq****

Examples

Success response

JSON format

{
  "JobId": "72dcd26b-f12d-4c27-b3af-18f6aed5****",
  "RequestId": "365F4154-92F6-4AE4-92F8-7FF34B540750",
  "RuleId": "rule-a3x3pg1yohq3lq****"
}

Error codes

HTTP status code

Error code

Error message

Description
400 IncorrectStatus.Listener The status of %s [%s] is incorrect.
400 OperationDenied.SameGroupForForwardAndMirrorAction The operation is not allowed because of %s. The operation is not allowed because of %s.
400 OperationDenied.IpGroupCanNotUsedForMirrorAction The operation is not allowed because of %s. The operation is not allowed because of %s.
400 OperationDenied.GRPCServerGroup The operation is not allowed because of %s.
400 Conflict.Priority There is already %s having the same configuration with %s.
400 ResourceQuotaExceeded.LoadBalancerRulesNum The quota of %s is exceeded for resource %s, usage %s/%s.
400 ResourceQuotaExceeded.ServerGroupAttachedNum The quota of %s is exceeded for resource %s, usage %s/%s.
400 ResourceQuotaExceeded.LoadBalancerServersNum The quota of %s is exceeded for resource %s, usage %s/%s.
400 ResourceQuotaExceeded.ServerAddedNum The quota of %s is exceeded for resource %s, usage %s/%s.
400 QuotaExceeded.RuleWildcardsNum The quota of %s is exceeded, usage %s/%s. The quota of %s is exceeded, usage %s/%s.
400 QuotaExceeded.RuleMatchEvaluationsNum The quota of %s is exceeded, usage %s/%s.
400 QuotaExceeded.RuleActionsNum The quota of %s is exceeded, usage %s/%s. The quota of %s is exceeded. Usage: %s/%s.
400 Mismatch.Protocol The %s is mismatched for %s and %s. The %s is mismatched for %s and %s.
400 Mismatch.VpcId The %s is mismatched for %s and %s. The %s is mismatched for %s and %s.
400 OperationDenied.RewriteMissingForwardGroup The operation is not allowed because of RewriteMissingForwardGroup. The operation is not allowed because rewrite is missing the forward group.
400 ResourceInConfiguring.Listener The specified listener is being configured, please try again later.
400 OperationDenied.MirrorActionSupportHttpGroupOnly The operation is not allowed because of MirrorActionSupportHttpGroupOnly.
400 OperationDenied.ProtocolMustSameForForwardGroupAction The operation is not allowed because of ProtocolMustSameForForwardGroupAction.
404 ResourceNotFound.Listener The specified resource %s is not found.
404 ResourceNotFound.ServerGroup The specified resource %s is not found.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.