All Products
Search

This Product

    ApsaraMQ for RocketMQ:CreateInstance

    Document Center

    ApsaraMQ for RocketMQ:CreateInstance

    Last Updated:May 20, 2026

    Creates an ApsaraMQ for RocketMQ 5.x instance.

    Operation description

    Important

    Alibaba Cloud's OpenAPI is a management API for managing and querying your resources. It is intended for integration with the management plane only. To prevent instability, do not use OpenAPI for message transport in core data links.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    rocketmq:CreateInstance

    create

    *Instance

    acs:rocketmq:{#regionId}:{#accountId}:Instance/*

    		 None None

    Request syntax

    POST /instances HTTP/1.1

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    clientToken

    string

    No

    A client-generated token to ensure request idempotence. The token must be unique for each request and can contain up to 64 ASCII characters.

    c2c5d1274a8d4317a13bc5b0d4******
    body

    object

    No

    The request body.

    instanceName

    string

    No

    The name of the instance. If you do not specify this parameter, the instance ID is used as its name.

    If left blank, the instance ID is used as the instance name.

    rmq-cn-72u3048uxxx
    serviceCode

    string

    Yes

    The service code of the instance. For Message Queue for Apache RocketMQ, the service code is rmq.

    rmq
    seriesCode

    string

    Yes

    The primary edition of the instance. For more information about the differences between primary editions, see Product selection.

    Important

    After an instance is created, you can only upgrade its edition, not downgrade it. The upgrade path is: Standard Edition > Professional Edition > Platinum Edition.

    Valid values:

    • standard :

      Standard Edition

    • ultimate :

      Platinum Edition

    • professional :

      Professional Edition

    standard
    subSeriesCode

    string

    Yes

    The sub-edition of the instance. For more information about the differences between sub-editions, see Product selection.

    If you set the seriesCode parameter to ultimate (Platinum Edition), this parameter can only be set to cluster_ha (High-availability Cluster Edition).

    Important After an instance is created, you cannot change its sub-edition.

    Valid values:

    • serverless :

      Serverless Edition

    • cluster_ha :

      High-availability Cluster Edition

    • single_node :

      Single-node Testing Edition

    cluster_ha
    paymentType

    string

    Yes

    The billing method of the instance. Message Queue for Apache RocketMQ supports subscription and pay-as-you-go.

    For more information, see Billing methods.

    Valid values:

    • PayAsYouGo :

      pay-as-you-go. This is a postpaid mode in which you are billed for your actual usage.

    • Subscription :

      subscription. This is a prepaid mode in which you pay for a subscription duration in advance.

    Subscription
    period

    integer

    No

    The subscription duration. This parameter is required only if you set the paymentType parameter to Subscription.

    Valid values:

    • If periodUnit is set to Month, valid values are 1, 2, 3, 4, 5, and 6.

    • If periodUnit is set to Year, valid values are 1, 2, and 3.

    3
    periodUnit

    string

    No

    The unit of the subscription duration.

    Valid values:

    • Month :

      The subscription duration is specified in months.

    • Year :

      The subscription duration is specified in years.

    Month
    autoRenew

    boolean

    No

    Specifies whether to enable auto-renewal for the instance. This parameter is valid only for subscription instances.

    Valid values:

    • true :

      Enables auto-renewal.

    • false :

      Disables auto-renewal.

    true
    autoRenewPeriod

    integer

    No

    The auto-renewal period. This parameter is valid only if auto-renewal is enabled. Unit: months.

    Valid values:

    • 1, 2, 3, 6, and 12.

    3
    remark

    string

    No

    The remarks on the instance.

    This is the remark for test.
    productInfo

    object

    No

    The specifications of the instance.

    msgProcessSpec

    string

    No

    The computing specification for message sending and receiving. For information about the TPS limits for message sending and receiving, see Instance specifications.

    rmq.s2.2xlarge
    sendReceiveRatio

    number

    No

    The ratio of TPS for sending messages to the total TPS of the instance.

    For example, if the TPS limit for an instance is 1,000 and the ratio is 0.8, the TPS limit for sending messages is 800 and the TPS limit for receiving messages is 200.

    The value of this parameter must be a decimal between 0.05 and 0.95. Default value: 0.5.

    0.5
    autoScaling

    boolean

    No

    Specifies whether to enable elastic TPS for the instance.

    If you enable this feature, the instance can process more messages than the number specified by the basic specifications. You are charged for the extra TPS. For more information, see Computing fees.

    Note

    This feature is supported only by specific instance editions. For more information, see Instance specifications.

    Valid values:

    • true :

      Enables elastic TPS.

    • false :

      Disables elastic TPS.

    true
    messageRetentionTime

    integer

    No

    The message retention period. Unit: hours.

    For information about the value range, see the "Message retention period" section in the Limits topic.

    Message Queue for Apache RocketMQ provides serverless message storage that is billed based on your actual usage. You can adjust the message retention period to manage storage capacity. For more information, see Storage fees.

    72
    storageEncryption

    boolean

    No

    Specifies whether to enable storage encryption.

    false
    storageSecretKey

    string

    No

    The key that is used for storage encryption.

    xxxxx
    capacityType

    string

    No

    The capacity mode.

    Valid values:

    • provisioned :

      Reserved + Elastic

    • ondemand :

      pay-as-you-go

    provisioned
    provisionedCapacity

    integer

    No

    The reserved capacity.

    5000
    traceOn

    boolean

    No

    Specifies whether to enable the message trace feature. Valid values:

    This parameter is valid only for serverless instances. If you enable the message trace feature, you are charged for the feature. For more information, see Billing of serverless instances. For pay-as-you-go and subscription instances, this parameter does not take effect. The message trace feature is enabled for these instances by default.

    true
    drReplicationMode

    string

    No

    The cross-zone replication mode.

    Valid values:

    • async_cross_az :

      asynchronous replication

    • sync_cross_az :

      synchronous replication

    async_cross_az
    networkInfo

    object

    Yes

    The network configurations.

    vpcInfo

    object

    Yes

    The virtual private cloud (VPC) configurations.

    vpcId

    string

    Yes

    The ID of the VPC to which the instance is connected.

    Note

    After a Message Queue for Apache RocketMQ instance is created, you cannot change the VPC to which the instance is connected. If you want to change the VPC, you must release the instance and purchase a new one.

    vpc-wz9qt50xhtj9krb******
    vSwitchId deprecated

    string

    No

    The ID of the vSwitch to which the instance is connected. If you want to connect the instance to multiple vSwitches, separate the vSwitch IDs with vertical bars (|).

    Note

    After a Message Queue for Apache RocketMQ instance is created, you cannot change the vSwitch to which the instance is connected. If you want to change the vSwitch, you must release the instance and purchase a new one.

    Important

    This parameter is deprecated. We recommend that you use the vSwitches parameter.

    vsw-uf6gwtbn6etadpv*******
    securityGroupIds

    string

    No

    The ID of the security group.

    sg-bp17hpmgz96tvnsdy6so
    vSwitches

    array<object>

    No

    The list of vSwitches.

    Note

    After a Message Queue for Apache RocketMQ instance is created, you cannot change the vSwitches for the instance. If you want to change the vSwitches, you must release the instance and purchase a new one.

    Important

    This parameter is required. We recommend that you use this parameter to specify a vSwitch instead of the deprecated vSwitchId parameter.

    object

    No

    The vSwitches.

    vSwitchId

    string

    No

    The ID of the vSwitch to which the instance is connected.

    vsw-uf6gwtbn6etadpv*******
    internetInfo

    object

    Yes

    The Internet access configurations.

    internetSpec

    string

    Yes

    Specifies whether to enable Internet access.

    By default, instances can be accessed only within a VPC. If you enable Internet access for an instance, you are charged for Internet traffic that is generated by the instance. For more information, see Internet access fees.

    Valid values:

    • enable :

      Enables Internet access.

    • disable :

      Disables Internet access.

    disable
    flowOutType

    string

    Yes

    The billing method for Internet access.

    Valid values:

    • payByBandwidth :

      pay-by-bandwidth. This billing method is available only when you enable Internet access.

    • payByTraffic :

      pay-by-traffic. This billing method is available only when you enable Internet access.

    • uninvolved :

      not involved. This value is used when you disable Internet access.

    uninvolved
    flowOutBandwidth

    integer

    No

    The Internet bandwidth. Unit: Mbit/s.

    This parameter is required only when the billing method for Internet access is pay-by-bandwidth.

    Value range: 1 to 1000.

    100
    ipWhitelist deprecated

    array

    No

    The IP address whitelist for Internet access. You can configure an IP address whitelist only for public endpoints. VPC endpoints do not support this feature.

    • If you do not configure an IP address whitelist, all IP addresses are allowed to access the Message Queue for Apache RocketMQ instance over the Internet.

    • If you configure an IP address whitelist, only the IP addresses in the whitelist can access the Message Queue for Apache RocketMQ instance over the Internet.

    string

    No

    An IP address or CIDR block in the whitelist.

    192.168.x.x/24
    commodityCode deprecated

    string

    No

    The commodity code.

    • ons_rmqpost_public_intl: pay-as-you-go instance

    • ons_rmqsub_public_intl: subscription instance

    • ons_rmqsrvlesspost_public_intl: serverless instance

    ons_ rmqpost_public_cn
    resourceGroupId

    string

    No

    The ID of the resource group.

    rg-aekzy6pist7uuna
    tags

    array<object>

    No

    The resource tags.

    object

    No

    The resource tag.

    key

    string

    No

    The key of the resource tag.

    xxxKey
    value

    string

    No

    The value of the resource tag.

    xxxValue
    aclInfo

    object

    No

    The access control information.

    defaultVpcAuthFree

    boolean

    No

    Specifies whether to enable password-free access to the instance within the VPC by using intelligent identity recognition.

    • true: Enables password-free access.

    • false: Disables password-free access.

    false

    Response elements

    Element

    Type

    Description

    Example

    object

    The returned data.

    requestId

    string

    The request ID. This parameter is a common parameter. Each request has a unique ID. You can use this ID to troubleshoot issues.

    AF9A8B10-C426-530F-A0DD-96320B39****
    success

    boolean

    Indicates whether the call was successful.

    true
    data

    string

    The ID of the instance that is created.

    rmq-cn-7e22ody****
    code

    string

    The error code.

    200
    message

    string

    The error message.

    Success
    httpStatusCode

    integer

    The HTTP status code.

    200
    dynamicCode

    string

    The dynamic error code.

    InstanceId
    dynamicMessage

    string

    The dynamic error message.

    instanceId

    Examples

    Success response

    JSON format

    {
  "requestId": "AF9A8B10-C426-530F-A0DD-96320B39****",
  "success": true,
  "data": "rmq-cn-7e22ody****",
  "code": "200",
  "message": "Success",
  "httpStatusCode": 200,
  "dynamicCode": "InstanceId",
  "dynamicMessage": "instanceId"
}

    Error codes

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.