S3BucketBuilder¶

Purpose¶

The S3BucketBuilder class is a concrete implementation of the AbstractAWSResourceBuilder designed to create secure, compliant S3 buckets following organizational standards. This builder automatically applies security best practices including public access blocking, SSL enforcement, and optional KMS encryption while integrating with your foundation infrastructure.

Dependencies¶

This builder requires the following AWS resources to be available, typically provided by MARE-foundations:

Required Foundation Resources¶

KMS Key: Encryption key with alias pattern:
- alias/{domain}-foundation-{project}-{env}-s3-snc-key if use_foundation_key is true
- alias/{domain}-{project}-{env}-s3-snc-key if use_foundation_key is false
Parameter Store Access: Permissions to write parameters for cross-stack bucket name sharing
Environment Configuration: Account ID mapping for cross-account access resolution

AWS Permissions Required¶

S3 bucket creation and management
KMS key lookup (when encryption enabled)
Parameter Store write access
Resource tagging permissions
S3 PutObject permissions (when folder_structure is configured)

Configuration¶

The builder uses the S3BucketConfig model for the validation of your configuration and becomes the authoritative source of all bucket settings.

CDK Configuration Structure¶

The builder's configuration values should be sourced from the cdk.json file. The expected structure is as follows:

{
  "bucket_name": {
    "versioned": false,
    "use_kms_key": true,
    "use_foundation_key": true,
    "is_for_logs": false,
    "cross_account_role": "deployer-role",
    "target_env_name": "prod",
    "include_dummy_index": false,
    "folder_structure": {
      "artifacts_folder": [],
      "config_folder": ["ecas", "ssl"]
    },
    "lifecycle_rule": {
      "expiration_days": 90,
      "abort_incomplete_multipart_upload_days": 7
    }
  }
}

Configuration Parameters¶

Parameter	Mandatory	Type	Default	Description
	Yes	str		The configuration key that becomes the bucket base name
versioned	No	bool	false	Enable S3 versioning for the bucket
use_kms_key	No	bool	false	Use foundation KMS key for server-side encryption
use_foundation_key	No	bool	true	Use organizational KMS key from foundation infrastructure
is_for_logs	No	bool	false	Configure bucket for log delivery (sets object ownership)
cross_account_role	No	str	None	IAM role name in target account for cross-account access
target_env_name	No	str	None	Target environment name for cross-account access
include_dummy_index	No	bool	false	Create placeholder index.html file during bucket creation
folder_structure	No	Dict[str, List[str]]	None	Dictionary mapping parent folders to subfolders. Use empty list for top-level folders only
lifecycle_rule	No	Dict	None	Lifecycle management configuration for automatic object expiration and cleanup

Usage¶

Here’s an example of how to use the S3BucketBuilder to build an S3 bucket in a CDK stack:

bucket_config = app_helper.get_from_env("bucket_name")

s3_builder = S3BucketBuilder()
s3_bucket = s3_builder.set_application_helper(app_helper) \
                      .set_builder_config(bucket_config) \
                      .set_bucket_base_name("bucket_name") \
                      .build(scope_from_stack)

Behaviour and Features¶

KMS Encryption Options¶

The builder supports two encryption key strategies:

Foundation Key: When use_foundation_key is true, uses organizational shared KMS key
Project-Specific Key: When use_foundation_key is false, uses project-specific KMS key
S3 Managed: When use_kms_key is false, uses AWS S3-managed encryption (AES-256)

Lifecycle Management¶

When lifecycle_rule is configured, the builder automatically creates a lifecycle policy to manage object retention and cleanup. This feature is useful for:

Automatically expiring objects after a specified retention period
Cleaning up incomplete multipart uploads to reduce storage costs
Implementing data retention policies and compliance requirements
Managing temporary or staging data that should be automatically removed

Configuration Options¶

The lifecycle_rule parameter accepts a dictionary with the following optional fields:

expiration_days: Number of days after object creation when objects should be automatically deleted
abort_incomplete_multipart_upload_days: Number of days after initiation when incomplete multipart uploads should be automatically aborted

Both parameters can be used independently or together. If both are omitted, no lifecycle rule will be created.

Initial Folder Structure¶

When folder_structure is configured, the builder automatically creates an organized folder hierarchy in the bucket at deployment time. This feature is useful for:

Establishing consistent directory layouts across environments
Pre-creating folders for applications that expect specific paths
Organizing data by environment, type, or purpose before content upload

Configuration Format¶

The folder_structure parameter accepts a dictionary where:

Keys represent parent folder names
Values are lists of subfolder names (use empty list [] for top-level folders only)

Dummy Content Deployment¶

When include_dummy_index is enabled, the builder automatically:

Creates a simple HTML index file in the bucket
Uses the project name in the content: "Hello from {PROJECT}!"
Useful for testing bucket access and web hosting configurations

Automatic Security Configuration¶

All buckets are created with security best practices:

Public Access: Completely blocked via BlockPublicAccess.BLOCK_ALL
SSL Enforcement: Required for all requests via bucket policy
Encryption: KMS encryption when use_kms_key is true, otherwise S3-managed encryption
Bucket Keys: Enabled for cost optimization when using KMS encryption
Auto-deletion: Objects automatically deleted when bucket is destroyed (RemovalPolicy.DESTROY)
Object Ownership: Set to OBJECT_WRITER when is_for_logs is true for log delivery compatibility

Cross-Account Access¶

When cross_account_role and target_env_name are configured, the builder automatically:

Looks up the target account ID from environment configuration
Creates an IAM policy allowing the specified role to perform:
s3:GetObject - Read objects from the bucket
s3:GetObjectVersion - Read specific versions of objects
Attaches the policy to the bucket's resource policy

Naming Convention¶

Bucket names follow the pattern: ifdm-{bucket_base_name}-{account_id}

The builder automatically:

Truncates names to respect S3's 63-character limit
Applies organizational naming standards
Ensures uniqueness across AWS accounts

Parameter Store Integration¶

Each bucket's name is automatically stored in Parameter Store with the key pattern: S3_BUCKET_{BUCKET_BASE_NAME_UPPER_WITH_UNDERSCORES}

Notes

The set_usage method from the abstract class should not be used in this builder
The bucket base name must be set via set_bucket_base_name() method before building
KMS keys must exist before bucket creation when use_kms_key is enabled
Cross-account role and target environment name must both be provided together or both omitted
Bucket names are automatically made globally unique by appending the account ID