@aws-cdk/rds: Cluster requires VPC, doc says otherwise

[dbartholomae]

Describe the issue

The documentation says that the vpc prop for a Cluster is optional, but there's a check in code that throws an error if it isn't set.

Links

https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_rds-readme.html#default-vpc
https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/aws-rds/lib/cluster.ts#L795

[ykethan]

Hey @dbartholomae, thank you for reaching out. I was able to reproduce this issue and wanted to provide some additional finding while testing this.

Reproduction code:

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as rds from 'aws-cdk-lib/aws-rds';
export class Route53IssueStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const cluster = new rds.DatabaseCluster(this, 'Database', {
      engine: rds.DatabaseClusterEngine.auroraMysql({
        version: rds.AuroraMysqlEngineVersion.VER_3_08_2,
      }),
      credentials: rds.Credentials.fromGeneratedSecret('clusteradmin'),
      writer: rds.ClusterInstance.provisioned('writer', {
        publiclyAccessible: false,
      }),
      readers: [
        rds.ClusterInstance.provisioned('reader1', { promotionTier: 1 }),
        rds.ClusterInstance.serverlessV2('reader2'),
      ],
    });
  }
}

CDK Synth fails with

    const cluster = new rds.DatabaseCluster(this, 'Database', {
                    ^
ValidationError: Provide either vpc or instanceProps.vpc, but not both
    at path [BugStack/Database] in aws-cdk-lib.aws_rds.DatabaseCluster

From the documentation as you have pointed the vpc is an optional parameter when not specific should use the default vpc in the account. I was able to confirm this by deploying a simple CloudFormation template on the AWS console.

Resources:
  BugStackDatabaseSecretF03CD1BE3fdaad7efa858a3daf9490cf0a702aeb:
    Type: AWS::SecretsManager::Secret
    Properties:
      Description:
        Fn::Join:
          - ""
          - - "Generated by the CDK for stack: "
            - Ref: AWS::StackName
      GenerateSecretString:
        ExcludeCharacters: " %+~`#$&*()|[]{}:;<>?!'/@\"\\"
        GenerateStringKey: password
        PasswordLength: 30
        SecretStringTemplate: '{"username":"clusteradmin"}'
    UpdateReplacePolicy: Delete
    DeletionPolicy: Delete
    Metadata:
      aws:cdk:path: BugStack/Database/Secret/Resource
  DatabaseSecretAttachmentE5D1B020:
    Type: AWS::SecretsManager::SecretTargetAttachment
    Properties:
      SecretId:
        Ref: BugStackDatabaseSecretF03CD1BE3fdaad7efa858a3daf9490cf0a702aeb
      TargetId:
        Ref: DatabaseB269D8BB
      TargetType: AWS::RDS::DBCluster
    Metadata:
      aws:cdk:path: BugStack/Database/Secret/Attachment/Resource
  DatabaseB269D8BB:
    Type: AWS::RDS::DBCluster
    Properties:
      CopyTagsToSnapshot: true
      DBClusterParameterGroupName: default.aurora-mysql8.0
      Engine: aurora-mysql
      EngineVersion: 8.0.mysql_aurora.3.04.0
      MasterUserPassword:
        Fn::Join:
          - ""
          - - "{{resolve:secretsmanager:"
            - Ref: BugStackDatabaseSecretF03CD1BE3fdaad7efa858a3daf9490cf0a702aeb
            - :SecretString:password::}}
      MasterUsername: clusteradmin
      ServerlessV2ScalingConfiguration:
        MaxCapacity: 2
        MinCapacity: 0.5
    UpdateReplacePolicy: Snapshot
    DeletionPolicy: Snapshot
    Metadata:
      aws:cdk:path: BugStack/Database/Resource
  Databasewriter2462CC03:
    Type: AWS::RDS::DBInstance
    Properties:
      DBClusterIdentifier:
        Ref: DatabaseB269D8BB
      DBInstanceClass: db.t3.medium
      Engine: aurora-mysql
      PromotionTier: 0
      PubliclyAccessible: false
    UpdateReplacePolicy: Delete
    DeletionPolicy: Delete
    Metadata:
      aws:cdk:path: BugStack/Database/writer/Resource
  Databasereader1F54479B8:
    Type: AWS::RDS::DBInstance
    Properties:
      DBClusterIdentifier:
        Ref: DatabaseB269D8BB
      DBInstanceClass: db.t3.medium
      Engine: aurora-mysql
      PromotionTier: 1
    DependsOn:
      - Databasewriter2462CC03
    UpdateReplacePolicy: Delete
    DeletionPolicy: Delete
    Metadata:
      aws:cdk:path: BugStack/Database/reader1/Resource
  Databasereader25BC5BEC8:
    Type: AWS::RDS::DBInstance
    Properties:
      DBClusterIdentifier:
        Ref: DatabaseB269D8BB
      DBInstanceClass: db.serverless
      Engine: aurora-mysql
      PromotionTier: 2
    DependsOn:
      - Databasewriter2462CC03
    UpdateReplacePolicy: Delete
    DeletionPolicy: Delete
    Metadata:
      aws:cdk:path: BugStack/Database/reader2/Resource
