Updated on 2022-08-12 GMT+08:00

Creating an Instance

Function

This API is used to create a Kafka instance.

URI

POST /v1.0/{project_id}/instances

Table 1 describes the parameter.

Table 1 Parameters

Parameter

Type

Mandatory

Description

project_id

String

Yes

Project ID.

Request

Request parameters

Table 2 describes the parameters.

Table 2 Request parameters

Parameter

Type

Mandatory

Description

name

String

Yes

Instance name.

An instance name starts with a letter, consists of 4 to 64 characters, and can contain letters, digits, and hyphens (-).

description

String

No

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

Message engine. Set the value to kafka.

engine_version

String

Yes

Version of the message engine. Value: 1.1.0 or 2.3.0.

specification

String

Yes

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

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

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.

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.

Instance password.

The password must meet the following complexity requirements:

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

vpc_id

String

Yes

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: Call the API for querying VPCs. For details, see the "Querying VPCs" section in the Virtual Private Cloud API Reference.

security_group_id

String

Yes

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 the "Querying Security Groups" section in the Virtual Private Cloud API Reference.

subnet_id

String

Yes

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 the "Querying Subnets" section in the Virtual Private Cloud API Reference.

available_zones

Array

Yes

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.

product_id

String

Yes

Product ID.

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

kafka_manager_user

String

Yes

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

kafka_manager_password

String

Yes

Password for logging in to the Kafka Manager.

The password must meet the following complexity requirements:

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

maintain_begin

String

No

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

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.

ssl_enable

Boolean

No

Whether to enable SSL-encrypted access.

  • true: enable
  • false: disable

retention_policy

String

No

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

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

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

Enterprise project ID.

tags

Array<Object>

No

List of tags.

Table 3 tags

Parameter

Type

Mandatory

Description

key

String

No

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

Tag 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",
	"description": "",
	"engine": "kafka",
	"engine_version": "XXXX",
	"storage_space": 600,
	"access_user": "",
	"password": "",
	"kafka_manager_user": "******",
	"kafka_manager_password": "******",
	"vpc_id": "1e93f86e-13af-46c8-97d6-d40fa62b76c2",
	"security_group_id": "0aaa0033-bf7f-4c41-a6c2-18cd04cad2c8",
	"subnet_id": "b5fa806c-35e7-4299-b659-b39398dd4718",
	"available_zones": ["d573142f24894ef3bd3664de068b44b0"],
	"product_id": "00300-30308-0--0",
	"maintain_begin": "22:00:00",
	"maintain_end": "02:00:00",
	"ssl_enable": false,
	"enterprise_project_id": "0",
	"specification": "100MB",
	"partition_num": "300",
	"retention_policy": "produce_reject",
        "enable_auto_topic": true,
	"storage_spec_code": "dms.physical.storage.ultra"
}

Response

Response parameters

Table 4 describes the parameters.

Table 4 Response parameters

Parameter

Type

Description

instance_id

String

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.