UpdateServerGroupAttribute-阿里云帮助中心

Update a server group's settings, such as health check, session persistence, name, scheduling algorithm, and protocol.

Operation description

The UpdateServerGroupAttribute API is asynchronous. After you call this API, the system returns a request ID and runs the update in the background. The configuration change is not immediate. You can call the ListServerGroups API to query the status of the server group:

A Configuring status indicates that the server group is being updated.
An Available status indicates that the update is complete.

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

Request parameters

Parameter	Type	Required	Description	Example
ServerGroupName	string	No	The name of the server group. The name must be 2 to 128 characters long, start with a letter, digit, or Chinese character, and can contain letters, digits, periods (.), underscores (_), hyphens (-), and spaces.	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. The algorithm routes requests based on both the weight and the current load (number of connections) of each backend server. If backend servers have the same weight, the one with fewer active connections receives more requests. Sch: consistent hashing. The source IP address is used as the hash key by default. If you configure the `UchConfig` parameter, a URL parameter is used as the hash key instead.	Wrr
ClientToken	string	No	The client token, which is used to ensure the idempotence of the request. Generate a unique value on your client and ensure that the value is unique for each request. The client token can contain only ASCII characters. Note If you do not specify this parameter, the system uses the RequestId of the API request as the client token.	5A2CFF0E-5718-45B5-9D4D-70B3******
DryRun	boolean	No	Specifies whether to perform a dry run. Valid values: true: Performs a dry run to check the request's validity without modifying the resource. The system checks for required parameters, request format, and service limits. If the check is successful, the `DryRunOperation` error code is returned. false (default): Sends a normal request. If the request is valid, the operation is performed and an HTTP `2xx` status code is returned.	true
HealthCheckConfig	object	No	The health check settings.	true
HealthCheckConnectPort	integer	No	The port on the backend server that is used for health checks. Valid values: 0 to 65535. If you set this value to 0, the backend server's port is used for health checks. Note This parameter takes effect only when HealthCheckEnabled is set to true.	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 used for health checks. Use the private IP address of the backend server (default): The private IP address of the backend server is used for the health check. Specify a domain name: Enter a domain name that meets the following requirements: 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 (.), which cannot be the first or last character. The rightmost domain label can contain only letters and cannot contain digits or hyphens (-). A hyphen (-) cannot be the first or last character. Note This parameter takes effect only when HealthCheckProtocol is set to HTTP, HTTPS, or gRPC.	example.com
HealthCheckCodes	array	No	The HTTP status codes that indicate a successful health check.
	string	No	The status code that indicates a successful health check. When HealthCheckProtocol is set to HTTP or HTTPS, you can specify http_2xx (default), http_3xx, http_4xx, and http_5xx. Separate multiple values with commas (,). When HealthCheckProtocol is set to gRPC, the valid status codes are from 0 to 99. The default value is 0. You can specify up to 20 ranges. 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.	200
