S3 CDK Construct Library

City of Philadelphia s3 bucket CDK constructs.

Overview

This CDK construct library provides reusable AWS S3 bucket constructs for different use cases: web hosting files, log storage, and general file storage. Each construct is configured with appropriate security settings, encryption, and lifecycle management.

Installation

npm install @phila/cdk-s3

Bucket Types

WebfilesBucket

Creates an S3 bucket for static website files which must be served via CloudFront. Do not use for protected and private files, just public website ones. This bucket is configured with:

• S3-managed encryption (no KMS)
• No lifecycle rules
• Fully private. (Must use AOC in CloudFront for serving)
• SSL enforcement
• No versioning
• Automatic cleanup in non-production environments

Props:

• GlobalProps (required) - See GlobalProps documentation
• logBucket?: IBucket (optional) - Optional log bucket for access logging. Provide an instance of LogBucket.

Usage:

import { Compliance, Confidentiality, WebfilesBucket } from "@phila/cdk-s3";

const webfilesBucket = new WebfilesBucket(stack, "WebfilesBucket", {
  project: "my-project",
  environment: "production",
  department: "4-oit",
  team: "Platform Engineering",
  contact: "[email protected]",
  compliance: Compliance.STANDARD,
  confidentiality: Confidentiality.LOW,
  tags: {
    Example: "Example tag",
  },
  logBucket: logBucket.bucket, // optional
});

LogBucket

Creates an S3 bucket for centralized S3 access logs. This bucket is configured with:

• KMS encryption
• Configurable log retention (default: 30 days)
• Fully private with SSL enforcement
• No versioning
• Automatic cleanup enabled

Props:

• GlobalProps (required) - See GlobalProps documentation
• logRetentionDays?: number (optional) - Log retention days (default: 30).
• logBucket?: IBucket (optional) - Optional log bucket for access logging (typically not used for log buckets themselves because it may create a cycle loop)

Usage:

import { Compliance, Confidentiality, LogBucket } from "@phila/cdk-s3";

const logBucket = new LogBucket(stack, "LogBucket", {
  project: "my-project",
  environment: "production",
  department: "4-oit",
  team: "Platform Engineering",
  contact: "[email protected]",
  compliance: Compliance.STANDARD,
  confidentiality: Confidentiality.LOW,
  tags: {
    Example: "Example tag",
  },
  logRetentionDays: 90, // optional, default is 30
});

FilesBucket

Creates an S3 bucket for application file storage. This bucket is configured with:

• KMS encryption
• Optional Glacier transition for cost optimization
• Fully private (all public access blocked), access must be granted via IAM policies. (e.g. Fargate task role to Read and Write application files in the bucket)
• Optional versioning (default: false)
• SSL enforcement
• Automatic cleanup in non-production environments

Props:

• GlobalProps (required) - See GlobalProps documentation
• glacierTransitionDays?: number (optional) - Days before transitioning files to Glacier (default: 60). Set to 0 to disable Glacier transition.
• versioned?: boolean (optional) - Enable versioning on the bucket (default: false)
• logBucket?: IBucket (optional) - Optional log bucket for access logging

Usage:

import { Compliance, Confidentiality, FilesBucket } from "@phila/cdk-s3";

const filesBucket = new FilesBucket(stack, "FilesBucket", {
  project: "my-project",
  environment: "production",
  department: "4-oit",
  team: "Platform Engineering",
  contact: "[email protected]",
  compliance: Compliance.STANDARD,
  confidentiality: Confidentiality.MEDIUM,
  tags: {
    Example: "Example tag",
  },
  glacierTransitionDays: 90, // optional, default is 60, set to 0 to disable
  versioned: true, // optional, default is false
  logBucket: logBucket.bucket, // optional
});

GlobalProps

All bucket constructs require GlobalProps. For complete documentation on GlobalProps, including all properties, enums, and usage examples, see the Shared CDK Construct Library documentation.

Features

• Security: All buckets are fully private with SSL enforcement
• Encryption: KMS encryption for log and files buckets, S3-managed for web files
• Lifecycle Management: Configurable retention and Glacier transitions
• CDK Outputs: Exposes bucket names as CloudFormation outputs
• Compliance: NIST 800-53 Rev 5 compliant with appropriate CDK Nag suppressions

Development

Prerequisites

• Node.js 22+
• pnpm
• AWS CDK CLI

Commands

• pnpm run build - Build the library
• pnpm run watch - Build in watch mode
• pnpm run test - Run tests
• pnpm run lint - Lint code
• pnpm run format - Format code