All Products
Search
Document Center

Server Load Balancer:CreateRule

Last Updated:Jul 17, 2024

Creates a forwarding rule for a listener.

Operation description

Take note of the following limits:

  • When you configure the Redirect action, you can use the default value only for the HttpCode parameter. Do not use the default values for the other parameters.

  • If you specify the Rewrite action together with other actions in a forwarding rule, make sure that the ForwardGroup action is specified.

  • CreateRule 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 a forwarding rule.

    • If a forwarding rule is in the Provisioning state, the forwarding rule is being created.
    • If a forwarding rule is in the Available state, the forwarding rule is created.
  • You can set RuleConditions and RuleActions to add conditions and actions to a forwarding rule. The limits on conditions and actions are:

    • Limits on conditions: 5 for a basic Application Load Balancer (ALB) instance, 10 for a standard ALB instance, and 10 for a WAF-enabled ALB instance.
    • Limits on actions: 3 for a basic ALB instance, 5 for a standard ALB instance, and 5 for 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.

Authorization information

There is currently no authorization information disclosed in the API.

Request parameters

ParameterTypeRequiredDescriptionExample
ListenerIdstringYes

The listener ID of the ALB instance.

lsr-bp1bpn0kn908w4nbw****
ClientTokenstringNo

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
DryRunbooleanNo

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 performs the actual request. If the request passes the dry run, a 2xx HTTP status code is returned and the operation is performed.
false
PriorityintegerYes

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
DirectionstringNo

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

  • Request (default): The forwarding rule is applied to the requests received by ALB.
  • Response: The forwarding rule is applied to the responses returned by backend servers.
Note Basic ALB instances do not support the Response value.
Request
RuleActionsarray<object>Yes

The maximum cache time of dry run requests in the browser. Unit: seconds.

Valid values: -1 to 172800.

objectYes

The headers that can be exposed. You can specify an asterisk (*) or one or more values. Separate multiple values with commas (,). A single 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.

FixedResponseConfigobjectNo

The configuration of the custom response.

ContentstringNo

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

dssacav
ContentTypestringNo

The format of the response.

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

text/plain
HttpCodestringNo

The HTTP status code in the response. Valid values: HTTP_2xx, HTTP_4xx, and HTTP_5xx. x must be a digit.

HTTP_200
ForwardGroupConfigobjectNo

The server groups to which requests are distributed. Each forwarding rule supports at most five server groups.

ServerGroupTuplesarray<object>No

The server groups to which requests are distributed. Each forwarding rule supports at most five server groups.

objectNo

The server groups to which requests are distributed.

ServerGroupIdstringNo

The server group to which requests are distributed.

sgp-k86c1ov501id6p****
WeightintegerNo

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
ServerGroupStickySessionobjectNo

The configuration of session persistence for server groups.

EnabledbooleanNo

Specifies whether to enable session persistence. Valid values:

  • true
  • false (default)
false
TimeoutintegerNo

The timeout period of sessions. Unit: seconds. Valid values: 1 to 86400. Default value: 1000.

100
InsertHeaderConfigobjectNo

The configuration of the header to be inserted.

