UpdateServerGroupAttribute-阿里云帮助中心

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

Operation description

The UpdateServerGroupAttribute operation is asynchronous. After you send the request, the system returns a request ID, but the configurations of the server group are not immediately updated. The update task is still running 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

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 must start with a letter or a digit. It 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. Requests are distributed based on the weights and actual loads (number of connections) of backend servers. If the weights are the same, backend servers with fewer connections receive 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 make sure that the value 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 a dry run. Valid values: true: performs a dry run without modifying resources. The system checks whether required parameters are specified, the request format is valid, and the service limits are met. If the request fails the dry run, an error is returned. If the request passes the dry run, the `DryRunOperation` error code is returned. false (default): performs a dry run and sends the 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 configurations.	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. Use the 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. Specify a 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 cannot start or end with a period (.). The rightmost domain label can contain only letters and cannot contain digits or hyphens (-). It 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 exceeds 8 KB, the response is truncated. However, this does not affect the health check result. POST: By default, gRPC listeners use the POST method for health checks. HEAD: By default, HTTP and HTTPS listeners use the HEAD method for 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 of the forwarding rule for health checks. The path must be 1 to 80 characters in length. It can contain only letters, digits, the characters `-/.%?#&=`, and extension characters `_;~!()[]@$^:',+`. The URL must start with `/`. Note* This parameter takes effect only when HealthCheckEnabled is set to true and HealthCheckProtocol is set to 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 impersonation of browser access to check whether the server application is healthy. HTTPS: sends HEAD or GET requests for impersonation of browser access to check whether the server application is healthy (data encryption, which makes HTTPS 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 within the specified timeout period, the health check is considered 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 configurations.
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: yes. false: no.	false
StickySessionType	string	No	The method that is used to process 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, load balancing forwards the request to the previously recorded backend server. Server: rewrites a cookie. When load balancing detects a user-defined cookie, it rewrites the original cookie. The next time the client accesses the server with the new cookie, load balancing forwards the request to the previously 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 keep-alive for backend connections. true: enables keep-alive. false: disables keep-alive.	false
ServiceName	string	No	The name of the `K8s Service` that corresponds to the server group. This parameter is applicable only to ALB Ingress scenarios.	test2
UchConfig	object	No	The parameter settings for URL consistent hashing.
Type	string	Yes	The type of the parameter. Only QueryString is supported.	QueryString
Value	string	Yes	The value of the consistent hashing parameter.	abc
ConnectionDrainConfig	object	No	The configurations for connection draining. After connection draining is enabled, load balancing allows existing connections to maintain normal transmission within a specified period after a backend server is removed or the health check fails. Note Basic Edition instances do not support connection draining. Only Standard Edition and WAF-enhanced Edition instances support this feature. Server groups of the server type and IP type support connection draining. Server groups of the Function Compute type do not support this feature.
ConnectionDrainEnabled	boolean	No	Specifies whether to enable connection draining. true: enables connection draining. false: disables connection draining.	false
ConnectionDrainTimeout	integer	No	The timeout period for connection draining. Valid values: 0 to 900.	300
SlowStartConfig	object	No	The configurations for slow start. After slow start is enabled, ALB preheats newly added backend servers in the backend server group within a specified period. The number of requests forwarded to the newly added backend servers increases linearly. Note Basic Edition instances do not support slow start. Only Standard Edition and WAF-enhanced Edition instances support this feature. Server groups of the server type and IP type support slow start. Server groups of the Function Compute type do not support this feature. Slow start can be enabled only when the backend scheduling algorithm is weighted round-robin.
SlowStartDuration	integer	No	The duration of the slow start period. Valid values: 30 to 900.	30
SlowStartEnabled	boolean	No	Specifies whether to enable slow start. 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. This is the default value. 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 groups of the server type and IP type support disabling cross-zone load balancing. Server groups of the Function Compute type do not support this feature. Session persistence 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 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.