Use the CreateTairInstance API to create a Tair instance - Tair (Redis® OSS-Compatible) - Alibaba Cloud - Tair (Redis® OSS-Compatible)

Creates a cloud-native Tair (Enhanced Edition) instance.

Operation description

For information about instance selection, see ApsaraDB for Tair (Redis® OSS-Compatible) Selection Guide.

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

Note

For information about how to perform this operation in the console, see Create a Tair instance.
To create other types of instances, such as open source or Tair memory-optimized classic instances, invoke the CreateInstance operation.

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:CreateTairInstance

create

*DBInstance

acs:kvstore:{#regionId}:{#accountId}:instance/*

kvstore:InstanceClass
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
InstanceName	string	No	The instance name. The name must meet the following requirements: The name must be 2 to 80 characters in length. The name must start with a letter or a Chinese character and cannot contain spaces or the following special characters: `@/:="<>{[]}`.	apitest
Password	string	No	The instance password. The password must meet the following requirements: The password must be 8 to 32 characters in length. The password must contain at least three of the following character types: uppercase letters, lowercase letters, special characters, and digits. Supported special characters are `!@#$%^&*()_+-=`.	Pass!123456
InstanceClass	string	Yes	The instance type. For more information, see: Memory-optimized instance types Persistent memory-optimized instance types Disk-based instance types	tair.scm.standard.4m.32d
ZoneId	string	No	The primary zone ID. You can call DescribeRegions to query available zones. Use this parameter to specify the zone in which to create the instance. Note You can also specify the SecondaryZoneId parameter to set a secondary zone. The primary and secondary nodes are deployed in the specified primary and secondary zones to implement a dual-center primary/secondary architecture within 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 DescribeRegions 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 (default): subscription. PostPaid: pay-as-you-go. Valid values: PostPaid : PostPaid PrePaid : PrePaid	PrePaid
VpcId	string	Yes	The VPC ID. You can call the DescribeVpcs operation of VPC to query VPC IDs.	vpc-bp1nme44gek34slfc****
VSwitchId	string	Yes	The vSwitch ID within the specified VPC. You can call the DescribeVpcs operation of VPC to query vSwitch IDs.	vsw-bp1e7clcw529l773d****
Period	integer	No	The subscription period. Unit: months. Valid values: 1 to 9, 12, 24, 36, and 60. Note This parameter is required when ChargeType is set to PrePaid.	1
BusinessInfo	string	No	The activity ID and business information.	000000000
CouponNo	string	No	The coupon code.	youhuiquan_promotion_option_id_for_blank
SrcDBInstanceId	string	No	To create an instance from a backup set of an existing instance, specify the source instance ID 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.	r-bp1zxszhcgatnx****
BackupId	string	No	The backup set ID 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, we recommend that you invoke DescribeClusterBackupList to obtain the cluster backup set ID, such as "cb-xx", and then specify the ClusterBackupId request parameter to clone the cluster instance. This way, you do not need to specify the backup set IDs of individual shards.	2158****20
ClusterBackupId	string	No	The cluster backup set ID. Some new cluster architectures support cluster backup set IDs. You can call the DescribeClusterBackupList operation 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. The original backup set must contain the account, kernel parameter, or whitelist information. You can call the DescribeBackups operation to check whether the RecoverConfigMode parameter of the specified backup set contains the preceding information.	whitelist,config,account
PrivateIpAddress	string	No	The private IP address of the instance. Note The IP address must be within the CIDR block of the vSwitch to which the instance belongs. You can call the DescribeVSwitches operation of VPC to query the CIDR block information.	172.16.88.***
AutoUseCoupon	string	No	Specifies whether to use a coupon. Valid values: true: uses a coupon. false (default): does not use a coupon.	true
AutoRenew	string	No	Specifies whether to enable auto-renewal. Valid values: true: enables auto-renewal. false (default): disables auto-renewal.	true
AutoRenewPeriod	string	No	The auto-renewal period. 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 ID of the resource group to which the instance belongs. Note You can invoke the ListResourceGroups operation or use the console to obtain the resource group ID. Related operations, see View basic information of a resource group. Before you modify the resource group to which the instance belongs, you can invoke the ListResources operation to query the current resource group of the instance.	rg-acfmyiu4ekp****
AutoPay	boolean	No	Specifies whether to enable automatic payment. The value is fixed to true.	true
ClientToken	string	No	The client token that is used to ensure the idempotence of the request. You can use the client to generate the value. Make sure that the token is unique among different requests. The token is case-sensitive and can contain up to 64 ASCII characters.	ETnLKlblzczshOTUbOCz****
StorageType	string	No	The storage type. Valid values: essd_pl1, essd_pl2, and essd_pl3. Note This parameter is required only when InstanceType is set to tair_essd and you are creating an ESSD-based instance.	essd_pl1
Storage	integer	No	The storage capacity of a disk-based instance. The valid values vary based on the instance type. For more information, see Disk-based instance types. Note This parameter is required only when InstanceType is set to tair_essd and you are creating an ESSD-based instance. For Tair disk-based SSD instances, the storage capacity is a fixed value determined by the instance type. You do not need to specify this parameter.	60
ShardType	string	No	The instance type. Valid values: MASTER_SLAVE (default): high availability. The instance uses a primary/secondary architecture to ensure availability. STAND_ALONE: single replica. The instance uses a single-node architecture. If the node fails, data is lost and the system automatically creates a new empty instance. This value is supported only in a single zone and does not support cluster or read/write splitting architectures.	MASTER_SLAVE
ShardCount	integer	No	The number of data nodes in the instance. Valid values: 1 (default): The instance uses a standard architecture with only one data node. 2 to 32: The instance uses a cluster architecture with the specified number of data nodes. Note You can set this parameter to a value from 2 to 32 only when InstanceType is set to tair_rdb or tair_scm. Only memory-optimized and persistent memory-optimized instances support the cluster architecture.	2
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 a standard architecture instance, valid values are 1 to 9. For a cluster architecture instance, valid values are 1 to 4, which indicates 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 a standard architecture instance, the sum of this parameter and SlaveReadOnlyCount cannot exceed 9. For a cluster architecture instance, the sum of this parameter and SlaveReadOnlyCount cannot exceed 4.	5
SlaveReadOnlyCount	integer	No	The number of read-only nodes in the secondary zone.	1
EngineVersion	string	No	The database engine version. Default value: 1.0. The valid values vary based on the Tair product type: Tair_rdb: Tair memory-optimized instances are compatible with Redis 5.0, Redis 6.0, and Redis 7.0 protocols. Set this parameter to 5.0, 6.0, or 7.0. Tair_scm: Tair persistent memory-optimized instances are compatible with the Redis 6.0 protocol. Set this parameter to 1.0. Tair_essd: Tair disk-based (ESSD/SSD) instances are compatible with the Redis 6.0 protocol. Set this parameter to 1.0 for ESSD-based instances or 2.0 for SSD-based instances.	1.0
InstanceType	string	Yes	The storage medium. Valid values: tair_rdb: memory-optimized. tair_scm: persistent memory-optimized. tair_essd: disk-based.	tair_scm
GlobalInstanceId	string	No	Specifies whether to add the new instance as a child instance of a distributed instance. To add the new instance as the first child instance, set this parameter to true. To add the new instance as the second or third child instance, set this parameter to the distributed instance ID, such as gr-bp14rkqrhac**. If you do not want to create a distributed instance, leave this parameter empty. Note** To create a distributed instance, the new instance must be a Tair memory-optimized instance.	gr-bp14rkqrhac****
Tag	array<object>	No	The tags of the instance.
	object	No	The tag information.
Key	string	No	The key of the tag. The key and value together form a key-value pair for the tag. Note You can specify up to 5 key-value pairs of tags at a time.	key1_test
Value	string	No	The value of the tag. Note N indicates the sequence number of the tag value. For example, Tag.1.Value indicates the value of the first tag, and Tag.2.Value indicates the value of the second tag.	value1_test
DryRun	boolean	No	Specifies whether to perform a dry run for this 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 check succeeds, the instance is created.	false
Port	integer	No	The service port of the instance. Valid values: 1 to 65535. Default value: 6379.	6379
GlobalSecurityGroupIds	string	No	The global IP whitelist templates for the instance. Separate multiple templates with commas (,). Duplicate values are not allowed.	g-zsldxfiwjmti0kcm****
ParamGroupId	string	No	The parameter template ID. The instance is created based on the parameters in the specified parameter template. Duplicate values are not allowed.	g-50npzjcqb1ua6q6j****
RestoreTime	string	No	If data flashback is enabled for the source instance, you can specify a point in time within the backup retention period of the source instance. 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 yyyy-MM-ddTHH:mm:ssZ format (UTC).	2021-07-06T07:25:57Z
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 following format: .redis.rds.aliyuncs.com.	r-bp1zxszhcgatnx****
InstanceEndpointType	string	No	The type of endpoint used when you create a cloud-native dual-zone deployment read/write splitting instance. If this parameter is not explicitly specified, the default value is AzIndependentEndpoint. AzIndependentEndpoint: default value. Zone-independent endpoints. The primary and secondary zones provide independent endpoints. You can use different endpoints to achieve nearest access to the active zone. UnifiedEndpoint: unified endpoint. A unified endpoint is provided to access nodes in both the primary and secondary zones. However, 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 you commit UnifiedEndpoint, the setting does not take effect. Important The UnifiedEndpoint value is available only to users in the whitelist. If you are not in the whitelist and invoke this value, the invocation fails. 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 (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 18:00Z (UTC), which is 02:00 (UTC+8).
MaintainEndTime	string	No	The end time of the maintenance window. Specify the time in the HH:mmZ format (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 22:00Z (UTC), which is 06:00 (UTC+8).

Response elements

Element	Type	Description	Example
	object	The response object.
Bandwidth	integer	The maximum bandwidth of the instance. Unit: MB/s.	96
ChargeType	string	The billing method of the instance. Valid values: PrePaid: subscription. PostPaid: pay-as-you-go.	PrePaid
Config	string	The detailed configurations of the instance. The value is a JSON string. For more information about the parameters, see Parameter settings.	{\"EvictionPolicy\":\"volatile-lru\",\"hash-max-ziplist-entries\":512,\"zset-max-ziplist-entries\":128,\"list-max-ziplist-entries\":512,\"list-max-ziplist-value\":64,\"zset-max-ziplist-value\":64,\"set-max-intset-entries\":512,\"hash-max-ziplist-value\":64}
ConnectionDomain	string	The internal network endpoint of the instance.	r-bp13ac3d047b****.tairpena.rds.aliyuncs.com
Connections	integer	The maximum number of connections for the instance.	10000
InstanceId	string	The instance ID.	r-bp13ac3d047b****
InstanceName	string	The instance name. Note This parameter is returned only when the InstanceName request parameter is specified.	redistest
InstanceStatus	string	The current status of the instance. The return value is fixed to Creating.	Creating
OrderId	integer	The order ID.	2084452111111
Port	integer	The port number of the instance.	6379
QPS	integer	The maximum number of read and write operations per second. Unit: operations per second. This is the theoretical value for the current instance type.	100000
RegionId	string	The region ID.	cn-hangzhou
RequestId	string	The request ID.	12123216-4B00-4378-BE4B-08005BFC****
TaskId	string	The task ID.	10****
ZoneId	string	The zone ID.	cn-hangzhou-h

Examples

Success response

JSON format

{
  "Bandwidth": 96,
  "ChargeType": "PrePaid",
  "Config": "{\\\"EvictionPolicy\\\":\\\"volatile-lru\\\",\\\"hash-max-ziplist-entries\\\":512,\\\"zset-max-ziplist-entries\\\":128,\\\"list-max-ziplist-entries\\\":512,\\\"list-max-ziplist-value\\\":64,\\\"zset-max-ziplist-value\\\":64,\\\"set-max-intset-entries\\\":512,\\\"hash-max-ziplist-value\\\":64}",
  "ConnectionDomain": "r-bp13ac3d047b****.tairpena.rds.aliyuncs.com",
  "Connections": 10000,
  "InstanceId": "r-bp13ac3d047b****",
  "InstanceName": "redistest",
  "InstanceStatus": "Creating",
  "OrderId": 2084452111111,
  "Port": 6379,
  "QPS": 100000,
  "RegionId": "cn-hangzhou",
  "RequestId": "12123216-4B00-4378-BE4B-08005BFC****",
  "TaskId": "10****",
  "ZoneId": "cn-hangzhou-h"
}

Error codes

HTTP status code	Error code	Error message	Description
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.
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.
403	UserCannotBuyNotInnerCommodity	The user can not buy this commodity without alibaba group tag.
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.