EfsBuilder¶

Purpose¶

The EfsBuilder class is a concrete implementation of the AbstractAWSResourceBuilder designed to create comprehensive AWS EFS (Elastic File System) infrastructure for scalable, fully managed NFS file systems. This builder orchestrates the deployment of production-ready file systems with configurable performance characteristics, throughput modes, encryption settings, fine-grained access control through access points, and cross-account parameter sharing for enterprise-grade persistent storage solutions.

Dependencies¶

This builder requires the following AWS resources and permissions:

Required AWS Permissions¶

EFS Management: Create and configure EFS file systems, mount targets, and access points
VPC Operations: Deploy EFS resources within VPC with private subnet configuration
KMS Operations: Encrypt/decrypt data and manage encryption keys for file system storage
Security Group Management: Configure network access control for EFS mount operations
IAM Role Management: Create and manage resource policies for EFS service integration
Systems Manager: Store and retrieve parameter values for cross-stack integration
Cross-Account Sharing: Share SSM parameters across AWS accounts for multi-environment access
Resource Tagging: Apply organizational tags to resources for governance and cost tracking

Foundation Dependencies¶

VPC Infrastructure: Existing VPC with private subnets for secure file system deployment
Security Groups: Pre-configured own-efs-sg security group for EFS network access control
KMS Key: Foundation encryption key with alias pattern:
- alias/{domain}-foundation-{project}-{env}-efs-snc-key if use_foundation_key is true
- alias/{domain}-{project}-{env}-efs-snc-key if use_foundation_key is false
Cross-Account Roles: DevOps account access for parameter sharing and operational management
Environment Configuration: Account and region mappings for multi-environment deployments

Configuration¶

The builder uses the EfsConfig model for the validation of your configuration and becomes the authoritative source of all ECS infrastructure settings.

Please check the also following models to have a detailed view on the configuration possibilities:

EfsAccessPointConfig model

CDK Configuration Structure¶

Basic EFS Configuration¶

{
  "efs_base_name": "app-storage",
  "removal_policy": "DESTROY",
  "performance_mode": "GeneralPurpose",
  "throughput_mode": "Bursting",
  "encrypted": true,
  "use_foundation_key": true,
  "access_points": [
    {
      "name": "app-data",
      "path": "/app/data",
      "owner_uid": 1000,
      "owner_gid": 1000,
      "permissions": "755",
      "posix_uid": 1000,
      "posix_gid": 1000,
      "create_creation_info": true,
      "create_posix_user": true
    },
    {
      "name": "logs",
      "path": "/app/logs",
      "owner_uid": 1001,
      "owner_gid": 1001,
      "permissions": "644",
      "posix_uid": 1001,
      "posix_gid": 1001,
      "create_creation_info": true,
      "create_posix_user": false
    }
  ]
}

Configuration Parameters¶

Parameter	Mandatory	Type	Default	Description
efs_base_name	Yes	str		Base name for the EFS file system resource
removal_policy	No	str		DESTROY CDK removal policy (DESTROY, RETAIN, SNAPSHOT)
performance_mode	No	str	None	EFS performance mode (GeneralPurpose, MaxIO)
throughput_mode	No	str	None	EFS throughput mode (Bursting, Provisioned)
encrypted	No	bool	False	Whether to enable encryption at rest
use_foundation_key	No	bool	True	Whether to use organizational KMS key from foundation
access_points	No	List	[]	List of access point configurations for controlled access

Access Point Configuration Structure¶

{
  "name": "access-point-name",
  "path": "/custom/path",
  "owner_uid": 1000,
  "owner_gid": 1000,
  "permissions": "755",
  "posix_uid": 1000,
  "posix_gid": 1000,
  "create_creation_info": true,
  "create_posix_user": true
}

Usage¶

Here's an examples of how to use the EfsBuilder to build EFS infrastructure in a CDK stack:

efs_config = app_helper.get_from_env("efs")

efs_builder = EfsBuilder()
efs_file_system = efs_builder.set_application_helper(app_helper) \
                            .set_efs_base_name("production-storage") \
                            .set_builder_config(efs_config) \
                            .build(scope_from_stack)

Behavior and Features¶

Automatic Infrastructure Configuration¶

File System Configuration¶

