Help Center/ Elastic Cloud Server/ API Reference/ APIs/ Template Management/ Creating a Template
Updated on 2026-08-14 GMT+08:00
View PDF
Share

Creating a Template

Function

This API is used to create a launch template.

The automatically-generated version 1 is the default version.

Constraints

  • The template does not support the yearly/monthly billing mode.
  • The template does not support IPv6 and driver_mode specifications.
  • The template cannot be used to launch ECSs from DeH, DCC, or DSS.
  • This API does not check the existence and validity of the request parameters.

Debugging

You can debug this API in API Explorer.

Authorization

Each account has all of the permissions required to call all APIs, but IAM users must have the required permissions specifically assigned.
  • If you are using role/policy-based authorization, see the required permissions in Permissions and Supported Actions.
  • If you are using identity policy-based authorization, the permissions listed below are required.

Action

Access Level

Resource Type (*: required)

Condition Key

Alias

Dependencies

ecs:launchTemplates:create

write

-

-

-

-

URI

POST /v3/{project_id}/launch-templates

Table 1 describes the parameters in the URI.
Table 1 Parameter description

Parameter

Mandatory

Description

project_id

Yes

Definition

Specifies the project ID.

For details about how to obtain the ID, see Obtaining a Project ID.

Constraints

N/A

Range

N/A

Default Value

N/A

Request

Table 2 describes the request parameters.

Table 2 Request parameters

Parameter

Mandatory

Type

Description

launch_template

Yes

Object

Definition

Specifies the template information. For details, see Table 3.

Constraints

N/A

Range

N/A

Default Value

N/A

dry_run

No

Boolean

Definition

Specifies whether the system checks the request. If this parameter is set to true, the system checks the request, but no template will be created.

Constraints

N/A

Range

  • true: The system checks the request. Check items include mandatory parameters and request format.
    • If the check fails, the system returns an error.
    • If the check is successful, the system returns status code 202.
  • false: The system sends the request without checking the request body.

Default Value

false
Table 3 launch_template field description

Parameter

Mandatory

Type

Description

template_data

No

Object

Definition

Specifies the template creation request information. For details, see Table 4.

Constraints

N/A

Range

N/A

Default Value

N/A

name

Yes

String

Definition

Specifies the template name.

Constraints

N/A

Range

  • The length is 1 to 64 characters.
  • Only letters, digits, hyphens (-), underscores (_), and periods (.) are allowed.

Default Value

N/A

description

No

String

Definition

Specifies the template description.

Constraints

N/A

Range

The maximum length is 85 characters.

Default Value

N/A

version_description

No

String

Definition

Specifies the version description of the first version.

Constraints

N/A

Range

The maximum length is 85 characters.

Default Value

N/A
Table 4 template_data field description

Parameter

Mandatory

Type

Description

flavor_id

No

String

Definition

Specifies the flavor ID of the ECS to be created based on the template.

Constraints

N/A

Range

N/A

Default Value

N/A

name

No

String

Definition

Specifies the ECS name.

Constraints

N/A

Range

N/A

Default Value

N/A

description

No

String

Definition

Specifies the ECS description.

Constraints

N/A

Range

N/A

Default Value

N/A

availability_zone_id

No

String

Definition

Specifies the AZ.

Constraints

N/A

Range

N/A

Default Value

N/A

enterprise_project_id

No

String

Definition

Specifies the enterprise project ID.

Constraints

N/A

Range

N/A

Default Value

N/A

auto_recovery

No

Boolean

Definition

Specifies whether automatic recovery is enabled on the ECS.

Constraints

N/A

Range

  • true: Automatic recovery is enabled.
  • false: Automatic recovery is disabled.

Default Value

N/A

os_profile

No

Object

Definition

Specifies the image attribute. For details, see Table 5.

Constraints

N/A

Range

N/A

Default Value

N/A

security_group_ids

No

Array of strings

Definition

Specifies the security group ID list. This parameter applies to all network interfaces.

Constraints

N/A

Range

N/A

Default Value

N/A

network_interfaces

No

Array of Objects

Definition

Specifies the network interfaces. For details, see Table 6.

Constraints

N/A

Range

N/A

Default Value

N/A

block_device_mappings

No

Array of Objects

Definition

Specifies the BDM mounting information. The value is subject to the flavor. For details, see Table 8.

Constraints

N/A

Range

N/A

Default Value

N/A

market_options

No

Object

Definition

Specifies the billing information. For details, see Table 10.

Constraints

N/A

Range

N/A

Default Value

N/A

internet_access

No

Object

Definition

Specifies the public network access. For details, see Table 12.

Constraints

N/A

Range

N/A

Default Value

N/A

metadata

No

Map<String,String>

Definition

Specifies ECS metadata.

You can use metadata to customize key-value pairs. For details about reserved key-value pairs, see Table 11.

Constraints

N/A

Range

  • key: The length is greater than 0 and less than 256 characters.
  • value: The length is greater than or equal to 0 and less than 256 characters.