KeystringNo

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 (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, and authority.
key
ValuestringNo

The value of the header to be inserted.

  • If ValueType is set to SystemDefined, you can specify one of the following header values:

    • 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 listening port.
  • If ValueType is set to UserDefined, you can specify a custom header value. 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 lower than 127. You can use asterisks (*) and question marks (?) as wildcards. The 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
ValueTypestringNo

The type of header. Valid values:

  • UserDefined: a custom header
  • ReferenceHeader: a header that references one of the request headers
  • SystemDefined: a header predefined by the system
UserDefined
OrderintegerYes

The priority of the action. Valid values: 1 to 50000. A smaller 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.

1
RedirectConfigobjectNo

The redirect configuration.

Note When you configure the RedirectConfig action, you can use the default value only for the httpCode parameter. Do not use the default values for the other parameters.
HoststringNo

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. Make sure that the custom value meets the following requirements:

    • The hostname must be 3 to 128 characters in length, and can contain lowercase letters, digits, and the following special characters: - . * = ~ _ + \ ^ ! $ & | ( ) [ ] ?.
    • The hostname must contain at least one period (.) but 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 (*).
    • The domain labels cannot start or end with a hyphen (-).
    • You can use asterisks (*) and question marks (?) anywhere in a domain label as wildcard characters.
${host}
HttpCodestringNo

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

301
PathstringNo

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.

  • A custom value. You must make sure that the custom value meets the following requirements:

    • The value must be 1 to 128 characters in length, and can contain asterisks (*) and question marks (?) as wildcards. The value is case-sensitive.
    • 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.
/test
PortstringNo

The port to which requests are redirected.

  • ${port} (default): If you set the value to ${port}, you cannot add other characters to the value.
  • You can also enter a port number. Valid values: 1 to 63335.
10
ProtocolstringNo

The redirect protocol. Valid values:

  • ${protocol} (default): If you set the value to ${protocol}, you cannot add other characters to the value.
  • HTTP or HTTPS.
Note HTTPS listeners support only HTTPS to HTTPS redirects.
HTTP
QuerystringNo

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. You can specify one or more of the preceding variables in each request. You can also combine them with a custom value.

  • A custom value. You must make sure that the custom value meets the following requirements:

    • The value must be 1 to 128 characters in length.
    • It can contain printable characters, except space characters, the special characters # [ ] { } \ | < > &, and uppercase letters.
${query}
RewriteConfigobjectNo

The rewrite configuration.

Note If multiple actions are configured within a forwarding rule, you must set RewriteConfig to the value of ForwardGroup.
HoststringNo

The hostname to which requests are redirected. Valid values:

  • ${host} (default): If you set the value to ${host}, you cannot append other characters.

  • If you want to specify a custom value, make sure that the following requirements are met:

    • The hostname must be 3 to 128 characters in length, and can contain lowercase letters, digits, and the following special characters: - . * = ~ _ + \ ^ ! $ & | ( ) [ ] ?.
    • The hostname must contain at least one period (.) but 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 (*).
    • The domain labels cannot start or end with a hyphen (-). You can use asterisks (*) and question marks (?) anywhere in a domain label as wildcard characters.
www.example.com
PathstringNo

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.

  • A custom value. You must make sure that the custom value meets the following requirements:

    • The value must be 1 to 128 characters in length, and can contain asterisks (*) and question marks (?) as wildcards. The value is case-sensitive.
    • 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.
/tsdf
QuerystringNo

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. You can specify one or more of the preceding variables in each request. You can also combine them with a custom value.

  • A custom value. You must make sure that the custom value meets the following requirements:

    • The value must be 1 to 128 characters in length.
    • It can contain printable characters, except space characters, the special characters # [ ] { } \ | < > &, and uppercase letters.
${query}
TypestringYes

The action type. Valid values:

  • ForwardGroup: forwards a request to multiple vServer groups.
  • Redirect: redirects a request.
  • FixedResponse: returns a custom response.
  • Rewrite: rewrites a request.
  • InsertHeader: inserts a header.
  • RemoveHeaderConfig: deletes a header.
  • TrafficLimitConfig: throttles network traffic.
  • TrafficMirrorConfig: mirrors traffic.
  • CorsConfig: forwards requests based on 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 the ForwardGroup, Redirect, or FixedResponse action as the FinalType action.
  • ExtType: the action or the actions to be performed before the FinalType action. A forwarding rule can contain one or more ExtType actions. To specify this parameter, you must also specify FinalType. You can specify multiple InsertHeader actions or one Rewrite action.
ForwardGroup
TrafficLimitConfigobjectNo

The action to throttle traffic.

QPSintegerNo

The queries per second (QPS). Valid values: 1 to 100000.

100
PerIpQpsintegerNo

The QPS of each IP address. Valid values: 1 to 100000.

Note If both the QPS and PerIpQps properties are specified, make sure that the value of the QPS property is smaller than the value of the PerIpQps property.
80
TrafficMirrorConfigobjectNo

The action to mirror traffic.

TargetTypestringNo

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

  • ForwardGroupMirror: a server group
  • SlsMirror: Log Service
ForwardGroupMirror
MirrorGroupConfigobjectNo

The configuration of the server group to which traffic is mirrored.

ServerGroupTuplesarray<object>No

The configuration of the server group to which traffic is mirrored.

objectNo

The server group to which network traffic is mirrored.

ServerGroupIdstringNo

The ID of the server group.

sgp-00mkgijak0w4qgz9****
CorsConfigobjectNo

The origins allowed.

AllowOriginarrayNo

The allowed origins of CORS requests.

stringNo

The source site that is allowed to access the destination. You can specify an asterisk (*) or one or more values. The values cannot be asterisks (*).

  • A value must start with http:// or https://, followed by a valid domain name or a first-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
AllowMethodsarrayNo

The allowed HTTP methods for CORS requests.

stringNo

The allowed HTTP methods for CORS requests. Valid values:

  • GET
  • POST
  • PUT
  • DELETE
  • HEAD
  • OPTIONS
  • PATCH
GET
AllowHeadersarrayNo

The allowed headers for CORS requests.

stringNo

The allowed headers for CORS requests. You can specify an asterisk (*) or one or more values. Separate multiple values with commas (,). A 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
ExposeHeadersarrayNo

The headers that can be exposed.

stringNo

The headers that can be exposed. You can specify * or specify one or more values. Separate multiple values with commas (,). A 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
AllowCredentialsstringNo

Specifies whether credentials can be carried in CORS requests. Valid values:

  • on: yes
  • off: no
on
MaxAgelongNo

The maximum cache time of dry run requests in the browser. Unit: seconds.

Valid values: -1 to 172800.

1000
RuleConditionsarray<object>Yes

The configuration of the source IP-based forwarding rule.

objectYes

The IP addresses or CIDR blocks.

CookieConfigobjectNo

The configurations of the cookies.

Valuesarray<object>No

The cookie values.

objectNo

The value construct of the cookie.

KeystringNo

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.
  • The key can contain printable characters, except uppercase letters, space characters, and the following special characters: ; # [ ] { } \ | < > &.
test
ValuestringNo

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.
  • The value can contain printable characters, except uppercase letters, space characters, and the following special characters: ; # [ ] { } \ | < > &.
test
HeaderConfigobjectNo

The configuration of the header.

KeystringNo

The key of the header.

  • The key must be 1 to 40 characters in length.
  • It can contain lowercase letters, digits, hyphens (-), and underscores (_).
  • Cookie and Host are not supported.
Port
ValuesarrayNo

The value of the header.

stringNo

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
HostConfigobjectNo

The configurations of the host.

ValuesarrayNo

The hostname.

stringNo

The hostname. Each match condition of a forwarding rule can contain only one hostname. The hostname must be unique.

  • The hostname must be 3 to 128 characters in length, and can contain lowercase letters, digits, and the following special characters: - . * = ~ _ + \ ^ ! $ & | ( ) [ ] ?.
  • The hostname must contain at least one period (.) but 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 (*).
  • The domain labels cannot start or end with a hyphen (-). You can use asterisks (*) and question marks (?) anywhere in a domain label as wildcard characters.
  • If you enter a specific hostname or a wildcard hostname, the hostname cannot start with a tilde (~).
  • If you enter a regular expression, the regular expression cannot start with an asterisk (*). The regular expression is not case-sensitive.
www.example.edu
MethodConfigobjectNo

The configurations of the request methods.

ValuesarrayNo

The request methods.

stringNo

The request methods.

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

PUT
PathConfigobjectNo

The configurations of the URLs.

ValuesarrayNo

The path.

stringNo

The path. Valid values:

  • The path must be 1 to 128 characters in length, and can contain asterisks (*) and question marks (?) as wildcards. The path is case-sensitive.
  • If the URL path is not a regular expression, 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.
  • If the URL path is a regular expression, it must start with a tilde (~) and can contain letters, digits, and the following special characters: . - _ / = ? ~ ^ * $ : ( ) [ ] + |.
/test
QueryStringConfigobjectNo

The configurations of the query strings.

Valuesarray<object>No

The query strings.

objectNo

The query strings.

KeystringNo

The key of the query string.

  • The key must be 1 to 100 characters in length.
  • You can use asterisks (*) and question marks (?) as wildcards. The key can contain printable characters, except uppercase letters, space characters, and the following special characters: # [ ] { } \ | < > &.
test
ValuestringNo

The value of the query string.

  • The value must be 1 to 128 characters in length.
  • It can contain printable characters, except uppercase letters, space characters, and the following special characters: # [ ] { } \ | < > &. You can use asterisks (*) and question marks (?) as wildcard characters.
test
TypestringYes

The type of forwarding rule. Valid values:

  • Host: Requests are distributed based on hosts.
  • Path: Requests are distributed based on paths.
  • Header: Requests are distributed based on HTTP headers.
  • QueryString: Requests are distributed based on query strings.
  • Method: Requests are distributed based on request methods.
  • Cookie: Requests are distributed based on cookies.
  • SourceIp: Requests are distributed based on source IP addresses.
Host
SourceIpConfigobjectNo

The configuration of the source IP-based forwarding rule. This parameter is required and takes effect only when Type is set to SourceIP.

ValuesarrayNo

The configuration of the source IP-based forwarding rule.

stringNo

The IP addresses or CIDR blocks.

192.168.0.0/32
RuleNamestringYes

The name of the forwarding rule.

  • 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.
rule-doc

Response parameters

ParameterTypeDescriptionExample
object

The response parameters.

JobIdstring

The ID of the asynchronous task.

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

The request ID.

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

The forwarding rule ID.

rule-a3x3pg1yohq3lq****

Examples

Sample success responses

JSONformat

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

Error codes

HTTP status codeError codeError messageDescription
400IncorrectStatus.ListenerThe status of %s [%s] is incorrect.The status of %s [%s] is incorrect.
400OperationDenied.SameGroupForForwardAndMirrorActionThe operation is not allowed because of %s.The operation is not allowed because of %s.
400OperationDenied.IpGroupCanNotUsedForMirrorActionThe operation is not allowed because of %s.The operation is not allowed because of %s.
400OperationDenied.GRPCServerGroupThe operation is not allowed because of %s.The operation is not allowed because of %s.
400Conflict.PriorityThere is already %s having the same configuration with %s.There is already %s having the same configuration with %s.
400ResourceQuotaExceeded.LoadBalancerRulesNumThe quota of %s is exceeded for resource %s, usage %s/%s.The quota of %s is exceeded for resource %s. Usage: %s/%s.
400ResourceQuotaExceeded.ServerGroupAttachedNumThe quota of %s is exceeded for resource %s, usage %s/%s.The quota of %s is exceeded for resource %s, usage %s/%s.
400ResourceQuotaExceeded.LoadBalancerServersNumThe quota of %s is exceeded for resource %s, usage %s/%s.The quota of %s is exceeded for resource %s. Usage: %s/%s.
400ResourceQuotaExceeded.ServerAddedNumThe quota of %s is exceeded for resource %s, usage %s/%s.The quota of %s is exceeded for resource %s. Usage: %s/%s.
400QuotaExceeded.RuleWildcardsNumThe quota of %s is exceeded, usage %s/%s.The quota of %s is exceeded, usage %s/%s.
400QuotaExceeded.RuleMatchEvaluationsNumThe quota of %s is exceeded, usage %s/%s.The quota of %s is exceeded. Usage: %s/%s.
400QuotaExceeded.RuleActionsNumThe quota of %s is exceeded, usage %s/%s.The quota of %s is exceeded. Usage: %s/%s.
400Mismatch.ProtocolThe %s is mismatched for %s and %s.The %s is mismatched for %s and %s.
400Mismatch.VpcIdThe %s is mismatched for %s and %s.The %s is mismatched for %s and %s.
400OperationDenied.RewriteMissingForwardGroupThe operation is not allowed because of RewriteMissingForwardGroup.The operation is not allowed because rewrite is missing the forward group.
400ResourceInConfiguring.ListenerThe specified listener is being configured, please try again later.-
400OperationDenied.MirrorActionSupportHttpGroupOnlyThe operation is not allowed because of MirrorActionSupportHttpGroupOnly.-
400OperationDenied.ProtocolMustSameForForwardGroupActionThe operation is not allowed because of ProtocolMustSameForForwardGroupAction.-
404ResourceNotFound.ListenerThe specified resource %s is not found.The specified resource %s is not found.
404ResourceNotFound.ServerGroupThe specified resource %s is not found.The specified resource %s is not found.

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

Change history

Change timeSummary of changesOperation
2024-01-18The Error code has changedView Change Details
2023-11-09The Error code has changedView Change Details