A few foundational definitions before diving into architecture and history.

Kubernetes is a system for automatically deploying, scaling, and managing containerized applications across a cluster of machines. Kubernetes itself does not actually create or run containers directly — it delegates that job to a separate piece of software running on each machine (called a node) known as a container runtime. Kubernetes was deliberately designed to not care which specific container runtime a node uses, as long as that runtime can perform a standard set of operations: create a container, start it, stop it, report its status, and so on.

Docker was the original, dominant container runtime in the early years of the container ecosystem, and Kubernetes’s very first releases were built with tight, direct integration to Docker specifically, before the idea of supporting multiple interchangeable runtimes even existed as a formal design goal. As Kubernetes matured and other container runtimes emerged, the project introduced a standardized interface — the Container Runtime Interface (CRI) — so that any runtime implementing this interface could work with Kubernetes without Kubernetes needing custom, hardcoded logic for each one individually.

Here’s the core problem this guide is about: Docker, as a piece of software, was never built to natively speak this new CRI interface — it predates CRI’s existence and has its own separate, independent API. Dockershim was the piece of adapter code Kubernetes maintained specifically to translate between the standardized CRI calls Kubernetes made internally, and the different, Docker-specific API calls that Docker Engine actually understood. Dockershim deprecation refers to Kubernetes’s decision, announced well in advance and finalized in the Kubernetes 1.24 release, to remove this translator entirely from its own codebase.

This is the single most important, and most commonly misunderstood, fact about the entire topic: dockershim deprecation did not mean Docker itself was deprecated, broken, or removed. Docker continued to work exactly as it always had for running standalone containers, for local development, and for Docker Compose workflows. What changed was specifically, narrowly, Kubernetes’s own built-in bridge code that let a Kubernetes cluster use Docker Engine directly as its container runtime.

It’s worth being explicit, too, about the difference between “deprecation” and “removal” as Kubernetes uses those terms, since the two are often conflated in casual conversation but describe genuinely different moments in a formal process. Deprecation is an announcement: the project signals that a feature is expected to be removed at a specific point in the future, giving users advance warning and time to plan, while the feature itself continues to function normally in the meantime. Removal is the later, separate event where the feature actually stops being available. Dockershim’s deprecation was announced roughly a year before its actual removal in Kubernetes 1.24 — meaning for that entire year, dockershim kept working exactly as before, while the community had a clear, publicly documented deadline to plan around rather than being caught by surprise.

To understand why dockershim was ever created, and why it was eventually removed, it helps to understand the problem CRI was designed to solve in the first place.

In Kubernetes’s earliest years, its code that talked to a container runtime was written specifically, directly, and exclusively for Docker. There was no abstraction layer — Kubernetes’s core scheduling and orchestration logic was tightly interwoven with Docker-specific API calls. This worked well while Docker was effectively the only serious container runtime in widespread use, but it created a real problem as alternative runtimes — like rkt (an early, now-retired competitor) and later containerd and CRI-O — began to emerge, each offering genuine advantages for certain use cases.

Every time Kubernetes wanted to support a new runtime, its maintainers had to write and maintain entirely separate, deeply embedded integration code specific to that runtime, directly inside Kubernetes’s own core codebase. This was expensive to maintain, made the core codebase harder to reason about, and effectively meant runtime maintainers had to convince Kubernetes’s own maintainers to accept and maintain runtime-specific code on their behalf — a significant coordination burden for both sides.

This is precisely the gap dockershim was built to paper over during the transition. When CRI was introduced, Docker Engine itself did not implement CRI natively — it had its own separate API, built years earlier for entirely different purposes, and there was no realistic expectation that Docker’s own maintainers (a separate company, with their own priorities) would immediately rewrite Docker Engine to natively speak this new Kubernetes-specific interface. So, rather than break compatibility with the most widely used container runtime in the ecosystem overnight, Kubernetes’s own maintainers wrote and maintained dockershim themselves, as a temporary, Kubernetes-side bridge specifically so existing Docker-based clusters could keep working uninterrupted while CRI matured and while genuinely CRI-native runtimes became production-ready alternatives.

