pulumi-aws-kotlin/com.pulumi.aws.rds.kotlin/Instance

Instance

class Instance : KotlinCustomResource

Provides an RDS instance resource. A DB instance is an isolated database environment in the cloud. A DB instance can contain multiple user-created databases. Changes to a DB instance can occur when you manually change a parameter, such as allocated_storage, and are reflected in the next maintenance window. Because of this, this provider may report a difference in its planning phase because a modification has not yet taken place. You can use the apply_immediately flag to instruct the service to apply the change immediately (see documentation below). When upgrading the major version of an engine, allow_major_version_upgrade must be set to true.

Note: using apply_immediately can result in a brief downtime as the server reboots. See the AWS Docs on instance-maintenance for more information. Note: All arguments including the username and password will be stored in the raw state as plain-text. Read more about sensitive data instate.

RDS Instance Class Types

Amazon RDS supports three types of instance classes: Standard, Memory Optimized, and Burstable Performance. For more information please read the AWS RDS documentation about DB Instance Class Types

Low-Downtime Updates

By default, RDS applies updates to DB Instances in-place, which can lead to service interruptions. Low-downtime updates minimize service interruptions by performing the updates with an blue-green and switching over the instances when complete. Low-downtime updates are only available for DB Instances using MySQL and MariaDB, as other engines are not supported by RDS Blue/Green deployments. Backups must be enabled to use low-downtime updates. Enable low-downtime updates by setting blue_green_update.enabled to true.

Example Usage

Basic Usage

package generated_program;
import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.rds.Instance;
import com.pulumi.aws.rds.InstanceArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;
public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }
    public static void stack(Context ctx) {
        var default_ = new Instance("default", InstanceArgs.builder()
            .allocatedStorage(10)
            .dbName("mydb")
            .engine("mysql")
            .engineVersion("5.7")
            .instanceClass("db.t3.micro")
            .parameterGroupName("default.mysql5.7")
            .password("foobarbaz")
            .skipFinalSnapshot(true)
            .username("foo")
            .build());
    }
}

RDS Custom for Oracle Usage with Replica

package generated_program;
import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.rds.RdsFunctions;
import com.pulumi.aws.rds.inputs.GetOrderableDbInstanceArgs;
import com.pulumi.aws.kms.KmsFunctions;
import com.pulumi.aws.kms.inputs.GetKeyArgs;
import com.pulumi.aws.rds.Instance;
import com.pulumi.aws.rds.InstanceArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;
public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }
    public static void stack(Context ctx) {
        final var custom-oracle = RdsFunctions.getOrderableDbInstance(GetOrderableDbInstanceArgs.builder()
            .engine("custom-oracle-ee")
            .engineVersion("19.c.ee.002")
            .licenseModel("bring-your-own-license")
            .storageType("gp3")
            .preferredInstanceClasses(
                "db.r5.xlarge",
                "db.r5.2xlarge",
                "db.r5.4xlarge")
            .build());
        final var byId = KmsFunctions.getKey(GetKeyArgs.builder()
            .keyId("example-ef278353ceba4a5a97de6784565b9f78")
            .build());
        var default_ = new Instance("default", InstanceArgs.builder()
            .allocatedStorage(50)
            .autoMinorVersionUpgrade(false)
            .customIamInstanceProfile("AWSRDSCustomInstanceProfile")
            .backupRetentionPeriod(7)
            .dbSubnetGroupName(local.db_subnet_group_name())
            .engine(custom_oracle.engine())
            .engineVersion(custom_oracle.engineVersion())
            .identifier("ee-instance-demo")
            .instanceClass(custom_oracle.instanceClass())
            .kmsKeyId(byId.applyValue(getKeyResult -> getKeyResult.arn()))
            .licenseModel(custom_oracle.licenseModel())
            .multiAz(false)
            .password("avoid-plaintext-passwords")
            .username("test")
            .storageEncrypted(true)
            .timeouts(%!v(PANIC=Format method: runtime error: invalid memory address or nil pointer dereference))
            .build());
        var test_replica = new Instance("test-replica", InstanceArgs.builder()
            .replicateSourceDb(default_.identifier())
            .replicaMode("mounted")
            .autoMinorVersionUpgrade(false)
            .customIamInstanceProfile("AWSRDSCustomInstanceProfile")
            .backupRetentionPeriod(7)
            .identifier("ee-instance-replica")
            .instanceClass(custom_oracle.instanceClass())
            .kmsKeyId(byId.applyValue(getKeyResult -> getKeyResult.arn()))
            .multiAz(false)
            .skipFinalSnapshot(true)
            .storageEncrypted(true)
            .timeouts(%!v(PANIC=Format method: runtime error: invalid memory address or nil pointer dereference))
            .build());
    }
}

