Migrating an AWS S3 File Gateway Without Breaking User Drive Mappings

Replacing an AWS S3 File Gateway looks simple until the gateway also provides a shared SMB drive to a fleet of Windows desktops. The storage backend may be S3, but users still depend on a stable drive letter, directory-based authentication, local cache behavior, and a predictable cutover.

The migration pattern here keeps the S3 data intact, replaces the gateway appliance, and uses AWS Systems Manager to remap Windows drives.

Terms used here

Term	Meaning
S3 File Gateway	AWS Storage Gateway mode that exposes S3 objects through file protocols such as SMB.
SMB share	A Windows-compatible network file share. Users see it as a mapped drive.
Cache disk	Local disk used by the gateway to keep recently accessed or pending file data close to users.
Dirty cache	Local writes that have not fully reached S3 yet. A zero dirty-cache metric is important before cutover.
SSM State Manager	AWS Systems Manager feature that applies a desired script or association to managed instances.
Drive mapping	The Windows setting that connects a drive letter, such as Z:, to a network share.

The migration goal

The environment had four requirements:

• Replace a legacy gateway before its support deadline
• Keep the existing S3 objects and SMB share name
• Preserve the user-facing drive letter
• Avoid manually reconfiguring every Windows desktop

The final architecture was:

Windows desktops
      |
      | SMB with directory-based authentication
      v
New S3 File Gateway
      |
      | Private VPC endpoints
      v
Existing S3 bucket

The gateway instance and cache were replaced. The S3 bucket remained the source of truth. File Gateway maps files to S3 objects and uploads file changes to S3 asynchronously.^[1]

Protect the rollback path first

Before changing the old gateway, collect enough evidence to recover or explain the state later:

• Export the gateway, SMB, and file-share configuration
• Disable delete-on-termination for the attached volumes
• Take snapshots of the system and cache volumes
• Wait for every snapshot to complete
• Confirm that CachePercentDirty has reached zero

The dirty-cache check matters more than a simple “running” status. A clean cache means there are no pending local writes that still need to reach S3. AWS explicitly requires CachePercentDirty to reach zero before stopping a gateway host when unpersisted cache data could otherwise be lost.^[2]

Why reusing the old disks was abandoned

An early attempt attached the legacy system and cache disks to a replacement EC2 instance. The network path looked healthy: the expected TCP ports accepted connections. The appliance was not healthy, however:

• The activation endpoint returned an empty HTTP response
• The browser showed ERR_EMPTY_RESPONSE
• SSH exposed a server banner but stalled during key exchange

This is an important diagnostic boundary:

Open TCP port != healthy appliance service

Continuing to debug a legacy boot disk would have increased the outage window without improving the data recovery position. Because the durable files were already in S3 and the dirty cache was zero, a clean gateway deployment was the lower-risk path.

Build a clean gateway against the same S3 data

The successful approach used a current Storage Gateway image and new local disks:

1. Deploy a new S3 File Gateway.
2. Connect it through the required public or VPC-hosted service endpoint.
3. Allocate new cache storage.
4. Join the existing directory service.
5. Create an SMB share backed by the existing S3 location.
6. Reapply logging, alarms, IAM, security groups, and instance protections.

The local cache does not need to be copied to preserve S3 objects. The new gateway rebuilds its cache as files are accessed.

Automate the Windows drive migration with SSM

AWS Systems Manager commands run as SYSTEM, while a mapped network drive belongs to a user session. A command that runs net use only as SYSTEM may succeed without making the drive visible to the signed-in user.

The reliable pattern is:

1. Use SSM State Manager to install a PowerShell script on each managed Windows node.
2. Register the script in an HKLM Run entry.
3. Execute the actual mapping when the user signs in.
4. Write logs to the user’s %LOCALAPPDATA%, not to a protected system directory.

The login script should be conservative:

• If the drive letter is unused, map the new share.
• If it points to the legacy share, replace it.
• If it is a local disk or an unrelated network share, do nothing.

This prevents a migration script from overwriting an unrelated user configuration.

Treat offline desktops as a normal state

Many desktop nodes will be stopped when a State Manager association runs. SSM reports those targets as Undeliverable, which is expected for offline instances.

Use a scheduled association so that configuration is retried after a desktop starts. State Manager attempts to apply an association when a managed node comes online after missing a scheduled run.^[3] The user communication should include:

• A realistic propagation window based on the association interval
• The expected drive label and path
• A sign-out and sign-in fallback
• A request for the execution time, screenshot, and local log if the mapping still fails

This turns an infrastructure rollout into an operationally supportable user change.

Validate the complete path

Do not stop after the gateway reports RUNNING. Validate from a normal user desktop:

echo gateway-test > E:\gateway-test.txt
type E:\gateway-test.txt
del E:\gateway-test.txt

Also verify:

• The expected drive appears in File Explorer
• Existing folders are visible
• Create, read, update, and delete operations work
• The SMB session points to the new gateway
• Gateway and file-share logs are receiving events
• Availability and dirty-cache alarms are healthy

Retire the old stack in dependency order

After the new path is verified, remove the old resources in a controlled sequence:

1. Delete the old SMB file share without forcing deletion.
2. Delete the old gateway.
3. Terminate the old EC2 instance.
4. Inventory unattached EBS volumes.
5. Delete only volumes that are confirmed unused and have the required snapshots.

Keep the new gateway’s active system and cache volumes explicitly excluded from cleanup.

Conditions for a safe migration

• S3 is the durable data layer; gateway cache is replaceable when dirty writes are zero.
• Network reachability is not application health.
• A clean appliance replacement can be safer than reviving an old boot disk.
• User-visible drive mappings must be created in the user session.
• SSM scheduled associations handle intermittent desktop availability better than a one-time command.
• Define monitoring, user communication, and cleanup order before the cutover.

References

[1] Amazon Web Services. “How Amazon S3 File Gateway works.” AWS Storage Gateway User Guide.

[2] Amazon Web Services. “File Gateway setup requirements.” AWS Storage Gateway User Guide.

[3] Amazon Web Services. “Understanding how State Manager works.” AWS Systems Manager User Guide.