CreateCustomRoutingEndpointGroups - Global Accelerator - Alibaba Cloud Documentation Center

You can call the CreateCustomRoutingEndpointGroups operation to create endpoint groups for a custom routing listener.

Operation description

Global Accelerator distributes traffic to endpoints in an endpoint group based on the forwarding method that is defined for the listener.

If you configure an intelligent routing listener, the Global Accelerator instance automatically selects the nearest and healthiest endpoint group to forward traffic. This ensures that network requests from clients are forwarded to healthy endpoints.
If you configure a custom routing listener, the Global Accelerator instance can generate a port mapping table based on the listener port range, the protocols and port ranges of the destination endpoint groups, and the IP addresses of the endpoints (vSwitches). This way, traffic can be deterministically routed to specific IP addresses and ports of vSwitches.

This operation is used to create endpoint groups for a custom routing listener. To create endpoint groups for an intelligent routing listener, see CreateEndpointGroup.

Before you call this operation, note the following:

CreateCustomRoutingEndpointGroups is an asynchronous operation. After you send a request, the system returns a request ID and runs the task in the background. The endpoint groups are not created immediately. You can call the DescribeCustomRoutingEndpointGroup or ListCustomRoutingEndpointGroups operation to query the status of the endpoint groups.
- If an endpoint group is in the init state, it is being created. In this case, you can perform only query operations.
- If all endpoint groups are in the active state, they are created.
The CreateCustomRoutingEndpointGroups operation cannot be called repeatedly to create endpoint groups for the same Global Accelerator instance.

Prerequisites

Before you create endpoint groups for a custom routing listener, make sure that the following requirements are met:

A standard Global Accelerator instance is created. For more information, see CreateAccelerator.
A bandwidth plan is associated with the standard Global Accelerator instance. For more information, see BandwidthPackageAddAccelerator.
An application is deployed to receive and forward requests as a backend service for Global Accelerator. For a custom routing listener, the backend service must be a vSwitch.
You have been granted permission to use custom routing listeners and have created a custom routing listener. The custom routing listener feature is in invitational preview. To use this feature, contact your account manager. To create a custom routing listener, see CreateListener.

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 support 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

ga:CreateCustomRoutingEndpointGroups

create

*CustomRoutingEndpointGroup