It’s worth appreciating just how large a share of the ecosystem dockershim needed to support during this transitional period. At the time CRI was introduced, Docker was not simply one option among several — it was, by a wide margin, the default assumption most Kubernetes users, tutorials, and third-party tooling had already built around. Removing Docker support immediately, the moment CRI was defined, would have broken a very large number of existing production clusters overnight, with no reasonable migration path available yet, since containerd and CRI-O were not yet mature, independently packaged, CRI-native options at that early stage. Dockershim’s real value, in this light, was buying the ecosystem time — letting CRI-native runtimes mature into genuinely production-ready alternatives while the overwhelming majority of existing Docker-based clusters kept working exactly as they always had, with no forced, premature migration.

A detail that surprises many people learning this topic for the first time: Docker Engine itself is not one single monolithic program — it’s built from several layered components, and one of those components is the very same technology many Docker alternatives use directly.

When you run a container with the Docker CLI, the request passes through several distinct layers before a container actually starts. The Docker CLI is what a user types commands into. It talks to the Docker daemon (dockerd), a long-running background process that handles image management, networking, volumes, and the overall Docker API surface most tools integrate with. The Docker daemon, in turn, delegates the actual work of running containers to containerd, a separate, more focused container runtime that Docker itself originally created and later donated to the Cloud Native Computing Foundation as its own independent open-source project. Containerd itself delegates the lowest-level work — actually creating the isolated process using kernel features like namespaces and cgroups — to runc, a minimal, low-level tool implementing the Open Container Initiative (OCI) runtime specification.

flowchart TB
    CLI["Docker CLI"] --> D["Docker Daemon (dockerd)"]
    D --> C["containerd"]
    C --> R["runc"]
    R --> K["Linux Kernel\n(namespaces, cgroups)"]
    style D fill:#111,stroke:#dc2626,color:#fff
    

This layered architecture is central to understanding why the dockershim deprecation turned out to be far less disruptive in practice than its announcement initially made it sound. Because containerd already sat directly underneath Docker, doing the actual container-running work, switching a Kubernetes cluster’s configured runtime from “Docker” to “containerd directly” did not require replacing some entirely foreign, unfamiliar piece of technology — for most clusters, it meant removing one layer (Docker Engine and dockershim together) and letting Kubernetes talk to a component, containerd, that had effectively been doing the real work all along, just one hop further down the chain.

It’s worth pausing on why Docker was ever built this way in the first place, since it explains a great deal about the ecosystem’s later direction. In Docker’s earlier years, before containerd existed as a distinct, independent project, Docker Engine handled the entire chain — image management, networking, and low-level container execution — as one more tightly bundled piece of software. As container adoption grew well beyond Docker’s own original use cases, Docker’s own engineers recognized that other projects, including but not limited to Kubernetes, could benefit from reusing just the lower-level, execution-focused part of Docker’s own stack, without needing everything else Docker Engine bundled alongside it. Splitting that execution layer out into containerd, and subsequently donating it to the Cloud Native Computing Foundation as an independently governed project, was Docker’s own deliberate step toward exactly the kind of modular, interchangeable runtime ecosystem that CRI was later designed to standardize access to.

A precise look at where dockershim physically lived and what it was responsible for.

Dockershim lived inside the kubelet — the Kubernetes agent that runs on every node in a cluster and is directly responsible for actually starting, stopping, and monitoring the containers that make up the Pods scheduled onto that node. Before dockershim’s removal, when the kubelet needed to perform a container operation, it made that request internally using CRI’s standard, gRPC-based method calls, exactly as it would for any CRI-compliant runtime. Dockershim intercepted those calls, on the kubelet’s own side, translated them into the equivalent Docker Engine API calls, sent those to the Docker daemon, and then translated Docker’s responses back into the shape CRI expected, handing that back to the rest of the kubelet’s logic.

