# ClusterInstanceOptions

Common options for creating a cluster instance.

- Source: [`aws-rds/lib/aurora-cluster-instance.ts`](https://github.com/aws/aws-cdk/blob/v2.274.0/packages/aws-cdk-lib/aws-rds/lib/aurora-cluster-instance.ts#L188)
- Type last changed: v2.184.0 · 13 Mar 2025

## Example

```ts
// The code below shows an example of how to instantiate this type.
// The values are placeholders you should change.
import { aws_kms as kms } from 'aws-cdk-lib';
import { aws_rds as rds } from 'aws-cdk-lib';

declare const caCertificate: rds.CaCertificate;
declare const key: kms.Key;
declare const parameterGroup: rds.ParameterGroup;
const clusterInstanceOptions: rds.ClusterInstanceOptions = {
  allowMajorVersionUpgrade: false,
  applyImmediately: false,
  autoMinorVersionUpgrade: false,
  availabilityZone: 'availabilityZone',
  caCertificate: caCertificate,
  enablePerformanceInsights: false,
  instanceIdentifier: 'instanceIdentifier',
  isFromLegacyInstanceProps: false,
  parameterGroup: parameterGroup,
  parameters: {
    parametersKey: 'parameters',
  },
  performanceInsightEncryptionKey: key,
  performanceInsightRetention: rds.PerformanceInsightRetention.DEFAULT,
  preferredMaintenanceWindow: 'preferredMaintenanceWindow',
  publiclyAccessible: false,
};
```

## Properties

- `allowMajorVersionUpgrade`: boolean = false — Whether to allow upgrade of major version for the DB instance.

- `applyImmediately`: boolean — Specifies whether changes to the DB instance and any pending modifications are applied immediately, regardless of the `preferredMaintenanceWindow` setting.

  **Default:** Changes will be applied immediately

  If set to `false`, changes are applied during the next maintenance window.

  Until RDS applies the changes, the DB instance remains in a drift state.
  As a result, the configuration doesn't fully reflect the requested modifications and temporarily diverges from the intended state.

  This property also determines whether the DB instance reboots when a static parameter is modified in the associated DB parameter group.

- `autoMinorVersionUpgrade`: boolean = true — Whether to enable automatic upgrade of minor version for the DB instance.

- `availabilityZone`: string — The Availability Zone (AZ) where the database will be created.

  **Default:** A random, system-chosen Availability Zone in the endpointʼs AWS Region.

  For Amazon Aurora, each Aurora DB cluster hosts copies of its storage in three separate Availability Zones.
  Specify one of these Availability Zones. Aurora automatically chooses an appropriate Availability Zone if you don't specify one.

- `caCertificate`: [CaCertificate](/cdk/api/v2/docs/aws-cdk-lib.aws_rds.CaCertificate.html) — The identifier of the CA certificate for this DB cluster's instances.

  **Default:** RDS will choose a certificate authority

  Specifying or updating this property triggers a reboot.

  For RDS DB engines:

- `enablePerformanceInsights`: boolean — Whether to enable Performance Insights for the DB instance.

  **Default:** false, unless ``performanceInsightRetention`` or ``performanceInsightEncryptionKey`` is set.

- `instanceIdentifier`: string — The identifier for the database instance.

  **Default:** CloudFormation generated identifier

- `isFromLegacyInstanceProps`: boolean = false — Only used for migrating existing clusters from using `instanceProps` to `writer` and `readers`.

  ```ts
  // existing cluster
  declare const vpc: ec2.Vpc;
  const cluster = new rds.DatabaseCluster(this, 'Database', {
    engine: rds.DatabaseClusterEngine.auroraMysql({
      version: rds.AuroraMysqlEngineVersion.VER_3_03_0,
    }),
    instances: 2,
    instanceProps: {
      instanceType: ec2.InstanceType.of(ec2.InstanceClass.BURSTABLE3, ec2.InstanceSize.SMALL),
      vpcSubnets: { subnetType: ec2.SubnetType.PUBLIC },
      vpc,
    },
  });

  // migration

  const instanceProps = {
    instanceType: ec2.InstanceType.of(ec2.InstanceClass.BURSTABLE3, ec2.InstanceSize.SMALL),
    isFromLegacyInstanceProps: true,
  };

  const myCluster = new rds.DatabaseCluster(this, 'Database', {
    engine: rds.DatabaseClusterEngine.auroraMysql({
      version: rds.AuroraMysqlEngineVersion.VER_3_03_0,
    }),
    vpcSubnets: { subnetType: ec2.SubnetType.PUBLIC },
    vpc,
    writer: rds.ClusterInstance.provisioned('Instance1', {
      instanceType: instanceProps.instanceType,
      isFromLegacyInstanceProps: instanceProps.isFromLegacyInstanceProps,
    }),
    readers: [
      rds.ClusterInstance.provisioned('Instance2', {
        instanceType: instanceProps.instanceType,
        isFromLegacyInstanceProps: instanceProps.isFromLegacyInstanceProps,
      }),
    ],
  });
  ```

- `parameterGroup`: [IParameterGroup](/cdk/api/v2/docs/aws-cdk-lib.aws_rds.IParameterGroup.html) — The DB parameter group to associate with the instance.

  **Default:** the cluster parameter group is used

  This is only needed if you need to configure different parameter
  groups for each individual instance, otherwise you should not
  provide this and just use the cluster parameter group

- `parameters`: { [key: string]: string } = None — The parameters in the DBParameterGroup to create automatically.

  You can only specify parameterGroup or parameters but not both.
  You need to use a versioned engine to auto-generate a DBParameterGroup.

- `performanceInsightEncryptionKey`: [IKey](/cdk/api/v2/docs/aws-cdk-lib.aws_kms.IKey.html) — The AWS KMS key for encryption of Performance Insights data.

  **Default:** default master key

- `performanceInsightRetention`: [PerformanceInsightRetention](/cdk/api/v2/docs/aws-cdk-lib.aws_rds.PerformanceInsightRetention.html) = 7 — The amount of time, in days, to retain Performance Insights data.

- `preferredMaintenanceWindow`: string — A preferred maintenance window day/time range. Should be specified as a range ddd:hh24:mi-ddd:hh24:mi (24H Clock UTC).

  **Default:** 30-minute window selected at random from an 8-hour block of time for each AWS Region, occurring on a random day of the week.

  Example: 'Sun:23:45-Mon:00:15'

- `publiclyAccessible`: boolean — Indicates whether the DB instance is an internet-facing instance.

  **Default:** `true` if the cluster's `vpcSubnets` is `subnetType: SubnetType.PUBLIC`, `false` otherwise

  If not specified,
  the cluster's vpcSubnets will be used to determine if the instance is internet-facing
  or not.