All Products
Search

This Product

    Tair (Redis® OSS-Compatible):CreateInstance

    Document Center

    Tair (Redis® OSS-Compatible):CreateInstance

    Last Updated:Jul 03, 2026

    Creates a Redis Community Edition classic instance, a Redis Community Edition cloud-native architecture instance, or a Tair memory-optimized classic instance. To create a cloud-native architecture Tair instance, call the CreateTairInstance operation.

    Operation description

    Before you invoke this operation, make sure that you fully understand the billing methods and pricing of ApsaraDB for Tair (Redis® OSS-Compatible).

    This operation creates Redis Community Edition instances and Tair memory-optimized classic instances. To create a Tair cloud-native instance, invoke the CreateTairInstance operation.

    Note

    For the corresponding console operations and instance selection recommendations, see Create a Redis instance.

    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

    kvstore:CreateInstance

    create

    *DBInstance

    acs:kvstore:{#regionId}:{#accountId}:instance/*
    • kvstore:InstanceClass
    • kvstore:Appendonly
    • kvstore:InstanceType
    		 None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    RegionId

    string

    Yes

    The region ID. You can call DescribeRegions to query available regions. Use this parameter to specify the region in which to create the instance.

    cn-hangzhou
    Token

    string

    No

    The client token that is used to ensure the idempotence of the request. The token value is generated by the client and must be unique among different requests. The token is case-sensitive and cannot exceed 64 ASCII characters in length.

    ETnLKlblzczshOTUbOCz****
    InstanceName

    string

    No

    The name of the instance. The name must be 2 to 80 characters in length and must start with a letter or a Chinese character. The name cannot contain @/:="<>{[]} or spaces.

    apitest
    Password

    string

    No

    The password of the instance. The password must be 8 to 32 characters in length and must contain at least three of the following character types: uppercase letters, lowercase letters, special characters, and digits. The following special characters are supported: !@#$%^&*()_+-=.

    Pass!123456
    Capacity

    integer

    No

    The storage capacity of the instance. Unit: MB.

    Note

    You must specify at least one of the Capacity and InstanceClass parameters when you call this operation.

    16384
    InstanceClass

    string

    No

    The instance type. For example, redis.master.small.default specifies a Community Edition (classic) standard architecture dual-replica 1 GB instance. For more information, see Instance type overview.

    Note

    You must specify at least one of the Capacity and InstanceClass parameters when you call this operation.

    redis.master.small.default
    ZoneId

    string

    No

    The primary zone ID. You can invoke DescribeRegions to query active zones. Use this parameter to specify the zone in which to create the instance.

    Note

    You can also specify the SecondaryZoneId parameter to set the secondary zone. The primary and secondary nodes are deployed in the specified primary and secondary zones respectively, which implements a dual-center primary/secondary architecture in the same city. For example, set ZoneId to "cn-hangzhou-h" and SecondaryZoneId to "cn-hangzhou-g".

    cn-hangzhou-h
    SecondaryZoneId

    string

    No

    The secondary zone ID. You can call DescribeZones to query available zones.

    Note

    The value of this parameter must be different from the value of ZoneId. You cannot set this parameter to the ID of a multi-zone.

    cn-hangzhou-g
    ChargeType

    string

    No

    The billing method. Valid values:

    • PrePaid: subscription.

    • PostPaid (default): pay-as-you-go.

    PostPaid
    NodeType

    string

    No

    The node type. Valid values:

    • MASTER_SLAVE: high availability (dual-replica)

    • STAND_ALONE: single replica

    • double: dual-replica

    • single: single replica

    Note

    For cloud-native instances, set this parameter to MASTER_SLAVE or STAND_ALONE. For classic instances, set this parameter to double or single.

    STAND_ALONE
    NetworkType

    string

    No

    The network type. Valid values:

    • VPC: Virtual Private Cloud (VPC). This is the default value.

    VPC
    VpcId

    string

    No

    The ID of the VPC.

    vpc-bp1nme44gek34slfc****
    VSwitchId

    string

    No

    The ID of the vSwitch.

    vsw-bp1e7clcw529l773d****
    Period

    string

    No

    The subscription period. Unit: months. Valid values: 1 to 9, 12, 24, 36, and 60.

    Note

    This parameter is available and required only when ChargeType is set to PrePaid.

    12
    BusinessInfo

    string

    No

    The activity ID and business information.

    000000000
    CouponNo

    string

    No

    The coupon code. Default value: default.

    youhuiquan_promotion_option_id_for_blank
    SrcDBInstanceId

    string

    No

    To create an instance from a backup set of an existing instance, specify the instance ID of the source instance in this parameter.

    Note

    Then use the BackupId, ClusterBackupId (recommended for cloud-native cluster instances), or RestoreTime parameter to specify the backup set or point in time. This parameter must be used together with one of the preceding three parameters. The value is a string, not an array.

    r-bp1zxszhcgatnx****
    BackupId

    string

    No

    The ID of the backup set of the source instance. The system uses the data stored in the backup set to create the instance. You can invoke DescribeBackups to query the BackupId. If the source instance is a cluster instance, specify the backup set IDs of all shards of the source instance, separated by commas (,). Example: "10**,11**,15**".

    Note

    If your instance is a cloud-native architecture cluster instance, use DescribeClusterBackupList to query the cluster backup set ID, such as "cb-xx", and specify it in the ClusterBackupId request parameter to clone the cluster instance. This eliminates the need to specify individual shard backup set IDs.

    111111111
    InstanceType

    string

    No

    The instance type. Valid values:

    • Redis (default)

    • Memcache

    Redis
    EngineVersion

    string

    No

    Redis classic engine version. Valid values:

    Redis cloud-native engine version. Valid values:

    • 5.0

    • 6.0 (recommended)

    • 7.0

    Note

    Default value: 5.0.

    Valid values:

    • 4.0 :

      4.0

    • 5.0 :

      5.0

    • 6.0 :

      6.0

    • 7.0 :

      7.0

    • 2.8 :

      2.8

    5.0
    PrivateIpAddress

    string

    No

    The internal network IP address of the new instance.

    Note

    The internal network IP address must be within the vSwitch CIDR block to which the instance belongs.

    172.16.0.***
    AutoUseCoupon

    string

    No

    Specifies whether to use a coupon. Valid values:

    • true: uses a coupon.

    • false (default): does not use a coupon.

    false
    AutoRenew

    string

    No

    Specifies whether to enable auto-renewal. Valid values:

    • true: enables auto-renewal.

    • false (default): does not enable auto-renewal.

    true
    AutoRenewPeriod

    string

    No

    The auto-renewal epoch. Unit: months. Valid values: 1, 2, 3, 6, and 12.

    Note

    This parameter is required when AutoRenew is set to true.

    3
    ResourceGroupId

    string

    No

    The resource group ID.

    rg-resourcegroupid1
    RestoreTime

    string

    No

    If flashback is enabled for the source instance, you can specify a point in time within the backup retention period. The system uses the backup data of the source instance at the specified point in time to create the instance. Specify the time in the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time must be in UTC.

    2019-06-19T16:00:00Z
    DedicatedHostGroupId

    string

    No

    The ID of the dedicated cluster. This parameter is required when you create an instance in a dedicated cluster.

    dhg-uv4fnk6r7zff****
    ShardCount

    integer

    No

    The number of shards. This parameter is applicable only to cloud-native instances. You can use this parameter to customize the number of shards.

    • 1: creates a non-cluster instance.

    • A value greater than 1: creates a cluster instance.

    4
    ReplicaCount

    integer

    No

    The number of replica nodes in the primary zone. This parameter is applicable only to cloud-native cluster multi-replica instances. You can use this parameter to customize the number of replica nodes. Valid values: 1 to 4.

    Note

    If you create a multi-zone instance, you can use this parameter together with the SlaveReplicaCount parameter to customize the number of replica nodes in the primary and secondary zones. The sum of this parameter and the SlaveReplicaCount parameter cannot exceed 4.

    2
    SlaveReplicaCount

    integer

    No

    The number of replica nodes in the secondary zone.

    2
    ReadOnlyCount

    integer

    No

    The number of read-only nodes in the primary zone. This parameter is applicable only to cloud-native read/write splitting instances.

    • For standard architecture instances, valid values are 1 to 9.

    • For cluster architecture instances, valid values are 1 to 4, which specifies the number of read-only nodes per data shard.

    Note

    If you create a multi-zone instance, you can use this parameter together with the SlaveReadOnlyCount parameter to customize the number of read-only nodes in the primary and secondary zones.

    • For standard architecture instances, the sum of this parameter and SlaveReadOnlyCount cannot exceed 9.

    • For cluster architecture instances, the sum of this parameter and SlaveReadOnlyCount cannot exceed 4.

    2
    SlaveReadOnlyCount

    integer

    No

    The number of read-only nodes in the secondary zone.

    2
    GlobalInstanceId

    string

    No

    The instance ID of the distributed instance. This parameter is applicable only to Chinese site (aliyun.com).

    gr-bp14rkqrhac****
    GlobalInstance

    boolean

    No

    Specifies whether to use the new instance as the first child instance of a distributed instance. This allows you to create a distributed instance. Valid values:

    • true: uses the instance as the first child instance.

    • false (default): does not use the instance as the first child instance.

    Note

    • To set this parameter to true, the new instance must be a Tair memory-optimized instance with a database DPI engine version of 5.0.

    • This parameter is applicable only to Chinese site (aliyun.com).

    false
    Port

    string

    No

    The service port of the instance. Valid values: 1 to 65535. Default value: 6379.

    6379
    DryRun

    boolean

    No

    Specifies whether to perform a dry run for this instance creation request. Valid values:

    • true: performs a dry run without creating the instance. The system checks items such as the request parameters, request format, service limits, and available resources. If the check fails, the corresponding error is returned. If the check succeeds, the error code DryRunOperation is returned.

    • false (default): sends the request. After the request passes the check, the instance is created.

    false
    GlobalSecurityGroupIds

    string

    No

    The global IP whitelist templates for the instance. Separate multiple templates with commas (,). Duplicates are not allowed.

    Important This parameter is applicable only to cloud-native instances. Classic instances do not support the whitelist template feature.

    g-zsldxfiwjmti0kcm****
    Appendonly

    string

    No

    The Append Only File (AOF) persistence parameter settings for the new instance. Valid values:

    • yes (default): enables AOF persistence.

    • no: disables AOF persistence.

    Note

    This parameter is applicable to classic instances. Cloud-native instances do not support specifying the AOF parameter.

    Valid values:

    • no :

      Disables AOF.

    • yes :

      Enables AOF.

    yes
    ConnectionStringPrefix

    string

    No

    The prefix of the endpoint. The prefix must consist of lowercase letters and digits, start with a lowercase letter, and be 8 to 40 characters in length.

    Note

    The endpoint is in the format of: .redis.rds.aliyuncs.com.

    r-bp1zxszhcgatnx****
    ParamGroupId

    string

    No

    The ID of the parameter template. The ID is globally unique.

    Important This parameter is applicable only to cloud-native instances.

    rpg-test**
    Tag

    array<object>

    No

    The tags of the instance.

    object

    No

    The object.

    Key

    string

    No

    The key of the tag.

    Note

    • N specifies the sequence number of the tag. A maximum of 20 tags can be attached to a single instance. For example, Tag.1.Key specifies the key of the first tag, and Tag.2.Key specifies the key of the second tag.

    • If the tag key does not exist, the tag is automatically created.

    testkey
    Value

    string

    No

    The value of the tag.

    Note

    N specifies the sequence number of the tag. For example, Tag.1.Value specifies the value of the first tag, and Tag.2.Value specifies the value of the second tag.

    testvalue
    ClusterBackupId

    string

    No

    The cluster backup set ID, which is supported by some new cluster architecture instances. You can call DescribeClusterBackupList to obtain the ID.

    • If supported, specify the cluster backup set ID. You do not need to specify the BackupId parameter.

    • If not supported, specify the backup set IDs of all shards of the source instance in the BackupId parameter, separated by commas (,). Example: "2158****20,2158****22".

    cb-hyxdof5x9kqb****
    RecoverConfigMode

    string

    No

    Specifies whether to restore the account, kernel parameter (config), or whitelist information from the original backup set when you create an instance from a specified backup set. For example, to restore account information, set this parameter to account.

    The default value is empty, which indicates that the account, kernel parameter, and whitelist information is not restored from the original backup set.

    Note

    This parameter is applicable only to cloud-native instances, and the original backup set must contain the account, kernel parameter, or whitelist information. You can call DescribeBackups to check whether the RecoverConfigMode parameter of the specified backup set contains the preceding information.

    whitelist,config,account
    InstanceEndpointType

    string

    No

    The endpoint type used when you create a cloud-native dual-zone deployment read/write splitting instance. If this parameter is not explicitly committed, the default value is AzIndependentEndpoint.

    • AzIndependentEndpoint: default value. Zone-independent endpoints. The primary and secondary zones provide independent endpoints, which allow nearest access through different endpoints.

    • UnifiedEndpoint: unified endpoint. A unified endpoint is provided to access nodes in both the primary and secondary zones, but cross-zone access may occur.

    Important This parameter is applicable only to cloud-native dual-zone deployment read/write splitting instances. For other instance types, only zone-independent endpoints are supported. Even if UnifiedEndpoint is specified, it does not take effect.
    Important The UnifiedEndpoint option is available only to users on the whitelist. If you are not on the whitelist and specify this parameter, the invocation returns an error. To request access, submit a ticket.

    AzIndependentEndpoint
    MaintainStartTime

    string

    No

    The start time of the maintenance window. Specify the time in the HH:mmZ format in UTC. For example, to set the start time to 01:00 (UTC+8), specify 17:00Z.

    Note

    If this parameter is not specified, the default value is 02:00 (UTC+8), which is 18:00Z in UTC.

    03:00Z
    MaintainEndTime

    string

    No

    The end time of the maintenance window. Specify the time in the HH:mmZ format in UTC. For example, to set the end time to 02:00 (UTC+8), specify 18:00Z.

    Note

    The interval between the start time and end time must be at least 1 hour.

    Note

    If this parameter is not specified, the default value is 06:00 (UTC+8), which is 22:00Z in UTC.

    07:00Z

    The following example shows a request to create a Redis 7.0 cluster instance.

    {
  "RegionId": "ap-southeast-1",
  "InstanceName": "apitest",
  "Password": "D****23",
  "ZoneId": "ap-southeast-1a",
  "ChargeType": "PrePaid",
  "InstanceClass": "redis.shard.with.proxy.small.ce",
  "NetworkType": "VPC",
  "Period": "1",
  "InstanceType": "Redis",
  "EngineVersion": "7.0",
  "ShardCount": 4,
  "SourceIp": "10.10.10.10"
}

    Response elements

    Element

    Type

    Description

    Example

    object

    The response object.

    VpcId

    string

    The ID of the VPC.

    vpc-bp1nme44gek34slfc****
    QPS

    integer

    The queries per second (QPS). This value is the theoretical maximum for the current instance type.

    100000
    Capacity

    integer

    The storage capacity of the instance. Unit: MB.

    16384
    ConnectionDomain

    string

    The internal network endpoint of the Redis instance.

    r-bp1zxszhcgatnx****.redis.rds.aliyuncs.com
    ChargeType

    string

    The billing method. Valid values:

    • PrePaid: subscription.

    • PostPaid: pay-as-you-go.

    PostPaid
    NetworkType

    string

    The network type. Valid values:

    • CLASSIC: classic network.

    • VPC: VPC.

    VPC
    InstanceId

    string

    The instance ID, which is globally unique.

    r-bp1zxszhcgatnx****
    Port

    integer

    The Redis service port.

    6379
    Config

    string

    The detailed configuration of the instance.

    {\"EvictionPolicy\":\"volatile-lru\",\"hash-max-ziplist-entries\":512,\"zset-max-ziplist-entries\":128,\"zset-max-ziplist-value\":64,\"set-max-intset-entries\":512,\"hash-max-ziplist-value\":64}
    RegionId

    string

    The region ID of the instance.

    cn-hongkong
    EndTime

    string

    The time when the subscription instance expires. The time is in the yyyy-MM-ddTHH:mm:ssZ format in UTC.

    2019-01-18T16:00:00Z
    VSwitchId

    string

    The vSwitch ID.

    vsw-bp1e7clcw529l773d****
    RequestId

    string

    The request ID.

    5DEA3CC9-F81D-4387-8E97-CEA40F09****
    NodeType

    string

    The node type. Valid values:

    • STAND_ALONE: single replica.

    • MASTER_SLAVE: dual-replica.

    MASTER_SLAVE
    Connections

    integer

    The maximum number of connections supported by the instance.

    10000
    Bandwidth

    integer

    The bandwidth limit of the instance. Unit: MB/s.

    32
    InstanceName

    string

    The name of the instance.

    apitest
    ZoneId

    string

    The zone ID of the instance.

    cn-hangzhou-b
    InstanceStatus

    string

    The current status of the instance. The return value is fixed as Creating.

    Creating
    PrivateIpAddr

    string

    The internal IP address of the instance.

    172.16.0.10
    UserName

    string

    The account used to connect to the Redis instance. By default, an account named after the instance ID is included.

    r-bp1zxszhcgatnx****
    OrderId

    integer

    The order ID.

    2084452111111

    Examples

    Success response

    JSON format

    {
  "VpcId": "vpc-bp1nme44gek34slfc****",
  "QPS": 100000,
  "Capacity": 16384,
  "ConnectionDomain": "r-bp1zxszhcgatnx****.redis.rds.aliyuncs.com",
  "ChargeType": "PostPaid",
  "NetworkType": "VPC",
  "InstanceId": "r-bp1zxszhcgatnx****",
  "Port": 6379,
  "Config": "{\\\"EvictionPolicy\\\":\\\"volatile-lru\\\",\\\"hash-max-ziplist-entries\\\":512,\\\"zset-max-ziplist-entries\\\":128,\\\"zset-max-ziplist-value\\\":64,\\\"set-max-intset-entries\\\":512,\\\"hash-max-ziplist-value\\\":64}",
  "RegionId": "cn-hongkong",
  "EndTime": "2019-01-18T16:00:00Z",
  "VSwitchId": "vsw-bp1e7clcw529l773d****",
  "RequestId": "5DEA3CC9-F81D-4387-8E97-CEA40F09****",
  "NodeType": "MASTER_SLAVE",
  "Connections": 10000,
  "Bandwidth": 32,
  "InstanceName": "apitest",
  "ZoneId": "cn-hangzhou-b",
  "InstanceStatus": "Creating",
  "PrivateIpAddr": "172.16.0.10",
  "UserName": "r-bp1zxszhcgatnx****",
  "OrderId": 2084452111111
}

    Error codes

    HTTP status code

    Error code

    Error message

    Description
    400 ZoneIdNotFound Specify iz not support switch network. Unable to find Availability Zone
    400 InvalidShardInfo.Format Shard total number is out of range.
    400 InvalidInstancelevel Specified Instance level dose not match gdc other member instance level.
    400 InvalidBackupLogStatus Backup logs are not enabled for the specified source instance.
    400 InvalidStatus Specified instance status is Modifying. Specified instance status is Modifying.
    400 SecurityRisk.AuthVerification we have detected a risk with your default payment method. An email and notification has been sent to you. Please re-submit your order before after verificaiton.
    400 MissingParameter Period is mandatory for this action.
    400 InvalidToken.Malformed The Specified parameter Token is not valid.
    400 InvalidInstanceName.Malformed The Specified parameter InstanceName is not valid.
    400 InvalidPassword.Malformed The Specified parameter Password is not valid.
    400 InsufficientBalance Your account does not have enough balance.
    400 QuotaExceed.AfterpayInstance Living afterpay instances quota exceeded.
    400 InvalidCapacity.NotFound The Capacity provided does not exist in our records.
    400 ResourceNotAvailable Resource you requested is not available for finance user.
    400 PaymentMethodNotFound No payment method has been registered on the account.
    400 IdempotentParameterMismatch Request uses a client token in a previous request but is not identical to that request. Idempotent check.
    400 QuotaNotEnough Quota not enough in this zone.
    400 QuotaExceed Living afterpay instances quota exceed.
    400 VpcServiceError Invoke vpc service failed.
    400 IzNotSupportVpcError Specify iz not support vpc.
    400 InvalidvSwitchId The vpc does not cover the vswitch.
    400 InvalidIzNo.NotSupported The Specified vpc zone not supported.
    400 InvalidAccountPassword.Format Specified account password is not valid.
    400 InstanceClass.NotMatch Current instance class and instance type is not match.
    400 InvalidVPCId.NotFound Specified virtual vpc is not found. The specified VPC is not found. Check whether the VPC ID is correct.
    400 AccountMoneyValidateError Account money validate error.
    400 RequestTokenConflict Specified request token conflict.
    400 InvalidIPNotInSubnet Error ip not in subnet.
    400 InvalidEngineVersion.Malformed Specified engine version is not valid. The error message returned because the instance engine version is invalid.
    400 Zone.Closed The specified zone is closed.
    400 VSwithNotBelongToNotVpcFault The vSwitch does not belong to current vpc.
    400 PayIllegalAgreement Pay mayi with holding agreement illegal.
    400 IllegalParamError validateSaleConditionWithSubArticle failed.
    400 CASH_BOOK_INSUFFICIENT No payment method is specified for your account. We recommend that you add a payment method or maitain a minimum prepayment balance of INR 1000.
    400 InvalidRegion.Format Specified Region is not valid. The specified region is invalid.
    400 DryRunOperation Request validation has been passed with DryRun flag set. The request performs the pre-check operation and has passed the pre-check, and does not create an instance.
    400 ResourceGroupNotExist The Specified ResourceGroupId does not exist.
    403 RealNameAuthenticationError Your account has not passed the real-name authentication yet.
    403 AuthorizationFailure The request processing has failed due to authorization failure.
    403 TokenServiceError The specified token is duplicated, please change it.
    404 InvalidCapacity.NotFound The Capacity provided does not exist in our records. The specified storage specification does not exist.
    404 InvalidvSwitchId The Specified vSwitchId zone not supported.
    404 InvalidVpcIdOrVswitchId.NotSupported The Specified vpcId or vSwitchId not supported.

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.