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

Create a cloud-native Tair Enterprise Edition instance.

Operation description

For information about instance selection, see ApsaraDB for Tair (Redis-compatible) instance selection guide.

Before you call this API, ensure you understand the billing methods and pricing for ApsaraDB for Tair (Redis-compatible).

Note

To create an instance in the console, see Create a Tair instance.
To create other instance types, such as open-source or Tair memory-enhanced classic edition, call the CreateInstance API.

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 ID of the region where you want to create the instance. You can call the DescribeRegions operation to query available regions.	cn-hangzhou
InstanceName	string	No	The name of the instance. The name must meet the following requirements: It must be 2 to 80 characters in length. It must start with an uppercase or lowercase letter or a Chinese character. It cannot contain spaces or the following special characters: `@/:=”<>{[]}`.	apitest
Password	string	No	The password of the instance. The password must meet the following requirements: It must be 8 to 32 characters in length. It must contain at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters. The supported special characters are `!@#$%^&*()_+-=`.	Pass!123456
InstanceClass	string	Yes	The instance type. For more information, see the following topics: Memory-enhanced instance types Persistent memory-optimized instance types Disk-based instance types	tair.scm.standard.4m.32d
ZoneId	string	No	The ID of the primary zone where you want to create the instance. You can call the DescribeRegions operation to query available zones. Note You can also specify a secondary zone by using the `SecondaryZoneId` parameter. This deploys the primary and replica nodes in different zones within the same region for a high-availability primary/replica architecture. For example, you can set `ZoneId` to `cn-hangzhou-h` and `SecondaryZoneId` to `cn-hangzhou-g`.	cn-hangzhou-h
SecondaryZoneId	string	No	The ID of the secondary zone. You can call the DescribeRegions operation to query available zones. Note The value of this parameter cannot be the same as the value of the `ZoneId` parameter. You cannot specify a multi-zone ID.	cn-hangzhou-g
ChargeType	string	No	The billing method of the instance. Valid values: PrePaid (default): The subscription billing method. PostPaid: The pay-as-you-go billing method. Valid values: PostPaid : PostPaid PrePaid : PrePaid	PrePaid
VpcId	string	Yes	The ID of the Virtual Private Cloud (VPC) where you want to create the instance. You can call the DescribeVpcs operation to query available VPCs.	vpc-bp1nme44gek34slfc****
VSwitchId	string	Yes	The ID of the vSwitch in the specified VPC. You can call the VPC API operation DescribeVSwitches to obtain the vSwitch ID.	vsw-bp1e7clcw529l773d****
Period	integer	No	The subscription duration, in months. Valid values: 1, 2, 3, 4, 5, 6, 7, 8, 9, 12, 24, 36, and 60. Note This parameter is required only when you set the `ChargeType` parameter to `PrePaid`.	1
BusinessInfo	string	No	The business information. This can be the ID of a promotion or a business context.	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 ID of the source instance. Note You must also specify the backup data by using one of the following parameters: BackupId, ClusterBackupId, or RestoreTime. We recommend that you use `ClusterBackupId` for cloud-native instances that use a cluster architecture.	r-bp1zxszhcgatnx****
BackupId	string	No	The ID of the backup set from the source instance. The system creates a new instance based on the data in this backup set. You can call the DescribeBackups operation to query the backup set ID. If the source instance is a cluster instance, you must specify the backup ID for each shard, separated by commas, for example, "10,11,15". Note** If your instance is a cloud-native cluster instance, we recommend that you call the DescribeClusterBackupList operation to query the cluster backup ID, such as `cb-xx`. Then, specify the cluster backup ID for the `ClusterBackupId` parameter to clone the cluster instance. This avoids the need to specify the backup ID of each shard.	2158****20
ClusterBackupId	string	No	The ID of the cluster backup set. Some instances that use the cluster architecture support cluster backup sets. You can call the DescribeClusterBackupList operation to query for cluster backup set IDs. If this feature is supported, you can specify this parameter and leave the BackupId parameter empty. If this feature is not supported, you must specify the backup ID of each shard of the source instance for the `BackupId` parameter. Separate the backup IDs with commas, for example, "2158**20,2158**22".	cb-hyxdof5x9kqb****
RecoverConfigMode	string	No	When creating an instance from a backup set, specifies whether to restore configurations such as account information (`account`), kernel parameters (`config`), and whitelists (`whitelist`) from the source backup set. To restore a specific configuration, specify its keyword. To restore multiple configurations, separate the keywords with commas. If this parameter is not specified, no configurations are restored from the source backup set. Note This parameter applies only to cloud-native instances, and the source backup set must contain the specified configuration information. You can call the DescribeBackups operation and check the `RecoverConfigMode` parameter in the response to check if the backup set contains the 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 to query the CIDR block information.	172.16.88.***
AutoUseCoupon	string	No	Specifies whether to use a coupon. Valid values: true: Use a coupon. false (default): Do not use a coupon.	true
AutoRenew	string	No	Specifies whether to enable auto-renewal for the instance. Valid values: true: Enable auto-renewal. false (default): Disable auto-renewal.	true
AutoRenewPeriod	string	No	The auto-renewal duration. Unit: month. Valid values: 1, 2, 3, 6, and 12. Note This parameter is required only when the AutoRenew parameter is set to true.	3
ResourceGroupId	string	No	The ID of the resource group to which the instance belongs. Note You can call the ListResourceGroups operation or use the Resource Management console to query the IDs of resource groups. For more information, see View basic information of a resource group. Before you change the resource group of an instance, you can call the ListResources operation to view the current resource group of the instance.	rg-acfmyiu4ekp****
AutoPay	boolean	No	Specifies whether to enable automatic payment. Set the value to true.	true
ClientToken	string	No	A client-generated token that ensures the idempotence of the request. The token must be unique among different requests. It is case-sensitive and cannot exceed 64 ASCII characters in length.	ETnLKlblzczshOTUbOCz****
StorageType	string	No	The storage type. Valid values: essd_pl1, essd_pl2, and essd_pl3. Note This parameter is required only when you set the InstanceType parameter to `tair_essd` to create a Tair instance that uses an Enhanced SSD (ESSD).	essd_pl1
Storage	integer	No	The storage space of the disk-based instance. The valid values of this parameter vary based on the instance type. For more information, see Disk-based instance types. Note This parameter is required only when you set the InstanceType parameter to `tair_essd` to create a Tair instance that uses an ESSD. For Tair instances that use standard `SSD`s, the storage capacity is determined by the instance type and you do not need to specify this parameter.	60
ShardType	string	No	The architecture type of the instance. Valid values: MASTER_SLAVE (default): The primary/replica architecture, which provides high availability. STAND_ALONE: single-replica. This architecture uses a single node. If the node fails, data is lost, and the system automatically creates a new, empty instance. This architecture is supported only for single-zone deployments and does not support cluster or read/write splitting architectures.	MASTER_SLAVE
ShardCount	integer	No	The number of shards in the instance. Valid values: 1 (default): Creates a standard architecture instance with a single shard. From 2 to 32: Creates a cluster architecture instance with the specified number of shards. Note You can specify a value from 2 to 32 for this parameter only when you set the InstanceType parameter to `tair_rdb` or `tair_scm`. Only memory-enhanced 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, multi-replica cluster 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 and the `SlaveReplicaCount` parameter to customize the number of replica nodes in the primary and secondary zones. The sum of `ReplicaCount` and `SlaveReplicaCount` 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 instances that use the read/write splitting architecture. If the instance uses the standard architecture, the valid values are 1 to 9. If the instance uses the cluster architecture, specify the number of read-only nodes per shard. The valid values are 1 to 4. Note If you create a multi-zone instance, you can use this parameter and the `SlaveReadOnlyCount` parameter to customize the number of read-only nodes in the primary and secondary zones. If the instance uses the standard architecture, the sum of `ReadOnlyCount` and `SlaveReadOnlyCount` cannot exceed 9. If the instance uses the cluster architecture, the sum of `ReadOnlyCount` 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 version. Default value: 1.0. The valid values depend on the Tair instance series: tair_rdb: Tair memory-enhanced instances are compatible with Redis 5.0, Redis 6.0, and Redis 7.0. Set the value to 5.0, 6.0, or 7.0. tair_scm: Tair persistent memory-optimized instances are compatible with Redis 6.0. Set the value to 1.0. tair_essd: Tair disk-based instances (ESSD/SSD) are compatible with Redis 6.0. Set the value to 1.0 to create an ESSD-based instance or 2.0 to create an SSD-based instance.	1.0
InstanceType	string	Yes	The Tair instance series, which determines the storage medium. Valid values: tair_rdb: memory-enhanced tair_scm: persistent memory-optimized tair_essd: disk-based	tair_scm
GlobalInstanceId	string	No	Specifies whether to create the instance as a child instance in a distributed instance. By using this parameter, you can create a distributed instance. To create the first child instance, set this parameter to true. To create the second or third child instance, specify the ID of the distributed instance, such as `gr-bp14rkqrhac**`. If you do not want to create a distributed instance, do not specify this parameter. Note** To be created as a child instance of a distributed instance, the new instance must be a Tair memory-enhanced instance.	gr-bp14rkqrhac****
Tag	array<object>	No	The tags of the instance.
	object	No	The information about the tags.
