Part 1 - The S3 Files EC2 Infrastructure Handbook Manual Configuration & Architecture

Introduction

Amazon S3 Files allows you to mount S3 buckets as standard NFS v4.1 file systems. Unlike previous FUSE-based solutions, this is a managed gateway service that provides high-performance, concurrent access across EC2, Lambda, and ECS.

This manual documents the precise steps required to engineer an S3-backed file system on Linux (Amazon Linux 2023), from initial VPC setup to final protocol verification.

Architecture: The VPC NFS Gateway

S3 Files operates through Mount Targets within your VPC. Your compute resources connect to these targets via standard NFS (Port 2049), which then orchestrates the object-to-file translation.

graph TD
    subgraph VPC
        EC2["EC2 Instance (Client)"]
        MT["S3 Files Mount Target (AZ-Specific)"]
        SG["Security Group (TCP 2049 Inbound)"]
    end
 
    subgraph AWS_Managed_Service
        S3F["S3 Files Metadata Engine"]
        IAM_FS["IAM File System Role"]
    end
 
    S3[("Amazon S3 Bucket (Versioned)")]
 
    EC2 -- "NFS v4.1" --> MT
    MT -- "Gateway Sync" --> S3F
    S3F -- "AssumeRole" --> IAM_FS
    IAM_FS -- "GetObject/PutObject" --> S3

Phase 1: Environment Preparation

Before creating the file system, you must satisfy the architectural prerequisites for the backing S3 bucket and the network environment.

1. S3 Bucket Configuration

• S3 Versioning: Mandatory. The S3 Files metadata engine uses object versions to track file system state and handle concurrent operations.
• Server-Side Encryption (SSE): Standard SSE-S3 is recommended.
• Bucket Naming: Ensure the bucket name conforms to DNS standards for high-performance naming.

2. Security Group Orchestration

You must deploy a Security Group for the Mount Targets that allows inbound traffic on the NFS port.

3. IAM Identity & Access Management

You require two distinct roles for the file system to function:

A. File System System Role

This role is assumed by the S3 Files service itself to interact with your S3 bucket.

Trust Policy: Refer to the iam module in the source repository for the precise trust hierarchy. The SourceArn check is mandatory.

Permissions Checklist:

[!IMPORTANT] KMS Nuance: If using a Customer Managed Key (CMK), you MUST include a Condition block in your policy that limits the key usage to the S3 service via kms:ViaService = "s3.REGION.amazonaws.com".

B. Compute Client Role (EC2)

Your EC2 instance requires an Instance Profile containing the AmazonS3FilesClientFullAccess managed policy.

Phase 2: File System & Client Setup

1. Create the S3 Files File System

Register the file system through the AWS CLI v2.34.26+ or the AWS Console.

[!NOTE] Transient Console Error: While the file system is in the Creating state, the AWS Console may display an "Unknown Error" in the Synchronization configuration panel. This is often transient and should clear once the status reaches available. If it persists, re-verify your IAM File System role trust policy.

2. Deploy Mount Targets

You must create a mount target in each Subnet (Availability Zone) where your EC2 instances reside.

[!IMPORTANT] AZ Alignment: Your EC2 instance must reside in a subnet that is in the same Availability Zone as at least one S3 Files mount target to ensure high-performance NFS discovery.

3. Install the NFS Helper (Amazon Linux 2023)

The mount process requires amazon_efs_utils version 3.0.x or later. Ensure your instance has reachability to Amazon Linux package mirrors (via IGW or NAT).

# Update local packages
sudo dnf update -y
 
# Install the mount helper
sudo dnf install -y amazon-efs-utils

Phase 3: Mounting & Persistence

1. Execute the Mount

Create a local directory and mount the file system using the native s3files type.

# Prepare the mount point
sudo mkdir -p /mnt/s3files
sudo chmod 755 /mnt/s3files
 
