ALIYUN::RDS::DBInstance is used to create an ApsaraDB RDS instance.

Syntax

{
  "Type": "ALIYUN::RDS::DBInstance",
  "Properties": {
    "PeriodType": String,
    "Category": String,
    "PrivateIpAddress": String,
    "ResourceGroupId": String,
    "TargetDedicatedHostIdForSlave": String,
    "DBInstanceNetType": String,
    "DBTimeZone": String,
    "DedicatedHostGroupId": String,
    "EncryptionKey": String,
    "PreferredBackupPeriod": List,
    "SecurityIPList": String,
    "SecurityGroupId": String,
    "DBIsIgnoreCase": Integer,
    "DBInstanceStorage": Integer,
    "DBMappings": List,
    "Port": Integer,
    "ConnectionStringPrefix": String,
    "ConnectionStringType": String,
    "MultiAZ": Boolean,
    "MaintainTime": String,
    "Engine": String,
    "DBParamGroupId": String,
    "DBInstanceDescription": String,
    "Tags": Map,
    "TargetDedicatedHostIdForMaster": String,
    "EngineVersion": String,
    "ZoneId": String,
    "DBInstanceClass": String,
    "AllocatePublicConnection": Boolean,
    "PreferredBackupTime": String,
    "VSwitchId": String,
    "BackupPolicyMode": String,
    "Period": Integer,
    "PayType": String,
    "DBInstanceStorageType": String,
    "RoleARN": String,
    "MasterUserPassword": String,
    "MasterUserType": String,
    "VpcId": String,
    "MasterUsername": String,
    "ConnectionMode": String,
    "BackupRetentionPeriod": Number,
    "TargetDedicatedHostIdForLog": String,
    "SlaveZoneIds": List,
    "AutoRenew": Boolean,
    "SQLCollectorStatus": String,
    "SSLSetting": String,
    "LogBackupFrequency": String,
    "EnableBackupLog": Boolean,
    "ReleasedKeepPolicy": String,
    "ArchiveBackupRetentionPeriod": Integer,
    "ArchiveBackupKeepPolicy": String,
    "ArchiveBackupKeepCount": Integer,
    "LogBackupRetentionPeriod": Integer,
    "HighSpaceUsageProtection": String,
    "LocalLogRetentionSpace": Integer,
    "BackUpCategory": String,
    "CompressType": Integer,
    "LocalLogRetentionHours": Integer,
    "LogBackupLocalRetentionNumber": Integer,
    "ServerlessConfig": Map
  }
}

Properties

PropertyTypeRequiredEditableDescriptionConstraint
ResourceGroupIdStringNoYesThe ID of the resource group to which the instance belongs. None.
EngineString Yes NoThe database engine. Valid values:
  • MySQL
  • SQLServer
  • PostgreSQL
  • PPAS
  • MariaDB
DBInstanceStorageInteger Yes Yes The storage capacity of the ApsaraDB RDS instance. Valid values:
  • If you set the Engine property to MySQL: 5 to 1000.
  • If you set the Engine property to SQLServer: 10 to 1000.
  • If you set the Engine property to PostgreSQL: 5 to 2000.
  • If you set the Engine property to PPAS: 5 to 2000.
Unit: GB.
Note You can specify values in multiples of 5.
EngineVersionString Yes No The version of the database engine. Valid values:
  • If you set the Engine property to MySQL: 5.5, 5.6, 5.7, and 8.0.
  • If you set the Engine property to SQLServer: 2008r2, 08r2_ent_ha, 2012, 2012_ent_ha, 2012_std_ha, 2012_web, 2014_std_ha, 2016_ent_ha, 2016_std_ha, 2016_web, 2017_std_ha, 2017_ent, and 2019_ent.
  • If you set the Engine property to PostgreSQL: 9.4, 10.0, 11.0, and 12.0.
  • If you set the Engine property to PPAS: 9.3 and 10.0.
  • If you set the Engine property to MariaDB: 10.3.
