aws

AWS Best Practices

This document outlines our definitive AWS development standards, rooted in the AWS Well-Architected Framework and modern DevOps guidance. We mandate CDK v2 for infrastructure-as-code and prioritize serverless patterns. Adhere to these guidelines to build secure, reliable, performant, and cost-optimized AWS applications.

1. Code Organization and Structure (AWS CDK v2)

Always structure your AWS CDK applications for clarity, reusability, and maintainability.

1.1 Use AWS CDK v2 Exclusively

CDK v1 is deprecated. All new development and migrations must use CDK v2.

❌ BAD: Using CDK v1

// cdk.json
{
  "app": "npx ts-node bin/my-app.ts",
  "context": {
    "@aws-cdk/core:enableStackNameDuplicates": "true",
    // ... other v1 context
  }
}

✅ GOOD: Using CDK v2

// cdk.json
{
  "app": "npx ts-node --prefer-ts-exts bin/my-app.ts",
  "context": {
    "@aws-cdk/aws-ecr:disableCrossAccountPush": true,
    "@aws-cdk/aws-iam:minimizePolicies": true,
    "@aws-cdk/core:stackRelativeExports": true,
    "@aws-cdk/aws-lambda:recognizeVersionProps": true,
    // ... other v2 context
  }
}

1.2 Modularize with Constructs

Encapsulate related resources, runtime code, and configuration into reusable CDK Constructs. This promotes componentization and reduces boilerplate.

// lib/api-construct.ts
import { Construct } from 'aws-cdk-lib';
import { RestApi, LambdaIntegration } from 'aws-cdk-lib/aws-apigateway';
import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
import { Runtime } from 'aws-cdk-lib/aws-lambda';
import { Table } from 'aws-cdk-lib/aws-dynamodb';

interface ApiConstructProps {
  tableName: string;
  table: Table;
}

export class ApiConstruct extends Construct {
  constructor(scope: Construct, id: string, props: ApiConstructProps) {
    super(scope, id);

    const handler = new NodejsFunction(this, 'MyApiHandler', {
      runtime: Runtime.NODEJS_20_X,
      entry: 'src/lambda/api-handler.ts',
      environment: {
        TABLE_NAME: props.tableName,
      },
    });

    props.table.grantReadWriteData(handler);

    const api = new RestApi(this, 'MyApi', {
      restApiName: 'MyServiceApi',
    });

    api.root.addMethod('GET', new LambdaIntegration(handler));
  }
}