CreateServerGroup - Server Load Balancer - Alibaba Cloud Documentation Center

Creates a server group in a region.

Operation description

CreateServerGroup 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 ListServerGroups to query the status of a server group.

If a server group is in the Creating state, it indicates that the server group is being created.
If a server group is in the Available state, it indicates that the server group is created.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

Debug

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

Operation: the value that you can use in the Action element to specify the operation on a resource.
Access level: the access level of each operation. The levels are read, write, and list.
Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- The required resource types are displayed in bold characters.
- If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
Condition Key: the condition key that is defined by the cloud service.
Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.

Operation	Access level	Resource type	Condition key	Associated operation
alb:CreateServerGroup	Write	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, and can contain letters, digits, periods (.), underscores (_), and hyphens (-). The name must start with a letter.	sg-atstuj3rtoptyui****
ServerGroupType	string	No	The type of server group. Valid values: Instance (default): allows you to add servers by specifying Ecs, Eni, or Eci. Ip: allows you to add servers by specifying IP addresses. Fc: allows you to add servers by specifying functions of Function Compute.	Instance
VpcId	string	No	The ID of the virtual private cloud (VPC). You can add only backend servers that are deployed in the specified VPC to the server group. Note This parameter takes effect when the ServerGroupType parameter is set to Instance or Ip.	vpc-bp15zckdt37pq72zv****
Scheduler	string	No	The scheduling algorithm. Valid values: Wrr (default): The weighted round-robin algorithm is used. Backend servers that have higher weights receive more requests than those that have lower weights. Wlc: The weighted least connections algorithm is used. Requests are distributed based on the weights and the number of connections to backend servers. If two backend servers have the same weight, the backend server that has fewer connections is expected to receive more requests. Sch: The consistent hashing algorithm is used. Requests from the same source IP address are distributed to the same backend server. Note This parameter takes effect when the ServerGroupType parameter 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 If the ServerGroupType parameter is set to Fc, you can set Protocol only to HTTP.	HTTP
ResourceGroupId	string	No	The ID of the resource group.	rg-atstuj3rtop****
HealthCheckConfig	object	Yes	The configuration of health checks.
HealthCheckConnectPort	integer	No	The backend port that is used for health checks. Valid values: 0 to 65535. Default value: 0. If you set the value to 0, the port of a backend server is used for health checks.	80
HealthCheckEnabled	boolean	Yes	Specifies whether to enable the health check feature. Valid values: true: enables the health check feature. false: disables the health check feature. Note If the ServerGroupType parameter is set to Instance or Ip, the health check feature is enabled by default. If the ServerGroupType parameter is set to Fc, the health check feature is disabled by default.	true
HealthCheckHost	string	No	The domain name that is used for health checks. The domain name meets the following requirements: The domain name is 1 to 80 characters in length. The domain name contains lowercase letters, digits, hyphens (-), and periods (.). The domain name contains at least one period (.) but does not start or end with a period (.). The rightmost domain label of the domain name contains only letters, and does not contain digits or hyphens (-). The domain name does not start or end with a hyphen (-). Note This parameter takes effect only when HealthCheckProtocol is set to HTTP or HTTPS. HTTPS is unavailable by default. If you want to use HTTPS, log on to the SLB console, go to the Quota Center page, and then apply for the privilege to use HTTPS on the ALB tab.	www.example.com
HealthCheckCodes	array	No	The HTTP status codes that are used to indicate whether the backend server passes the health check.
	string	No	The HTTP status codes that indicate a successful health check. You can set HealthCheckCodes to http_2xx (default value), http_3xx, http_4xx, and http_5xx when HealthCheckProtocol is set to HTTP or HTTPS. Separate multiple HTTP status codes with commas (,). If HealthCheckProtocol is set to gRPC, HealthCheckCodes can be set to 0 to 99. Default value: 0. Value ranges are supported. You can enter up to 20 value ranges. Separate multiple value ranges with commas (,). Note If HealthCheckProtocol is set to HTTP, HTTPS, or gRPC, this parameter takes effect. HTTPS is unavailable by default. If you want to use HTTPS, log on to the SLB console, go to the Quota Center page, and then apply for the privilege to use HTTPS on the ALB tab.	http_2xx