• CRI shim — the general term for any adapter component that lets a non-CRI-native runtime be used as if it were CRI-compliant; dockershim was the specific shim built for Docker.
• Kubelet — the node-level Kubernetes agent that dockershim was embedded directly inside of, rather than existing as a separate, standalone process.
• CRI (Container Runtime Interface) — the standardized gRPC API contract the kubelet expects any runtime (or shim acting on a runtime’s behalf) to implement.
• Docker Engine API — Docker’s own, separate, pre-existing API that dockershim translated CRI calls into on the other side of the bridge.

Zooming into the actual mechanics of the translation process, to see precisely why maintaining this bridge was a genuinely heavy, ongoing engineering burden.

Every CRI request the kubelet made was defined in terms of concepts CRI itself introduced — pods, sandboxes, standardized container states — while Docker’s own API was defined in terms of Docker’s own, older concepts, which didn’t always map cleanly one-to-one. Dockershim’s internal job was to sit in the middle of this mismatch and paper over every one of these conceptual gaps, consistently, correctly, for every single call, release after release.

This translation had to happen correctly for every operation type CRI defines, and had to keep working correctly as both Kubernetes’s own CRI specification and Docker’s own independent API continued to evolve over time, on their own separate release schedules, maintained by two entirely different engineering organizations with no obligation to coordinate their changes with each other. That ongoing, dual-sided maintenance burden — keeping a translation layer correct between two independently moving targets — is the central engineering reality that eventually made the case for removing dockershim rather than continuing to maintain it indefinitely.

A good way to appreciate the scale of this burden is to consider what happens whenever either side of the translation changes independently. If a new Kubernetes release introduced a new CRI capability — say, a more precise way of reporting container resource usage — dockershim’s maintainers had to figure out whether, and how, that new capability could be expressed using Docker’s existing, unrelated API, which was never designed with that specific CRI feature in mind. Sometimes the mapping was straightforward; sometimes it required an awkward workaround, or wasn’t fully achievable at all, producing a subtle compatibility gap between what CRI formally promised and what a Docker-backed cluster could actually deliver. Symmetrically, if Docker’s own API changed in a new release — deprecating an old field, restructuring how a particular response was shaped — dockershim’s translation logic for that specific area had to be updated to match, or risk silently breaking. Neither Kubernetes’s release cycle nor Docker’s release cycle was designed around the other’s needs, which meant dockershim’s maintainers were perpetually reconciling two independently moving targets, indefinitely, for as long as the shim continued to exist.

A side-by-side walkthrough of what happens when Kubernetes schedules a new Pod onto a node, comparing the dockershim-based path to the direct, post-deprecation path.

Notice the structural difference this table makes visible: in the dockershim path, a request from the kubelet actually passed through two separate containerd-adjacent layers on its way to a container actually starting — first Kubernetes’s own dockershim translation, then Docker Engine’s internal delegation to its own bundled containerd. In the post-deprecation path, that request goes directly to containerd in a single hop, with one fewer translation layer for the request (and every response) to pass through.

flowchart LR
    subgraph Before["Before: With Dockershim"]
      K1["Kubelet"] --> DS["Dockershim\n(CRI translation)"]
      DS --> DD["Docker Daemon"]
      DD --> C1["containerd"]
      C1 --> R1["runc"]
    end
    subgraph After["After: Direct CRI"]
      K2["Kubelet"] --> C2["containerd\n(native CRI)"]
      C2 --> R2["runc"]
    end
    style DS fill:#111,stroke:#dc2626,color:#fff
    

This is also, practically speaking, why most workloads themselves noticed essentially no difference after migration: from an application container’s own point of view, it is still ultimately started by runc, still isolated by the same kernel namespaces and cgroups, and still scheduled by the same Kubernetes control plane. The change was almost entirely confined to the node-level plumbing connecting the kubelet to the runtime — not to how the application itself actually ran once started.

