On this page

Show all

Help Center/ Distributed Message Service for Kafka/ API Reference/ Out-of-Date APIs/ API V2/ Managing Lifecycle/ Creating an Instance

Creating an Instance

Updated on 2025-05-06 GMT+08:00

Online Debugging

CLI Examples

View PDF

Function

This API is used to create an instance.

NOTE:

This API is out-of-date and may not be maintained in the future. Please use the API described in Creating an Instance.

URI

POST /v2/{engine}/{project_id}/instances

**Table 1** URI parameters
Parameter	Mandatory	Type	Description
engine	Yes	String	Message engine.
project_id	Yes	String	Project ID. For details, see Obtaining a Project ID.

Request

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
name	Yes	String	Instance name. An instance name starts with a letter, consists of 4 to 64 characters, and can contain only letters, digits, underscores (_), and hyphens (-).
description	No	String	Description of an instance. 0 to 1024 characters. NOTE: The backslash (\) and quotation mark (") are special characters for JSON messages. When using these characters in a parameter value, add the escape character (\) before the characters, for example, \\ and \".
engine	Yes	String	Message engine. Set the value to kafka.
engine_version	Yes	String	Version of the engine. Values: 1.1.0 2.3.0 2.7 3.x
broker_num	Yes	Integer	Number of brokers.
storage_space	Yes	Integer	Message storage space, in GB. 300–300,000 GB for c6.2u4g.cluster Kafka instances 300–600,000 GB for c6.4u8g.cluster Kafka instances 300–1,500,000 GB for c6.8u16g.cluster Kafka instances 300–1,500,000 GB for c6.12u24g.cluster Kafka instances 300–1,500,000 GB for c6.16u32g.cluster Kafka instances
access_user	No	String	This parameter is mandatory when ssl_enable is set to true. This parameter is invalid when ssl_enable is set to false. A username must start with a letter and only letters, digits, hyphens (-), and underscores (_) are allowed. It can contain 4 to 64 characters.
password	No	String	This parameter is mandatory when ssl_enable is set to true. This parameter is invalid when ssl_enable is set to false. Instance password. The password must meet the following complexity requirements: Can contain 8 to 32 characters. Must contain at least three of the following character types: Lowercase letters Uppercase letters Digits Special characters include `~!@#$%^&*()-_=+\|[{}]:',"<.>/? and spaces, and cannot start with a hyphen (-).
vpc_id	Yes	String	VPC ID. To obtain it, log in to the VPC console and view the VPC ID on the VPC details page.
security_group_id	Yes	String	Security group which the instance belongs to. To obtain it, log in to the VPC console and view the security group ID on the security group details page.
subnet_id	Yes	String	Subnet information. To obtain it, log in to VPC console and click the target subnet on the Subnets page. You can view the network ID on the displayed page.
available_zones	Yes	Array of strings	ID of the AZ where instance brokers reside and which has available resources. Obtain the AZ ID by referring to Listing AZ Information. This parameter cannot be empty or null. When creating a Kafka instance, you can select either 1 AZ or at least 3 AZ. When specifying AZs for brokers, use commas (,) to separate multiple AZs.
product_id	Yes	String	Product ID. You can obtain the product ID from Querying Product Specifications.
maintain_begin	No	String	Time at which the maintenance time window starts. Format: HH:mm.
maintain_end	No	String	Time at which the maintenance time window ends. Format: HH:mm.
enable_publicip	No	Boolean	Whether to enable public access. true: enable false (default): disable
publicip_id	No	String	ID of the elastic IP address (EIP) bound to an instance. Use commas (,) to separate multiple EIP IDs. This parameter is mandatory if public access is enabled (that is, enable_publicip is set to true).
ssl_enable	No	Boolean	Whether to enable SSL-encrypted access. This setting is fixed once the instance is created. true: enable false: disable
kafka_security_protocol	No	String	Security protocol to use after SASL is enabled. This parameter is mandatory if SASL authentication is enabled (that is, when ssl_enable is set to true). If this parameter is left blank, SASL_SSL authentication is enabled by default. This setting is fixed once the instance is created. SASL_SSL: Data is encrypted with SSL certificates for high-security transmission. SASL_PLAINTEXT: Data is transmitted in plaintext with username and password authentication. This protocol uses the SCRAM-SHA-512 mechanism to deliver better performance.
sasl_enabled_mechanisms	No	Array of strings	Authentication mechanism to use after SASL is enabled. This parameter is mandatory if SASL authentication is enabled (that is, when ssl_enable is set to true). If this parameter is left blank, PLAIN authentication is enabled by default. Select both or either of the following mechanisms. Options: PLAIN: simple username and password verification. SCRAM-SHA-512: user credential verification, which is more secure than PLAIN.
retention_policy	No	String	Action to be taken when the memory usage reaches the disk capacity threshold. Values: produce_reject: New messages cannot be created. time_base: The earliest messages are deleted.
ipv6_enable	No	Boolean	Indicates whether IPv6 is enabled. This parameter is available only when the VPC supports IPv6.
disk_encrypted_enable	No	Boolean	Indicates whether to enable disk encryption.
disk_encrypted_key	No	String	Disk encryption key. If disk encryption is not enabled, this parameter is left blank.
enable_auto_topic	No	Boolean	Indicates whether to enable automatic topic creation. true: enable false: disable If automatic topic creation is enabled, a topic will be automatically created with 3 partitions and 3 replicas when a message is produced to or consumed from a topic that does not exist. The default value is false.
storage_spec_code	Yes	String	Storage I/O specification. Values: dms.physical.storage.high.v2: high I/O dms.physical.storage.ultra.v2: ultra-high I/O For details about selecting a disk type, see "Disk Types and Disk Performance" in Elastic Volume Service User Guide.
enterprise_project_id	No	String	Enterprise project ID. This parameter is mandatory for an enterprise project account.
tags	No	Array of TagEntity objects	List of tags.
arch_type	No	String	CPU architecture. x86 is available. Values: x86
vpc_client_plain	No	Boolean	Private plaintext access in a VPC.
bss_param	No	BssParam object	Parameter related to the yearly/monthly billing mode. If this parameter is left blank, the billing mode is pay-per-use by default. If this parameter is not left blank, the billing mode is yearly/monthly.

**Table 3** TagEntity
Parameter	Mandatory	Type	Description
key	No	String	Tag key, which: Cannot be left blank. Must be unique for the same instance. Can contain 1 to 128 characters. Can contain letters, digits, spaces, and special characters _.:=+-@ Cannot start or end with a space.
value	No	String	Tag value. Can contain 0 to 255 characters. Can contain letters, digits, spaces, and special characters _.:=+-@ Cannot start or end with a space.

**Table 4** BssParam
Parameter	Mandatory	Type	Description
is_auto_renew	No	Boolean	Indicates whether auto-renewal is enabled. Values: true: Yes false: No By default, auto renewal is disabled.
charging_mode	No	String	Billing mode. Values: prePaid: yearly/monthly postPaid: pay-per-use The default value is postPaid.
is_auto_pay	No	Boolean	Specifies whether the order is automatically or manually paid. Values: true: Yes. The order will be automatically paid. false: No. The order needs to be paid manually. The default value is false.
period_type	No	String	Subscription period Values: month year This parameter is valid and mandatory when chargingMode is set to prePaid.
period_num	No	Integer	Number of subscription periods. Values: If periodType is month, the value ranges from 1 to 9. If periodType is year, the value ranges from 1 to 3. This parameter is valid and mandatory when chargingMode is set to prePaid.

Response

Status code: 200

**Table 5** Response body parameter
Parameter	Type	Description
instance_id	String	Instance ID.

Example Request

Creating a pay-per-use Kafka instance whose version is 2.7, specifications are 2 vCPUs | 4 GB × 3, and storage space is 300 GB

POST https://{endpoint}/v2/{engine}/{project_id}/instances

{
  "name" : "kafka-test",
  "description" : "",
  "engine" : "kafka",
  "engine_version" : "2.7,3.x",
  "storage_space" : 300,
  "vpc_id" : "********-9b4a-44c5-a964-************",
  "subnet_id" : "********-8fbf-4438-ba71-************",
  "security_group_id" : "********-e073-4aad-991f-************",
  "available_zones" : [ "********706d4c1fb0eb72f0********" ],
  "product_id" : "c6.2u4g.cluster",
  "ssl_enable" : true,
  "kafka_security_protocol" : "SASL_SSL",
  "sasl_enabled_mechanisms" : [ "SCRAM-SHA-512" ],
  "storage_spec_code" : "dms.physical.storage.ultra.v2",
  "broker_num" : 3,
  "arch_type" : "X86",
  "enterprise_project_id" : "0",
  "access_user" : "********",
  "password" : "********",
  "enable_publicip" : true,
  "tags" : [ {
    "key" : "aaa",
    "value" : "111"
  } ],
  "retention_policy" : "time_base",
  "disk_encrypted_enable" : true,
  "disk_encrypted_key" : "********-b953-4875-a743-************",
  "publicip_id" : "********-88fc-4a8c-86d0-************,********-16af-455d-8d54-************,********-3d69-4367-95ab-************",
  "vpc_client_plain" : true,
  "enable_auto_topic" : true
}

Example Response

Status code: 200

Instance created successfully.

{
  "instance_id" : "8959ab1c-7n1a-yyb1-a05t-93dfc361b32d"
}

Status Code


Status Code	Description
200	Instance created successfully.

Error Code

See Error Codes.

Parent Topic: Managing Lifecycle

Previous topic: Managing Lifecycle

Next topic: Querying an Instance

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot