Build and Monitor ALB Server Groups via API - ALB - Alibaba Cloud - Server Load Balancer

Creates a server group in a specified region.

Operation description

The CreateServerGroup operation is asynchronous. After a request is sent, the system returns a request ID. However, the server group is not yet created. The creation task continues to run in the background. You can call ListServerGroups to query the creation status of the server group:

If the server group is in the Creating state, the server group is being created.
If the server group is in the Available state, the server group is created.

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:CreateServerGroup

create

*ServerGroup

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

alb:ServerGroupProtocol

None

Request parameters

Parameter	Type	Required	Description	Example
ServerGroupName	string	Yes	The server group name. The name must be 2 to 128 characters in length, and must start with an uppercase letter, lowercase letter, Chinese character, or digit. The name can contain digits, periods (.), underscores (_), hyphens (-), and spaces.	test
ServerGroupType	string	No	The type of the server group. Valid values: Instance (default): server type. This type of server group supports adding Ecs, Eni, and Eci instances. Ip: IP address type. This type of server group supports adding backend servers by IP address. Fc: Function Compute type. This type supports adding Function Compute-based backend servers.	Instance
VpcId	string	No	The VPC-connected instance ID. Only servers in this VPC can be added to the server group. Note This parameter takes effect only when ServerGroupType is set to Instance or Ip.	vpc-bp15zdkdt37pq72zv****
Scheduler	string	No	The scheduling algorithm. Valid values: Wrr (default): weighted round-robin. Backend servers with higher weights receive more requests. Wlc: weighted least connections. In addition to the weight assigned to each backend server, the actual load (number of connections) is also considered. When the weights are the same, backend servers with fewer current connections receive more requests. Sch: consistent hashing. Requests with the same hash factor are routed to the same backend server. If the UchConfig parameter is not configured, the default hash factor is the source IP address, and requests from the same source IP address are distributed to the same backend server. If the UchConfig parameter is configured, the hash factor is the URL parameter, and requests with the same URL parameter are distributed to the same backend server. Note This parameter takes effect only when ServerGroupType is set to Instance or Ip.	Wrr
Protocol	string	No	The backend protocol. Valid values: HTTP (default): can be associated with HTTPS, HTTP, and QUIC listeners. HTTPS: can be associated with HTTPS listeners. gRPC: can be associated with HTTPS and QUIC listeners. Note You do not need to configure the backend protocol when ServerGroupType is set to Fc.	HTTP
ResourceGroupId	string	No	The resource group ID.	rg-atstuj3rsop****
HealthCheckConfig	object	Yes	The health check configurations.	rg-123
HealthCheckConnectPort	integer	No	The port of the backend server used for health checks. Valid values: 0 to 65535. Default value: 0, which indicates that the port of the backend server is used for health checks.	80
HealthCheckEnabled	boolean	Yes	Specifies whether to enable health checks. Valid values: true: enabled. false: disabled. Note Health checks are enabled by default when ServerGroupType is set to Instance or Ip. Health checks are disabled by default when ServerGroupType is set to Fc.	true
HealthCheckHost	string	No	The domain name used for health checks. Use the internal IP address of the backend server (default): uses the internal IP address of the backend server as the health check domain name. Specify a specific domain name: enter a domain name. The domain name must be 1 to 80 characters in length. The domain name can contain lowercase letters, digits, hyphens (-), and periods (.). The domain name must contain at least one period (.). Periods (.) cannot appear at the beginning or end. The rightmost domain label can contain only letters, not digits or hyphens (-). Hyphens (-) cannot appear at the beginning or end. Note This parameter takes effect only when HealthCheckProtocol is set to HTTP, HTTPS, or gRPC.	www.example.com
HealthCheckCodes	array	No	The list of status codes that indicate a Normal health check status.
	string	No	The status code that indicates a Normal health check status. When HealthCheckProtocol is set to HTTP or HTTPS, valid values for HealthCheckCodes are http_2xx (default), http_3xx, http_4xx, and http_5xx. Separate multiple status codes with commas (,). When HealthCheckProtocol is set to gRPC, valid values for HealthCheckCodes range from 0 to 99. Default value: 0. Range input is supported, with a maximum of 20 range values. Separate multiple range values with commas (,). Note This parameter takes effect when HealthCheckProtocol is set to HTTP, HTTPS, or gRPC.	http_2xx
