Skip to content

API.md

Latest commit

 

History

History
702 lines (450 loc) · 26.4 KB

API.md

File metadata and controls

702 lines (450 loc) · 26.4 KB

API Reference

Constructs

Aurora

Opinionated Aurora.

Three users: manager, writer, reader all in SecretsManager w/ rotations.

  • All access is via the proxy, enforced by security group.
  • Proxy is available from the ProxyEndpoint output.
const a = new Aurora(this, 'Aurora', {
  kmsKey: aws_kms.Key.fromKeyArn(this, 'Key', 'some arn'),
  instanceType: aws_ec2.InstanceType.of(aws_ec2.InstanceClass.R6G, aws_ec2.InstanceSize.XLARGE24)
 });

We have a CustomResource which fills the gap of creating the users and provisioning some default grants:

GRANT CONNECT ON DATABASE databaseName TO "my_stack_reader";
GRANT USAGE ON SCHEMA public TO "my_stack_reader";
ALTER DEFAULT PRIVILEGES GRANT USAGE ON SEQUENCES TO "my_stack_reader";
ALTER DEFAULT PRIVILEGES GRANT SELECT ON TABLES TO "my_stack_reader";

GRANT CONNECT ON DATABASE databaseName TO "my_stack_writer";
GRANT USAGE ON SCHEMA public TO "my_stack_writer";
ALTER DEFAULT PRIVILEGES GRANT USAGE ON SEQUENCES TO "my_stack_writer";
ALTER DEFAULT PRIVILEGES GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO "my_stack_writer";

Initializers 

import { Aurora } from '@time-loop/cdk-aurora'

new Aurora(scope: Construct, id: Namer, props: AuroraProps)
Name Type Description
scope constructs.Construct No description.
id multi-convention-namer.Namer No description.
props AuroraProps No description.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: multi-convention-namer.Namer
propsRequired

Methods

Name Description
toString Returns a string representation of this construct.
with Applies one or more mixins to this construct.
toString 
public toString(): string

Returns a string representation of this construct.

with 
public with(mixins: IMixin): IConstruct

Applies one or more mixins to this construct.

Mixins are applied in order. The list of constructs is captured at the start of the call, so constructs added by a mixin will not be visited. Use multiple with() calls if subsequent mixins should apply to added constructs.

mixinsRequired
  • Type: constructs.IMixin

The mixins to apply.

Static Functions

Name Description
isConstruct Checks if x is a construct.
isConstruct 
import { Aurora } from '@time-loop/cdk-aurora'

Aurora.isConstruct(x: any)

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

xRequired
  • Type: any

Any object.

Properties

Name Type Description
node constructs.Node The tree node.
cluster aws-cdk-lib.aws_rds.DatabaseCluster No description.
kmsKey aws-cdk-lib.aws_kms.IKey No description.
secrets aws-cdk-lib.aws_rds.DatabaseSecret[] No description.
securityGroups aws-cdk-lib.aws_ec2.ISecurityGroup[] No description.
vpcSubnets aws-cdk-lib.aws_ec2.SubnetSelection No description.
activityStreamArn string No description.
proxy aws-cdk-lib.aws_rds.DatabaseProxy No description.
proxySecurityGroups aws-cdk-lib.aws_ec2.ISecurityGroup[] No description.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

clusterRequired 
public readonly cluster: DatabaseCluster;
  • Type: aws-cdk-lib.aws_rds.DatabaseCluster
kmsKeyRequired 
public readonly kmsKey: IKey;
  • Type: aws-cdk-lib.aws_kms.IKey
secretsRequired 
public readonly secrets: DatabaseSecret[];
  • Type: aws-cdk-lib.aws_rds.DatabaseSecret[]
securityGroupsRequired 
public readonly securityGroups: ISecurityGroup[];
  • Type: aws-cdk-lib.aws_ec2.ISecurityGroup[]
vpcSubnetsRequired 
public readonly vpcSubnets: SubnetSelection;
  • Type: aws-cdk-lib.aws_ec2.SubnetSelection