HealthCheckHttpVersion	string	No	The version of the HTTP protocol. Valid values: HTTP1.0 and HTTP1.1. Default value: HTTP1.1. Note This parameter takes effect only when HealthCheckProtocol is set to HTTP or HTTPS. HTTPS is unavailable by default. If you want to use HTTPS, log on to the SLB console, go to the Quota Center page, and then apply for the privilege to use HTTPS on the ALB tab.	HTTP1.1
HealthCheckInterval	integer	No	The interval at which health checks are performed. Unit: 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 length of a response exceeds 8 KB, the response is truncated. However, the health check result is not affected. POST: By default, gRPC health checks use the POST method. HEAD: HTTP and HTTPS health checks in listeners use the HEAD method by default. Note This parameter takes effect only when HealthCheckProtocol is set to HTTP, HTTPS, or gRPC. HTTPS is unavailable by default. If you want to use HTTPS, log on to the SLB console, go to the Quota Center page, and then apply for the privilege to use HTTPS on the ALB tab.	HEAD
HealthCheckPath	string	No	The path that is used for health checks. The path must be 1 to 80 characters in length and can contain only letters, digits, and the following special characters: `- / . % ? # & =`. It can also contain the following extended characters: `_ ; ~ ! ( ) * [ ] @ $ ^ : ' , +`. The URL must start with a forward slash (/). Note This parameter takes effect only when HealthCheckProtocol is set to HTTP or HTTPS. HTTPS is unavailable by default. If you want to use HTTPS, log on to the SLB console, go to the Quota Center page, and then apply for the privilege to use HTPS on the ALB tab.	/test/index.html
HealthCheckProtocol	string	No	The protocol that is used for health checks. Valid values: HTTP: ALB performs HTTP health checks by sending HEAD or GET requests to a backend server to check whether the backend server is healthy. HTTPS: ALB performs HTTPS health checks by sending HEAD or GET requests to a backend server to check whether the backend server is healthy. HTTPS supports data encryption and provides higher data security than HTTP. TCP: To perform TCP health checks, SLB sends SYN packets to the backend server to check whether the port of the backend server is available to receive requests. gRPC: To perform gRPC health checks, SLB sends POST or GET requests to a backend server to check whether the backend server is healthy. Note HTTPS is unavailable by default. If you want to use HTTPS, log on to the SLB console, go to the Quota Center page, and then apply for the privilege to use HTTPS on the ALB tab.	HTTP
HealthCheckTimeout	integer	No	The timeout period for a health check response. If a backend server, such as an Elastic Compute Service (ECS) instance, does not return a health check response within the specified timeout period, the server fails the health check. Unit: seconds. Valid values: 1 to 300. Default value: 5. Note If the value of HealthCHeckTimeout is smaller than the value of HealthCheckInterval, the value of HealthCHeckTimeout is ignored and the value of HealthCheckInterval is used.	5
HealthyThreshold	integer	No	The number of times that an unhealthy backend server must consecutively pass health checks before it is declared healthy. In this case, the health status changes from fail to success. Valid values: 2 to 10. Default value: 3.	3
UnhealthyThreshold	integer	No	The number of times that a healthy backend server must consecutively fail health checks before it is declared unhealthy. In this case, the health status changes from success to fail. Valid values: 2 to 10. Default value: 3.	3
StickySessionConfig	object	No	The configuration of session persistence. Note This parameter takes effect when the ServerGroupType parameter is set to Instance or Ip.
Cookie	string	No	The cookie to be configured on the server. The cookie must be 1 to 200 characters in length and can contain only ASCII characters and digits. It cannot contain commas (,), semicolons (;), or space characters. It cannot start with a dollar sign ($). Note This parameter takes effect when the StickySessionEnabled parameter is set to true and the StickySessionType parameter is set to Server.	B490B5EBF6F3CD402E515D22BCDA****
CookieTimeout	integer	No	The timeout period of a cookie. Unit: seconds. Valid values: 1 to 86400. Default value: 1000. Note This parameter takes effect only when the StickySessionEnabled parameter is set to true and the StickySessionType parameter is set to Insert.	1000
StickySessionEnabled	boolean	No	Specifies whether to enable session persistence. Valid values: true false (default) Note This parameter takes effect when the ServerGroupType parameter is set to Instance or Ip.	false
StickySessionType	string	No	The method that is used to handle a cookie. Valid values: Insert (default): inserts a cookie. ALB inserts a session cookie (SERVERID) into the first HTTP or HTTPS response that is sent to a client. Subsequent requests to ALB carry this cookie, and ALB determines the destination servers of the requests based on the cookies. Server: rewrites a cookie. When ALB detects a user-defined cookie, it overwrites the original cookie with the user-defined cookie. Subsequent requests to ALB carry this user-defined cookie, and ALB determines the destination servers of the requests based on the cookies. Note This parameter takes effect when the StickySessionEnabled parameter is set to true.	Insert
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-70B3FF3898
DryRun	boolean	No	Specifies whether to perform only a dry run, without performing the actual request. Valid values: true: performs only 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
UpstreamKeepaliveEnabled	boolean	No	Specifies whether to enable persistent TCP connections.
ServiceName	string	No	This parameter is available only if the ALB Ingress controller is used. In this case, set this parameter to the name of the `Kubernetes Service` that is associated with the server group.	test
UchConfig	object	No	The configuration of consistent hashing based on URLs.
Type	string	Yes	The type of the parameter.	QueryString
Value	string	Yes	The parameter value for consistent hashing.	abc
Tag	object []	No	The tag.
Key	string	No	The tag key. The tag key can be up to 128 characters in length, and cannot start with `acs:` or `aliyun`. It cannot 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 `acs:` or `aliyun`. It cannot contain `http://` or `https://`.	product