Performance Modes: GeneralPurpose for most workloads, MaxIO for high-performance scenarios
Throughput Modes: Bursting for variable workloads, Provisioned for consistent high throughput
Encryption: Optional KMS encryption with organizational key management
Network Security: Integration with pre-configured security groups for access control
Private Deployment: File systems deployed in private subnets for enhanced security

Access Point Management¶

Fine-Grained Access: Application-specific entry points with predefined paths
POSIX Enforcement: User/group ID mapping for consistent file ownership
Permission Control: Configurable directory permissions using standard Unix octal notation
Creation Policies: Automatic directory creation with specified ownership and permissions

Cross-Account Integration¶

Parameter Store Integration¶

File System ID Storage: EFS_FILE_SYSTEM_ID_{BASE_NAME} for cross-stack references
Access Point Storage: EFS_{BASE_NAME}_ACCESS_POINT_ID_{AP_NAME} for specific access points
DevOps Sharing: Automatic parameter sharing with DevOps account for operational access
Advanced Parameters: Uses advanced tier for cross-account parameter sharing scenarios

Producer-Consumer Model: EFS resources created in one account, accessed from others
Environment Isolation: Separate EFS systems per environment with shared operational access
Parameter Hierarchies: Organized parameter naming for easy discovery and management

Naming Convention¶

EFS resources follow the pattern: {organization-prefix}-{environment}-{efs-base-name}

The builder automatically:

Applies organizational naming standards across all resources
Includes environment context for multi-stage deployments
Truncates names to respect AWS service limits
Generates unique CloudFormation logical IDs

Security and Access Control¶

Network Security¶

VPC Integration: File systems deployed within organizational VPC infrastructure
Security Group Control: Uses pre-configured own-efs-sg for network access management
Mount Target Security: Access restricted to authorized subnets and security groups
Private Subnets: File systems only accessible from private network segments

Access Points Security¶

Path Isolation: Each access point restricted to specific directory paths
User Enforcement: POSIX user/group ID enforcement for file operations
Permission Control: Fine-grained directory permissions for application security
Creation Policies: Automatic ownership assignment during directory creation

IAM Policies¶

Service Integration: Policies enable DataSync, ECS, and other AWS service access
Mount Target Conditions: Access restricted to legitimate mount target connections
Least Privilege: Minimal permissions required for specific operational needs

Performance and Optimization¶

Performance Modes¶

General Purpose: Default mode suitable for most applications with lower latency
Max I/O: Higher aggregate throughput and operations per second for large-scale workloads
Automatic Selection: Defaults to General Purpose when not specified

Throughput Modes¶

Bursting: Scales throughput with file system size, includes burst credits
Provisioned: Dedicated throughput independent of storage amount
Cost Optimization: Bursting mode recommended for variable workloads

EFS Integration Patterns¶

Container Integration¶

ECS Task Definitions: Access point IDs used for container volume mounting
Cross-Container Sharing: Multiple containers can share the same EFS through different access points
Persistent Storage: Application data survives container restarts and deployments
User Context: Container processes run with specified POSIX user/group identities

DataSync Integration¶

Backup Operations: EFS policies enable DataSync for automated backup workflows
Migration Support: Cross-region and cross-account data transfer capabilities
Incremental Sync: Efficient data synchronization for disaster recovery scenarios

Encryption and Key Management¶

KMS Integration¶

*Foundation Keys**: Uses organizational KMS keys for consistent encryption standards
*Project Keys**: Option for project-specific keys when foundation key is not used
*Key Rotation**: Supports automatic key rotation policies when configured
*Cross-Account Access**: Encryption keys accessible across organizational accounts

Data Protection¶

Encryption at Rest: All data encrypted when stored on EFS
Transit Encryption: Supports encryption in transit for mount operations
Backup Encryption: Automated backups inherit file system encryption settings

Notes

The set_usage method from the abstract class should not be used in this builder.
EFS base name must be set via set_efs_base_name method before building
Security groups must be pre-created following organizational naming patterns (own-efs-sg)
Access point names become part of SSM parameter keys and should follow naming conventions
KMS keys must exist before EFS creation when encryption is enabled
Performance mode cannot be changed after file system creation
Access points provide application isolation but share the same underlying file system
Cross-account parameter sharing requires proper IAM permissions in both accounts
UID/GID values should match container or EC2 instance user configurations for proper permissions
File system policies allow DataSync integration but can be customized for specific security requirements