PortIntegerNoYesThe port that is used to connect to the instance. None.
ConnectionStringPrefixStringNoYesThe prefix of the connection string. The prefix must be 8 to 64 characters in length and can contain letters, digits, and hyphens (-).
ConnectionStringTypeStringNoYesThe type of the connection string. Valid values:
  • Inner: virtual private cloud (VPC).
  • Public: Internet.
DBTimeZoneStringNoNoThe UTC time zone of the instance. Valid values: -12:59 to +13:00.
Note
  • If you do not specify this property, the system uses the default time zone of the region to which the instance belongs.
  • If you create an instance to which local SSDs are attached, you can name the time zone.
DBParamGroupIdStringNoNoThe ID of the parameter template. None.
CategoryStringNoNoThe edition of the instance. Valid values:
  • Basic: Basic Edition.
  • HighAvailability: High-availability Edition.
  • AlwaysOn: Cluster Edition.
  • Finance: Enterprise Edition.
TargetDedicatedHostIdForMasterStringNoNoThe ID of the host on which you want to create the primary instance within a dedicated cluster. None.
DBIsIgnoreCaseIntegerNoNoSpecifies whether table names on the instance are case-sensitive. Valid values:
  • 0: Yes.
  • 1: No. This is the default value.
EncryptionKeyStringNoNoThe ID of the key that is used for disk encryption in the region where the instance resides. You can obtain the ID of the key from the Key Management Service (KMS) console. You can also create a key. If you specify this property, disk encryption is enabled and you must also specify the RoleARN property. Disk encryption cannot be disabled after it is enabled.
MaintainTimeStringNoNoThe maintenance window of the instance. Specify the maintenance window in the HH:mmZ-HH:mmZ format. The time must be in UTC.
TargetDedicatedHostIdForSlaveStringNoNoThe ID of the host on which you want to create the secondary instance within a dedicated cluster. None.
DedicatedHostGroupIdStringNoNoThe ID of the dedicated cluster in which you want to create the instance. None.
DBInstanceStorageTypeStringNoNoThe storage type of the instance. Valid values:
  • local_ssd: local SSD. This is the recommended storage type.
  • cloud_ssd: SSD.
  • cloud_essd: enhanced SSD (ESSD).
RoleARNStringNoNoThe Alibaba Cloud Resource Name (ARN) that is provided by your Alibaba Cloud account for RAM users. RAM users can use the ARN to connect ApsaraDB RDS to KMS. For more information about the RoleARN property, see Authorize an ApsaraDB RDS for MySQL instance to access KMS.
DBInstanceClass String Yes Yes The instance class. For more information about the DBInstanceClass property, see Primary ApsaraDB RDS instance types.
SecurityIPList String Yes Yes The whitelist of IP addresses that are allowed to access all databases in the instance.

Separate IP addresses with commas (,). Each IP address in the whitelist must be unique. A maximum of 1,000 IP addresses can be specified.

You can specify the following types of IP addresses:
  • Individual IP addresses, such as 10.23.XX.XX.
  • CIDR blocks, such as 10.23.XX.XX/24. In this example, 24 indicates that the prefix of each IP address in the IP whitelist is 24 bits in length. You can replace 24 with a value within the range of 1 to 32.
SecurityGroupIdStringNoYesThe ID of the associated security group. Each ApsaraDB RDS instance can be associated with up to three security groups. Separate security groups with commas (,). To disassociate the instance from all security groups, set this property to an empty string.
MultiAZ Boolean No No Specifies whether the instance can be deployed across zones. Valid values:
  • true
  • false
VpcId String No No The ID of the virtual private cloud (VPC). None.
DBMappings List No No The databases that are to be created in the instance. For more information about the DBMappings property, see DBMappings properties.
DBInstanceDescription String No No The description of the instance. The description must be 2 to 256 characters in length, The description must start with a letter and cannot start with http:// or https://. The description can contain letters, digits, underscores (_), and hyphens (-).
ConnectionMode String No No The connection mode of the database instance. Valid values:
  • Standard: the standard mode.
  • Safe: the database proxy mode.
If you do not specify this property, the system assigns a connection mode.
Note SQL Server 2012, SQL Server 2016, and SQL Server 2017 support only the standard mode.
MasterUsername String No No The username of the account that is used to manage the databases of the instance. The username must be globally unique. The username must be 1 to 16 characters in length and can contain letters, digits, and underscores (_). It must start with a letter.
MasterUserPassword String No No The password of the account that is used to manage the databases of the instance. The password must be 8 to 32 characters in length and can contain letters, digits, and underscores (_).
ZoneId String No No The ID of the zone where the instance resides. None.
DBInstanceNetType String No No The type of network connection of the instance. Valid values:
  • Internet.
  • Intranet. This is the default value.
VSwitchId String No No The ID of the vSwitch to which the database instance is connected. Separate vSwitch IDs with commas (,). If you set the Engine property to MariaDB, you must specify the VSwitchId property.
BackupPolicyModeStringNoNoThe backup type. Valid values:
  • DataBackupPolicy.
  • LogBackupPolicy.
AllocatePublicConnection Boolean No No Specifies whether to apply for a public endpoint for the instance. Valid values:
  • true
  • false
PreferredBackupTime String No No The backup window.
  • Specify the window in the HH:mmZ- HH:mmZ format.
  • Valid values: 00:00Z-01:00Z, 01:00Z-02:00Z, 02:00Z-03:00Z, 03:00Z-04:00Z, 04:00Z-05:00Z, 05:00Z-06:00Z, 06:00Z-07:00Z, 07:00Z-08:00Z, 08:00Z-09:00Z, 09:00Z-10:00Z, 10:00Z-11:00Z, 11:00Z-12:00Z, 12:00Z-13:00Z, 13:00Z-14:00Z, 14:00Z-15:00Z, 15:00Z-16:00Z, 16:00Z-17:00Z, 17:00Z-18:00Z, 18:00Z-19:00Z, 19:00Z-20:00Z, 20:00Z-21:00Z, 21:00Z-22:00Z, 22:00Z-23:00Z, and 23:00Z-24:00Z.
BackupRetentionPeriod Number No No The number of days for which the backup is retained. Valid values: 7 to 30.

Unit: day.

Default value: 7.

PrivateIpAddress String No No The private IP address within the CIDR block of the vSwitch. If you do not specify this property, the system allocates a private IP address.
PreferredBackupPeriod List No No The day on which data is backed up. Valid values:
  • Monday
  • Tuesday
  • Wednesday
  • Thursday
  • Friday
  • Saturday
  • Sunday
MasterUserTypeStringNoNoThe type of the account that is used to manage the databases of the instance. Valid values:
  • Normal: standard account. This is the default value.
  • Super: privileged account.
  • Sysadmin: administrator account.
    Note This property can be set to Sysadmin only when the Engine property is set to SQLServer.
TagsMapNoYesThe tags. Each tag consists of a tag key and a tag value. You cannot specify an empty string as the tag key. You can specify an empty string as the tag value.

Format example: {"key1":"value1","key2":""}.

PeriodTypeStringNoNoThe unit of the subscription period. Valid values:
  • Month. This is the default value.
  • Year
PayTypeStringNoNoThe billing method of the instance. Valid values:
  • Postpaid: pay-as-you-go.
  • Prepaid: subscription.
PeriodIntegerNoNoThe subscription duration of the instance. Valid values:
  • If you set the PeriodType property to Year: 1 to 3.
  • If you set the PeriodType property to Month: 1 to 9.
TargetDedicatedHostIdForLogStringNoNoThe ID of the host on which you want to create the logger instance within a dedicated cluster. None.
SlaveZoneIdsListNoNoThe secondary zone IDs that you need to specify when you create a High-availability Edition or Enterprise Edition instance. You can specify a maximum of two secondary zones. For example, you can set this property to ["zone-b"] or ["zone-b", "zone-c"].
You must specify a vSwitch for each primary or secondary zone. For example, if ZoneId is set to "zone-a" and SlaveZoneIds is set to ["zone-c", "zone-b"], you must set the VSwitchId value in the following format:
"vsw-zone-a,vsw-zone-c,vsw-zone-b"
SQLCollectorStatusStringNoYesSpecifies whether to enable SQL Explorer and Audit. Valid values:
  • Enable.
  • Disabled.