Response parameters

Parameter	Type	Description	Example
	object	The response parameters.
JobId	string	The ID of the asynchronous job.	72dcd26b-f12d-4c27-b3af-18f6aed5****
RequestId	string	The request ID.	365F4154-92F6-4AE4-92F8-7FF34B540710
ServerGroupId	string	The ID of the server group.	sg-atstuj3rtoptyui****

Examples

Sample success responses

JSONformat

{
  "JobId": "72dcd26b-f12d-4c27-b3af-18f6aed5****",
  "RequestId": "365F4154-92F6-4AE4-92F8-7FF34B540710",
  "ServerGroupId": "sg-atstuj3rtoptyui****"
}

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.

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

Change history

Change time

Summary of changes

Operation

2024-02-27

The Error code has changed

see changesets

Change item	Change content
Error Codes	The Error code has changed.
	Error Codes 400 change
	delete Error Codes: 404

2024-02-23

The Error code has changed. The request parameters of the API has changed

see changesets

Change item	Change content
Error Codes	The Error code has changed.
	Error Codes 400 change
	Added Error Codes: 404
Input Parameters	The request parameters of the API has changed.
	Added Input Parameters: ConnectionDrainConfig
	Added Input Parameters: SlowStartConfig

2023-11-03

The Error code has changed. The request parameters of the API has changed

see changesets

Change item	Change content
Error Codes	The Error code has changed.
	delete Error Codes: 400
Input Parameters	The request parameters of the API has changed.
	Added Input Parameters: UpstreamKeepaliveEnabled

2023-04-11

The Error code has changed. The request parameters of the API has changed

see changesets

Change item	Change content
Error Codes	The Error code has changed.
	delete Error Codes: 400
Input Parameters	The request parameters of the API has changed.
	Added Input Parameters: UchConfig