RDS Custom for SQL Server

package generated_program;
import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.rds.RdsFunctions;
import com.pulumi.aws.rds.inputs.GetOrderableDbInstanceArgs;
import com.pulumi.aws.kms.KmsFunctions;
import com.pulumi.aws.kms.inputs.GetKeyArgs;
import com.pulumi.aws.rds.Instance;
import com.pulumi.aws.rds.InstanceArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;
public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }
    public static void stack(Context ctx) {
        final var custom-sqlserver = RdsFunctions.getOrderableDbInstance(GetOrderableDbInstanceArgs.builder()
            .engine("custom-sqlserver-se")
            .engineVersion("15.00.4249.2.v1")
            .storageType("gp3")
            .preferredInstanceClasses(
                "db.r5.xlarge",
                "db.r5.2xlarge",
                "db.r5.4xlarge")
            .build());
        final var byId = KmsFunctions.getKey(GetKeyArgs.builder()
            .keyId("example-ef278353ceba4a5a97de6784565b9f78")
            .build());
        var example = new Instance("example", InstanceArgs.builder()
            .allocatedStorage(500)
            .autoMinorVersionUpgrade(false)
            .customIamInstanceProfile("AWSRDSCustomSQLServerInstanceRole")
            .backupRetentionPeriod(7)
            .dbSubnetGroupName(local.db_subnet_group_name())
            .engine(custom_sqlserver.engine())
            .engineVersion(custom_sqlserver.engineVersion())
            .identifier("sql-instance-demo")
            .instanceClass(custom_sqlserver.instanceClass())
            .kmsKeyId(byId.applyValue(getKeyResult -> getKeyResult.arn()))
            .multiAz(false)
            .password("avoid-plaintext-passwords")
            .storageEncrypted(true)
            .username("test")
            .timeouts(%!v(PANIC=Format method: runtime error: invalid memory address or nil pointer dereference))
            .build());
    }
}

Storage Autoscaling

To enable Storage Autoscaling with instances that support the feature, define the max_allocated_storage argument higher than the allocated_storage argument. This provider will automatically hide differences with the allocated_storage argument value if autoscaling occurs.

package generated_program;
import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.rds.Instance;
import com.pulumi.aws.rds.InstanceArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;
public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }
    public static void stack(Context ctx) {
        var example = new Instance("example", InstanceArgs.builder()
            .allocatedStorage(50)
            .maxAllocatedStorage(100)
            .build());
    }
}

Managed Master Passwords via Secrets Manager, default KMS Key

More information about RDS/Aurora Aurora integrates with Secrets Manager to manage master user passwords for your DB clusters can be found in the RDS User Guide and Aurora User Guide. You can specify the manage_master_user_password attribute to enable managing the master password with Secrets Manager. You can also update an existing cluster to use Secrets Manager by specify the manage_master_user_password attribute and removing the password attribute (removal is required).

package generated_program;
import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.rds.Instance;
import com.pulumi.aws.rds.InstanceArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;
public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }
    public static void stack(Context ctx) {
        var default_ = new Instance("default", InstanceArgs.builder()
            .allocatedStorage(10)
            .dbName("mydb")
            .engine("mysql")
            .engineVersion("5.7")
            .instanceClass("db.t3.micro")
            .manageMasterUserPassword(true)
            .parameterGroupName("default.mysql5.7")
            .username("foo")
            .build());
    }
}

Managed Master Passwords via Secrets Manager, specific KMS Key

More information about RDS/Aurora Aurora integrates with Secrets Manager to manage master user passwords for your DB clusters can be found in the RDS User Guide and Aurora User Guide. You can specify the master_user_secret_kms_key_id attribute to specify a specific KMS Key.

package generated_program;
import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.aws.kms.Key;
import com.pulumi.aws.kms.KeyArgs;
import com.pulumi.aws.rds.Instance;
import com.pulumi.aws.rds.InstanceArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;
public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }
    public static void stack(Context ctx) {
        var example = new Key("example", KeyArgs.builder()
            .description("Example KMS Key")
            .build());
        var default_ = new Instance("default", InstanceArgs.builder()
            .allocatedStorage(10)
            .dbName("mydb")
            .engine("mysql")
            .engineVersion("5.7")
            .instanceClass("db.t3.micro")
            .manageMasterUserPassword(true)
            .masterUserSecretKmsKeyId(example.keyId())
            .username("foo")
            .parameterGroupName("default.mysql5.7")
            .build());
    }
}

Import