# Mount by File System ID with root-path syntax
sudo mount -t s3files fs-0123456789abcdef0:/ /mnt/s3files

2. Configure Persistence & Permissions (/etc/fstab)

To ensure the mount survives reboots and maintains non-root access, add the fstab entry and a specialized systemd permission watcher.

fstab Entry:

fs-0123456789abcdef0:/ /mnt/s3files s3files _netdev,noresvport 0 0

[!TIP] Production Note: Permission Persistence S3 Files mount roots often revert to root-only ownership. To allow ec2-user or ssm-user to access the volume without sudo after a reboot, create a systemd service to re-apply permissions:

# /etc/systemd/system/s3files-mount-perms.service
[Unit]
Description=Maintain S3 Files Persistence
After=mnt-s3files.mount
 
[Service]
Type=oneshot
ExecStart=/bin/sh -c '/bin/chmod 755 /mnt/s3files && /bin/chown ec2-user:ec2-user /mnt/s3files || true'
 
[Install]
WantedBy=multi-user.target

Phase 4: Technical Verification Checklist

Perform these steps inside the instance to confirm protocol integrity:

1. IMDSv2 Check: Ensure the instance has http_put_response_hop_limit = 2 set in its metadata options; without this, the gateway sync agent may fail to retrieve tokens.
2. Protocol Check: findmnt -T /mnt/s3files — FSTYPE must show s3files.
3. Mount Context: df -h /mnt/s3files — Verify the size is listed as 8.0E (Exabytes).
4. Write Test: echo "handbook-check" > /mnt/s3files/verify.txt.
5. S3 Consistency: aws s3 ls s3://BUCKET/verify.txt — Confirm the object appears in the bucket after a few seconds.

Phase 5: Resource Teardown (Cleanup)

To avoid orphaned costs and ENIs, follow this strict deletion sequence:

1. Unmount: sudo umount /mnt/s3files.
2. De-schedule Compute: Shut down EC2 instances using the file system.
3. Delete Mount Targets: Remove all targets across AZs.
4. Delete File System: aws s3files delete-file-system --file-system-id FS_ID. Note: The API will reject this command if any mount target remains in the deleting state. Wait for them to fully terminate.
5. Security Groups: Delete the Mount Target Security Group.

Phase 6: Common Engineering Hurdles & Troubleshooting

Even with correct configuration, S3 Files can encounter operational issues in complex VPC environments.

1. Error: File System Creation Fails (Unknown Error / Access Denied)

• Cause: Unsupported bucket encryption type (SSE-C or DSSE-KMS).
• Fix: S3 Files explicitly does not support SSE-C (customer-provided keys) or DSSE-KMS. You must configure your bucket with standard SSE-S3 (AES256) or regular SSE-KMS (aws:kms).

2. Error: mount.s3files: command not found

• Cause: The amazon-efs-utils version is below 3.0.x.
• Fix: Run yum list installed amazon-efs-utils and ensure the version is 3.x. Update via dnf install -y amazon-efs-utils.

3. Error: mount.nfs4: Connection timed out

• Cause: Security Group or Routing failure.
• Fix: Verify TCP Port 2049 is open inbound on the Mount Target SG. Note: If the mount hangs for more than 60 seconds, it is a confirmed timeout; standard latency is typically 10–30s.

4. Error: Permission Denied during mount

• Cause: IAM Role misconfiguration or missing Versioning on the bucket.
• Fix: Check the SourceArn. Nuance: Ensure the instance is using a supported kernel—the definitive filter is al2023-ami-*-kernel-*-x86_64.

5. Symptom: Files written on EC2 do not appear in S3 immediately

• Root Cause: S3 Files uses an asynchronous metadata engine for high-performance I/O.
• Verification: Wait 5–10 seconds for the EventBridge sync rule to trigger. For large batch writes, the delay may scale based on the metadata churn.

The Lambda Handbook (Part 2) continues with Access Point logic and serverless persistence.