All Products
Search
Document Center

Server Load Balancer:CreateHealthCheckTemplate

Last Updated:Oct 26, 2026

Creates a health check template in a specified region.

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

create

*HealthCheckTemplate

acs:alb:{#regionId}:{#accountId}:healthchecktemplate/*

None None

Request parameters

Parameter

Type

Required

Description

Example

ClientToken

string

No

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

Generate a parameter value on your client to ensure that the value is unique across different requests. The ClientToken parameter supports only ASCII characters.

Note

If you do not specify this parameter, the system automatically uses the RequestId of the API request as the ClientToken. The RequestId of each API request is unique.

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

HealthCheckTemplateName

string

Yes

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

HealthCheckTemplate1

HealthCheckConnectPort

integer

No

The port used for health checks.

Valid values: 0 to 65535.

Default value: 0, which indicates that the port of the backend server is used for health checks.

80

HealthCheckHost

string

No

The domain name used for health checks. Valid values:

  • $SERVER_IP: the private IP of the backend server. If an IP address is specified or this parameter is not specified, load balancing uses the private IP of the backend server as the domain name for health checks.

  • domain: The domain name must be 1 to 80 characters in length, and can contain only letters, digits, periods (.), and hyphens (-).

Note

This parameter takes effect only when HealthCheckProtocol is set to HTTP or HTTPS.

$SERVER_IP

HealthCheckCodes

array

No

The list of normal status codes for health checks.

5

string

No

The normal HTTP status codes for health checks.

  • When HealthCheckProtocol is set to HTTP or HTTPS, valid values of HealthCheckCodes are http_2xx (default), http_3xx, http_4xx, and http_5xx. Separate multiple status codes with commas (,).

  • When HealthCheckProtocol is set to gRPC, the valid values of 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 is available only when HealthCheckProtocol is set to HTTP, HTTPS, or gRPC.

http_2xx

HealthCheckInterval

integer

No

The interval between health checks.

Valid values: 1 to 50. Unit: seconds.

Default value: 2.

2

HealthCheckTimeout

integer

No

The timeout period for receiving a response from a health check. If the backend server does not respond within the specified timeout period, the health check fails.

Valid values: 1 to 300. Unit: seconds.

Default value: 5.

5

HealthCheckPath

string

No

The URL used for health checks.

The URL must be 1 to 80 characters in length, and can contain letters, digits, hyphens (-), forward slashes (/), periods (.), percent signs (%), question marks (?), number signs (#), ampersands (&), and the following extended characters: _;~!()*[]@$^:',+. The URL must start with a forward slash (/).

Note

This parameter is available only when HealthCheckProtocol is set to HTTP or HTTPS.

/test/index.html

HealthCheckMethod

string

No

The health check method. Valid values:

  • HEAD (default): the default method for HTTP and HTTPS listener health checks.

  • POST: the default method for gRPC listener health checks.

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

Note

This parameter is available only when HealthCheckProtocol is set to HTTP, HTTPS, or gRPC.

HEAD

HealthCheckProtocol

string

No

The protocol used for health checks. Valid values:

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

  • HTTPS: sends HEAD or GET requests for browser access impersonation to check whether the server application is healthy. (Provides data encryption, making it more secure than HTTP.)

  • TCP: sends SYN handshake messages to check whether the server port is alive.

  • gRPC: sends POST or GET requests to check whether the server application is healthy.

HTTP

HealthCheckHttpVersion

string

No

The HTTP version for health checks.

Valid values: HTTP 1.0 and HTTP 1.1.

Default value: HTTP 1.1.

Note

This parameter is available only when HealthCheckProtocol is set to HTTP or HTTPS.

HTTP 1.0

HealthyThreshold

integer

No

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

Valid values: 2 to 10.

Default value: 3.

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 Successful to Failed.

Valid values: 2 to 10.

Default value: 3.

4

DryRun

boolean

No

Specifies whether to only precheck the request. Valid values:

  • true: sends a precheck request without creating the resource. The system checks whether required parameters are specified, the request format is valid, and service limits are met. If the request fails the precheck, the corresponding error is returned. If the request passes the precheck, the DryRunOperation error code is returned.

  • false (default): sends a normal request. After the request passes the precheck, the http_2xx status code is returned and the operation is performed.

true

Tag

array<object>

No

The tags.

object

No

The tag structure.

Key

string

No

The tag key. The key can be up to 128 characters in length, and cannot start with aliyun or acs:. It cannot contain http:// or https://.

env

Value

string

No

The tag value. The value can be up to 128 characters in length, and cannot start with aliyun or acs:. It cannot contain http:// or https://.

product

ResourceGroupId

string

No

The ID of the resource group.

rg-atstuj3rtop****

Response elements

Element

Type

Description

Example

object

The health check template.

HealthCheckTemplateId

string

The ID of the health check template.

hct-pno8sisi******

RequestId

string

The ID of the request.

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

Examples

Success response

JSON format

{
  "HealthCheckTemplateId": "hct-pno8sisi******",
  "RequestId": "365F4154-92F6-4AE4-92F8-7FF34******"
}

Error codes

HTTP status code

Error code

Error message

Description

400 QuotaExceeded.HealthCheckTemplatesNum The quota of %s is exceeded, usage %s/%s. The quota of %s is exceeded. Usage: %s/%s.
403 Forbidden.HealthCheckTemplate Authentication has failed for HealthCheckTemplate. Authentication failed for the HealthCheckTemplate.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.