CreateRules - Server Load Balancer - Alibaba Cloud Documentation Center

Creates one or more forwarding rules at a time.

Operation description

When you call this operation, take note of the following limits:

When you configure the Redirect action, you can use the default value for the HttpCode parameter but you cannot use the default values for all of the other parameters.
If you specify the Rewrite action and other actions in a forwarding rule, make sure that one of the actions is ForwardGroup.
CreateRules is an asynchronous operation. After a request is sent, the system returns a request ID and runs the task in the background. You can call the ListRules operation to query the status of forwarding rules.
- If forwarding rules are in the Provisioning state, the forwarding rules are being created.
- If forwarding rules are in the Available state, the forwarding rules have been created.
You can set RuleConditions and RuleActions to add conditions and actions to a forwarding rule. Take note of the following limits on the number of conditions and the number of actions in each forwarding rule:
- Limits on conditions: You can specify at most 5 conditions if you use a basic Application Load Balancer (ALB) instance, at most 10 conditions if you use a standard ALB instance, and at most 10 conditions if you use a WAF-enabled ALB instance.
- Limits on actions: You can specify at most 3 actions if you use a basic ALB instance, at most 5 actions if you use a standard ALB instance, and at most 10 actions if you use a WAF-enabled ALB instance.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

Debug

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

Operation: the value that you can use in the Action element to specify the operation on a resource.
Access level: the access level of each operation. The levels are read, write, and list.
Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- The required resource types are displayed in bold characters.
- If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
Condition Key: the condition key that is defined by the cloud service.
Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.