HealthCheckHttpVersion	string	No	The HTTP version for health checks. Valid values: HTTP1.0 and HTTP1.1 (default). Note This parameter takes effect only when HealthCheckProtocol is set to HTTP or HTTPS.	HTTP1.1
HealthCheckInterval	integer	No	The interval between two consecutive health checks. Unit: seconds. Valid values: 1 to 50. Default value: 2.	2
HealthCheckMethod	string	No	The health check method. Valid values: GET: If the response body exceeds 8 KB, it is truncated. However, this does not affect the health check result. POST: gRPC listener health checks use the POST method by default. HEAD (default): HTTP and HTTPS listener health checks use the HEAD method by default. Note This parameter takes effect only when HealthCheckProtocol is set to HTTP, HTTPS, or gRPC.	HEAD
HealthCheckPath	string	No	The forwarding rule path for health checks. The path must be 1 to 80 characters in length and can contain only letters, digits, and the characters `-/.%?#&=` and the extended characters `_;~!（)[]@$^:',+`. The URL must start with a forward slash (/). Note* This parameter takes effect only when HealthCheckProtocol is set to HTTP or HTTPS.	/test/index.html
HealthCheckProtocol	string	No	The health check protocol. Valid values: HTTP: uses impersonation of browser access behavior by sending HEAD or GET requests to check whether the server application is healthy. HTTPS: uses impersonation of browser access behavior by sending HEAD or GET requests to check whether the server application is healthy. Data encryption is used, which is more secure than HTTP. TCP: sends SYN handshake packets to check whether the server port is alive. gRPC: sends POST or GET requests to check whether the server application is healthy.	HTTP
HealthCheckTimeout	integer	No	The maximum period of time to wait for a response from a health check. If the backend server does not respond correctly within the specified period of time, the health check fails. Unit: seconds. Valid values: 1 to 300. Default value: 5.	5
HealthyThreshold	integer	No	The number of consecutive successful health checks required before the health check status of a backend server changes from fail to success. Valid values: 2 to 10. Default value: 3.	3
UnhealthyThreshold	integer	No	The number of consecutive failed health checks required before the health check status of a backend server changes from success to fail. Valid values: 2 to 10. Default value: 3.	3
StickySessionConfig	object	No	The session persistence configuration. Note This parameter takes effect only when ServerGroupType is set to Instance or Ip.
Cookie	string	No	The cookie configured on the server. The cookie must be 1 to 200 characters in length and can contain only ASCII letters and digits. It cannot contain commas (,), semicolons (;), or spaces, and cannot start with a dollar sign ($). Note This parameter takes effect when StickySessionEnabled is set to true and StickySessionType is set to server.	B490B6EBF6F3CD402E515D22BCDA****
CookieTimeout	integer	No	The cookie timeout period. Unit: seconds. Valid values: 1 to 86400. Default value: 1000. Note This parameter takes effect when StickySessionEnabled is set to true and StickySessionType is set to Insert.	1000
StickySessionEnabled	boolean	No	Specifies whether to enable session persistence. Valid values: true: enabled. false: disabled. Note This parameter takes effect only when ServerGroupType is set to Instance or Ip.	false
StickySessionType	string	No	The method used to handle cookies. Valid values: Insert (default): inserts a cookie. When a client first accesses the load balancer, the load balancer inserts a cookie (SERVERID) into the HTTP or HTTPS response. Subsequent requests that carry this cookie are forwarded to the previously recorded backend server. Server: rewrites a cookie. When the load balancing service detects a user-defined cookie, it rewrites the original cookie. Subsequent requests that carry the new cookie are forwarded to the previously recorded backend server. Note This parameter takes effect when StickySessionEnabled is set to true.	Insert
ClientToken	string	No	The client token that is used to ensure the idempotence of the request. Generate a parameter value from your client to ensure that the value is unique among different requests. ClientToken supports only ASCII characters. Note If you do not specify this parameter, the system uses the RequestId of the API request as the ClientToken. The RequestId may vary for each API request.	5A2CAF0E-5718-45B5-9D4D-70B******
DryRun	boolean	No	Specifies whether to perform a dry run. Valid values: true: performs a dry run without creating the server group. The system checks required parameters, request syntax, and business restrictions. If the check fails, the corresponding error is returned. If the check succeeds, the error code `DryRunOperation` is returned. false (default): sends a normal request. After the check succeeds, an HTTP 2xx status code is returned and the operation is performed.	false
Ipv6Enabled	boolean	No	Specifies whether to enable IPv6.	true
UpstreamKeepaliveEnabled	boolean	No	Specifies whether to enable upstream keepalive connections. true: enabled. false (default): disabled.	false
ServiceName	string	No	This parameter is applicable only to ALB Ingress scenarios and specifies the `K8s Service` name that corresponds to the server group.	test
UchConfig	object	No	The URL consistent hashing parameter settings.
Type	string	Yes	The parameter type. Set the value to QueryString.	QueryString
Value	string	Yes	The consistent hashing parameter value.	abc
ConnectionDrainConfig	object	No	The connection draining configuration. After connection draining is enabled, when a backend server is removed or a health check failure occurs, the load balancing service allows existing connections to continue Normal data transmission for a specified period of time. Note Basic Edition instances do not support connection draining. Only Standard Edition and WAF Enhanced Edition instances support this feature. Server type and IP type server groups support connection draining. Function Compute type server groups do not.
ConnectionDrainEnabled	boolean	No	Specifies whether to enable connection draining. true: enabled. false: disabled (default).	false
ConnectionDrainTimeout	integer	No	The connection draining timeout period. Valid values: 0 to 900. Default value: 300.	300
SlowStartConfig	object	No	The slow start configuration. After slow start is enabled, newly added backend servers are warmed up during a specified period of time. The number of requests forwarded to the server increases linearly. Note Basic Edition instances do not support slow start. Only Standard Edition and WAF Enhanced Edition instances support this feature. Server type and IP backend server groups support slow start configuration. Function Compute backend server groups do not. Slow start can be enabled only when the backend scheduling algorithm is weighted round-robin.
SlowStartEnabled	boolean	No	Specifies whether to enable slow start. true: enabled. false: disabled (default).	false
SlowStartDuration	integer	No	The slow start duration. Valid values: 30 to 900. Default value: 30.	30
Tag	array<object>	No	The tags.
	object	No	The tag structure.
Key	string	No	The tag key. 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 tag value. The tag value can be up to 128 characters in length, and cannot start with `aliyun` or `acs:`, or contain `http://` or `https://`.	product
CrossZoneEnabled	boolean	No	Specifies whether to enable cross-zone load balancing for the server group. Valid values: true: enabled (default). false: disabled. Note Basic Edition instances do not support binding server groups with cross-zone load balancing disabled. Only Standard Edition and WAF Enhanced Edition instances support this feature. Server type and IP type server groups support disabling cross-zone load balancing. Function Compute type server groups do not. Session persistence is not supported when cross-zone load balancing is disabled.	true
IpVersionAffinityMode	string	No	The IP version affinity mode.	Affinity

Response elements

Element	Type	Description	Example
	object	The response struct.
JobId	string	The asynchronous task ID.	72dcd26b-f12d-4c27-b3af-18f6aed5****
RequestId	string	The request ID.	365F4154-92F6-4AE4-92F8-7FF******
ServerGroupId	string	The server group ID.	sgp-8ilqs4axp6******

Examples

Success response

JSON format

{
  "JobId": "72dcd26b-f12d-4c27-b3af-18f6aed5****",
  "RequestId": "365F4154-92F6-4AE4-92F8-7FF******",
  "ServerGroupId": "sgp-8ilqs4axp6******"
}

Error codes

HTTP status code	Error code	Error message	Description
400	QuotaExceeded.ServerGroupsNum	The quota of %s is exceeded, usage %s/%s.	The quota of %s is exceeded, usage %s/%s.
400	Mismatch.LoadBalancerEditionAndSlowStartEnable	The %s and %s are mismatched.	The %s and %s are mismatched.
400	Mismatch.ServerGroupSchedulerAndSlowStartEnable	The %s and %s are mismatched.	The %s and %s are mismatched.
400	QuotaExceeded.SlowStartDuration	The quota of %s is exceeded, usage %s/%s.	The quota of %s is exceeded, usage %s/%s.
400	UnsupportedFeature.SlowStart	The feature of %s is not supported.	The %s feature is not supported.
400	Mismatch.LoadBalancerEditionAndConnectionDrain	The %s and %s are mismatched.	The %s and %s are mismatched.
400	QuotaExceeded.ConnectionDrainTimeout	The quota of %s is exceeded, usage %s/%s.	The quota of %s is exceeded, usage %s/%s.
400	UnsupportedFeature.ConnectionDrain	The feature of %s is not supported.	The feature of %s is not supported.
400	NotExist.ResourceGroup	ResourceGroup does not exist.	The resource group does not exist.
400	OperationDenied.VpcNotSupportIpv6	The operation is not allowed because of VpcNotSupportIpv6.	The operation is not allowed because of VpcNotSupportIpv6.
400	UnsupportedFeature.FcServerGroup	Server groups of type FC are not supported.	Server groups of type FC are not supported
404	ResourceNotFound.Vpc	The specified resource %s is not found.	The VPC does not exist.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.