It’s also worth tracing what happened to that extra “pause” container concept discussed in the previous chapter, since it’s a detail that occasionally surprised operators inspecting their nodes closely during migration. Under dockershim, each Pod’s sandbox was represented as an actual, visible Docker container — the pause container — sitting alongside the Pod’s real application containers when inspected with Docker’s own tooling. Under a direct CRI-native runtime like containerd, the equivalent sandbox concept is typically represented more natively within the runtime’s own internal model, without necessarily appearing as a separate, independently listed container in quite the same way Docker’s own tooling used to show it. This is a cosmetic, tooling-visible difference rather than a functional one — the underlying purpose (holding open a shared network namespace for the Pod’s lifetime) remains identical — but it’s exactly the kind of small, easy-to-notice change that prompted operators to double-check they hadn’t broken something, when in fact everything was working precisely as intended.

The Kubernetes project publicly documented several specific, concrete reasons behind this decision — it wasn’t an arbitrary or purely political choice.

It’s also worth directly addressing a common misconception from when this announcement first circulated: the deprecation was not a statement that Docker Engine was somehow inferior, insecure, or unreliable as a piece of software. It was a statement, specific to the Kubernetes project’s own architecture and maintenance priorities, that maintaining a Kubernetes-side translation layer for one specific, non-CRI-native runtime was no longer the sustainable long-term approach, now that genuinely CRI-native alternatives — chief among them containerd, which Docker itself had already built and donated to the ecosystem — were mature and production-ready.

There is also a useful open-source governance lesson embedded in this story, worth calling out on its own. Kubernetes and Docker, despite both being central, closely associated pillars of the same broader container ecosystem, are governed by entirely separate organizations, with separate roadmaps, separate priorities, and separate release cadences. For years, dockershim quietly papered over the fact that these two separately governed projects had no formal obligation to keep their respective APIs in sync with each other. The deprecation decision was, in part, an acknowledgment that relying indefinitely on one open-source project’s maintainers to keep bridging gaps introduced by another, separately governed project’s own independent evolution was structurally fragile — a healthier long-term architecture put that bridging responsibility on whichever party controlled the runtime side of the equation, aligning ownership with capability rather than leaving it with a third party that had no direct control over either side of what it was translating between.

The practical steps organizations running Docker-based Kubernetes clusters actually needed to take.

A closer look at the two runtimes that absorbed the vast majority of clusters migrating off dockershim.

Both runtimes speak CRI natively, meaning neither requires any Kubernetes-maintained translation layer at all — the kubelet talks to them directly, using CRI’s standard gRPC interface, exactly as CRI’s designers originally intended every runtime to eventually support. Choosing between them is typically driven less by raw capability differences, since both are mature, production-proven options, and more by an organization’s existing ecosystem — for example, which runtime their chosen Kubernetes distribution or managed cloud offering ships and supports by default.

Beyond containerd and CRI-O, it’s worth knowing that the CRI-native runtime landscape has continued to broaden further, particularly around specialized isolation requirements. Runtimes like gVisor and Kata Containers, for example, implement the same CRI interface while providing meaningfully stronger workload isolation than a standard runc-based container — gVisor by intercepting and mediating system calls through its own user-space kernel, and Kata Containers by running each container inside its own lightweight, dedicated virtual machine rather than sharing the host kernel directly. Neither of these approaches existed as practical, CRI-compliant options for most organizations during Docker’s early dominance of the ecosystem, and their emergence is itself a direct product of the same architectural shift dockershim’s deprecation reinforced: once CRI became the universal contract every runtime needed to speak, the door opened for genuinely novel runtime implementations, optimized for very different trade-offs, to plug into Kubernetes on equal footing with more traditional options.

An honest look at what this architectural change actually cost, and what it genuinely improved, for the Kubernetes ecosystem.

On balance, this trade-off is widely regarded within the Kubernetes community as a healthy, necessary piece of technical debt repayment — a temporary bridge, explicitly announced as temporary from very early on, being retired once its purpose (giving genuinely CRI-native runtimes time to mature) had been fully served. The disruption was real but time-bounded and well-telegraphed; the maintenance savings and architectural cleanliness it produced are ongoing and permanent.