SSLSettingStringNoNoThe secure sockets layer (SSL) connection settings for the instance. Valid values:
  • Disabled: The SSL connection is disabled. This is the default value.
  • EnabledForPublicConnection: The SSL connection is enabled. SSL certificates are used to protect public endpoints.
    Note If you set this property to EnabledForPublicConnection, you must set the AllocatePublicConnection property to true.
  • EnabledForInnerConnection: The SSL connection is enabled. SSL certificates are used to protect internal endpoints.
AutoRenewBooleanNoNoSpecifies whether to enable auto-renewal for the database instance. If you create a subscription instance, you must specify this property. Valid values:
  • true
  • false
Note
  • If you set the PeriodType property to Month, the auto-renewal cycle is one month.
  • If you set the PeriodType property to Year, the auto-renewal cycle is one year.
LogBackupFrequencyStringNoNoThe backup frequency of logs. Set the value to LogInterval. This value specifies that logs are backed up every 30 minutes. The default value of LogBackupFrequency is the same as that of PreferredBackupPeriod.
Note If you create an instance that runs SQL Server, you must specify the LogBackupFrequency property.
EnableBackupLogBooleanNoNoSpecifies whether to enable the log backup feature. Valid values:
  • True: enables the log backup feature.
  • False: disables the log backup feature.
Note If you set the BackupPolicyMode property to LogBackupPolicy, you must specify the EnableBackupLog property.
ReleasedKeepPolicyStringNoNoThe policy that is used to retain archived backup files if the instance is released Valid values:
  • Lastest: Only the last archived backup file is retained.
  • All: All archived backup files are retained.
ArchiveBackupRetentionPeriodIntegerNoNoThe number of days for which the archived backup is retained. Valid values: 30 to 1095.

Unit: day.

ArchiveBackupKeepPolicyStringNoNoThe cycle based on which the archived backup is retained. Valid values:
  • ByMonth
  • ByWeek
  • KeepAll
ArchiveBackupKeepCountIntegerNoNoThe number of archived backup files that are retained. Valid values:
  • If you set the ArchiveBackupKeepPolicy property to ByMonth: 1 to 31.
  • If you set the ArchiveBackupKeepPolicy property to ByWeek: 1 to 7.
  • If you set the ArchiveBackupKeepPolicy property to KeepAll, you can leave this property empty.

Default value: 1.

LogBackupRetentionPeriodIntegerNoNoThe number of days for which the log backup is retained. Valid values: 7 to 730.

The retention period of log backup files cannot be longer than that of data backup files.

Note If you enable the log backup feature, you can specify the retention period of log backup files.
HighSpaceUsageProtectionStringNoNoSpecifies whether to delete log backup files if the disk capacity is insufficient. The capacity is insufficient if the usage of your RDS instance capacity exceeds 80% or the remaining capacity is less than 5 GB on the instance. Valid values:
  • Enable
  • Disable

If you set the BackupPolicyMode property to LogBackupPolicy, you must specify the HighSpaceUsageProtection property.

LocalLogRetentionSpaceIntegerNoNoThe maximum percentage of space that can be used to store log backup files on the instance. Valid values: 0 to 50.

If the space usage of log backup files exceeds this percentage, the system deletes earlier binary log files until the space usage falls below this percentage.

Note If you set the BackupPolicyMode property to LogBackupPolicy, you must specify the LocalLogRetentionSpace property.
BackUpCategoryStringNoNoSpecifies whether to enable level-2 backup. Valid values:
  • Flash: enables level-2 backup.
  • Standard: disables level-2 backup.