Operation	Access level	Resource type	Condition key	Associated operation
alb:CreateRules	Write	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 listener ID of the ALB instance.	lsr-bp1bpn0kn908w4nbw****
ClientToken	string	No	The client token that is used to ensure the idempotence of the request. You can use the client to generate the token, but you must make sure that the token is unique among different requests. The token can contain only ASCII characters. Note If you do not specify this parameter, the system automatically uses the request ID as the client token. The request ID may be different for each request.	5A2CFF0E-5718-45B5-9D4D-70B3FF3898
DryRun	boolean	No	Specifies whether to perform only a dry run, without performing the actual request. Valid values: true: performs a dry run. The system checks the request for potential issues, including missing parameter values, incorrect request syntax, and service limits. If the request fails the dry run, an error code is returned. If the request passes the dry run, the `DryRunOperation` error code is returned. false (default): performs a dry run and sends the request. If the request passes the dry run, a `2xx HTTP` status code is returned and the operation is performed.	false
Rules	object []	Yes	The forwarding rules. You can specify at most 10 forwarding rules in each call.
Priority	integer	Yes	The priority of the forwarding rule. Valid values: 1 to 10000. A lower value specifies a higher priority. You can specify priorities for at most 10 forwarding rules. Note The priority of each forwarding rule added to a listener must be unique.	10
RuleActions	object []	Yes	The actions of the forwarding rule.
FixedResponseConfig	object	No	The configuration of the custom response. You can specify at most 20 responses.
Content	string	No	The content of the custom response. The content can be up to 1 KB in size and can contain only ASCII characters.	dssacav
ContentType	string	No	The format of the content. Valid values: text/plain text/css text/html application/javascript application/json	text/plain
HttpCode	string	No	The HTTP status code in the response. Valid values: HTTP_2xx, HTTP_4xx, and HTTP_5xx. x must be a digit.	HTTP_200
ForwardGroupConfig	object	No	The configuration of the server group. You can add at most 20 server groups.
ServerGroupTuples	object []	No	The server groups to which requests are forwarded.
ServerGroupId	string	No	The server group to which requests are distributed.	sgp-k86c1ov501id6p****
Weight	integer	No	The weight of the server group. A larger value specifies a higher weight. A server group with a higher weight receives more requests. Valid values: 0 to 100. If only one destination server group exists and you do not specify a weight, the default value 100 is used. If more than one destination server group exists, you must specify weights.	100
ServerGroupStickySession	object	No	The configuration of session persistence for server groups.
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 of sessions. Unit: seconds. Valid values: 1 to 86400.	2
InsertHeaderConfig	object	No	The configuration of the header to be inserted. You can specify at most 20 headers.
Key	string	No	The key of the header. The key must be 1 to 40 characters in length, and can contain letters, digits, underscores (_), and hyphens (-). The header key specified by InsertHeaderConfig must be unique. Note You cannot specify the following header keys: `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`, and `authority`. The header keys are case-insensitive.	key
Value	string	No	The value of the header. If ValueType is set to SystemDefined, one of the following values is supported: ClientSrcPort: the client port. ClientSrcIp: the client IP address. Protocol: the request protocol (HTTP or HTTPS). SLBId: the ID of the ALB instance. SLBPort: the listener port. If ValueType is set to UserDefined, a custom header value is supported. The header value must be 1 to 128 characters in length, and can contain printable characters whose ASCII values are `greater than or equal to 32 and smaller than 127`. You can use asterisks () and question marks (?) as wildcard characters. The header value cannot start or end with a space character. If ValueType* is set to ReferenceHeader, you can reference one of the request headers. The header value must be 1 to 128 characters in length, and can contain lowercase letters, digits, underscores (_), and hyphens (-).	UserDefined
ValueType	string	No	The type of the header. Valid values: UserDefined: a custom header ReferenceHeader: a header that references one of the request headers SystemDefined: a system-defined header	UserDefined
Order	integer	Yes	The priority of the action. Valid values: 1 to 50000. A lower value indicates a higher priority. The actions of a forwarding rule are applied in descending order of priority. This parameter is required. The priority of each action within a forwarding rule must be unique. You can specify priorities for at most 20 actions.	1
RedirectConfig	object	No	The redirect configuration. You can specify at most 20 redirects.
Host	string	No	The hostname to which requests are redirected. Valid values: ${host} (default): If ${host} is returned, no other character is appended. Limits on the value: The hostname must be 3 to 128 characters in length, and can contain lowercase letters, digits, hyphens (-), and periods (.). Asterisks () and question marks (?) can be used as wildcards. The hostname contains at least one period (.) but does not start or end with a period (.). The rightmost domain label can contain only letters and wildcard characters. It does not contain digits or hyphens (-). The domain labels do not start or end with hyphens (-). You can use asterisks () and question marks (?) as wildcards anywhere in a domain label.	www.example.com
HttpCode	string	No	The HTTP status code that indicates the redirect type. Valid values: 301, 302, 303, 307, and 308.	301
Path	string	No	The path to which requests are redirected. Valid values: Default value: ${path}. ${host}, ${protocol}, and ${port} are also supported. Each variable can be specified only once. You can specify one or more of the preceding variables in each request. You can also combine them with a custom value. Limits on the value: The path must be 1 to 128 characters in length. It must start with a forward slash (/) and can contain letters, digits, and the following special characters: `$ - _ .+ / & ~ @ :`. It cannot contain the following special characters: `" % # ; ! ( ) [ ]^ , "`. You can use asterisks (*) and question marks (?) as wildcard characters. The path is case-sensitive.	/test
Port	string	No	The port to which requests are distributed. ${port} (default): If you set the value to ${port}, you cannot add other characters to the value. Other valid values: 1 to 63335.	10
Protocol	string	No	The redirect protocol. Valid values: ${protocol} (default): If ${protocol} is returned, no other character is appended. HTTP or HTTPS. Note HTTPS listeners support only HTTPS to HTTPS redirects.	HTTP
Query	string	No	The query string of the URL to which requests are redirected. Default value: ${query}. ${host}, ${protocol}, and ${port} are also supported. Each variable can be specified only once. The preceding variables can be used at the same time or combined with a custom value. Limits on the value: The query string must be 1 to 128 characters in length. It can contain printable characters, except space characters, the special characters `# [ ] { } \ \| < > &`, and uppercase letters.	quert
RewriteConfig	object	No	The rewrite configuration. You can specify at most 20 rewrites.
Host	string	No	The hostname to which requests are redirected. Valid values: ${host} (default): If you set the value to ${host}, you cannot append other characters. A custom value that meets the following requirements: The hostname must be 3 to 128 characters in length, and can contain lowercase letters, digits, hyphens (-), and periods (.). You can use asterisks () and question marks (?) as wildcard characters. The hostname contains at least one period (.) but does not start or end with a period (.). The rightmost domain label can contain only letters and wildcard characters. It does not contain digits or hyphens (-). The domain labels do not start or end with hyphens (-). You can use asterisks () and question marks (?) anywhere in a domain label as wildcard characters.	www.example.com
Path	string	No	The path to which requests are redirected. Valid values: Default value: ${path}. ${host}, ${protocol}, and ${port} are also supported. Each variable can be specified only once. You can specify one or more of the preceding variables in each request. You can also combine them with a custom value. Limits on the value: The path must be 1 to 128 characters in length. It must start with a forward slash (/) and can contain letters, digits, and the following special characters: `$ - _ .+ / & ~ @ :`. It cannot contain the following special characters: `" % # ; ! ( ) [ ]^ , "`. You can use asterisks (*) and question marks (?) as wildcard characters. The path is case-sensitive.	/tsdf
Query	string	No	The query string of the URL to which requests are redirected. Default value: ${query}. ${host}, ${protocol}, and ${port} are also supported. Each variable can be specified only once. The preceding variables can be used at the same time or combined with a custom value. Limits on the value: The query string must be 1 to 128 characters in length. It can contain printable characters, except space characters, the special characters `# [ ] { } \ \| < > &`, and uppercase letters.	quedsa
Type	string	Yes	The action type. You can specify at most 11 types of actions. Valid values: ForwardGroup: distributes requests to multiple vServer groups. Redirect: redirects a request. FixedResponse: returns a custom response. Rewrite: rewrites a request. InsertHeader: inserts a header. RemoveHeaderConfig: deletes the header of a request. TrafficLimit: throttles traffic. trafficMirror: mirrors network traffic. Cors: enables cross-origin resource sharing (CORS). The following action types are supported: FinalType: the last action to be performed in a forwarding rule. Each forwarding rule can contain only one FinalType action. You can specify a ForwardGroup, Redirect, or FixedResponse action as the FinalType action. ExtType: one or more actions to be performed before the FinalType action. A forwarding rule can contain one or more ExtType actions. To specify an ExtType action, you must specify a FinalType action. You can specify multiple InsertHeader actions or one Rewrite action.	ForwardGroup
TrafficLimitConfig	object	No	The configuration of traffic throttling. You can add at most 20 configuration records.
QPS	integer	No	The queries per second (QPS). Value range: 1 to 1000000.	100
PerIpQps	integer	No	The QPS of each IP address. Value range: 1 to 1000000. Note If QPS and PerIpQps are specified, the value of PerIpQps must be smaller than the value of QPS.	80
TrafficMirrorConfig	object	No	The configuration of traffic mirroring. You can add at most 20 traffic mirrors.
TargetType	string	No	The type of destination to which network traffic is mirrored. Valid values: ForwardGroupMirror: a server group.	ForwardGroupMirror
MirrorGroupConfig	object	No	The configuration of the server group to which traffic is mirrored.
ServerGroupTuples	object []	No	The server group to which traffic is mirrored.
ServerGroupId	string	No	The ID of the server group.	srg-00mkgijak0w4qgz9****
RemoveHeaderConfig	object	No	The configuration of the header to be removed.
Key	string	No	The key of the header to be removed. The key must be 1 to 40 characters in length and can contain letters, digits, underscores, and hyphens (-). The header key must be unique. You cannot specify the following header keys for an inbound forwarding rule: `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`, and `authority`. The preceding keys are case-insensitive. You cannot specify the following header keys for an outbound forwarding rule: `connection`, `upgrade`, `content-length`, and `transfer-encoding`. The preceding keys are case-insensitive.	test
CorsConfig	object	No	The CORS configuration.
AllowOrigin	array	No	The allowed origins of CORS requests.
	string	No	The allowed origin of CORS requests. You can specify an asterisk (``) or one or more values. The value cannot be an asterisk (``). The value must start with `http://` or `https://` and include a valid domain name or top-level wildcard domain name, such as `.test.abc.example.com`. You can specify a port in a value. Port range: 1 to 65535*.	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 allowed headers for CORS requests.
	string	No	The allowed header for CORS requests. You can specify `*` or specify one or more values. Separate multiple values with commas (,). The value can contain only letters and digits. It cannot start or end with an underscore (_) or a hyphen (-). It can be up to 32 characters in length.	test_123