Key	string	No	The key of the tag. Note A single request can contain up to five key-value pairs.	key1_test
Value	string	No	The value of the tag. Note N specifies the Nth tag in the request. For example, Tag.1.Value specifies the value of the first tag, and Tag.2.Value specifies the value of the second tag.	value1_test
DryRun	boolean	No	Specifies whether to perform a precheck for this request. Valid values: true: Performs a precheck and does not create the instance. The system checks the request parameters, request format, service limits, and available inventory. If the request fails the precheck, an error message is returned. If the request passes the precheck, the `DryRunOperation` error code is returned. false (default): Sends a normal request and creates the instance after the request passes the precheck.	false
Port	integer	No	The service port of the instance. Valid values: 1 to 65535. Default value: 6379.	6379
GlobalSecurityGroupIds	string	No	The IDs of the global IP whitelist templates for the instance. To specify multiple template IDs, separate them with commas. The IDs cannot be repeated.	g-zsldxfiwjmti0kcm****
ParamGroupId	string	No	The ID of the parameter template. The instance is created by using the parameters defined in this template.	g-50npzjcqb1ua6q6j****
RestoreTime	string	No	If point-in-time recovery (PITR) is enabled for the source instance, you can specify a point in time within the backup retention period. The system creates a new instance by using the backup data of the source instance at that point in time. Specify the time in the yyyy-MM-ddTHH:mm:ssZ format (UTC).	2021-07-06T07:25:57Z
ConnectionStringPrefix	string	No	The prefix of the connection string. It must start with a lowercase letter, consist of lowercase letters and digits, and be 8 to 40 characters in length. Note The full connection string is in the format of `<prefix>-<instance ID>.redis.rds.aliyuncs.com`.	r-bp1zxszhcgatnx****
InstanceEndpointType	string	No	The type of connection string to use when creating a cloud-native, dual-zone instance with the read/write splitting architecture. If you do not specify this parameter, the default value `AzIndependentEndpoint` is used. AzIndependentEndpoint (default): Zone-specific connection string. The primary and secondary zones each provide an independent connection string, allowing clients to connect to the nearest zone. UnifiedEndpoint: Unified connection string. A single connection string is provided to access nodes in both the primary and secondary zones, but this may cause cross-zone access. Important This parameter applies only to cloud-native, dual-zone instances with the read/write splitting architecture. Other instance types support only zone-specific connection strings. Important The `UnifiedEndpoint` option is available only to users on a whitelist. If a non-whitelisted user specifies this value, the request 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 start the maintenance at 01:00 (UTC+8), set this parameter to `17:00Z`. Note If this parameter is not specified, the maintenance window starts at 18:00 UTC (02:00 UTC+8) by default.
MaintainEndTime	string	No	The end time of the maintenance window. Specify the time in the HH:mmZ format (UTC). For example, to end the maintenance at 02:00 (UTC+8), set this parameter to `18:00Z`. Note The maintenance window must be at least one hour long. Note If this parameter is not specified, the maintenance window ends at 22:00 UTC (06:00 UTC+8) by default.

