CDK Constructs

Arda’s Runtime platform defines specific configurations, patterns and groups of the basic AWS resources that represent the best practices and standards adopted by Arda’s Engineering. These practices and standards are captured by defining high level CDK constructs that are reusable and can be used to build the Infrastructure, Purpose and Component elements of the Runtime Architecture. These constructs are defined in the resources/src/cdk/constructs directory of this repository. Currently all existing Constructs are in the same directory, in the future there will be a need for further classification of constructs, likely along the lines of their intent: Compute, Network, Storage, Ingres/Egress, OAM, Mixed.

Standard Construct Pattern

Arda Constructs follow a pattern to make them reusable and easy to integrate when building the elements of the runtime architecture. Each construct defines:

• Configuration: A typescript interface that defines the configuration parameters of the construct. These are true configuration parameters that affect the behavior of the resources defined by the construct. See Props for other parameters.
• Props: A typescript interface that provides information about the context where the construct will be used like bindings to other resources, etc. These are different than the ones in the Configuration interface and are usually aws-cdk types like ecs.IVpc that inform the construct about resources that it needs to bind to. This interface extends the Configuration interface to capture all the parameters for a construct. All the members of this interface should be readonly
• Built: A typescript interface that defines a subset of the values and resources that the Construct creates and builds when instantiated. These may represent values needed by other constructs or external tools (e.g. the authentication url of a Cognito User Pool). All the members of this interface should be readonly

The construct itself that extends the cdk.Construct class. The constructor of this class should accept the arguments:

• scope: cdk.Construct: The parent Construct that instantiates it.
• id: string: It is directly the id parameter of the parent construct. It is used to name the AWS resources created by the construct in the context of the CloudFormation stack.
• props: Props: The configuration and context parameters of the construct.

The construct also has a public readonly build: Built member to capture the results of the instantiation of the construct.

It is best practice to have a static validateProps(prefix: string, id: string, props: Props): boolean in the Construct to be called before invoking the super constructor that throws an Error if the properties, prefix or id are incompatible. This is to ensure that the construct is instantiated with valid parameters and to avoid having to deal with errors and rollback once the instantiation process is started.

Template of a Construct

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';

export interface Configuration {
  // Configuration parameters of the construct
  // These are the parameters set by the caller to configure the behavior of the resources defined by the construct.
};

export interface Props extends Configuration {
  // Props parameters of the construct
  // These are the parameters that provide access to resources from the context where the construct will be used. E.g. the VPC where the construct will be deployed, Role Arn's to use, etc.
};
export interface Built {
  // Built parameters of the construct
  // These are the parameters that represent the values and resources that the Construct creates and builds when instantiated.
};

export class MyConstruct extends Construct {
  public readonly build: Built;

  static validateProps(id: string, props: Props): boolean {
    // Validate the props and throw an error if they are not valid
    return true;
  }

  constructor(scope: cdk.Construct, id: string, props: Props) {
    validateProps(id, props);
    super(scope, id)

    // Define the resources of the construct here
    // Use the props to configure the resources

    this.build = {
      // Define the built parameters here
    };
  }
}

Organization of Constructs

Constructs are organized by their functionality into:

Compute

Computing resources like Lambda functions, EKS clusters, etc.

Network

Networking resources like VPCs, Load Balancers, etc.

Storage

Storage resources like S3 buckets, EFS, as well as more sophisticated storage like DynamoDB, RDS, etc.

Xgress

Ingress and Egress resources like API Gateway, VPC Links, DNS entries, etc.

OAM

Observability, Audit and Monitoring resources like CloudWatch, X-Ray, etc.

Platform

Constructs and Configurations that are specific to Global configuration of the Arda Platform.

Each Construct should document its own functionality and usage

Comments