Help Center/ Distributed Message Service for Kafka/ API Reference/ Out-of-Date APIs/ API V1/ APIs for Managing Instances/ Creating an Instance
Updated on 2022-09-15 GMT+08:00
View PDF

Creating an Instance

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

Function

This API is used to create a pay-per-use instance.

URI

POST /v1.0/{project_id}/instances

Table 1 describes the parameter.

Table 1 Parameters

Parameter

Type

Mandatory

Description

project_id

String

Yes

Indicates the ID of a project.

Request

Request parameters

Table 2 describes the parameters.

Table 2 Request parameters

Parameter

Type

Mandatory

Description

name

String

Yes

Indicates the 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

String

No

Indicates the description of an instance.

It is a character string containing not more than 1024 characters.

NOTE:

The backslash (\) and quotation mark (") are special characters for JSON packets. When using these characters in a parameter value, add the escape character (\) before these characters, for example, \\ and \".

engine

String

Yes

Indicates the message engine. Set the value to kafka.

engine_version

String

Yes

Indicates the version of the message engine. Value: 1.1.0 or 2.3.0.

specification

String

Yes

Indicates the baseline bandwidth of a Kafka instance, that is, the maximum amount of data transferred per unit time. Unit: MB

Options:

  • 100MB
  • 300MB
  • 600MB
  • 1200MB

storage_space

Integer

Yes

Indicates the message storage space.

Unit: GB. Value range:

  • Kafka instance with specification being 100MB: 600–90,000 GB
  • Kafka instance with specification being 300MB: 1200–90,000 GB
  • Kafka instance with specification being 600MB: 2400–90,000 GB
  • Kafka instance with specification being 1200MB: 4800–90,000 GB

partition_num

Integer

Yes

Indicates the maximum number of partitions in a Kafka instance.

Options:

  • When specification is 100MB: 300
  • When specification is 300MB: 900
  • When specification is 600MB: 1800
  • When specification is 1200 MB: 1800

access_user

String

No

This parameter is mandatory when ssl_enable is set to true. This parameter is invalid when ssl_enable is set to false.

Indicates a username. A username consists of 4 to 64 characters and can contain letters, digits, and hyphens (-).

password

String

No

This parameter is mandatory when ssl_enable is set to true. This parameter is invalid when ssl_enable is set to false.

Indicates an instance password.

The password must meet the following complexity requirements:

  • Must be a string consisting of 8 to 32 characters.
  • Must contain at least three of the following character types:
    • Lowercase letters
    • Uppercase letters
    • Digits
    • Special characters `~!@#$%^&*()-_=+\|[{}];:',<.>/?

vpc_id

String

Yes

Indicates the VPC ID.

Obtain the value by using either of the following methods:

  • Method 1: Log in to VPC console and view the VPC ID in the VPC details.
  • Method 2: Query the VPC ID through the VPC API. For details, see Querying VPCs.

security_group_id

String

Yes

Indicates the security group which the instance belongs to.

Obtain the value by using either of the following methods:

  • Method 1: Log in to VPC console. Choose Access Control > Security Groups in the navigation pane on the left. On the displayed page, click the target security group. You can view the security group ID on the displayed page.
  • Method 2: Call the API for querying security groups. For details, see Querying Security Groups.

subnet_id

String

Yes

Indicates the subnet ID.

Obtain the value by using either of the following methods:

  • Method 1: Log in to VPC console and click the target subnet on the Subnets tab page. You can view the network ID on the displayed page.
  • Method 2: Call the API for querying subnets. For details, see Querying Subnets.

available_zones

Array

Yes

Indicates the ID of the AZ where brokers reside and which has available resources. The parameter value cannot be an empty array or an empty array. For details on how to obtain the value, see Querying AZ Information. Check whether the AZ has available resources.

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. Example parameter settings:

  • One AZ: "available_zones": [ "a0865121f83b41cbafce65930a22a6e8" ]
  • Three or more AZs: "available_zones": ["a0865121f83b41cbafce65930a22a6e8","a0865121f83b41cbafce65930a22a6e7","a0865121f83b41cbafce65930a22a6e6"]

product_id

String

Yes

Indicates the product ID.

For details on how to obtain the ID, see Querying Product Specifications.

kafka_manager_user

String

Yes

Indicates the username for logging in to Kafka Manager. The username consists of 4 to 64 characters and can contain letters, digits, hyphens (-), and underscores (_).

kafka_manager_password

String

Yes

Indicates the password for logging in to Kafka Manager.

The password must meet the following complexity requirements:

  • Must be a string consisting of 8 to 32 characters.
  • Must contain at least three of the following character types:
    • Lowercase letters
    • Uppercase letters
    • Digits
    • Special characters `~!@#$%^&*()-_=+\|[{}];:',<.>/?

maintain_begin

String

No

Indicates the time at which a maintenance time window starts.

Format: HH:mm:ss

  • The start time and end time of the maintenance time window must indicate the time segment of a supported maintenance time window. For details about how to query the time segments of supported maintenance time windows, see Querying Maintenance Time Windows.
  • The start time must be set to 22:00:00, 02:00:00, 06:00:00, 10:00:00, 14:00:00, or 18:00:00.
  • Parameters maintain_begin and maintain_end must be set in pairs. If parameter maintain_begin is left blank, parameter maintain_end is also left blank. In this case, the system automatically sets the start time to 02:00:00.

maintain_end

String

No

Indicates the time at which a maintenance time window ends.

Format: HH:mm:ss

  • The start time and end time of the maintenance time window must indicate the time segment of a supported maintenance time window. For details about how to query the time segments of supported maintenance time windows, see Querying Maintenance Time Windows.
  • The end time is four hours later than the start time. For example, if the start time is 22:00:00, the end time is 02:00:00.
  • Parameters maintain_begin and maintain_end must be set in pairs. If parameter maintain_end is left blank, parameter maintain_start is also blank. In this case, the system automatically sets the end time to 06:00:00.

enable_publicip

Boolean

No

Indicates whether to enable public access for an instance.

  • true: enable
  • false: disable

public_bandwidth

String

No

Indicates the public network bandwidth. Unit: Mbit/s

Value range:

  • When specification is 100MB, the value must be a multiple of the number of brokers and fall in the range from 3 to 900.
  • When specification is 300MB, the value must be a multiple of the number of brokers and fall in the range from 3 to 900.
  • When specification is 600MB, the value must be a multiple of the number of brokers and fall in the range from 4 to 1200.
  • When specification is 1200MB, the value must be a multiple of the number of brokers and fall in the range from 8 to 2400.

publicip_id

String

No

Indicates the 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

Boolean

No

Indicates whether to enable SSL-encrypted access.

  • true: enable
  • false: disable

retention_policy

String

No

Indicates the action to be taken when the memory usage reaches the disk capacity threshold. Options:

  • time_base: Automatically delete the earliest messages.
  • produce_reject: Stop producing new messages.

enable_auto_topic

Boolean

No

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.

storage_spec_code

String

Yes

Indicates storage I/O specification.

Options:

  • dms.physical.storage.high or dms.physical.storage.ultra when the parameter specification is 100MB
  • dms.physical.storage.high or dms.physical.storage.ultra when the parameter specification is 300MB
  • dms.physical.storage.ultra when the parameter specification is 600MB
  • dms.physical.storage.ultra when the parameter specification is 1200MB

enterprise_project_id

String

No

Indicates the enterprise project ID.

tags

Array<Object>

No

Indicates the list of tags.
Table 3 tags

Parameter

Type

Mandatory

Description

key

String

No

Indicates the tag key. A tag key can contain a maximum of 36 Unicode characters.

The key cannot be left blank or be an empty string.

It cannot contain nonprintable ASCII (0–31) characters and the following special characters: =*<>\,|/

value

String

No

Indicates the value. A tag value can contain a maximum of 43 Unicode characters.

The value cannot be left blank or be an empty string.

It cannot contain nonprintable ASCII (0–31) characters and the following special characters: =*<>\,|/

 
{
 "name": "kafka-test",
 "engine": "kafka",
 "engine_version": "2.3.0",
 "specification": "100MB",
 "storage_space": 600,
 "partition_num": 300,
 "vpc_id": "b50c1aa7-39e0-420e-936b-ee5d35288f9c",
 "security_group_id": "d8c81e0f-de6a-4110-8c96-81af3eacb3d1",
 "subnet_id": "0b6cfaea-bce7-48eb-b38d-267c24df5f79",
 "available_zones": [
  "38b0f7a602344246bcb0da47b5d548e7"
 ],
 "product_id": "00300-30308-0--0",
 "kafka_manager_user": "test",
 "kafka_manager_password": "Zxxxx",
 "enable_publicip": true,
 "publicip_id": "87864b85-7097-4c06-9d62-718d7359a503,72c12ba7-fade-4b06-a680-01d335cf786d,11b535df-ed6d-4521-8d00-12bb60beb617",
 "storage_spec_code": "dms.physical.storage.high"
}

Response

Response parameters

Table 4 describes the parameters.

Table 4 Response parameters

Parameter

Type

Description

instance_id

String

Indicates the instance ID.

Example response

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

Status Code

Table 5 describes the status code of successful operations. For details about other status codes, see Status Code.

Table 5 Status code

Status Code

Description

200

The instance is created successfully.