CreateServerGroup-阿里云帮助中心

Create a server group in the specified region.

Operation description

The CreateServerGroup API is asynchronous. After you send a request, the system returns a request ID but the server group is still being created in the background. You can call the ListServerGroups operation to query the status of the server group.

If the server group is in the Creating state, it is being created.
If the server group is in the Available state, it 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 name of the server group. The name must be 2 to 128 characters in length, start with a letter, digit, or Chinese character, and can contain digits, periods (.), underscores (_), hyphens (-), and spaces.	test
ServerGroupType	string	No	The type of the server group. Valid values: Instance (default): an instance-type server group. You can add ECS instances, elastic network interfaces, and elastic container instances to this type of server group. Ip: an IP-type server group. You can add IP addresses as backend servers to this type of server group. Fc: a function-type server group. You can add functions of Function Compute as backend servers to this type of server group.	Instance
VpcId	string	No	The ID of the VPC where the server group is created. You can add only servers within this VPC to the server group. Note This parameter is valid 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. Requests are distributed based on the weight and the number of connections for each backend server. If two backend servers have the same weight, the one with fewer connections receives more requests. Sch: consistent hashing. Routes requests with the same hash factor to the same backend server. By default, if the UchConfig parameter is not configured, the source IP address is used as the hash factor. If the UchConfig parameter is configured, a specified URL parameter is used as the hash factor. Note This parameter is valid only when ServerGroupType is set to Instance or Ip.	Wrr
Protocol	string	No	The backend protocol. Valid values: HTTP (default): The server group can be associated with HTTPS, HTTP, and QUIC listeners. HTTPS: The server group can be associated with HTTPS listeners. gRPC: The server group can be associated with HTTPS and QUIC listeners. Note You do not need to configure this parameter if ServerGroupType is set to Fc.	HTTP
ResourceGroupId	string	No	The ID of the resource group.	rg-atstuj3rsop****
HealthCheckConfig	object	Yes	The health check settings.	rg-123
HealthCheckConnectPort	integer	No	The port on the backend server that is used for health checks. Valid values: 0 to 65535. Default value: 0. A value of 0 indicates that the backend server's traffic port is used for health checks.	80
HealthCheckEnabled	boolean	Yes	Specifies whether to enable the health check feature. Valid values: true: Enables health checks. false: Disables health checks. Note If ServerGroupType is set to Instance or Ip, health checks are enabled by default. If ServerGroupType is set to Fc, health checks are disabled by default.	true
HealthCheckHost	string	No	The domain name that is used for health checks. Use the private IP address of the backend server (default): The private IP address of a backend server is used as the host name for health checks. Specify a domain name: Enter a specific domain name. The domain name must be 1 to 80 characters in length. It can contain lowercase letters, digits, hyphens (-), and periods (.). It must contain at least one period (.). A period cannot be the first or last character. The rightmost domain label can contain only letters and cannot contain digits or hyphens (-). The domain name cannot start or end with a hyphen (-). Note This parameter is valid only when HealthCheckProtocol is set to HTTP, HTTPS, or gRPC.	www.example.com
HealthCheckCodes	array	No	The HTTP status codes that indicate a successful health check.
	string	No	The HTTP status code for a successful health check. If HealthCheckProtocol is set to HTTP or HTTPS, you can specify one or more of the following values: http_2xx (default), http_3xx, http_4xx, and http_5xx. Separate multiple values with commas (,). If HealthCheckProtocol is set to gRPC, the valid status codes are from 0 to 99. Default value: 0. You can specify up to 20 value ranges. Separate multiple ranges with commas (,). Note This parameter is valid only when HealthCheckProtocol is set to HTTP, HTTPS, or gRPC.	http_2xx