Conditions:
  CDKMetadataAvailable:
    Fn::Or:
      - Fn::Or:
          - Fn::Equals:
              - Ref: AWS::Region
              - af-south-1
          - Fn::Equals:
              - Ref: AWS::Region
              - ap-east-1
          - Fn::Equals:
              - Ref: AWS::Region
              - ap-northeast-1
          - Fn::Equals:
              - Ref: AWS::Region
              - ap-northeast-2
          - Fn::Equals:
              - Ref: AWS::Region
              - ap-northeast-3
          - Fn::Equals:
              - Ref: AWS::Region
              - ap-south-1
          - Fn::Equals:
              - Ref: AWS::Region
              - ap-south-2
          - Fn::Equals:
              - Ref: AWS::Region
              - ap-southeast-1
          - Fn::Equals:
              - Ref: AWS::Region
              - ap-southeast-2
          - Fn::Equals:
              - Ref: AWS::Region
              - ap-southeast-3
      - Fn::Or:
          - Fn::Equals:
              - Ref: AWS::Region
              - ap-southeast-4
          - Fn::Equals:
              - Ref: AWS::Region
              - ca-central-1
          - Fn::Equals:
              - Ref: AWS::Region
              - ca-west-1
          - Fn::Equals:
              - Ref: AWS::Region
              - cn-north-1
          - Fn::Equals:
              - Ref: AWS::Region
              - cn-northwest-1
          - Fn::Equals:
              - Ref: AWS::Region
              - eu-central-1
          - Fn::Equals:
              - Ref: AWS::Region
              - eu-central-2
          - Fn::Equals:
              - Ref: AWS::Region
              - eu-north-1
          - Fn::Equals:
              - Ref: AWS::Region
              - eu-south-1
          - Fn::Equals:
              - Ref: AWS::Region
              - eu-south-2
      - Fn::Or:
          - Fn::Equals:
              - Ref: AWS::Region
              - eu-west-1
          - Fn::Equals:
              - Ref: AWS::Region
              - eu-west-2
          - Fn::Equals:
              - Ref: AWS::Region
              - eu-west-3
          - Fn::Equals:
              - Ref: AWS::Region
              - il-central-1
          - Fn::Equals:
              - Ref: AWS::Region
              - me-central-1
          - Fn::Equals:
              - Ref: AWS::Region
              - me-south-1
          - Fn::Equals:
              - Ref: AWS::Region
              - sa-east-1
          - Fn::Equals:
              - Ref: AWS::Region
              - us-east-1
          - Fn::Equals:
              - Ref: AWS::Region
              - us-east-2
          - Fn::Equals:
              - Ref: AWS::Region
              - us-west-1
      - Fn::Equals:
          - Ref: AWS::Region
          - us-west-2

which used the account default vpc security group

this validation does appear to be added in https://github.com/aws/aws-cdk/pull/25437/files#diff-49b4a9e1bf0b7db3ab71f4f08580da0cb2191d84605dc82a70c324bd122d5cf7R510-R519

Marking this as bug for further investigation on the expected behavior.

[pahud]

Hi @dbartholomae,

Thanks for raising this issue and providing clear links to the documentation and code!

You're correct that there's a discrepancy between the expectation that the vpc prop for aws_rds.Cluster might be optional (potentially inferring a default VPC) and the actual behavior in the code.

Our investigation confirms that the constructor of the DatabaseClusterNew class(which DatabaseCluster extends) includes a validation check:

aws-cdk/packages/aws-cdk-lib/aws-rds/lib/cluster.ts

Line 795 in ae0c7b7

if ((props.vpc && props.instanceProps?.vpc) || (!props.vpc && !props.instanceProps?.vpc)) {

This code makes it mandatory to provide a VPC context, either through the direct vpc prop on DatabaseClusterProps (via DatabaseClusterBaseProps) or via instanceProps.vpc. If neither is supplied, a ValidationError is thrown.

This means that, as implemented, a DatabaseCluster cannot be created without an explicitly defined VPC configuration. While DatabaseInstance constructs might offer default VPC behavior, DatabaseCluster currently requires this to be explicit.

We have two paths forward:

1. Align Documentation: Update the documentation for aws_rds.Cluster to clearly state that specifying a VPC (either via props.vpc or props.instanceProps.vpc) is mandatory.
2. Modify Behavior: Change the code to allow for a default VPC to be created or used if none is specified. This would be a more involved change and would need careful consideration of the implications for cluster networking.

Given the typical requirements for database clusters, the current explicit VPC requirement might be intentional for better control and to avoid unintended network configurations.

We'll discuss this with the team to determine the best course of action – whether to update the documentation to match the current behavior or to consider a feature change.

In the meantime, please ensure you provide a VPC configuration when defining an aws_rds.Cluster.

We highly encourage contributions! If you'd like to help by submitting a PR to clarify the documentation once we've confirmed the intended behavior, that would be greatly appreciated.

Thanks again for bringing this to our attention!