acs:ga:{#regionId}:{#accountId}:ga/{#gaId}

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The region ID of the GA instance. Set the value to cn-hangzhou.	cn-hangzhou
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 RequestId of the request as the ClientToken. The RequestId may be different for each request.	123e4567-e89b-12d3-a456-426655440000
DryRun	boolean	No	Specifies whether to perform a dry run. 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 message is returned. If the request passes the dry run, the `DryRunOperation` error code is returned. false (default): sends a normal request. If the request passes the check, the HTTP 2xx status code is returned and the endpoint groups are created.	false
AcceleratorId	string	Yes	The ID of the GA instance.	ga-bp1odcab8tmno0hdq****
ListenerId	string	Yes	The ID of the custom routing listener.	lsr-bp1bpn0kn908w4nbw****
EndpointGroupConfigurations	array<object>	Yes	The configurations of the endpoint groups. You can specify up to five endpoint groups.
	array<object>	No	The configurations of the endpoint groups. You can specify up to five endpoint groups.
EndpointGroupRegion	string	Yes	The region ID of the endpoint group. You can specify up to five endpoint group region IDs.	cn-hangzhou
Name	string	No	The name of the endpoint group. The name must be 1 to 128 characters in length, and can contain letters, digits, underscores (_), and hyphens (-). The name must start with a letter. You can specify up to five endpoint group names.	test
Description	string	No	The description of the endpoint group. The description can be up to 256 characters in length and cannot contain `http://` or `https://`. You can specify up to five endpoint group descriptions.	test
DestinationConfigurations	array	No	The mapping configurations of the endpoint group. You must specify the port ranges and protocols for the backend service. The specified port ranges and protocols are mapped to the port ranges of the listener. You can specify up to 20 mapping configurations for each endpoint group.
	object	No	The mapping configurations of the endpoint group. You must specify the port ranges and protocols for the backend service. The specified port ranges and protocols are mapped to the port ranges of the listener. You can specify up to 20 mapping configurations for each endpoint group.
Protocols	array	No	The protocols of the backend service. You can specify up to four protocols for each mapping configuration.
	string	No	The protocol of the backend service. Valid values: TCP: TCP. UDP: UDP. TCP,UDP: TCP and UDP. You can specify up to four protocols for each mapping configuration.	TCP
FromPort	integer	No	The first port of the backend service. Valid values: 1 to 65499. The value of FromPort must be smaller than or equal to the value of ToPort. You can specify up to 20 first ports of the backend service for each endpoint group.	80
ToPort	integer	No	The last port of the backend service. Valid values: 1 to 65499. The value of FromPort must be smaller than or equal to the value of ToPort. You can specify up to 20 last ports of the backend service for each endpoint group.	80
EndpointConfigurations	array	No	The configurations of the endpoints. You can specify up to 10 endpoints for each endpoint group.
	array<object>	No	The configurations of the endpoints. You can specify up to 10 endpoints for each endpoint group.
Type	string	No	The type of the backend service. Valid values: PrivateSubNet (default): a private CIDR block.	PrivateSubNet
Endpoint	string	No	The name of the vSwitch.	vsw-test01
TrafficToEndpointPolicy	string	No	The traffic policy for the backend service. Valid values: AllowAll: allows all traffic to the backend service. DenyAll (default): denies all traffic to the backend service. AllowCustom: allows traffic from specific IP addresses and port ranges to access the backend service. If you set this parameter to AllowCustom, you must specify the IP addresses and port ranges from which traffic is allowed.	DenyAll
PolicyConfigurations	array	No	The configurations of the traffic policies. You can specify up to 20 traffic policies for each endpoint.
	array<object>	No	The configurations of the traffic policies. You can specify up to 20 traffic policies for each endpoint.
Address	string	No	The IP address that is allowed to access the backend service. This parameter is required only when TrafficToEndpointPolicy is set to AllowCustom. You can specify up to 20 IP addresses for each endpoint.	10.0.XX.XX
PortRanges	array	No	The port range that is allowed to access the backend service. The port range must be within the port range of the backend service. If you leave this parameter empty, traffic is allowed to access all ports. This parameter is required only when TrafficToEndpointPolicy is set to AllowCustom. You can specify up to 20 port ranges for each endpoint, and up to five port ranges for each traffic policy.
	object	No	The port range that is allowed to access the backend service. The port range must be within the port range of the backend service. If you leave this parameter empty, traffic is allowed to access all ports. This parameter is required only when TrafficToEndpointPolicy is set to AllowCustom. You can specify up to 20 port ranges for each endpoint, and up to five port ranges for each traffic policy.
FromPort	integer	No	The first port of the allowed port range. The value of this parameter must be in the port range of the backend service. This parameter is required only when TrafficToEndpointPolicy is set to AllowCustom. You can specify up to 20 port ranges for each endpoint, and up to five first ports for each traffic policy.	80
ToPort	integer	No	The last port of the allowed port range. The value of this parameter must be in the port range of the backend service. This parameter is required only when TrafficToEndpointPolicy is set to AllowCustom. You can specify up to 20 port ranges for each endpoint, and up to five last ports for each traffic policy.	80

Response parameters

Parameter	Type	Description	Example
	object	The response.
RequestId	string	The request ID.	04F0F334-1335-436C-A1D7-6C044FE73368
EndpointGroupIds	array	The IDs of the endpoint groups.
	string	The ID of the endpoint group.	epg-bp1dmlohjjz4kqaua****

Examples

Success response

JSON format

{
  "RequestId": "04F0F334-1335-436C-A1D7-6C044FE73368",
  "EndpointGroupIds": [
    "epg-bp1dmlohjjz4kqaua****"
  ]
}

Error codes

HTTP status code	Error code	Error message	Description
400	StateError.Accelerator	accelerator state %s is illegal	The GA instance is in an invalid state %s.
400	NotExist.Accelerator	accelerator %s is not exist	The GA instance %s does not exist.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.