Using pulumi import, import DB Instances using the identifier. For example:

$ pulumi import aws:rds/instance:Instance default mydb-rds-instance

Properties

address

val address: Output<String>

Specifies the DNS address of the DB instance.

allocatedStorage

val allocatedStorage: Output<Int>

The allocated storage in gibibytes. If max_allocated_storage is configured, this argument represents the initial storage allocation and differences from the configuration will be ignored automatically when Storage Autoscaling occurs. If replicate_source_db is set, the value is ignored during the creation of the instance.

allowMajorVersionUpgrade

val allowMajorVersionUpgrade: Output<Boolean>?

Indicates that major version upgrades are allowed. Changing this parameter does not result in an outage and the change is asynchronously applied as soon as possible.

applyImmediately

val applyImmediately: Output<Boolean>?

Specifies whether any database modifications are applied immediately, or during the next maintenance window. Default is false. See [Amazon RDS Documentation for more

arn

val arn: Output<String>

The ARN of the RDS instance.

autoMinorVersionUpgrade

val autoMinorVersionUpgrade: Output<Boolean>?

Indicates that minor engine upgrades will be applied automatically to the DB instance during the maintenance window. Defaults to true.

availabilityZone

val availabilityZone: Output<String>

The AZ for the RDS instance.

backupRetentionPeriod

val backupRetentionPeriod: Output<Int>

The days to retain backups for. Must be between 0 and 35. Default is 0. Must be greater than 0 if the database is used as a source for a instance-replication, uses low-downtime updates, or will use blue-green.

backupTarget

val backupTarget: Output<String>

Specifies where automated backups and manual snapshots are stored. Possible values are region (default) and outposts. See Working with Amazon RDS on AWS Outposts for more information.

backupWindow

val backupWindow: Output<String>

The daily time range (in UTC) during which automated backups are created if they are enabled. Example: "09:46-10:16". Must not overlap with maintenance_window.

blueGreenUpdate

val blueGreenUpdate: Output<InstanceBlueGreenUpdate>?

Enables low-downtime updates using blue-green. See blue_green_update below

caCertIdentifier

val caCertIdentifier: Output<String>

The identifier of the CA certificate for the DB instance.

characterSetName

val characterSetName: Output<String>

The character set name to use for DB encoding in Oracle and Microsoft SQL instances (collation). This can't be changed. See [Oracle Character Sets

copyTagsToSnapshot

val copyTagsToSnapshot: Output<Boolean>?

Copy all Instance tags to snapshots. Default is false.

customerOwnedIpEnabled

val customerOwnedIpEnabled: Output<Boolean>?

Indicates whether to enable a customer-owned IP address (CoIP) for an RDS on Outposts DB instance. See CoIP for RDS on Outposts for more information.

customIamInstanceProfile

val customIamInstanceProfile: Output<String>?

The instance profile associated with the underlying Amazon EC2 instance of an RDS Custom DB instance.

dbName

val dbName: Output<String>

The name of the database to create when the DB instance is created. If this parameter is not specified, no database is created in the DB instance. Note that this does not apply for Oracle or SQL Server engines. See the AWS documentation for more details on what applies for those engines. If you are providing an Oracle db name, it needs to be in all upper case. Cannot be specified for a replica.

dbSubnetGroupName

val dbSubnetGroupName: Output<String>

Name of DB subnet group. DB instance will be created in the VPC associated with the DB subnet group. If unspecified, will be created in the default VPC, or in EC2 Classic, if available. When working with read replicas, it should be specified only if the source database specifies an instance in another AWS Region. See [DBSubnetGroupName in API

deleteAutomatedBackups

val deleteAutomatedBackups: Output<Boolean>?

Specifies whether to remove automated backups immediately after the DB instance is deleted. Default is true.

deletionProtection

val deletionProtection: Output<Boolean>?

If the DB instance should have deletion protection enabled. The database can't be deleted when this value is set to true. The default is false.

domain

val domain: Output<String>?

The ID of the Directory Service Active Directory domain to create the instance in.

domainIamRoleName

val domainIamRoleName: Output<String>?

The name of the IAM role to be used when making API calls to the Directory Service.

enabledCloudwatchLogsExports

val enabledCloudwatchLogsExports: Output<List<String>>?

Set of log types to enable for exporting to CloudWatch logs. If omitted, no logs will be exported. Valid values (depending on engine). MySQL and MariaDB: audit, error, general, slowquery. PostgreSQL: postgresql, upgrade. MSSQL: agent , error. Oracle: alert, audit, listener, trace.

endpoint

val endpoint: Output<String>

The connection endpoint in address:port format.

engine

val engine: Output<String>

The database engine to use. For supported values, see the Engine parameter in API action CreateDBInstance. Note that for Amazon Aurora instances the engine must match the DB cluster's engine'. For information on the difference between the available Aurora MySQL engines see Comparison between Aurora MySQL 1 and Aurora MySQL 2 in the Amazon RDS User Guide.

engineVersion

val engineVersion: Output<String>

The engine version to use. If auto_minor_version_upgrade is enabled, you can provide a prefix of the version such as 5.7 (for 5.7.10). The actual engine version used is returned in the attribute engine_version_actual, see Attribute Reference below. For supported values, see the EngineVersion parameter in API action CreateDBInstance. Note that for Amazon Aurora instances the engine version must match the DB cluster's engine version'.

engineVersionActual

val engineVersionActual: Output<String>

The running version of the database.

finalSnapshotIdentifier

val finalSnapshotIdentifier: Output<String>?

The name of your final DB snapshot when this DB instance is deleted. Must be provided if skip_final_snapshot is set to false. The value must begin with a letter, only contain alphanumeric characters and hyphens, and not end with a hyphen or contain two consecutive hyphens. Must not be provided when deleting a read replica.

hostedZoneId

val hostedZoneId: Output<String>

Specifies the ID that Amazon Route 53 assigns when you create a hosted zone.

iamDatabaseAuthenticationEnabled

val iamDatabaseAuthenticationEnabled: Output<Boolean>?

Specifies whether mappings of AWS Identity and Access Management (IAM) accounts to database accounts is enabled.

val id: Output<String>

identifier

val identifier: Output<String>

The name of the RDS instance, if omitted, this provider will assign a random, unique identifier. Required if restore_to_point_in_time is specified.

identifierPrefix

val identifierPrefix: Output<String>

Creates a unique identifier beginning with the specified prefix. Conflicts with identifier.

instanceClass

val instanceClass: Output<String>

The instance type of the RDS instance.

iops

val iops: Output<Int>

The amount of provisioned IOPS. Setting this implies a storage_type of "io1". Can only be set when storage_type is "io1" or "gp3". Cannot be specified for gp3 storage if the allocated_storage value is below a per-engine threshold. See the RDS User Guide for details.

kmsKeyId

val kmsKeyId: Output<String>

The ARN for the KMS encryption key. If creating an encrypted replica, set this to the destination KMS ARN.

latestRestorableTime

val latestRestorableTime: Output<String>

The latest time, in UTC RFC3339 format, to which a database can be restored with point-in-time restore.

licenseModel

val licenseModel: Output<String>

(Optional, but required for some DB engines, i.e., Oracle SE1) License model information for this DB instance.

listenerEndpoints

val listenerEndpoints: Output<List<InstanceListenerEndpoint>>

Specifies the listener connection endpoint for SQL Server Always On. See endpoint below.

maintenanceWindow

val maintenanceWindow: Output<String>

The window to perform maintenance in. Syntax: "ddd:hh24:mi-ddd:hh24:mi". Eg: "Mon:00:00-Mon:03:00". See [RDS

manageMasterUserPassword

val manageMasterUserPassword: Output<Boolean>?

Set to true to allow RDS to manage the master user password in Secrets Manager. Cannot be set if password is provided.

masterUserSecretKmsKeyId

val masterUserSecretKmsKeyId: Output<String>

The Amazon Web Services KMS key identifier is the key ARN, key ID, alias ARN, or alias name for the KMS key. To use a KMS key in a different Amazon Web Services account, specify the key ARN or alias ARN. If not specified, the default KMS key for your Amazon Web Services account is used.

masterUserSecrets

val masterUserSecrets: Output<List<InstanceMasterUserSecret>>

A block that specifies the master user secret. Only available when manage_master_user_password is set to true. Documented below.

maxAllocatedStorage

val maxAllocatedStorage: Output<Int>?

When configured, the upper limit to which Amazon RDS can automatically scale the storage of the DB instance. Configuring this will automatically ignore differences to allocated_storage. Must be greater than or equal to allocated_storage or 0 to disable Storage Autoscaling.

monitoringInterval

val monitoringInterval: Output<Int>?

The interval, in seconds, between points when Enhanced Monitoring metrics are collected for the DB instance. To disable collecting Enhanced Monitoring metrics, specify 0. The default is 0. Valid Values: 0, 1, 5, 10, 15, 30, 60.

monitoringRoleArn

val monitoringRoleArn: Output<String>

The ARN for the IAM role that permits RDS to send enhanced monitoring metrics to CloudWatch Logs. You can find more information on the [AWS

multiAz

val multiAz: Output<Boolean>

Specifies if the RDS instance is multi-AZ

name

val ~~name~~: Output<String>?

ncharCharacterSetName

val ncharCharacterSetName: Output<String>

The national character set is used in the NCHAR, NVARCHAR2, and NCLOB data types for Oracle instances. This can't be changed. See [Oracle Character Sets

networkType

val networkType: Output<String>

The network type of the DB instance. Valid values: IPV4, DUAL.

optionGroupName

val optionGroupName: Output<String>

Name of the DB option group to associate.

parameterGroupName

val parameterGroupName: Output<String>

Name of the DB parameter group to associate.

password

val password: Output<String>?

(Required unless manage_master_user_password is set to true or unless a snapshot_identifier or replicate_source_db is provided or manage_master_user_password is set.) Password for the master DB user. Note that this may show up in logs, and it will be stored in the state file. Cannot be set if manage_master_user_password is set to true.

performanceInsightsEnabled

val performanceInsightsEnabled: Output<Boolean>?

Specifies whether Performance Insights are enabled. Defaults to false.

performanceInsightsKmsKeyId

val performanceInsightsKmsKeyId: Output<String>

The ARN for the KMS key to encrypt Performance Insights data. When specifying performance_insights_kms_key_id, performance_insights_enabled needs to be set to true. Once KMS key is set, it can never be changed.

performanceInsightsRetentionPeriod

val performanceInsightsRetentionPeriod: Output<Int>

Amount of time in days to retain Performance Insights data. Valid values are 7, 731 (2 years) or a multiple of 31. When specifying performance_insights_retention_period, performance_insights_enabled needs to be set to true. Defaults to '7'.

port

val port: Output<Int>

The port on which the DB accepts connections.

publiclyAccessible

val publiclyAccessible: Output<Boolean>?

Bool to control if instance is publicly accessible. Default is false.

pulumiChildResources

val pulumiChildResources: Set<KotlinResource>

pulumiResourceName

val pulumiResourceName: String

pulumiResourceType

val pulumiResourceType: String

replicaMode

val replicaMode: Output<String>

Specifies whether the replica is in either mounted or open-read-only mode. This attribute is only supported by Oracle instances. Oracle replicas operate in open-read-only mode unless otherwise specified. See Working with Oracle Read Replicas for more information.

replicas

val replicas: Output<List<String>>

replicateSourceDb

val replicateSourceDb: Output<String>?

Specifies that this resource is a Replicate database, and to use this value as the source database. This correlates to the identifier of another Amazon RDS Database to replicate (if replicating within a single region) or ARN of the Amazon RDS Database to replicate (if replicating cross-region). Note that if you are creating a cross-region replica of an encrypted database you will also need to specify a kms_key_id. See instance-replication and [Working with

resourceId

val resourceId: Output<String>

The RDS Resource ID of this instance.

restoreToPointInTime

val restoreToPointInTime: Output<InstanceRestoreToPointInTime>?

A configuration block for restoring a DB instance to an arbitrary point in time. Requires the identifier argument to be set with the name of the new DB instance to be created. See Restore To Point In Time below for details.

s3Import

val s3Import: Output<InstanceS3Import>?

Restore from a Percona Xtrabackup in S3. See Importing Data into an Amazon RDS MySQL DB Instance

skipFinalSnapshot

val skipFinalSnapshot: Output<Boolean>?

Determines whether a final DB snapshot is created before the DB instance is deleted. If true is specified, no DBSnapshot is created. If false is specified, a DB snapshot is created before the DB instance is deleted, using the value from final_snapshot_identifier. Default is false.

snapshotIdentifier

val snapshotIdentifier: Output<String>

Specifies whether or not to create this database from a snapshot. This correlates to the snapshot ID you'd find in the RDS console, e.g: rds:production-2015-06-26-06-05.

status

val status: Output<String>

The RDS instance status.

storageEncrypted

val storageEncrypted: Output<Boolean>?

Specifies whether the DB instance is encrypted. Note that if you are creating a cross-region read replica this field is ignored and you should instead declare kms_key_id with a valid ARN. The default is false if not specified.

storageThroughput

val storageThroughput: Output<Int>

The storage throughput value for the DB instance. Can only be set when storage_type is "gp3". Cannot be specified if the allocated_storage value is below a per-engine threshold. See the RDS User Guide for details.

storageType

val storageType: Output<String>

One of "standard" (magnetic), "gp2" (general purpose SSD), "gp3" (general purpose SSD that needs iops independently) or "io1" (provisioned IOPS SSD). The default is "io1" if iops is specified, "gp2" if not.