ExposeHeaders	array	No	The headers that can be exposed.
	string	No	The header that can be exposed. You can specify `*` or specify one or more values. Separate multiple values with commas (,). The value can contain only letters and digits. It cannot start or end with an underscore (_) or a hyphen (-). It can be up to 32 characters in length.	test_123
AllowCredentials	string	No	Specifies whether to allow credentials to be carried in CORS requests. Valid values: on: allows credentials to be carried in CORS requests. off: does not allow credentials to be carried in CORS requests.	on
MaxAge	long	No	The maximum cache time of preflight requests in the browser. Unit: seconds. Valid values: -1 to 172800.	1000
RuleConditions	object []	Yes	The conditions of the forwarding rule.
CookieConfig	object	No	The configurations of the cookies. You can add at most 20 cookies.
Values	object []	No	The key-value pairs of cookies.
Key	string	No	The key of the cookie. The key must be 1 to 100 characters in length. You can use asterisks (*) and question marks (?) as wildcard characters. It can contain printable characters, except uppercase letters, space characters, and the following special characters: `; # [ ] { } \ \| < > &`.	test
Value	string	No	The value of the cookie. The value must be 1 to 100 characters in length. You can use asterisks (*) and question marks (?) as wildcard characters. It can contain printable characters, except uppercase letters, space characters, and the following special characters: `; # [ ] { } \ \| < > &`.	test
HeaderConfig	object	No	The configuration of the header. You can add at most 20 headers.
Key	string	No	The key of the header. The key must be 1 to 40 characters in length. It can contain lowercase letters, digits, hyphens (-), and underscores (_). You cannot specify Cookie or Host.	Port
Values	array	No	The values of the header.
	string	No	The value of the header. The header values within a forwarding rule must be unique. The value must be 1 to 128 characters in length. It can contain printable characters whose ASCII values are `greater than or equal to 32 and lower than 127`. You can use asterisks (*) and question marks (?) as wildcard characters. The header value cannot start or end with a space character.	5006
