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.
Try it now
Test
RAM authorization
Action | Access level | Resource type | Condition key | Dependent action |
alb:CreateRule | create | *LoadBalancer
*ServerGroup
| None | None |
Request parameters
Parameter | Type | Required | Description | Example |
ListenerId | string | Yes | The listener ID of the ALB instance. | lsn-l16uo9y****** |
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-70B****** |
DryRun | boolean | No | Specifies whether to perform only a dry run, without performing the actual request. Valid values:
| false |
Priority | integer | Yes | 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 |
Direction | string | No | The direction to which the forwarding rule is applied. Valid values:
Note Basic ALB instances do not support the Response value. | Request |
| RuleActions | array<object> | Yes | The actions of the forwarding rule. | |
array<object> | Yes | The action of the forwarding rule. | ||
| FixedResponseConfig | object | No | The configuration of the custom response. | |
Content | string | No | The content of the custom response. The content cannot exceed 1 KB in size, and can contain only ASCII characters. | dssacav |
ContentType | string | No | The format of the response. Valid values: text/plain, text/css, text/html, application/javascript, and application/json. | text/plain |
HttpCode | string | No | The HTTP status code in responses. Valid values: 2xx, 4xx, 5xx. The value must be a numeric string. x must be a digit. | 200 |
| ForwardGroupConfig | object | No | The server groups to which requests are forwarded. You can specify at most five server groups for each forwarding rule. | |
| ServerGroupTuples | array<object> | No | The server groups to which requests are forwarded. You can specify at most five server groups for each forwarding rule. | |
object | No | The server group to which requests are forwarded. | ||
ServerGroupId | string | No | The server group to which requests are forwarded. | 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.
| 100 |
| ServerGroupStickySession | object | No | The configuration of session persistence for the server groups. | |
Enabled | boolean | No | Specifies whether to enable session persistence. Valid values:
| false |
Timeout | integer | No | The timeout period of sessions. Unit: seconds. Valid values: 1 to 86400. Default value: 1000. | 100 |
| InsertHeaderConfig | object | No | The key of the header to be inserted. | |
Key | string | No | The key of the header. The header key must be 1 to 40 characters in length, and can contain letters, digits, underscores (_), and hyphens (-). The header keys specified by InsertHeaderConfig must be unique. Note You cannot specify the following header keys: | key |
Value | string | No | The value of the header to be inserted.
| UserDefined |
ValueType | string | No | The type of the header. Valid values:
| UserDefined |
Order | integer | Yes | 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 cannot empty. The priority of each action within a forwarding rule must be unique. | 1 |
| RedirectConfig | object | No | The configuration of the redirect action. Note Do not set all fields in RedirectConfig to default values, except for httpCode. | |
Host | string | No | The hostname to which requests are forwarded. Valid values:
| ${host} |
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 URL to which requests are redirected. Valid values:
| /test |
Port | string | No | The port to which requests are distributed.
| 10 |
Protocol | string | No | The redirect protocol. Valid values:
Note
| HTTP |
Query | string | No | The query string to which requests are redirected.
| ${query} |
| RewriteConfig | object | No | The configuration of the rewrite action. Note If you specify multiple actions for a forwarding rule, you must configure the ForwardGroup parameter for the RewriteConfig action. | |
Host | string | No | The hostname to which requests are redirected. Valid values:
| www.example.com |
Path | string | No | The URL to which requests are redirected. Valid values:
| /tsdf |
Query | string | No | The query string of the URL to which requests are distributed.
| ${query} |
Type | string | Yes | The action. Valid values:
The following action types are supported:
| ForwardGroup |
| TrafficLimitConfig | object | No | The configuration of the traffic throttling action. | |
QPS | integer | No | The queries per second (QPS). Valid values: 1 to 1000000. | 100 |
PerIpQps | integer | No | The number of requests per IP address. Value values: 1 to 1000000. Note If both the QPS and PerIpQps parameters are specified, the value of the QPS parameter is smaller than the value of the PerIpQps parameter. | 80 |
| TrafficMirrorConfig | object | No | The configuration of the traffic mirroring action. | |
TargetType | string | No | The type of destination to which network traffic is mirrored. Valid values:
| ForwardGroupMirror |
| MirrorGroupConfig | object | No | The configuration of the server group to which traffic is mirrored. | |
| ServerGroupTuples | array<object> | No | The configuration of the server group to which traffic is mirrored. | |
object | No | The configuration of the server group to which traffic is mirrored. | ||
ServerGroupId | string | No | The server group ID. | sgp-00mkgijak0w4qgz9**** |
| RemoveHeaderConfig | object | No | The HTTP headers to be removed. | |
Key | string | No | The keys of the headers to be removed. The header keys must be 1 to 40 characters in length, and can contain letters, digits, underscores (_), and hyphens (-). The header keys specified in RemoveHeader must be unique.
| test |
| CorsConfig | object | No | Request forwarding based on CORS. | |
| AllowOrigin | array | No | The trusted origins of CORS requests. You can specify one or more values, or only the wildcard character (
| |
string | No | The allowed origin of CORS requests. | http://example.com | |
| AllowMethods | array | No | The allowed HTTP methods of CORS requests. | |
string | No | The allowed HTTP method of CORS requests. Valid values:
| GET | |
| AllowHeaders | array | No | The trusted headers of CORS requests. | |
string | No | The trusted header of CORS requests. You can specify an asterisk ( | test_123 | |
| ExposeHeaders | array | No | The headers that can be exposed. | |
string | No | The header that can be exposed. You can specify an asterisk ( | test_123 | |
AllowCredentials | string | No | Specifies whether credentials can be carried in CORS requests. Valid values:
| on |
MaxAge | integer | No | The maximum cache time of dry run requests in the browser. Unit: seconds. Valid values: -1 to 172800. | 1000 |
| RuleConditions | array<object> | Yes | The match conditions of the forwarding rule. | |
array<object> | Yes | The match condition of the forwarding rule. | ||
| CookieConfig | object | No | The key-value pairs of the cookie. | |
| Values | array<object> | No | The cookie values. | |
object | No | The cookie value. | ||
Key | string | No | The cookie key.
| test |
Value | string | No | The cookie value.
| test |
| HeaderConfig | object | No | The configuration of the header. | |
Key | string | No | The header key.
| Port |
| Values | array | No | The header values. | |
string | No | The header value. The header values within a forwarding rule must be unique.
| 5006 | |
| HostConfig | object | No | The configuration of the host. | |
| Values | array | No | The hostnames. | |
string | No | The hostname. A forwarding rule can contain only one hostname, which must be unique.
| www.example.edu | |
| MethodConfig | object | No | The configurations of the request method. | |
| 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 URL to which requests are forwarded. | |
| Values | array | No | The forwarding URLs. | |
string | No | The URL to which requests are forwarded. The URL must meet the following requirements:
| /test | |
| QueryStringConfig | object | No | The configuration of the query strings. | |
| Values | array<object> | No | The query strings. | |
object | No | The query string. | ||
Key | string | No | They key of the query string.
| test |
Value | string | No | The value of the query string.
| test |
| ResponseStatusCodeConfig | object | No | The configuration of the response status codes. | |
| Values | array | No | The response status codes. | |
string | No | The response status code. | test | |
| ResponseHeaderConfig | object | No | The configuration of headers. | |
Key | string | No | The header key.
| test |
| Values | array | No | The header values. | |
string | No | The header value.
| 50006 | |
Type | string | Yes | The type of forwarding rule. Valid values:
| Host |
| SourceIpConfig | object | No | Configuration of traffic matching based on source IP addresses. This parameter is required and valid when Type is set to SourceIP. | |
| Values | array | No | The source IP addresses used for traffic matching. | |
string | No | You can specify one or more IP addresses, including CIDR blocks. | 192.168.0.0/32 | |
RuleName | string | Yes | The name of the forwarding rule.
| rule-doc |
| Tag | array<object> | No | The tags. | |
object | No | The tag. | ||
Key | string | No | The tag key. The tag key can be up to 128 characters in length. It cannot start with aliyun or acs: and cannot contain http:// or https://. | env |
Value | string | No | The tag value can be up to 128 characters in length. It cannot start with aliyun or acs: and cannot contain http:// or https://. | product |
Response elements
Element | Type | Description | Example |
object | The response parameters. | ||
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 forwarding rule ID. | 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.