HealthCheckHttpVersion	string	No	The HTTP version 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.	HTTP1.1
HealthCheckInterval	integer	No	The interval, in seconds, between health checks. Valid values: 1 to 50. Note This parameter takes effect only when HealthCheckEnabled is set to true.	5
HealthCheckMethod	string	No	The method used for health checks. Valid values: GET: If the response body is larger than 8 KB, it is truncated. This does not affect the health check result. POST: By default, gRPC listeners use POST for health checks. HEAD: By default, HTTP and HTTPS listeners use HEAD for health checks. Note This parameter takes effect only when HealthCheckEnabled is set to true and HealthCheckProtocol is set to HTTP, HTTPS, or gRPC.	HEAD
HealthCheckPath	string	No	The path to which health check requests are sent. The path must be 1 to 80 characters in length. It can contain letters, digits, and the following characters: `-/.%?#&=` and `_~;!()[]@$^:',+`. The path must start with `/`. Note* This parameter takes effect only when HealthCheckEnabled is set to true and HealthCheckProtocol is set to HTTP or HTTPS.	/test/index.html
HealthCheckProtocol	string	No	The protocol used for health checks. Valid values: HTTP: The system checks whether the application is healthy by sending a HEAD or GET request that simulates a browser visit. HTTPS: The system checks whether the application is healthy by sending a HEAD or GET request that simulates a browser visit. Data is encrypted, which is more secure than HTTP. TCP: The system verifies that the port is open by sending a SYN packet. gRPC: The system checks whether the application is healthy by sending a POST or GET request.	HTTP
HealthCheckTimeout	integer	No	The timeout period, in seconds, for a health check response. If a backend server fails to respond within this period, the health check fails. Valid values: 1 to 300. Note This parameter takes effect only when HealthCheckEnabled is set to true.	3
HealthyThreshold	integer	No	The number of consecutive successful health checks required for a server's status to change from fail to success. Valid values: 2 to 10.	4
UnhealthyThreshold	integer	No	The number of consecutive failed health checks required for a server's status to change from success to fail. Valid values: 2 to 10.	4
StickySessionConfig	object	No	The sticky session settings.
Cookie	string	No	The cookie that is configured on the server. The cookie must be 1 to 200 characters long and consist of ASCII characters. 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.	B490B5EBF6F3CD402E515D22B******
CookieTimeout	integer	No	The cookie timeout period, in seconds. Valid values: 1 to 86400. Note This parameter takes effect only when 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: Disables sticky sessions.	false
StickySessionType	string	No	The method used to handle cookies. Valid values: Insert: The load balancer inserts a cookie (SERVERID) into the HTTP or HTTPS response to the first request from a client. Subsequent requests from the client that contain this cookie are routed to the same backend server. Server: The load balancer overwrites the original cookie when it detects a user-defined cookie. Subsequent requests from the client that contain the new cookie are routed to the same backend server. Note This parameter takes effect only when StickySessionEnabled is set to true.	Insert
ServerGroupId	string	Yes	The ID of the server group.	sgp-atstuj3rtop****
UpstreamKeepaliveEnabled	boolean	No	Specifies whether to enable persistent connections to backend servers. true: Enables persistent connections. false: Disables persistent connections.	sgp-123
ServiceName	string	No	The name of the corresponding Kubernetes (K8s) `Service`. This parameter is applicable only to Application Load Balancer (ALB) Ingress scenarios.	test2
UchConfig	object	No	The settings for URL-based consistent hashing.
Type	string	Yes	The type of the parameter. Only `QueryString` is supported.	QueryString
Value	string	Yes	The name of the query string parameter to use for consistent hashing.	abc
ConnectionDrainConfig	object	No	The connection draining settings. If connection draining is enabled, the load balancer allows existing connections to be processed for a specified period of time after a backend server is removed or declared unhealthy. Note Basic instances do not support connection draining. Only Standard and WAF-enhanced instances support this feature. Server groups of the instance and IP types support connection draining. Server groups of the Function Compute type do not.
ConnectionDrainEnabled	boolean	No	Specifies whether to enable connection draining. true: Enables connection draining. false: Disables connection draining.	false
ConnectionDrainTimeout	integer	No	The connection draining timeout period, in seconds. Valid values: 0 to 900.	300
SlowStartConfig	object	No	The slow start settings. If you enable slow start, the load balancer warms up a newly added backend server over a specified period. During this warm-up period, the number of requests routed to the server increases linearly. Note Basic instances do not support slow start. Only Standard and WAF-enhanced instances support this feature. Server groups of the instance and IP types support slow start. Server groups of the Function Compute type do not. Slow start can be enabled only when the scheduling algorithm is weighted round robin.
SlowStartEnabled	boolean	No	Specifies whether to enable slow start. true: Enables slow start. false: Disables slow start.	false
SlowStartDuration	integer	No	The duration of the slow start period, in seconds. Valid values: 30 to 900.	30
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 instances require cross-zone load balancing to be enabled. The option to disable it is supported only by Standard and WAF-enhanced instances. Server groups of the instance and IP types support disabling cross-zone load balancing. Server groups of the Function Compute type do not. Sticky sessions cannot be enabled when cross-zone load balancing is disabled.	true
IpVersionAffinityMode	string	No	The IP version affinity mode.	Affinity

Response elements

Element	Type	Description	Example
	object	The response data.
JobId	string	The ID of the asynchronous task.	72dcd26b-f12d-4c27-b3af-18f6aed5****
RequestId	string	The ID of the request.	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.
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
404	ResourceNotFound.ServerGroup	The specified resource %s is not found.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.