activityStreamArnOptional 
public readonly activityStreamArn: string;
  • Type: string
proxyOptional 
public readonly proxy: DatabaseProxy;
  • Type: aws-cdk-lib.aws_rds.DatabaseProxy
proxySecurityGroupsOptional 
public readonly proxySecurityGroups: ISecurityGroup[];
  • Type: aws-cdk-lib.aws_ec2.ISecurityGroup[]

Structs

AuroraProps

Initializer 

import { AuroraProps } from '@time-loop/cdk-aurora'

const auroraProps: AuroraProps = { ... }

Properties

Name Type Description
databaseName string Name the database you would like a database created.
kmsKey aws-cdk-lib.aws_kms.IKey The KMS key to use... everywhere.
vpc aws-cdk-lib.aws_ec2.IVpc In which VPC should the cluster be created?
activityStream boolean Turn on the Activity Stream feature of the Aurora cluster.
cloudwatchLogsExports string[] Which logs to export to CloudWatch.
cloudwatchLogsRetention aws-cdk-lib.aws_logs.RetentionDays How long to retain logs published to CloudWatch logs.
commonRotationUserOptions aws-cdk-lib.aws_rds.CommonRotationUserOptions Common password rotation options.
deletionProtection boolean Indicates whether the DB cluster should have deletion protection enabled.
instances number How many instances?
instanceType aws-cdk-lib.aws_ec2.InstanceType https://aws.amazon.com/blogs/aws/new-amazon-rds-on-graviton2-processors/ says we can use Graviton2 processors. Yay!
lambdaLogRetention aws-cdk-lib.aws_logs.RetentionDays How long to retain logs published by provisioning lambdas.
parameterGroup aws-cdk-lib.aws_rds.IParameterGroup Additional parameters to pass to the database engine.
parameters {[ key: string ]: string} The parameters in the DBClusterParameterGroup to create automatically.
performanceInsightRetention aws-cdk-lib.aws_rds.PerformanceInsightRetention How long to retain performance insights data in days.
postgresEngineVersion aws-cdk-lib.aws_rds.AuroraPostgresEngineVersion Postgres version Be aware of version limitations See https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/Concepts.AuroraFeaturesRegionsDBEngines.grids.html#Concepts.Aurora_Fea_Regions_DB-eng.Feature.RDS_Proxy.
proxySecurityGroups aws-cdk-lib.aws_ec2.ISecurityGroup[] Security groups to use for the RDS Proxy.
removalPolicy aws-cdk-lib.RemovalPolicy No description.
retention aws-cdk-lib.Duration RDS backup retention.
schemas string[] Schemas to create and grant defaults for users.
secretPrefix string | multi-convention-namer.Namer Prefix for secrets.
securityGroups aws-cdk-lib.aws_ec2.ISecurityGroup[] Security groups to use for the Aurora cluster.
skipAddRotationMultiUser boolean When bootstrapping, hold off on creating the addRotationMultiUser.
skipManagerRotation boolean Skipping rotation for the manager user's password.
skipProvisionDatabase boolean Skip provisioning the database?
skipProxy boolean By default, we provide a proxy for non-manager users.
skipUserProvisioning boolean When bootstrapping, hold off on provisioning users in the database.
vpcSubnets aws-cdk-lib.aws_ec2.SubnetSelection Used to decide which subnets to place the cluster in.
databaseNameRequired 
public readonly databaseName: string;
  • Type: string

Name the database you would like a database created.

This also will target which database has default grants applied for users.

kmsKeyRequired 
public readonly kmsKey: IKey;
  • Type: aws-cdk-lib.aws_kms.IKey

The KMS key to use... everywhere.

vpcRequired 
public readonly vpc: IVpc;
  • Type: aws-cdk-lib.aws_ec2.IVpc

In which VPC should the cluster be created?

activityStreamOptional 
public readonly activityStream: boolean;
  • Type: boolean
  • Default: false

