Skip to content

Latest commit

 

History

History
661 lines (420 loc) · 24.5 KB

API.md

File metadata and controls

661 lines (420 loc) · 24.5 KB
Raw

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.
toString 
public toString(): string

Returns a string representation of this construct.

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.

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: defaultParameters const defaultParameters = { // While these are mentioned in the docs, applying them doesn't work. 'rds.logical_replication': '1', // found in the cluster parameters. // wal_level: 'logical', // not found in cluster parameters, but implicitly set by rds.logical_replication max_replication_slots: '10', // Arbitrary, must be > 1 max_wal_senders: '10', // Arbitrary, must be > 1 wal_sender_timeout: '0', // Never time out. Risky, but recommended. };

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 
public readonly removalPolicy: RemovalPolicy;
  • Type: aws-cdk-lib.RemovalPolicy
  • Default: passthrough
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.