HostConfig	object	No	The configurations of the hosts. You can specify up to 20 resources.
Values	array	No	The hostnames.
	string	No	The hostname. A forwarding rule can contain only one unique hostname. The hostname must be 3 to 128 characters in length, and can contain lowercase letters, digits, hyphens (-), periods (.), asterisks (), and question marks (?). The hostname contains at least one period (.) but does not start or end with a period (.). The rightmost domain label can contain only letters and wildcard characters. It does not contain digits or hyphens (-). The domain labels do not start or end with hyphens (-). You can use asterisks () and question marks (?) anywhere in a domain label as wildcard characters.	www.example.com
MethodConfig	object	No	The configurations of the request methods. You can specify at most 20 request methods.
Values	array	No	The request methods.
	string	No	The request method. Valid values: HEAD, GET, POST, OPTIONS, PUT, PATCH, and DELETE.	PUT
PathConfig	object	No	The configurations of the paths. You can specify at most 20 paths.
Values	array	No	The paths.
	string	No	The path. Limits on the value: The path must be 1 to 128 characters in length. It must start with a forward slash (/) and can contain letters, digits, and the following special characters: `$ - _ .+ / & ~ @ :`. It cannot contain the following special characters: `" % # ; ! ( ) [ ]^ , "`. You can use asterisks (*) and question marks (?) as wildcard characters. The path is case-sensitive.	/test
QueryStringConfig	object	No	The configuration of the query conditions. You can specify at most 20 query conditions.
Values	object []	No	The configurations of the query string.
Key	string	No	They key of the query string. It must be 1 to 100 characters in length. You can use asterisks (*) and question marks (?) as wildcards. The key can contain printable characters, excluding uppercase letters, space characters, and the following special characters: `# [ ] { } \ \| < > &`.	test
Value	string	No	The value of the query string. The value must be 1 to 128 characters in length. It can contain printable characters, excluding uppercase letters, space characters, and the following special characters: `# [ ] { } \ \| < > &`. You can use asterisks (*) and question marks (?) as wildcards.	test
ResponseHeaderConfig	object	No	The configuration of the header. You can add at most 20 headers.
Key	string	No	The key of the header. The key must be 1 to 40 characters in length. It can contain lowercase letters, digits, hyphens (-), and underscores (_). You cannot specify Cookie or Host.	Port
Values	array	No	The values of the header.
	string	No	The value of the header. The value is 1 to 128 characters in length. It can contain printable characters whose ASCII character values are `greater than or equal to 32 and smaller than 127`, excluding uppercase letters. You can use asterisks (*) and question marks (?) as wildcards. The value cannot start or end with a space character.	5006
ResponseStatusCodeConfig	object	No	The configurations of the response status codes.
Values	array	No	The response status codes.
	string	No	The response status code.	200
