cdk-aurora-globaldatabase

Common errors

• ModuleNotFoundError: No module named 'cdk_aurora_globaldatabase'

  cause The library is not installed or the import path is incorrect.
  fix Run `pip install cdk-aurora-globaldatabase` to install the library. Ensure your import statement is `from cdk_aurora_globaldatabase import AuroraGlobalDatabase`.

• TypeError: __init__() got an unexpected keyword argument 'primaryRegion'

  cause CDK Python constructs use snake_case for property names (e.g., `primary_region`) instead of camelCase (`primaryRegion`). This is a common mistake when translating from TypeScript/JavaScript examples.
  fix Rename the argument from `primaryRegion` to `primary_region` and apply similar changes for other properties like `secondaryRegions` to `secondary_regions`.

• Failed to deploy stack 'AuroraGlobalDbStack' because the primary region 'us-east-1' or secondary region 'us-east-2' is not correctly bootstrapped or lacks credentials.

  cause CDK cross-region deployments require explicit bootstrapping for all regions involved and valid AWS credentials for each. The error can manifest if bootstrapping is incomplete or credentials lack permissions.
  fix Ensure you have run `cdk bootstrap aws://YOUR_ACCOUNT_ID/us-east-1` and `cdk bootstrap aws://YOUR_ACCOUNT_ID/us-east-2` (and any other secondary regions). Verify your AWS credentials can access all these regions and have the necessary permissions for RDS, EC2, KMS, etc.

Warnings

• breaking This library is built specifically for AWS CDK v2. Attempting to use it with an AWS CDK v1 project will result in `ModuleNotFoundError` for `aws_cdk` or `constructs` (v1 vs v2 imports) or incompatible API usage.
  Fix: Migrate your CDK project to AWS CDK v2 by installing `aws-cdk-lib` and `constructs>=10.0.0`. If you must use CDK v1, look for a v1-compatible version of this construct or implement it manually.
• gotcha Deploying an Aurora Global Database across multiple regions requires your AWS environment to be bootstrapped in *all* specified regions (primary and all secondaries).
  Fix: Before deploying, run `cdk bootstrap aws://YOUR_ACCOUNT_ID/PRIMARY_REGION` and `cdk bootstrap aws://YOUR_ACCOUNT_ID/SECONDARY_REGION` for every region involved in your global database. Replace `YOUR_ACCOUNT_ID` and region placeholders with your actual AWS account ID and region names.
• gotcha AWS credentials must be configured for all regions specified in `primary_region` and `secondary_regions`. CDK will attempt to deploy resources in each of these regions.
  Fix: Ensure your AWS CLI or SDK configuration (e.g., `~/.aws/credentials` file, environment variables like `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`) provides valid credentials for all regions where the global database will be deployed. This often means having a profile configured for each region or using global credentials with appropriate permissions.

Install

• pip install cdk-aurora-globaldatabase Install stable version

Imports

• AuroraGlobalDatabase

  from cdk_aurora_globaldatabase import AuroraGlobalDatabase

Quickstart

This quickstart deploys an AWS Aurora Global Database with a MySQL-compatible engine across two AWS regions. It provisions a new VPC for the database. Before running, ensure your AWS account is bootstrapped for CDK in 'us-east-1' and 'us-east-2', and your `CDK_DEFAULT_ACCOUNT` and `CDK_DEFAULT_REGION` environment variables are set, or replace the placeholder values. The `synth` command generates the CloudFormation templates.

import os
from aws_cdk import App, Stack, Environment
from aws_cdk import aws_ec2 as ec2
from aws_cdk import aws_rds as rds
from cdk_aurora_globaldatabase import AuroraGlobalDatabase

class GlobalDatabaseStack(Stack):
    def __init__(self, scope: App, id: str, **kwargs) -> None:
        super().__init__(scope, id, **kwargs)

        # For a quickstart, we create a new VPC. In a production environment,
        # you would typically look up an existing VPC: 
        # vpc = ec2.Vpc.from_lookup(self, "MyExistingVpc", vpc_name="YourVpcName")
        vpc = ec2.Vpc(
            self, "AuroraGlobalDbVpc",
            max_azs=2,  # Deploy resources across 2 availability zones
            cidr="10.0.0.0/16",
            enable_dns_hostnames=True,
            enable_dns_support=True
        )

        AuroraGlobalDatabase(
            self, "MyAuroraGlobalDatabase",
            primary_region="us-east-1",
            secondary_regions=["us-east-2"], # Add more regions as needed
            aurora_version=rds.AuroraMysqlEngineVersion.VER_3_06_0, # Example MySQL version
            vpc=vpc,
            # Optional: specify instance type, credentials, storage encryption, etc.
            # instance_type=ec2.InstanceType.of(ec2.InstanceClass.R6G, ec2.InstanceSize.LARGE),
            # credentials=rds.Credentials.from_generated_secret("auroraglobaladmin"),
            # encryption_key=kms.Key(self, "AuroraKey")
        )

app = App()
# Define an environment for the primary stack
primary_env = Environment(
    account=os.environ.get('CDK_DEFAULT_ACCOUNT', '123456789012'),
    region=os.environ.get('CDK_DEFAULT_REGION', 'us-east-1')
)
GlobalDatabaseStack(app, "AuroraGlobalDbStack", env=primary_env)
app.synth()