All Products
Search
Document Center

Server Load Balancer:CreateServerGroup

Last Updated:Jan 09, 2024

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.
OperationAccess levelResource typeCondition keyAssociated operation
alb:CreateServerGroupWrite
  • ServerGroup
    acs:alb:{#regionId}:{#accountId}:servergroup/*
  • alb:ServerGroupProtocol
none

Request parameters

ParameterTypeRequiredDescriptionExample
ServerGroupNamestringYes

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****
ServerGroupTypestringNo

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
VpcIdstringNo

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****
SchedulerstringNo

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
ProtocolstringNo

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
ResourceGroupIdstringNo

The ID of the resource group.

rg-atstuj3rtop****
HealthCheckConfigobjectYes

The configuration of health checks.

HealthCheckConnectPortintegerNo

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
HealthCheckEnabledbooleanYes

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
HealthCheckHoststringNo

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
HealthCheckCodesarrayNo

The HTTP status codes that are used to indicate whether the backend server passes the health check.

stringNo

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
HealthCheckHttpVersionstringNo

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
HealthCheckIntervalintegerNo

The interval at which health checks are performed. Unit: seconds.

Valid values: 1 to 50.

Default value: 2.

2
HealthCheckMethodstringNo

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
HealthCheckPathstringNo

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
HealthCheckProtocolstringNo

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
HealthCheckTimeoutintegerNo

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
HealthyThresholdintegerNo

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
UnhealthyThresholdintegerNo

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
StickySessionConfigobjectNo

The configuration of session persistence.

Note This parameter takes effect when the ServerGroupType parameter is set to Instance or Ip.
CookiestringNo

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****
CookieTimeoutintegerNo

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
StickySessionEnabledbooleanNo

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
StickySessionTypestringNo

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
ClientTokenstringNo

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
DryRunbooleanNo

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
UpstreamKeepaliveEnabledbooleanNo

Specifies whether to enable persistent TCP connections.

ServiceNamestringNo

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
UchConfigobjectNo

The configuration of consistent hashing based on URLs.

TypestringYes

The type of the parameter.

QueryString
ValuestringYes

The parameter value for consistent hashing.

abc
Tagobject []No

The tag.

KeystringNo

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
ValuestringNo

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

ParameterTypeDescriptionExample
object

The response parameters.

JobIdstring

The ID of the asynchronous job.

72dcd26b-f12d-4c27-b3af-18f6aed5****
RequestIdstring

The request ID.

365F4154-92F6-4AE4-92F8-7FF34B540710
ServerGroupIdstring

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 codeError codeError messageDescription
400QuotaExceeded.ServerGroupsNumThe 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 timeSummary of changesOperation
2023-11-03The Error code has changed. The request parameters of the API has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    delete Error Codes: 400
Input ParametersThe request parameters of the API has changed.
    Added Input Parameters: UpstreamKeepaliveEnabled
2023-04-11The Error code has changed. The request parameters of the API has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    delete Error Codes: 400
Input ParametersThe request parameters of the API has changed.
    Added Input Parameters: UchConfig