CompressTypeIntegerNoNoThe format that is used to compress backup data. Valid values:
  • 1: uses zlib to compress backup data into .tar.gz files.
  • 4: uses QuickLZ to compress backup data into .xb.gz files. Only instances that run MySQL 5.6 or 5.7 support this compression format. You can use this format to restore individual databases and tables.
  • 8: uses QuickLZ to compress backup data into .xb.gz files. Only instances that run MySQL 8.0 support this compression format. You cannot use this format to restore individual databases or tables.
LocalLogRetentionHoursIntegerNoNoThe number of hours for which the log backup is retained on the instance. Valid values: 0 to 168.

Unit: hour.

A value of 0 specifies that the log backup is not retained on the instance.

Note If you set the BackupPolicyMode property to LogBackupPolicy, you must specify the LocalLogRetentionHours property.
LogBackupLocalRetentionNumberIntegerNoNoThe number of log backup files that can be retained on the instance. Valid values: 6 to 100.

Default value: 60.

ServerlessConfigMapNoNoThe settings of the serverless instance. For more information about the ServerlessConfig property, see ServerlessConfig properties.

ServerlessConfig syntax

"ServerlessConfig": {
    "SwitchForce": Boolean,
    "MaxCapacity": Number,
    "MinCapacity": Number,
    "AutoPause": Boolean
  }

ServerlessConfig properties

PropertyTypeRequiredEditableDescriptionConstraint
SwitchForceBooleanNoNoSpecifies whether to enable the forced scaling feature for the serverless instance. Valid values:
  • true: enables the forced scaling feature.
  • false: disables the forced scaling feature. This is the default value.
Note
  • If you set this property to true, a transient connection that lasts approximately 1 minute occurs during the forced scaling process. Configure this property based on your business requirements.
  • In most cases, ApsaraDB RDS scales in or out the RDS Capacity Units (RCUs) of a serverless instance based on business requirements in real time. In some cases, such as the execution of a large transaction, the scaling does not take effect in real time. You can enable the forced scaling feature to forcibly scales in or out the RCUs of the instance.
MaxCapacityNumberYesNoThe maximum value of RCU scaling. Valid values: 0.5 to 8.
Note The value of this property must be greater than or equal to the value of the MinCapacity property.
MinCapacityNumberYesNoThe minimum value of RCU scaling. Valid values: 0.5 to 8.
Note The value of this property must be less than or equal to the value of the MaxCapacity property.
AutoPauseBooleanNoNoSpecifies whether to enable the smart startup and suspension feature for the serverless instance. Valid values:
  • true: enables the smart startup and suspension feature.
  • false: disables the smart startup and suspension feature. This is the default value.
Note After the smart startup and suspension feature is enabled, if no connections to the instance are established within 10 minutes, the instance is suspended. After a connection to the instance is established, the instance is resumed.

DBMappings syntax

"DBMappings": [
  {
    "DBDescription": String,
    "CharacterSetName": String,
    "DBName": String
  }
]

DBMappings properties

PropertyTypeRequiredEditableDescriptionConstraint
CharacterSetName String Yes No The character set. Valid values:
  • If you set the Engine property to MySQL:
    • utf8
    • gbk
    • latin1
    • utf8mb4 (applicable to versions 5.5 and 5.6)
  • If you set the Engine property to SQLServer:
    • Chinese_PRC_CI_AS
    • Chinese_PRC_CS_AS
    • SQL_Latin1_General_CP1_CI_AS
    • SQL_Latin1_General_CP1_CS_AS
    • Chinese_PRC_BIN
DBName String Yes No The name of the database. The name must be globally unique.

The name must be 1 to 64 characters in length and can contain letters, digits, and underscores (_). It must start with a letter.

DBDescription String No No The description of the database. The description must be 2 to 256 characters in length, The description must start with a letter and cannot start with http:// or https://. The description can contain letters, digits, underscores (_), and hyphens (-).

Return values

