Creates a server group for a Network Load Balancer (NLB) instance.

  • protocol specifies the protocol used to forward requests to the backend servers.
  • NLB instances support only backend server groups that use TCP, UDP, or SSL over TCP.
  • CreateServerGroup is an asynchronous operation. After you send the request, the system returns a request ID even though the operation is still being performed in the background. You can call the GetJobStatus operation to query the creation status of a server group.
    • If the task is in the Succeeded status, the server group is created.
    • If the task is in the Processing status, the server group is being created.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

ParameterTypeRequiredExampleDescription
ActionStringYesCreateServerGroup

The operation that you want to perform. Set the value to CreateServerGroup.

ServerGroupTypeStringNoInstance

The type of the server group. Valid values:

  • Instance: allows you to add servers of the Ecs, Ens, or Eci type. This is the default value.
  • Ip: allows you to add servers by specifying IP addresses.
ServerGroupNameStringYesNLB_ServerGroup

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.

AddressIPVersionStringNoipv4

The protocol version. Valid values:

  • ipv4: IPv4. This is the default value.
  • DualStack: dual stack.
ProtocolStringNoTCP

The protocol used to forward requests to the backend servers. Valid values:

  • TCP: This is the default value.
  • UDP
  • TCPSSL
VpcIdStringYesvpc-bp15zckdt37pq72zv****

The ID of the VPC to which the server group belongs.

Note If ServerGroupType is set to Instance, only servers in the specified VPC can be added to the server group.
AnyPortEnabledBooleanNofalse

Specifies whether to enable all-port forwarding. Valid values:

  • true: yes.
  • false: no. This is the default value.
ConnectionDrainEnabledBooleanNofalse

Specifies whether to enable connection draining. Valid values:

  • true: yes.
  • false: no. This is the default value.
ConnectionDrainTimeoutIntegerNo10

The timeout period of connection draining. Unit: seconds.

Valid values: 10 to 900.

SchedulerStringNoWrr

The scheduling algorithm. Valid values:

  • Wrr: The weighted round-robin algorithm is used. Backend servers with higher weights receive more requests than backend servers with lower weights. This is the default value.
  • rr: The round-robin algorithm is used. Requests are forwarded to backend servers in sequence.
  • sch: Source IP hashing is used. Requests from the same source IP address are forwarded to the same backend server.
  • tch: Four-element hashing is used. It specifies consistent hashing that is based on four factors: source IP address, destination IP address, source port, and destination port. Requests that contain the same information based on the four factors are forwarded to the same backend server.
  • qch: QUIC ID hashing is used. Requests that contain the same QUIC ID are forwarded to the same backend server.
PreserveClientIpEnabledBooleanNofalse

Specifies whether to enable client IP preservation. Valid values:

  • true: yes.
  • false: no. This is the default value.
HealthCheckConfig.HealthCheckEnabledBooleanNotrue

Specifies whether to enable the health check feature. Valid values:

  • true: yes. This is the default value.
  • false: no.
HealthCheckConfig.HealthCheckTypeStringNoTCP

The protocol that is used for health checks. Valid values: TCP (default) and HTTP.

HealthCheckConfig.HealthCheckConnectPortIntegerNo0

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.

HealthCheckConfig.HealthyThresholdIntegerNo2

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 is changed from fail to success.

Valid values: 2 to 10.

Default value: 2.

HealthCheckConfig.UnhealthyThresholdIntegerNo2

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 is changed from success to fail.

Valid values: 2 to 10.

Default value: 2.

HealthCheckConfig.HealthCheckConnectTimeoutIntegerNo5

The maximum timeout period of a health check response. Unit: seconds.

Valid values: 1 to 300.

Default value: 5.

HealthCheckConfig.HealthCheckIntervalIntegerNo10

The interval between two consecutive health checks. Unit: seconds.

Valid values: 5 to 50.

Default value: 10.

HealthCheckConfig.HealthCheckDomainStringNo$SERVER_IP