Type	string	Yes	The type of forwarding rule. You can specify at most seven types. Valid values: Host: Responses are forwarded based on hosts. Path: Responses are forwarded based on paths. Header: Responses are forwarded based on HTTP headers. QueryString: Responses are forwarded based on query strings. Method: Responses are forwarded based on request methods. Cookie: Responses are forwarded based on cookies. SourceIp:: Responses are forwarded based on source IP addresses. ResponseHeader: Responses are forwarded based on HTTP response headers. ResponseStatusCode: Responses are forwarded based on response status codes.	Host
SourceIpConfig	object	No	The configuration of the source IP addresses based on which user traffic is matched. This parameter is required and takes effect only when Type is set to SourceIP. You can specify at most five values for SourceIp.
Values	array	No	The configuration of the source IP addresses based on which user traffic is matched.
	string	No	The IP address or CIDR block based on which user traffic is matched. You can specify at most five values for SourceIp.	192.168.0.0/32
RuleName	string	Yes	The name of the forwarding rule. You can name at most 20 forwarding rules. The name must be 2 to 128 characters in length. It can contain letters, digits, periods (.), underscores (_), and hyphens (-). It must start with a letter.	test
Direction	string	No	The direction to which the forwarding rule is applied. You can specify only one direction. Valid values: Request (default): The forwarding rule is applied to the client requests received by ALB. Response: The forwarding rule is applied to the responses returned by backend servers. Note Basic ALB instances do not support forwarding rules of the Response type.	Request
Tag	object []	No	The tag that you want to add.
Key	string	No	The key of the tag. The tag key can be up to 128 characters in length, and cannot start with acs: or aliyun. It cannot contain http:// or https://.	env
Value	string	No	The value of the tag. The tag value can be up to 128 characters in length, and cannot start with acs: or aliyun. It cannot contain http:// or https://.	product

Response parameters

Parameter	Type	Description	Example
	object	Creates one or more forwarding rules at a time.
JobId	string	The ID of the asynchronous task.	72dcd26b-f12d-4c27-b3af-18f6aed5****
RequestId	string	The request ID.	365F4154-92F6-4AE4-92F8-7FF34B540710
RuleIds	object []	The priority of the forwarding rule. Valid values: 1 to 10000. A lower value specifies a higher priority. Note The priorities of the forwarding rules created for the same listener is unique.
RuleId	string	The forwarding rule ID.	rule-a3x3pg1yohq3lq****
Priority	integer	The priority of the forwarding rule. Valid values: 1 to 10000. A smaller value indicates a higher priority. Note The priorities of the forwarding rules created for the same listener must be unique.	10

Examples

Sample success responses

JSONformat

{
  "JobId": "72dcd26b-f12d-4c27-b3af-18f6aed5****",
  "RequestId": "365F4154-92F6-4AE4-92F8-7FF34B540710",
  "RuleIds": [
    {
      "RuleId": "rule-a3x3pg1yohq3lq****",
      "Priority": 10
    }
  ]
}

Error codes

For a list of error codes, visit the Service error codes.

Change history

Change time

Summary of changes

Operation

2024-01-18

The Error code has changed

see changesets

Change item	Change content
Error Codes	The Error code has changed.
	Error Codes 400 change
	delete Error Codes: 404

2023-11-09

The Error code has changed

see changesets

Change item	Change content
Error Codes	The Error code has changed.
	delete Error Codes: 400
	delete Error Codes: 404

HTTP status code	Error code	Error message	Description
400	IncorrectStatus.Listener	The status of %s [%s] is incorrect.	The status of %s [%s] is incorrect.
400	OperationDenied.IpGroupCanNotUsedForMirrorAction	The operation is not allowed because of %s.	The operation is not allowed because of %s.
400	OperationDenied.SameGroupForForwardAndMirrorAction	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.	The operation is not allowed because of %s.
400	Conflict.Priority	There is already %s having the same configuration with %s.	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.	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.	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.	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.	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.	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.VpcId	The %s is mismatched for %s and %s.	The %s is mismatched for %s and %s.
400	Mismatch.Protocol	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.
404	ResourceNotFound.Listener	The specified resource %s is not found.	The specified resource %s is not found.
404	ResourceNotFound.ServerGroup	The specified resource %s is not found.	The specified resource %s is not found.