Fn::GetAtt

  • DBInstanceId: the ID of the instance.
  • InnerPort: the internal port of the instance.
  • InnerIPAddress: the internal IP address of the instance.
  • InnerConnectionString: the internal connection string of the instance.
  • PublicPort: the public port of the instance.
  • PublicConnectionString: the public connection string of the instance.
  • PublicIPAddress: the public IP address of the instance.

Examples

  • YAML format

    ROSTemplateFormatVersion: '2015-09-01'
    Description: Test RDS DBInstance
    Parameters:
      VpcId:
        AssociationProperty: ALIYUN::ECS::VPC::VPCId
        Type: String
        Description:
          en: Please search the ID starting with (vpc-xxx) from console-Virtual Private Cloud
           
        Label:
          en: VPC ID
           
      VSwitchId:
        AssociationProperty: ALIYUN::ECS::VSwitch::VSwitchId
        AssociationPropertyMetadata:
          VpcId: ${VpcId}
          ZoneId: ${VSwitchZoneId}
        Type: String
        Description:
          en: Instance ID of existing business network switches, console-Virtual Private Cloud-VSwitches under query
           
        Label:
          en: VSwitch ID
           
    Resources:
      RDSInstance:
        DependsOn: VSwitch
        Type: ALIYUN::RDS::DBInstance
        Properties:
          VpcId:
            Ref: VpcId
          VSwitchId:
            Ref: VSwitchId
          EngineVersion: '5.6'
          DBInstanceClass: rds.mysql.s2.large
          SecurityIPList: 0.0.0.0/0
          DBInstanceStorage: 5
          Engine: MySQL
          DBMappings:
            - CharacterSetName: utf8
              DBName: DBTest
    Outputs:
      DBInstanceId:
        Value:
          Fn::GetAtt:
            - RDSInstance
            - DBInstanceId
  • JSON format

    {
      "ROSTemplateFormatVersion": "2015-09-01",
      "Description": "Test RDS DBInstance",
      "Parameters": {
        "VpcId": {
          "AssociationProperty": "ALIYUN::ECS::VPC::VPCId",
          "Type": "String",
          "Description": {
            "en": "Please search the ID starting with (vpc-xxx) from console-Virtual Private Cloud",
             
          },
          "Label": {
            "en": "VPC ID",
             
          }
        },
        "VSwitchId": {
          "AssociationProperty": "ALIYUN::ECS::VSwitch::VSwitchId",
          "AssociationPropertyMetadata": {
            "VpcId": "${VpcId}",
            "ZoneId": "${VSwitchZoneId}"
          },
          "Type": "String",
          "Description": {
            "en": "Instance ID of existing business network switches, console-Virtual Private Cloud-VSwitches under query",
             
          },
          "Label": {
            "en": "VSwitch ID",
             
          }
        }
      },
      "Resources": {
        "RDSInstance": {
          "DependsOn": "VSwitch",
          "Type": "ALIYUN::RDS::DBInstance",
          "Properties": {
            "VpcId": {
              "Ref": "VpcId"
            },
            "VSwitchId": {
              "Ref": "VSwitchId"
            },
            "EngineVersion": "5.6",
            "DBInstanceClass": "rds.mysql.s2.large",
            "SecurityIPList": "0.0.0.0/0",
            "DBInstanceStorage": 5,
            "Engine": "MySQL",
            "DBMappings": [
              {
                "CharacterSetName": "utf8",
                "DBName": "DBTest"
              }
            ]
          }
        }
      },
      "Outputs": {
        "DBInstanceId": {
          "Value": {
            "Fn::GetAtt": [
              "RDSInstance",
              "DBInstanceId"
            ]
          }
        }
      }
    }

For more examples, visit DBInstance.json and DBInstance.yml. The examples use the ALIYUN::RDS::DBInstance, ALIYUN::RDS::Account, ALIYUN::RDS::AccountPrivilege, ALIYUN::RDS::DBInstanceParameterGroup, ALIYUN::RDS::DBInstanceSecurityIps, ALIYUN::RDS::ReadOnlyDBInstance, and ALIYUN::RDS::Database resource types.