All Products
Search
Document Center

Server Load Balancer:UpdateServerGroupAttribute

Last Updated:Oct 30, 2026

Updates the configurations of a server group, such as health checks, session persistence, name, scheduling algorithm, and health check protocol.

Operation description

The UpdateServerGroupAttribute operation is asynchronous. After you send the request, the system returns a request ID, but the server group configurations are not immediately updated. The update task runs in the background. You can call the ListServerGroups operation to query the update status of the server group configurations:

  • If the server group configurations are in the Configuring state, the configurations are being updated.

  • If the server group configurations are in the Available state, the configurations are updated.

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

update

*ServerGroup

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

None None

Request parameters

Parameter

Type

Required

Description

Example

ServerGroupName

string

No

The name of the server group.

The name must be 2 to 128 characters in length, and can contain letters, digits, periods (.), underscores (_), hyphens (-), and spaces. It must start with a letter or a digit.

test

Scheduler

string

No

The scheduling algorithm. Valid values:

  • Wrr: weighted round-robin. Backend servers with higher weights receive more requests.

  • Wlc: weighted least connections. Requests are distributed based on the weights and actual loads (number of connections) of backend servers. If backend servers have the same weight, the server with the fewest connections receives more requests.

  • Sch: consistent hashing. Requests with the same hash factor are scheduled 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.

Wrr

ClientToken

string

No

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 ensure that it is unique among different requests. The client token can contain only ASCII characters.

Note

If you do not specify this parameter, the system automatically uses the RequestId of the API request as the client token. The RequestId of each API request may be different.

5A2CFF0E-5718-45B5-9D4D-70B3******

DryRun

boolean

No

Specifies whether to perform only a dry run. Valid values:

  • true: performs only a dry run and does not modify resources. The system checks the required parameters, request format, and service 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 (default): performs a dry run and sends the actual request. If the request passes the dry run, an HTTP 2xx status code is returned and the operation is performed.

true

HealthCheckConfig

object

No

The health check configuration struct.

true

HealthCheckCodes

array

No

The list of status codes that indicate a successful health check.

string

No

The status codes that indicate a successful health check.

  • If 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 (,).

  • If HealthCheckProtocol is set to gRPC, valid values for HealthCheckCodes range from 0 to 99. Default value: 0. You can specify ranges. A maximum of 20 ranges are supported. Separate multiple ranges with commas (,).

Note

This parameter takes effect only when HealthCheckEnabled is set to true and HealthCheckProtocol is set to HTTP, HTTPS, or gRPC for the server group.

200

HealthCheckConnectPort

integer

No

The port of the backend server that is used for health checks.

Valid values: 0 to 65535.

A value of 0 indicates that the port of the backend server is used for health checks.

Note

The parameter settings take effect only when HealthCheckEnabled is set to true for the server group.

80

HealthCheckEnabled

boolean

No

Specifies whether to enable health checks. Valid values:

  • true: enables health checks.

  • false: disables health checks.

true

HealthCheckHost

string

No

The domain name that is used for health checks.

  • Internal IP address of the backend server (default): The internal IP address of the backend server is used as the domain name for health checks.

  • Custom domain name: Enter a 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 (.), and the period (.) cannot be at the beginning or end.

    • 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 takes effect only when HealthCheckProtocol is set to HTTP, HTTPS, or gRPC.

example.com

HealthCheckHttpVersion

string

No

The HTTP version that is used for health checks. Valid values:

  • HTTP1.0

  • HTTP1.1

Note

This parameter takes effect only when HealthCheckEnabled is set to true and HealthCheckProtocol is set to HTTP or HTTPS for the server group.

HTTP1.1

HealthCheckInterval

integer

No

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

Valid values: 1 to 50.

Note

The parameter settings take effect only when HealthCheckEnabled is set to true for the server group.

5

HealthCheckMethod

string

No

The HTTP method that is used for health checks. Valid values:

  • GET: If the length of the response message exceeds 8 KB, the message is truncated. However, the health check result is not affected.

  • POST: The POST method is used by default for gRPC listener health checks.

  • HEAD: The HEAD method is used by default for HTTP and HTTPS listener health checks.

Note

This parameter takes effect only when HealthCheckEnabled is set to true and HealthCheckProtocol is set to HTTP, HTTPS, or gRPC for the server group.

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, the characters -/.%?#&=, and the extension characters _;~!()*[]@$^:',+. The path must start with a forward slash.

Note

This parameter takes effect only when HealthCheckEnabled is set to true and the HealthCheckProtocol settings are HTTP or HTTPS for the server group.

/test/index.html

HealthCheckProtocol

string

No