It’s worth framing this trade-off using a distinction familiar from broader software engineering practice: the difference between a one-time migration cost and a recurring maintenance cost. Every organization that migrated off dockershim paid a bounded, one-time cost — the audit, the testing, the tooling updates described earlier in this guide — that, once complete, was simply finished. Kubernetes’s own maintainers, by contrast, had been paying dockershim’s maintenance cost repeatedly, release after release, for as long as the shim continued to exist, with no natural endpoint in sight until the deprecation decision created one deliberately. Viewed this way, the decision effectively converted an unbounded, indefinitely recurring cost borne centrally by the Kubernetes project into a bounded, one-time cost distributed across the many individual organizations still relying on the shim — a trade generally considered favorable for the ecosystem’s long-term health, even though it understandably felt like an unwelcome, unplanned expense to any individual team that had to absorb its share of that one-time cost on a timeline not of their own choosing.

While primarily an architectural and maintenance story, this change carries a few genuine security implications worth understanding.

Removing an entire translation layer, by definition, removes whatever bugs — including potential security-relevant ones — that layer could have introduced or mishandled. A translation layer sitting between two independently evolving APIs is inherently a place where subtle mismatches can occur, and while dockershim was a mature, well-tested piece of code by the time of its removal, fewer moving parts in the critical path between the kubelet and the running container is generally a security improvement in its own right, independent of any specific vulnerability history.

It’s also worth noting that neither the removal of dockershim, nor the choice between containerd and CRI-O, meaningfully changes the deeper security fundamentals covered elsewhere in container security discussions — namespaces, cgroups, mandatory access control systems like AppArmor or SELinux, and seccomp filtering all continue to operate at the kernel level, beneath whichever specific runtime is in use, largely unaffected by this particular architectural change. Dockershim’s removal changed how the kubelet talks to a runtime; it did not change how that runtime, in turn, talks to the kernel to actually isolate a container.

One area genuinely worth a closer look during migration, however, is the socket or API endpoint a node’s various pieces of tooling authenticate against and are granted access to. Docker’s own socket, historically, was a frequent target of security hardening discussions precisely because anything with access to it effectively had broad control over every container on that host. Migrating to a different runtime doesn’t eliminate this category of risk — containerd and CRI-O expose their own equivalent sockets and APIs, which carry comparably significant privilege if left insufficiently restricted. The practical security task during migration is less “is the new runtime inherently safer” and more “have all the same access-control and least-privilege principles previously applied to the Docker socket been correctly reapplied to whichever new socket or API surface replaced it” — a migration is a natural, useful checkpoint to revisit and re-verify this kind of access policy, rather than simply assuming prior hardening carried over automatically.

Operators accustomed to Docker-specific tooling and troubleshooting habits needed to adjust some of their day-to-day debugging workflows after migration.

Commands and tools that directly relied on the Docker CLI or the Docker Engine API to inspect running containers on a Kubernetes node — for example, running docker ps directly on a node to see what’s running — stopped reflecting reality once that node’s runtime was no longer Docker, since there was no longer a Docker daemon present on the node to query in the first place. Operators needed to adopt the equivalent tooling for whichever new runtime was in place — crictl, a CRI-focused command-line tool, is the direct replacement most commonly used across both containerd and CRI-O, offering similar inspection capabilities without being tied to any single runtime’s proprietary API.

At the level Kubernetes users interact with most often — kubectl logs, kubectl exec, kubectl describe pod — essentially nothing changed at all, since these commands operate through the Kubernetes API server and kubelet, not by talking to the underlying runtime’s own tooling directly. The observability impact of this migration was overwhelmingly concentrated in lower-level, node-focused debugging workflows, not in everyday application-level Kubernetes usage.