HealthCheckHttpVersion	string	No	The HTTP version that is used for health checks. Valid values: HTTP1.0 and HTTP1.1. Default value: HTTP1.1. Note This parameter is valid only when HealthCheckProtocol is set to HTTP or HTTPS.	HTTP1.1
HealthCheckInterval	integer	No	The interval between health checks, in seconds. Valid values: 1 to 50. Default value: 2.	2
HealthCheckMethod	string	No	The HTTP method that is used for health checks. Valid values: GET: If the response body exceeds 8 KB, the response is truncated. This does not affect the health check result. POST: The default method for gRPC health checks. HEAD (default): The default method for HTTP and HTTPS health checks. Note This parameter is valid only when HealthCheckProtocol is set to HTTP, HTTPS, or gRPC.	HEAD
HealthCheckPath	string	No	The path for health checks. The path must be 1 to 80 characters in length. It must start with a forward slash (/) and can contain letters, digits, and the following special characters: `-/.%?#&=` and `_;~!()[]@$^:',+`. Note* This parameter is valid only when HealthCheckProtocol is set to HTTP or HTTPS.	/test/index.html
HealthCheckProtocol	string	No	The protocol that is used for health checks. Valid values: HTTP: Sends HEAD or GET requests to simulate a browser request to check whether the backend server is healthy. HTTPS: Sends HEAD or GET requests to simulate a browser request to check whether the backend server is healthy. HTTPS provides better security because the data is encrypted. TCP: Checks if the server port is reachable by sending SYN packets. gRPC: Sends POST or GET requests to check whether the backend server is healthy.	HTTP
HealthCheckTimeout	integer	No	The timeout for a health check response, in seconds. If a backend server does not respond within this time, the health check fails. Valid values: 1 to 300. Default value: 5.	5
HealthyThreshold	integer	No	The number of consecutive successful health checks that an unhealthy backend server must pass to be considered healthy. Valid values: 2 to 10. Default value: 3.	3
UnhealthyThreshold	integer	No	The number of consecutive failed health checks that a healthy backend server must have to be considered unhealthy. Valid values: 2 to 10. Default value: 3.	3
StickySessionConfig	object	No	The sticky session settings. Note This parameter is valid only when ServerGroupType is set to Instance or Ip.
Cookie	string	No	The cookie that is 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. It cannot start with a dollar sign ($). Note This parameter is required if StickySessionEnabled is set to true and StickySessionType is set to server.	B490B6EBF6F3CD402E515D22BCDA****
CookieTimeout	integer	No	The timeout period of the cookie. Unit: seconds. Valid values: 1 to 86400. Default value: 1000. Note This parameter is required if StickySessionEnabled is set to true and StickySessionType is set to Insert.	1000
StickySessionEnabled	boolean	No	Specifies whether to enable sticky sessions. Valid values: true: enables sticky sessions. false (default): disables sticky sessions. Note This parameter is valid only when ServerGroupType is set to Instance or Ip.	false
StickySessionType	string	No	The method that is used to manage cookies. Valid values: Insert (default): Inserts a cookie. The load balancer inserts a cookie (SERVERID) into the HTTP or HTTPS response for the first request. Subsequent requests from the same client that carry this cookie are routed to the same backend server. Server: Uses a custom cookie generated by the backend server. The load balancer relies on this cookie to route subsequent requests from the same client to the same backend server. Note This parameter is required if StickySessionEnabled is set to true.	Insert
ClientToken	string	No	The client token that is used to ensure the idempotency of the request. You can use the client to generate a 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 of each request may be different.	5A2CAF0E-5718-45B5-9D4D-70B******
DryRun	boolean	No	Specifies whether to perform a dry run. Valid values: true: Performs a dry run. The system validates the request for issues such as missing required parameters, incorrect syntax, and service limits, but does not create the server group. If the request is invalid, an error message is returned. If the request is valid, the `DryRunOperation` error code is returned. false (default): sends a normal request. If the request passes the check, 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 keep-alive. true: enables upstream keep-alive. false (default): disables upstream keep-alive.	false
ServiceName	string	No	This parameter is available only in ALB Ingress scenarios. It specifies the name of the Kubernetes `Service` that is associated with the server group.	test
UchConfig	object	No	The settings for URL-based consistent hashing.
Type	string	Yes	The type of the parameter. Set the value to QueryString.	QueryString
Value	string	Yes	The key of the query string parameter that is used for consistent hashing.	abc
ConnectionDrainConfig	object	No	The settings for connection draining. If you enable connection draining, the load balancer allows existing connections to be processed for a specified period of time after a backend server is removed or becomes unhealthy. Note Basic ALB instances do not support connection draining. This feature is supported only by standard and WAF-enabled ALB instances. Connection draining is supported for instance-type and IP-type server groups, but not for function-type server groups.
ConnectionDrainEnabled	boolean	No	Specifies whether to enable connection draining. true: enables connection draining. false (default): disables connection draining.	false
ConnectionDrainTimeout	integer	No	The timeout period for connection draining, in seconds. Valid values: 0 to 900. Default value: 300.	300
SlowStartConfig	object	No	The slow start settings. If you enable slow start, requests are gradually and linearly routed to a newly added backend server over a specified period of time. Note Basic ALB instances do not support slow start. This feature is supported only by standard and WAF-enabled ALB instances. Slow start is supported for instance-type and IP-type server groups, but not for function-type server groups. Slow start can be enabled only if the scheduling algorithm is set to Wrr (weighted round robin).
SlowStartEnabled	boolean	No	Specifies whether to enable slow start. true: enables slow start. false (default): disables slow start.	false
SlowStartDuration	integer	No	The duration of the slow start period, in seconds. Valid values: 30 to 900. Default value: 30.	30
Tag	array<object>	No	The tags.
	object	No	A tag.
Key	string	No	The tag key. The key can be up to 128 characters in length and cannot start with `aliyun` or `acs:`. It cannot contain `http://` or `https://`.	env
Value	string	No	The tag value. The value can be up to 128 characters in length and cannot start with `aliyun` or `acs:`. It cannot contain `http://` or `https`.	product
CrossZoneEnabled	boolean	No	Specifies whether to enable cross-zone load balancing for the server group. Valid values: true (default): Enables cross-zone load balancing. false: Disables cross-zone load balancing. Note Basic ALB instances cannot be associated with server groups for which cross-zone load balancing is disabled. This feature is supported only by standard and WAF-enabled ALB instances. You can disable cross-zone load balancing for instance-type and IP-type server groups, but not for function-type server groups. You cannot enable sticky sessions if you disable cross-zone load balancing.	true
IpVersionAffinityMode	string	No	The IP version affinity mode of the server group.	Affinity

Response elements

Element	Type	Description	Example
	object	The data returned.
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.
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.
400	OperationDenied.VpcNotSupportIpv6	The operation is not allowed because of VpcNotSupportIpv6.	This operation is not allowed because the IPv6 function is not enabled for the current VPC.
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.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.