Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Decouple container base image version from host OS version for process-isolated containers

Open
#652 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
30/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Active
Tech stack
docker

Research direction

Start by reviewing the process-isolation version check at the containerd/HCS entry point, then examine how ctr, Docker, and Kubernetes expose image metadata and choose isolation modes. The concrete near-term outcome is a graceful Hyper-V fallback with a clear log or event and a queryable compatibility contract; the shim-layer proposal is explicitly research-only.

Written by the indexing model from the issue text.

Description

enhancement triage

Is your feature request related to a problem? Please describe.

Process-isolated Windows Server containers require the container base image's kernel-mode-facing API version to match the host OS build (or fall within the narrow compatibility window Microsoft publishes per release). Linux containers have no equivalent constraint — a single host kernel runs userland from effectively any distro/version, because the container never depends on kernel-mode API/ABI stability beyond the (very stable, versioned) syscall interface.

This creates real, recurring friction:

  1. Fleets can't run a single, stable base image across a rolling host OS upgrade — teams must rebuild and redeploy images in lockstep with host patching, or the container fails to start outright with a version-mismatch error rather than degrading gracefully.
  2. Multi-tenant or shared CI infrastructure that needs to run images built against different Windows Server versions on the same host pool today must either maintain separate node pools per version or fall back to Hyper-V isolation everywhere "just in case," which erases the density/startup-time benefit of process isolation for workloads that didn't actually need version flexibility.
  3. There's no image-declared or runtime-queryable "minimum host version this image needs" contract analogous to a Linux image's declared syscall/glibc requirements — the failure mode when versions don't line up is opaque (an HCS error at container start) rather than something tooling can check and act on ahead of time.

Describe the solution you'd like

Proposing a phased in solution:

  • Near-term — graceful automatic fallback: when containerd/HCS detects a host/image version mismatch that process isolation can't support, automatically and transparently start the container under Hyper-V isolation instead of failing, with a clear log/event indicating why. This doesn't close the performance gap but converts a hard failure into a degraded-but-working path, which is the bigger operational pain point today.
  • Near-term — queryable compatibility contract: let an image declare (via manifest metadata) the minimum/maximum host build it supports for process isolation, and let ctr/docker/Kubernetes tooling query this before scheduling, so orchestrators can route a container to the right isolation mode or node pool proactively instead of discovering the mismatch at start time.
  • Medium-term — widen the supported compatibility window: extend the N-1/N-2 version compatibility Microsoft has incrementally supported in past releases (e.g., WS2022's broadened compatibility for certain image/host combinations) further, and publish it as a stable, documented support matrix rather than per-release release-note discovery.
  • Long-term — investigate a translation/shim layer: research whether a stable, versioned subset of the kernel-mode-facing API surface that containers actually exercise (as opposed to the full NT API) could be shimmed/versioned independently, similar in spirit to how the Linux syscall ABI is decoupled from glibc/userland versions. This is explicitly a research ask, not a committed feature — flagging it so it's tracked, not expecting it in a near-term release.

Describe alternatives you've considered

  • Always use Hyper-V isolation to sidestep version coupling entirely: works today and is the standard current recommendation, but reintroduces per-container VM overhead for every workload, including the majority that never actually hit a version mismatch — this ticket is specifically about not needing that trade-off universally.
  • Pin all images and hosts to the same Windows Server version fleet-wide: operationally works for smaller, homogeneous fleets, but doesn't scale to organizations with staggered patch cycles, third-party images, or long-lived images that outlive a given host OS's support window.
  • Rebuild/redeploy images on every host OS upgrade: the current de facto workaround; costs CI time and creates a hard coupling between host patch cadence and application release cadence that most teams don't want.

Additional context

Filed as the fourth and hardest ticket in this feature/performance parity-with-Linux-containers effort, following #[syscall/capability filtering https://github.com/microsoft/Windows-Containers/issues/649], #[PID namespace isolation https://github.com/microsoft/Windows-Containers/issues/650], and #[CimFS/overlay performance https://github.com/microsoft/Windows-Containers/issues/651]. Unlike those three, this one is explicit that a full fix likely requires changes below the container runtime layer (in the NT kernel/user-mode contract itself), so the ask here is deliberately staged — graceful degradation and a queryable compatibility contract are the concrete, near-term-actionable parts; the shim-layer idea is filed for visibility/research tracking, not as a committed ask.

Dominant language
PowerShell
Stars
551
Forks
76
PR merge metrics
No merged PRs in 30d

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from microsoft/Windows-Containers

All issues in microsoft/Windows-Containers

Similar issues

More DevOps issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.