Default Value

N/A

tag_options

No

Array of Objects

Definition

Specifies VM tags. Currently, only VMs can be tagged. In the future, associated resources such as volumes can be tagged, too.

For details, see Table 15.

Constraints

N/A

Range

N/A

Default Value

N/A
Table 5 os_profile field description

Parameter

Mandatory

Type

Description

key_name

No

String

Definition

Specifies the name of the SSH key pair used for logging in to the ECS.

Constraints

N/A

Range

N/A

Default Value

N/A

user_data

No

String

Definition

Specifies the user data to be injected to the ECS. Text and text files can be injected.

Constraints

  • The content of user_data must be encoded with base64.
  • The maximum size of the content to be injected (before encoding) is 32 KB.

Range

N/A

Default Value

N/A

iam_agency_name

No

String

Definition

Specifies the agency name.

Constraints

N/A

Range

N/A

Default Value

N/A

enable_monitoring_service

No

Boolean

Definition

Enables HSS.

Constraints

N/A

Range

N/A

Default Value

N/A
Table 6 network_interfaces field description

Parameter

Mandatory

Type

Description

virsubnet_id

No

String

Definition

Specifies the subnet ID.

Constraints

The value must be the ID of the subnet created in the VPC specified by vpcid and in the UUID format.

You can obtain the parameter value by calling a VPC API for Querying Subnets.

Range

N/A

Default Value

N/A

attachment

No

Object

Definition

Specifies the network interface details. For details, see Table 7.

Constraints

N/A

Range

N/A

Default Value

N/A
Table 7 attachment field description of network_interfaces

Parameter

Mandatory

Type

Description

device_index

No

Integer

Definition

Specifies the relative position of a NIC on a cloud server. The value is 0 for the primary NIC.

Constraints

  • The value cannot be set to 0 for multiple NICs.
  • If device_index is not specified, the system assigns values sequentially based on the list order.

Range

N/A

Default Value

N/A
Table 8 block_device_mappings field description

Parameter

Mandatory

Type

Description

source_id

No

String

Definition

Specifies the VM volume data source type.

  • If source_type is volume, the value of this parameter is a volume UUID.
  • If source_type is snapshot, the value of this parameter is a snapshot UUID.
  • If source_type is image, the value of this parameter is an image UUID.

Constraints

N/A

Range

N/A

Default Value

N/A

source_type

No

String

Definition

Specifies the source type of the volume device.

Constraints

N/A

Range

Currently, the value can only be volume, image, snapshot, or blank.

  • volume: An ECS is created from a volume.
  • image: An ECS is created from an image.
  • snapshot: An ECS is created from a snapshot.
  • blank: An empty data volume is created.

Default Value

N/A

encrypted

No

Boolean

Definition

Encrypted or not.

Constraints

N/A

Range

N/A

Default Value

N/A

cmk_id

No

String

Definition

Specifies the key ID.

Constraints

N/A

Range

N/A

Default Value

N/A

volume_type

No

String

Definition

Specifies the volume type.

For details about disk types, see Disk Types and Performance.

Constraints

This parameter is recommended when source_type is set to image and destination_type is set to volume.

Range

N/A

Default Value

N/A

volume_size

No

Integer

Definition

Specifies the volume size.

Constraints

N/A

Range

The value is an integer, in GiB.

Default Value

N/A

attachment

No

Object

Definition

Specifies the disk interface. For details, see Table 9.

Constraints

N/A

Range

N/A

Default Value

N/A
Table 9 attachment field description

Parameter

Mandatory

Type

Description

boot_index

No

Integer

Definition

Specifies a boot flag.

Constraints

If source_type is volume for all disks, there must be one boot_index whose value is 0.

Range

  • 0: boot disk.
  • -1: non-boot disk. If this parameter is not specified, the default value -1 is used.

Default Value

N/A

delete_on_termination

No

Boolean

Definition

Specifies whether the disk is released along with the instance.

Constraints

N/A

Range

  • true: The disk is released along with the instance.
  • false: The disk is not released along with the instance.

Default Value

By default, this parameter is set to true for the system disk, indicating that the system disk is released along with the instance, and set to false for data disks, indicating that they are not released along with the instance.
Table 10 market_options field description

Parameter

Mandatory

Type

Description

market_type

No

String

Definition

Specifies the billing mode.

Constraints

N/A

Range

N/A

Default Value

N/A

spot_options

No

Object

Definition

Specifies spot instance parameters. For details, see Table 11.

Constraints

N/A

Range

N/A

Default Value

N/A
Table 11 spot_options field description

Parameter

Mandatory

Type

Description

spot_price

No

Float

Definition

Specifies the highest price per hour you are willing to pay for a spot ECS.

Constraints

N/A

Range

N/A

Default Value

N/A

block_duration_minutes

No

Integer

Definition

Specifies the predefined duration of the spot ECS.

Constraints