Third-party observability and security platforms integrated with container infrastructure also had their own share of adjustment to make. Products that shipped a Docker-specific data collection agent — one that, for instance, watched the Docker daemon’s own event stream to detect container starts and stops — needed a CRI-compatible or containerd-specific equivalent to keep functioning on migrated nodes. Most established observability vendors had already anticipated this shift well ahead of the Kubernetes 1.24 release, given how publicly telegraphed the deprecation was, and released CRI-compatible or containerd-native collection agents in good time; but organizations running older versions of third-party tooling, or homegrown collectors built in-house without anyone tracking this specific upstream change, occasionally discovered gaps in their own observability coverage only after a cluster had already been migrated — a strong practical argument for including third-party tooling explicitly in the pre-migration dependency audit described earlier in this guide, rather than assuming vendor tooling would simply keep working unattended.

Lessons worth carrying forward, both about this specific migration and about managing dependencies on Kubernetes’s own evolving internals more broadly.

Practical guidance drawn from how organizations successfully navigated this migration in real production Kubernetes environments.

This deprecation was one of the most widely discussed changes in recent Kubernetes history, precisely because it touched such a large share of existing production clusters.

The public communication effort around this specific deprecation is also frequently cited, within the Kubernetes community itself, as a reference example for how a large, widely used open-source project can retire a significant piece of legacy infrastructure responsibly. The combination of an early, clearly dated announcement; detailed, freely available migration documentation; direct outreach and default-behavior changes from major managed platform providers; and a genuinely less disruptive technical reality than the initial announcement’s headline suggested, together meant that by the time Kubernetes 1.24 actually shipped, a substantial share of the ecosystem had already completed its migration calmly, well ahead of any forced deadline — turning what could have been portrayed as an abrupt, disruptive breaking change into a comparatively smooth, well-managed architectural transition.

No. It only means Kubernetes no longer includes a built-in translation layer for using Docker Engine directly as a cluster’s container runtime. Docker itself — the CLI, the daemon, Docker Compose, Docker Desktop — remains fully functional for local development, image building, and standalone container use, completely independent of this Kubernetes-specific change.

Yes. Docker builds standard, OCI-compliant container images, and both containerd and CRI-O can run OCI-compliant images without any issue, regardless of what tool built them. This is one of the most common points of confusion — the image format itself was never tied to dockershim at all.

The community-maintained cri-dockerd project, maintained by Mirantis outside of the core Kubernetes codebase, provides a standalone, genuinely CRI-compliant shim for Docker Engine, letting organizations with a specific reason to keep using Docker Engine on their nodes continue to do so, just via a differently maintained bridge than the one Kubernetes used to bundle internally.

Dockershim was removed from the Kubernetes codebase starting with the Kubernetes 1.24 release, following a deprecation announcement made roughly a year earlier to give the ecosystem time to plan and execute migrations.

No. This change is entirely confined to node-level infrastructure configuration — which container runtime the kubelet talks to. It has no effect on Pod specifications, Deployments, Services, or any other Kubernetes API object an application team would normally write or maintain.

Checking the container runtime reported for each node (available through standard Kubernetes node-inspection commands, which report the runtime and its version directly) reveals immediately whether a cluster is running Docker, containerd, CRI-O, or another CRI-compliant runtime — clusters already on containerd or CRI-O were never depending on dockershim in the first place and require no migration.

No. Docker Swarm is Docker’s own separate, built-in clustering and orchestration system, entirely independent of Kubernetes. Dockershim existed specifically as a bridge between Kubernetes’s kubelet and Docker Engine; Swarm doesn’t use the kubelet or CRI at all, so this deprecation has no bearing on Swarm-based deployments whatsoever.

Containerd is a native CRI implementation, maintained specifically with Kubernetes compatibility as one of its core goals, and it’s an independently governed CNCF project used by a large share of the Kubernetes ecosystem. The structural problem that led to dockershim’s removal — a Kubernetes-maintained translation layer bridging to a non-CRI-native external API — simply doesn’t apply to containerd, since it speaks CRI directly rather than requiring Kubernetes’s own maintainers to translate on its behalf.