Turn on the Activity Stream feature of the Aurora cluster.

cloudwatchLogsExportsOptional 
public readonly cloudwatchLogsExports: string[];
  • Type: string[]
  • Default: ['postgresql']

Which logs to export to CloudWatch.

See https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.CloudWatch.html

cloudwatchLogsRetentionOptional 
public readonly cloudwatchLogsRetention: RetentionDays;
  • Type: aws-cdk-lib.aws_logs.RetentionDays
  • Default: aws_logs.RetentionDays.ONE_MONTH

How long to retain logs published to CloudWatch logs.

commonRotationUserOptionsOptional 
public readonly commonRotationUserOptions: CommonRotationUserOptions;
  • Type: aws-cdk-lib.aws_rds.CommonRotationUserOptions
  • Default: none, AWS defaults to 30 day rotation

Common password rotation options.

See https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_rds.CommonRotationUserOptions.html

deletionProtectionOptional 
public readonly deletionProtection: boolean;
  • Type: boolean
  • Default: true if removalPolicy is RETAIN, undefined otherwise, which will not enable deletion protection. To disable deletion protection after it has been enabled, you must explicitly set this value to false.

Indicates whether the DB cluster should have deletion protection enabled.

instancesOptional 
public readonly instances: number;
  • Type: number
  • Default: 2 one for writer and one for reader

How many instances?

DevOps strongly recommends at least 3 in prod environments and only 1 in dev environments.

instanceTypeOptional 
public readonly instanceType: InstanceType;
  • Type: aws-cdk-lib.aws_ec2.InstanceType
  • Default: aws_ec2.InstanceType.of(aws_ec2.InstanceClass.T4G,aws_ec2.InstanceSize.MEDIUM)

https://aws.amazon.com/blogs/aws/new-amazon-rds-on-graviton2-processors/ says we can use Graviton2 processors. Yay!

lambdaLogRetentionOptional 
public readonly lambdaLogRetention: RetentionDays;
  • Type: aws-cdk-lib.aws_logs.RetentionDays
  • Default: aws_logs.RetentionDays.THREE_MONTHS

How long to retain logs published by provisioning lambdas.

These are extremely low volume, and super handy to have around.

parameterGroupOptional 
public readonly parameterGroup: IParameterGroup;
  • Type: aws-cdk-lib.aws_rds.IParameterGroup
  • Default: No parameter group.

Additional parameters to pass to the database engine.

You can only specify parameterGroup or parameters but not both.

parametersOptional 
public readonly parameters: {[ key: string ]: string};
  • Type: {[ key: string ]: string}
  • Default: defaults match tf aurora-cluster module, including: - Logical replication enabled (rds.logical_replication: '1') - SSL enforcement (rds.force_ssl: '1') - Query timeout protection (statement_timeout: 30s, idle_in_transaction: 5s) - Enhanced monitoring (log slow queries >200ms, lock waits, DDL statements) - Performance tuning (SSD-optimized costs, parallel workers, work_mem: 4MB) - Aggressive autovacuum (analyze_scale_factor: 0.01) - Extended replication slots (20) and wal senders (20)

The parameters in the DBClusterParameterGroup to create automatically.

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

performanceInsightRetentionOptional 
public readonly performanceInsightRetention: PerformanceInsightRetention;
  • Type: aws-cdk-lib.aws_rds.PerformanceInsightRetention
  • Default: passthrough (was 7 days as of cdk 2.78.0)

How long to retain performance insights data in days.

Free tier is 7 days. See: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-rds-dbinstance.html#cfn-rds-dbinstance-performanceinsightsretentionperiod

postgresEngineVersionOptional 
public readonly postgresEngineVersion: AuroraPostgresEngineVersion;
  • Type: aws-cdk-lib.aws_rds.AuroraPostgresEngineVersion
  • Default: 15.5

Postgres version Be aware of version limitations See https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/Concepts.AuroraFeaturesRegionsDBEngines.grids.html#Concepts.Aurora_Fea_Regions_DB-eng.Feature.RDS_Proxy.

