Map network share into windows docker container (WCOW)

by

Summary

We observed a critical regression in Windows Container (WCOW) volume mounting behavior when upgrading from Windows Server 2022 to Windows Server 2025. Specifically, the ability to bind-mount mapped network drives (e.g., M:\) into containers running in process isolation failed. While the legacy behavior allowed the Docker Engine (running as LocalSystem) to resolve drive letters mapped by a user session, the new OS version treats these drive letters as non-existent to the host service, even when running the daemon manually.

Root Cause

The failure is rooted in the Session Isolation and the way the Host Compute Service (HCS) interacts with the Windows Object Manager:

  • Drive Letter Scope: Mapped network drives (like M:) are user-session specific artifacts. They exist within the registry hive of the user who mapped them, not the global system scope.
  • Service Identity: The Docker Engine runs as the LocalSystem account. LocalSystem does not inherit the drive mappings created by a logged-in Administrator or Service Account.
  • HCS Validation Tightening: In Windows Server 2025, the underlying Host Compute Service (HCS) has stricter validation for bind-mount source paths. It no longer attempts to “guess” or resolve paths through user-session redirection that worked via legacy loopholes in Server 2022.
  • Namespace Separation: When dockerd is run manually, it still operates within a different session context than the user who mapped the M: drive, causing the The system cannot find the path specified error during the HCS compute system creation phase.

Why This Happens in Real Systems

In enterprise environments, engineers often rely on legacy automation that assumes a “global” view of the file system. This happens because:

  • Implicit Trust in Drive Letters: Developers treat M:\ as a physical path rather than a symbolic link to a network resource tied to a specific security token.
  • OS Evolution: Security hardening in newer Windows kernels (like Server 2025) moves toward Zero Trust for the host file system, closing “convenience” gaps that allowed services to access user-mapped resources.
  • Abstraction Leaks: The Docker CLI abstracts the complexity of the HCS, hiding the fact that the engine is a service and not the current interactive user.

Real-World Impact

  • Deployment Blockers: CI/CD pipelines or legacy batch jobs relying on shared storage via drive letters break immediately upon OS upgrades.
  • Operational Overhead: Engineers are forced to refactor complex deployment scripts to replace drive letters with UNC paths (\\server\share).
  • Security Risks: Attempting to fix this by running Docker/Services as a specific user can lead to privilege escalation risks or “brittle” configurations where containers fail if a user logs out.

Example or Code (if necessary and relevant)

The following demonstrates the failed command versus the required architectural correction.

# FAILS on Server 2025: Drive letters are invisible to the Docker Service
docker run --rm -v M:/.c:C:/.c mcr.microsoft.com/windows/server:ltsc2025 cmd /c dir C:\.c

# WORKS: Use absolute UNC paths to bypass session-specific drive mappings
docker run --rm -v \\fileserver\share\.c:C:\.c mcr.microsoft.com/windows/server:ltsc2025 cmd /c dir C:\.c

How Senior Engineers Fix It

A senior engineer avoids “band-aid” fixes (like mapping drives for the System account) and focuses on infrastructure-as-code robustness:

  • Standardize on UNC Paths: Eliminate all reliance on drive letters in container orchestration. Always use \\server\share\path in volume specifications.
  • Storage Abstraction: Implement CSI (Container Storage Interface) drivers or specialized Windows storage plugins if using orchestration like Kubernetes, rather than raw host bind-mounts.
  • Service Account Hardening: If network access is required, configure the Docker Engine/HCS to use a specific Managed Service Account (MSA) that has native, non-mapped permissions to the SMB share.
  • Validation Testing: Include “Path Existence” checks in the pre-flight stage of deployment scripts to ensure the host can actually see the source before invoking the Docker daemon.

Why Juniors Miss It

  • Mental Model Error: Juniors often view the “Host” as a single, unified entity where “if I can see the M: drive in File Explorer, Docker can see it too.” They fail to distinguish between User Session context and System Service context.
  • Symptom vs. Cause: A junior might try to fix the error by changing the volume syntax (e.g., switching slashes) or reinstalling Docker, rather than investigating the Windows Object Manager and session boundaries.
  • Lack of OS Depth: They often treat Windows as a black box, similar to how they might treat a Linux container, without realizing that Windows handles filesystem namespaces and session isolation with much higher complexity.

Leave a Comment