Creates a health check template.

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

Parameter Type Required Example Description
Action String Yes CreateHealthCheckTemplate

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

ClientToken String No 5A2CFF0E-5718-45B5-9D4D-70B3FF3898

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 all requests. ClientToken can contain only ASCII characters.

Note If you do not set this parameter, the system automatically uses RequestId as ClientToken. The ID of each request may be different.
HealthCheckTemplateName String Yes HealthCheckTemplate1

The name of the health check template.

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.

HealthCheckConnectPort Integer No 80

The port that is used for health checks.

Valid values: 0 to 65535.

Default value: 0. This value indicates that the port on a backend server is used for health checks.

HealthCheckHost String No $_ip

The domain name that is used for health checks.

Default value: $SERVER_IP. The domain name is 1 to 80 characters in length. Make sure that the destination CIDR block meets the following requirements:

  • The domain name can contain lowercase letters, digits, hyphens (-), and periods (.).
  • The domain name contains at least one period (.) but does not start or end with a period (.).
  • The rightmost domain label can contain only letters, and cannot contain digits or hyphens (-).
  • Other domain labels cannot start or end with a hyphen (-).

This parameter is required only if the HealthCheckProtocol parameter is set to HTTP.

HealthCheckCodes.N String No http_2xx,http_3xx

The HTTP status code for a successful health check.

  • If HealthCheckProtocol is set to HTTP, HealthCheckCodes can be set to http_2xx (default), http_3xx, http_4xx, and http_5xx. Separate multiple HTTP status codes with commas (,).
  • If HealthCheckProtocol is set to gRPC, HealthCheckCodes can be set to 0 to 99. Default value: 0. Value ranges are supported. You can enter at most 20 value ranges and must separate them with commas (,).
Note This parameter is required only if the HealthCheckProtocol parameter is set to HTTP.
HealthCheckInterval Integer No 2

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

Valid values: 1 to 50.

Default value: 2.

HealthCheckTimeout Integer No 5

The timeout period of a health check. Unit: seconds. If a backend server does not respond within the specified timeout period, the backend server fails the health check.

Valid values: 1 to 300.

Default value: 5.

Note If the value of the HealthCheckTimeout parameter is smaller than that of the HealthCheckInterval parameter, the timeout period specified by the HealthCheckTimeout parameter is ignored and the value of the HealthCheckInterval parameter is used as the timeout period.
HealthCheckPath String No /test/index.html

The URL path that is used for health checks.

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

Note This parameter is required only if the HealthCheckProtocol parameter is set to HTTP.
HealthCheckMethod String No HEAD

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

  • HEAD: By default, the ALB instance sends HEAD requests to a backend server to perform HTTP health checks.
  • POST: By default, gRPC health checks use the POST method.
  • GET: If the length of a response exceeds 8 KB, the response is truncated. However, the health check result is not affected.
Note This parameter is required only if the HealthCheckProtocol parameter is set to HTTP.
HealthCheckProtocol String No HTTP

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

  • HTTP: The ALB instance sends HEAD or GET requests to a backend server to simulate access from a browser and check whether the backend server is healthy. This is the default protocol.
  • TCP: To perform TCP health checks, ALB sends SYN packets to a backend server to check whether the port of the backend server is available to receive requests.
  • GRPC: To perform gRPC health checks, ALB sends POST or GET requests to a backend server to check whether the backend server is healthy.
HealthCheckHttpVersion String No HTTP 1.0

The HTTP version that is used for health checks.

Valid values: HTTP 1.0 and HTTP 1.1.

Default value: HTTP 1.1.

Note This parameter is required only if the HealthCheckProtocol parameter is set to HTTP.
HealthyThreshold Integer No 4

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: 3.

UnhealthyThreshold Integer No 4

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: 3.

DryRun Boolean No true

Specifies whether to only precheck this request. Valid values:

  • true: prechecks the request without creating a forwarding rule. The system prechecks the required parameters, request syntax, and limits. If the request fails to pass the precheck, an error message is returned. If the request passes the precheck, the DryRunOperation error code is returned.
  • false: prechecks the request and performs the requested operation. After the request passes the precheck, an HTTP 2xx status code is returned and the system performs the operation. This is the default value.

Response parameters

Parameter Type Example Description
HealthCheckTemplateId String hct-1224334

The ID of the health check template.

RequestId String 365F4154-92F6-4AE4-92F8-7FF34B540710

The ID of the request.

Examples

Sample requests

http(s)://[Endpoint]/?Action=CreateHealthCheckTemplate
&ClientToken=5A2CFF0E-5718-45B5-9D4D-70B3FF3898
&HealthCheckTemplateName=HealthCheckTemplate1
&HealthCheckConnectPort=80
&HealthCheckHost=$_ip
&HealthCheckCodes=["http_2xx,http_3xx"]
&HealthCheckInterval=2
&HealthCheckTimeout=5
&HealthCheckPath=/test/index.html
&HealthCheckMethod=HEAD
&HealthCheckProtocol=HTTP
&HealthCheckHttpVersion=HTTP 1.0
&HealthyThreshold=4
&UnhealthyThreshold=4
&DryRun=true
&<Common request parameters>

Sample success responses

XML format

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

<CreateHealthCheckTemplateResponse>
    <HealthCheckTemplateId>hct-1224334</HealthCheckTemplateId>
    <RequestId>365F4154-92F6-4AE4-92F8-7FF34B540710</RequestId>
</CreateHealthCheckTemplateResponse>

JSON format

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

{
  "HealthCheckTemplateId" : "hct-1224334",
  "RequestId" : "365F4154-92F6-4AE4-92F8-7FF34B540710"
}

Error codes

HttpCode Error code Error message Description
400 QuotaExceeded.HealthCheckTemplatesNum The quota of %s is exceeded, usage %s/%s. The error message returned because the usage %s has exceeded the quota %s.

For a list of error codes, visit the API Error Center.