proxySecurityGroupsOptional 
public readonly proxySecurityGroups: ISecurityGroup[];
  • Type: aws-cdk-lib.aws_ec2.ISecurityGroup[]
  • Default: create a single new security group to use for the proxy.

Security groups to use for the RDS Proxy.

removalPolicyOptional
  • Deprecated: This property is no longer used. Removal policies are now automatically set based on resource type: infrastructure resources (KMS, RDS, Security Groups, Secrets) are RETAINED for safety, while ephemeral resources (Lambdas, IAM, nested stacks) are DESTROYED. This enables safe CDK->Terragrunt migrations.
public readonly removalPolicy: RemovalPolicy;
  • Type: aws-cdk-lib.RemovalPolicy
  • Default: Automatic based on resource type
retentionOptional 
public readonly retention: Duration;
  • Type: aws-cdk-lib.Duration
  • Default: Duration.days(1) This should pass through, but nope. So, we're duplicating the default.

RDS backup retention.

schemasOptional 
public readonly schemas: string[];
  • Type: string[]
  • Default: ['public']

Schemas to create and grant defaults for users.

secretPrefixOptional 
public readonly secretPrefix: string | Namer;
  • Type: string | multi-convention-namer.Namer
  • Default: no prefix

Prefix for secrets.

Useful for sharding out multiple Auroras in the same environment.

securityGroupsOptional 
public readonly securityGroups: ISecurityGroup[];
  • Type: aws-cdk-lib.aws_ec2.ISecurityGroup[]
  • Default: create a single new security group to use for the cluster.

Security groups to use for the Aurora cluster.

skipAddRotationMultiUserOptional 
public readonly skipAddRotationMultiUser: boolean;
  • Type: boolean
  • Default: false

When bootstrapping, hold off on creating the addRotationMultiUser.

NOTE: the multiUser strategy relies on a _clone user, which is potentially surprising. See https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets_strategies.html#rotating-secrets-two-users

skipManagerRotationOptional 
public readonly skipManagerRotation: boolean;
  • Type: boolean
  • Default: false

Skipping rotation for the manager user's password.

skipProvisionDatabaseOptional 
public readonly skipProvisionDatabase: boolean;
  • Type: boolean
  • Default: false

Skip provisioning the database?

Useful for bootstrapping stacks to get the majority of resources in place. The db provisioner will:

  • create the database (if it doesn't already exist)
  • create the schemas (if they don't already exist)
  • create (if they don't already exist) and configure the r_reader and r_writer roles

NOTE: This will implicitly skip user provisioning, too.

skipProxyOptional 
public readonly skipProxy: boolean;
  • Type: boolean
  • Default: false

By default, we provide a proxy for non-manager users.

skipUserProvisioningOptional 
public readonly skipUserProvisioning: boolean;
  • Type: boolean
  • Default: false except when skipProvisionDatabase is true, then also true

When bootstrapping, hold off on provisioning users in the database.

Useful for bootstrapping stacks to get the majority of resources in place. The user provisioner will:

  • conform the users' secret (ensure the host, engine, proxyHost keys are present and correct)
  • create the user (if it doesn't already exist) and related _clone user
  • conform the user's password to what appears in the secrets manager secret (heal from broken rotations)
  • grant the r_reader or r_writer role to the user and it's _clone.

NOTE: This is implicitly true if skipProvisionDatabase is true.

vpcSubnetsOptional 
public readonly vpcSubnets: SubnetSelection;
  • Type: aws-cdk-lib.aws_ec2.SubnetSelection
  • Default: {subnetType:aws_ec2.SubnetType.PRIVATE_WITH_EGRESS} - all private subnets

Used to decide which subnets to place the cluster in.

Which also decides the subnets for the RDS Proxy, and the provisioning lambdas.

Previously we would just fallthrough for the Aurora and RDS stuff, but then we don't have a reasonable solution for our provisioning lambdas.