The protocol that is used for health checks. Valid values:

  • HTTP: sends HEAD or GET requests for browser impersonation to check whether the server application is healthy.

  • HTTPS: sends HEAD or GET requests for browser impersonation to check whether the server application is healthy. (Data encryption makes it 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 timeout period to accept a response from a health check. If the backend ECS instance does not respond correctly within the specified time, the health check is failed. Unit: seconds.

Valid values: 1 to 300.

Note

The parameter settings take effect only when HealthCheckEnabled is set to true for the server group.

3

HealthyThreshold

integer

No

The number of consecutive successful health checks that must occur before the health check status of a backend server changes from fail to success.

Valid values: 2 to 10.

4

UnhealthyThreshold

integer

No

The number of consecutive failed health checks that must occur before the health check status of a backend server changes from success to fail.

Valid values: 2 to 10.

4

StickySessionConfig

object

No

The session persistence configuration struct.

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 only when StickySessionEnabled is set to true and StickySessionType is set to Server for the server group.

B490B5EBF6F3CD402E515D22B******

CookieTimeout

integer

No

The timeout period of the cookie. Unit: seconds.

Valid values: 1 to 86400.

Note

This parameter takes effect only when StickySessionEnabled is set to true and StickySessionType is set to Insert for the server group.

1000

StickySessionEnabled

boolean

No

Specifies whether to enable session persistence. Valid values:

  • true: enables session persistence.

  • false: disables session persistence.

false

StickySessionType

string

No

The method that is used to handle cookies. Valid values:

  • Insert: inserts a cookie. When a client accesses the server for the first time, load balancing inserts a cookie (SERVERID) into the HTTP or HTTPS response. The next time the client accesses the server with this cookie, the load balancing service forwards the request to the recorded backend server.

  • Server: rewrites a cookie. When ALB detects a user-defined cookie, it rewrites the original cookie. The next time the client accesses the server with the new cookie, ALB forwards the request to the recorded backend server.

Note

This parameter takes effect only when StickySessionEnabled is set to true for the server group.

Insert

ServerGroupId

string

Yes

The ID of the server group.

sgp-atstuj3rtop****

UpstreamKeepaliveEnabled

boolean

No

Specifies whether to enable backend keep-alive. Valid values:

  • true: enables backend keep-alive.

  • false: disables backend keep-alive.

false

ServiceName

string

No

This parameter is applicable only to ALB Ingress scenarios and specifies the name of the K8s Service that corresponds to the server group.

test2

UchConfig

object

No

The URL consistent hashing parameter settings.

Type

string

Yes

The parameter type. Only QueryString is supported.

QueryString

Value

string

Yes

The consistent hashing parameter value.

abc

ConnectionDrainConfig

object

No

The graceful connection break configuration.

After the graceful connection break is enabled, load balancing allows existing connections to be normally transmitted within a specified period after a backend server is removed or a health check is failed.

Note
  • Basic Edition instances do not support connection draining. Only Standard Edition and WAF-enhanced Edition instances support this feature.

  • Server group types that support connection draining include server type and IP type. Function Compute type is not supported.

ConnectionDrainEnabled

boolean

No

Specifies whether to enable connection draining. Valid values:

  • true: enables connection draining.

  • false: disables connection draining.

false

ConnectionDrainTimeout

integer

No

The connection draining timeout period.

Valid values: 0 to 900.

300

SlowStartConfig

object

No

The slow start configuration.

After slow start is enabled, newly added backend servers in the backend server group are warmed up within the specified time period, and the number of requests forwarded to the servers increases linearly.

Note
  • Basic Edition instances do not support slow start. Only Standard Edition and WAF-enhanced Edition instances support this feature.

  • Server group types that support slow start include server type and IP type. Function Compute type is not supported.

  • Slow start can be enabled only when the backend scheduling algorithm is weighted round-robin polling.

SlowStartDuration

integer

No

The slow start duration.

Valid values: 30 to 900.

30

SlowStartEnabled

boolean

No

Specifies whether to enable slow start. Valid values:

  • true: enables slow start.

  • false: disables slow start.

false

CrossZoneEnabled

boolean

No

Specifies whether to enable cross-zone load balancing for the server group. Valid values:

  • true: enables cross-zone load balancing (default).

  • false: disables cross-zone load balancing.

Note
  • Basic Edition instances do not support server groups with cross-zone load balancing disabled. Only Standard Edition and WAF-enhanced Edition instances support this feature.

  • Server group types that support disabling cross-zone load balancing include server type and IP type. Function Compute type is not supported.

  • Session persistence cannot be enabled when cross-zone load balancing is disabled.

true

IpVersionAffinityMode

string

No

The IP version affinity mode. Valid values:

  • NonAffinity (default): no affinity mode.

  • Affinity: affinity mode.

This parameter takes effect only when Ipv6Enabled is set to true.

Affinity

Response elements

Element

Type

Description

Example

object

The response data structure.

JobId

string

The ID of the asynchronous task.

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

RequestId

string

The request ID.

365F4154-92F6-4AE4-92F8-7FF3*****

Examples

Success response

JSON format

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

Error codes

HTTP status code

Error code

Error message

Description

400 IncorrectStatus.ServerGroup The status of %s [%s] is incorrect. The status of %s [%s] is incorrect.
400 Mismatch.LoadBalancerEditionAndConnectionDrain 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.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 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 feature %s is not supported.
400 Mismatch.LoadBalancerEditionAndSlowStartEnable The %s and %s are mismatched. The %s and %s are mismatched.
400 OperationDenied.UpstreamKeepaliveDisabled The operation is not allowed because of UpstreamKeepaliveDisabled. Updating not allowed Backend long connection is closed
400 OperationDenied.UpstreamKeepaliveEnabled The operation is not allowed because of UpstreamKeepaliveEnabled. Update not allowed to open Backend Long connection is in the open state
400 CloseUpstreamKeepaliveNotSupport The param of UpstreamKeepalive is not Support. close keepalive attribute for server group is not supported
400 OperationDenied.VpcNotSupportIpv6 The operation is not allowed because of VpcNotSupportIpv6. The operation is not allowed because of VpcNotSupportIpv6.
400 OperationDenied.Ipv6ServerExists IPv6 backend servers exist in the specified server group. IPv6 backend servers exist in the specified server group.
404 ResourceNotFound.ServerGroup The specified resource %s is not found. The backend server group does not exist.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.