Response elements

Element	Type	Description	Example
	object	An object.
QPS	integer	The theoretical maximum number of read and write operations per second (QPS) for the instance.	100000
ConnectionDomain	string	The internal connection address.	r-bp13ac3d047b****.tairpena.rds.aliyuncs.com
ChargeType	string	The charge type. Valid values: PrePaid: prepaid. PostPaid: pay-as-you-go.	PrePaid
InstanceId	string	The instance ID.	r-bp13ac3d047b****
Port	integer	The instance port.	6379
Config	string	The detailed configuration of the instance, returned as a JSON string. For parameter details, see Configuration parameters.	{\"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}
RegionId	string	The region ID.	cn-hangzhou
RequestId	string	The request ID.	12123216-4B00-4378-BE4B-08005BFC****
Bandwidth	integer	The maximum bandwidth in MB/s.	96
Connections	integer	The maximum number of connections.	10000
InstanceName	string	The instance name. Note This parameter is returned only when the InstanceName parameter is specified in the request.	redistest
ZoneId	string	The availability zone ID.	cn-hangzhou-h
InstanceStatus	string	The instance status. The value is always Creating.	Creating
TaskId	string	The task ID.	10****
OrderId	integer	The order ID.	2084452111111

Examples

Success response

JSON format

{
  "QPS": 100000,
  "ConnectionDomain": "r-bp13ac3d047b****.tairpena.rds.aliyuncs.com",
  "ChargeType": "PrePaid",
  "InstanceId": "r-bp13ac3d047b****",
  "Port": 6379,
  "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}",
  "RegionId": "cn-hangzhou",
  "RequestId": "12123216-4B00-4378-BE4B-08005BFC****",
  "Bandwidth": 96,
  "Connections": 10000,
  "InstanceName": "redistest",
  "ZoneId": "cn-hangzhou-h",
  "InstanceStatus": "Creating",
  "TaskId": "10****",
  "OrderId": 2084452111111
}

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.