N/A

Range

N/A

Default Value

N/A

instance_interruption_behavior

No

String

Definition

Specifies the spot ECS interruption policy, which can only be set to immediate currently.

Constraints

N/A

Range

N/A

Default Value

N/A
Table 12 internet_access field description

Parameter

Mandatory

Type

Description

publicip

No

Object

Definition

Specifies the public network access. For details, see Table 13.

Constraints

N/A

Range

N/A

Default Value

N/A
Table 13 publicip field description

Parameter

Mandatory

Type

Description

publicip_type

No

String

Definition

Specifies the EIP type.

Constraints

The value must be supported by the system.

Range

5_bgp (dynamic BGP), 5_sbgp (static BGP)

Default Value

N/A

charging_mode

No

String

Definition

Specifies the EIP billing mode.

Constraints

N/A

Range

  • prePaid: yearly/monthly
  • postPaid: pay-per-use

Default Value

postPaid

bandwidth

No

Object

Definition

Specifies the EIP bandwidth. For details, see Table 14.

Constraints

N/A

Range

N/A

Default Value

N/A

delete_on_termination

No

Boolean

Definition

Specifies whether the EIP is released along with the instance.

Constraints

N/A

Range

  • true: The EIP is released along with the instance.
  • false: The EIP is not released along with the instance.

Default Value

N/A
Table 14 bandwidth field description

Parameter

Mandatory

Type

Description

share_type

No

String

Definition

Specifies the bandwidth type.

Constraints

N/A

Range

N/A

Default Value

N/A

size

No

integer

Definition

Specifies the bandwidth size.

Constraints

N/A

Range

N/A

Default Value

N/A

charge_mode

No

String

Definition

Specifies the billing mode.

Constraints

N/A

Range

N/A

Default Value

N/A

id

No

String

Definition

Specifies the bandwidth ID. You can use an existing shared bandwidth when applying for an EIP for the bandwidth of type WHOLE.

Constraints

N/A

Range

N/A

Default Value

N/A
Table 15 tag_options field description

Parameter

Mandatory

Type

Description

tags

No

Array of Objects

Definition

Specifies tags. For details, see Table 16.

Constraints

N/A

Range

N/A

Default Value

N/A
Table 16 tags field description

Parameter

Mandatory

Type

Description

key

No

String

Definition

Specifies the tag key.

Constraints

N/A

Range

N/A

Default Value

N/A

value

No

String

Definition

Specifies the tag value.

Constraints

N/A

Range

N/A

Default Value

N/A

Response

Table 17 describes the response parameters.

Table 17 Response parameters

Parameter

Type

Description

launch_template_id

String

Definition

Specifies the template ID.

Range

N/A

Example Request

Create a launch template with the flavor "s3.small.1" and name "ECS_Template".

POST https://{endpoint}/v3/{{projectId}}/launch-templates

{
	"launch_template": {
		"template_data": {
			"flavor_id": "s3.small.1",
			"name": "ECS_Template",
			"description": "aaa",
			"availability_zone_id": "az1",
			"enterprise_project_id": "0",
			"auto_recovery": true,
			"os_profile": {
				"key_name": "string",
				"user_data": "string",
				"iam_agency_name": "",
				"enable_monitoring_service": false
			},
			"security_group_ids": ["76b47fb1-166e-46b9-82e4-1e1c6ecf2af0"],
			"network_interfaces": [{
				"virsubnet_id": "1b223400-8aa1-444f-b3ad-d846fdbeff7e",
				"attachment": {
					"device_index": 0
				}
			}],
			"block_device_mappings": [{
				"source_id": "8e52e33d-1f2f-4d65-bd1f-c42cc420edc1",
				"source_type": "image",
				"encrypted": false,
				"cmk_id": "",
				"volume_type": "SATA",
				"volume_size": 40,
				"attachment": {
					"boot_index": 0				
                                 }
			}],
			"market_options": {
				"market_type": "postpaid",
				"spot_options": {
					"spot_price": 0,
					"block_duration_minutes": 0,
					"instance_interruption_behavior": ""
				}
			},
			"internet_access": {
				"publicip": {
					"publicip_type": "5_union",
					"charging_mode": "postPaid",
					"bandwidth": {
						"share_type": "PER",
						"size": 0,
						"charge_mode": "bandwidth",
						"id": ""
					}
				}
			},
			"metadata": {
				"additionalProp1": "",
				"additionalProp2": "",
				"additionalProp3": ""
			},
			"tag_options": [{
				"tags": [{
					"key": "aaa",
					"value": "bbb"
				}]
			}]
		},
		"name": "",
		"description": "create ecs template",
		"version_description": "1.0"
	},
	"dry_run": false
}

Example Response

{   "launch_template_id": "e6b99563-xxxx-xxxx-xxxx-1820d4fd2a67" }

Returned Values

See Returned Values for General Requests.

Error Codes

See Error Codes.

Parent topic: Template Management