The domain name that is used for health checks. Valid values:

  • $SERVER_IP: the private IP address of a backend server.
  • domain: the domain name you want to use for health checks. The domain name must be 1 to 80 characters in length and can contain lowercase letters, digits, hyphens (-), and periods (.).
Note This parameter takes effect only when you set HealthCheckType to HTTP.
HealthCheckConfig.HealthCheckUrlStringNo/test/index.html

The path to which health check requests are sent.

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 path must start with a forward slash (/).

Note This parameter takes effect only when you set HealthCheckType to HTTP.
HealthCheckConfig.HealthCheckHttpCode.NStringNohttp_2xx

The HTTP status codes to return for health checks. Separate multiple HTTP status codes with commas (,).

Valid values: http_2xx (default), http_3xx, http_4xx, and http_5xx.

Note This parameter takes effect only when you set HealthCheckType to HTTP.
HealthCheckConfig.HttpCheckMethodStringNoGET

The HTTP method that is used for health checks. Valid values: GET (default) and HEAD.

Note This parameter takes effect only when you set HealthCheckType to HTTP.
ResourceGroupIdStringNorg-atstuj3rtop****

The ID of the resource group to which the server group belongs.

DryRunBooleanNotrue

Specifies whether to perform a dry run. Valid values:

  • true: performs a dry run. The system checks the required parameters, request syntax, and 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: performs a dry run and sends the request. If the request passes the dry run, a 2xx HTTP status code is returned and the operation is performed.
ClientTokenStringNo123e4567-e89b-12d3-a456-426655440000

The client token that is used to ensure the idempotence of the request.

You can use the client to generate the value, but you must make sure that the value is unique among different requests. The token can contain only ASCII characters.

Note If you do not set this parameter, the system automatically uses the value of RequestId as the value of ClientToken. The value of RequestId may be different for each API request.
RegionIdStringNocn-hangzhou

The ID of the region where the NLB instance is deployed.

You can call the DescribeRegions operation to query the most recent region list.

Response parameters

ParameterTypeExampleDescription
RequestIdString54B48E3D-DF70-471B-AA93-08E683A1B45

The ID of the request.

ServerGroupIdStringsgp-atstuj3rtoptyui****

The ID of the server group.

JobIdString72dcd26b-f12d-4c27-b3af-18f6aed5****

The ID of the asynchronous task.

Examples

Sample requests

http(s)://[Endpoint]/?Action=CreateServerGroup
&ServerGroupType=Instance
&ServerGroupName=NLB_ServerGroup
&AddressIPVersion=ipv4
&Protocol=TCP
&VpcId=vpc-bp15zckdt37pq72zv****
&AnyPortEnabled=false
&ConnectionDrainEnabled=false
&ConnectionDrainTimeout=10
&Scheduler=Wrr
&PreserveClientIpEnabled=false
&HealthCheckConfig={"HealthCheckEnabled":true,"HealthCheckType":"TCP","HealthCheckConnectPort":0,"HealthyThreshold":2,"UnhealthyThreshold":2,"HealthCheckConnectTimeout":5,"HealthCheckInterval":10,"HealthCheckDomain":"$SERVER_IP","HealthCheckUrl":"/test/index.html","HealthCheckHttpCode":["http_2xx"],"HttpCheckMethod":"GET"}
&ResourceGroupId=rg-atstuj3rtop****
&DryRun=true
&ClientToken=123e4567-e89b-12d3-a456-426655440000
&RegionId=cn-hangzhou
&Common request parameters

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<CreateServerGroupResponse>
    <RequestId>54B48E3D-DF70-471B-AA93-08E683A1B45</RequestId>
    <ServerGroupId>sgp-atstuj3rtoptyui****</ServerGroupId>
    <JobId>72dcd26b-f12d-4c27-b3af-18f6aed5****</JobId>
</CreateServerGroupResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "RequestId" : "54B48E3D-DF70-471B-AA93-08E683A1B45",
  "ServerGroupId" : "sgp-atstuj3rtoptyui****",
  "JobId" : "72dcd26b-f12d-4c27-b3af-18f6aed5****"
}

Error codes

For a list of error codes, see Service error codes.