Before plugins make sense, volumes themselves need to make sense.

Containers forget everything by default

A Docker container is built from an image, and everything a running container writes to its own filesystem lives in a thin, temporary write layer on top of that image. The moment the container is removed, that write layer is destroyed along with it. This is intentional — containers are meant to be disposable, rebuildable, and identical every time they start. But it creates an obvious problem: a database container that loses its data every time it restarts is useless. Something outside the container’s disposable layer has to hold onto the data.

Enter the volume

A Docker volume is storage that lives outside the container’s writable layer, managed by Docker itself, and can be attached to (or detached from) one or more containers. When a container writes to a path that has a volume mounted on it, that data goes into the volume instead of into the disposable container layer, so it survives container removal, container recreation, and even movement to a different host in some setups.

Why “just write to disk” isn’t enough

The simplest kind of volume, called a local volume, just stores data in a folder on the Docker host’s own disk. That works fine for a single machine running a single workload. But real infrastructure rarely stays that simple. A company might want its container data to live on a network-attached storage array, replicate across three data centers, live on a cloud provider’s managed block storage, or be encrypted by a dedicated storage appliance. Docker cannot reasonably know how to speak the private language of every storage vendor on the planet — and it shouldn’t have to. This is exactly the gap that volume plugins were built to close.

Four pieces cooperate to make external storage feel native to Docker.

The Volume Plugin Architecture is not one single component — it is a small set of cooperating parts, each with one clear job. Understanding these parts individually makes the whole system much easier to reason about later, when we talk about how a request actually travels through them.

How Docker finds a plugin’s “address”

For a plugin to be usable, Docker has to know two things about it: its name, and how to reach it. Historically, this happened through small files placed in specific directories on the host — a .spec file containing a network address, or a .json file describing how to launch the plugin, or a Unix domain socket file that the plugin process is already listening on. Docker checks these locations, in a fixed order, whenever a driver name it doesn’t already have registered is requested. Once found, Docker keeps that plugin’s connection details cached in memory so it doesn’t have to repeat the discovery search on every single volume operation.

flowchart TB
    A["docker volume create
--driver=mystorage"] --> B{"Docker Engine"}
    B --> C["Volume Subsystem
(driver registry)"]
    C -->|"driver name known?"| D{"Lookup"}
    D -->|"Yes, cached"| E["Reuse existing
plugin connection"]
    D -->|"No, unknown"| F["Plugin Discovery:
check spec / json / socket files"]
    F --> G["Connect to Plugin Process
over HTTP-over-socket"]
    E --> H["Volume Driver Plugin"]
    G --> H
    H --> I["Real Storage Backend
(SAN, cloud disk, NFS, etc.)"]
        

Two generations of plugins

Docker has shipped two different mechanisms for running plugins over the years. The original, sometimes called “legacy” or “V1” plugins, are ordinary background processes that the host’s own operating system starts and manages, listening on a Unix socket or TCP port. The newer generation, called “managed plugins” or “plugin V2,” packages the plugin itself as a special kind of container, installed and controlled with Docker’s own plugin commands, and supervised by the Docker Engine the same way it supervises containers. Managed plugins are easier to distribute, version, and enable or disable, because Docker treats the whole plugin lifecycle the same way it treats image and container lifecycles.

Underneath everything, it’s a shared vocabulary sent as small JSON messages.

Once Docker has located a plugin, the two sides communicate using a simple, fixed vocabulary of remote procedure calls, sent as small JSON messages over HTTP — usually over a Unix domain socket, which is a local, file-based communication channel rather than a network connection, though a network address is also supported. Every volume plugin, no matter which vendor wrote it or what real storage system sits behind it, must understand the same handful of “endpoints,” each named after the action it performs.

Because this vocabulary is fixed and shared, the Docker Engine never needs to know anything specific about, say, a particular cloud provider’s disk API. It only ever needs to know how to send a “Create” or “Mount” request and interpret the plugin’s JSON response. All of the vendor-specific translation work — authenticating to a cloud account, formatting a filesystem, attaching a network share — happens entirely inside the plugin, hidden from Docker’s view.

From “doesn’t exist” to “gone forever,” a volume passes through a predictable sequence of states.

A volume’s life follows a fairly strict order of events, and understanding this order clears up a lot of confusion about when data actually gets created, attached, or destroyed.

sequenceDiagram
    participant User
    participant Engine as Docker Engine
    participant Plugin as Volume Plugin
    participant Backend as Storage Backend

    User->>Engine: docker volume create
    Engine->>Plugin: VolumeDriver.Create
    Plugin->>Backend: Provision storage
    Backend-->>Plugin: Storage ready
    Plugin-->>Engine: OK

    User->>Engine: docker run (uses volume)
    Engine->>Plugin: VolumeDriver.Mount
    Plugin->>Backend: Attach / connect
    Backend-->>Plugin: Mounted at host path
    Plugin-->>Engine: Host path
    Engine->>Engine: Bind path into container

    User->>Engine: docker stop
    Engine->>Plugin: VolumeDriver.Unmount

    User->>Engine: docker volume rm
    Engine->>Plugin: VolumeDriver.Remove
    Plugin->>Backend: Delete storage
        

Not all storage behaves the same way when containers move between machines.

When Docker runs across multiple machines — as it does in a Swarm cluster — a critical question arises: if a container using a particular volume gets rescheduled from Host A to Host B, will that volume’s data follow it? The answer depends entirely on the plugin’s declared scope, reported through the Capabilities endpoint described earlier.

Single-host vs multi-host in practice

On a single developer laptop, scope rarely matters — everything lives on one machine anyway. In production clusters, though, scope becomes one of the first questions to answer when selecting a storage plugin, right alongside performance and cost, because it directly determines whether the architecture can tolerate a node failure without losing data availability.

Different plugins wrap fundamentally different kinds of storage technology.

Volume plugins aren’t a single category of software — they’re a thin, standardized wrapper placed in front of very different underlying storage technologies. Grouping them by the kind of backend they wrap makes their trade-offs much easier to compare.

Block storage plugins

Block storage presents itself to a container as if it were a raw, unformatted disk — the kind of storage cloud providers sell as attachable “volumes” for virtual machines. Plugins in this category typically provision a disk, attach it to the host, format it if needed, and mount the resulting filesystem. Block storage tends to offer strong performance and per-container isolation, but it’s usually attachable to only one host at a time, pushing these plugins toward the “local scope” category discussed earlier unless the backend specifically supports multi-attach.

File storage (network filesystem) plugins

File storage plugins wrap systems like NFS or SMB/CIFS shares, or distributed filesystems purpose-built for this role. Because the underlying protocol is designed for many clients to read and write the same files simultaneously, these plugins are naturally suited to global scope and multi-container sharing, at some cost in raw throughput compared to block storage.

Object and distributed storage plugins

A smaller category of plugins presents object storage — normally accessed through an API rather than a filesystem — as if it were a mountable volume, or wraps a purpose-built distributed storage cluster designed from the ground up for container workloads. These plugins often add their own replication, snapshotting, and encryption features on top of the raw storage layer.

Plugins solve a real problem, but the flexibility they add is not free.

A plugin sits in a position of real trust, and that trust needs to be earned deliberately.

Privilege and trust boundaries

A volume plugin usually needs meaningful privileges to do its job — access to storage credentials, the ability to mount filesystems on the host, and in many cases network access to a storage backend that may hold data for many different tenants or applications. This makes the plugin itself a high-value target: a compromised or poorly written plugin can potentially read or corrupt data belonging to any container that uses it, not just one.

Legacy plugin exposure

Because legacy (V1) plugins are ordinary host processes, they typically run with the same broad privileges as the Docker daemon itself, with no additional sandboxing enforced by Docker. Managed (V2) plugins improve on this by running inside a container-like sandbox with an explicit, declared set of permissions — network access, mount capabilities, device access — that must be granted at install time, making the plugin’s access footprint visible and auditable up front.

A silent plugin failure often looks like a mysterious container start-up hang.

Where things go wrong, and where to look

Because a volume operation crosses two systems, useful monitoring has to cover both sides: Docker’s own engine logs, which record whether a plugin call was sent and what response came back, and the plugin’s own logs, which record what actually happened when it tried to reach its storage backend. When a container appears stuck starting, the very first place to look is whether its Mount call to the plugin ever completed.

Metrics worth tracking

Beyond raw availability, teams running plugin-backed storage at scale typically track mount latency (how long a Mount call takes to complete), call failure rates per plugin, volume creation success rates, and — on the backend — capacity utilization and I/O latency, since a plugin can be perfectly healthy while the storage behind it is running out of room or overloaded.

The same architecture can be used well or badly — here’s the difference.

Pattern: one driver, many named volumes

A healthy pattern is registering a single plugin driver per backend technology, then creating many distinctly-named volumes through it — one per application or per data set — rather than reusing a single shared volume across unrelated workloads. This keeps blast radius small: a problem with one application’s data doesn’t risk another’s.

Pattern: explicit scope awareness in orchestration

Well-designed deployments explicitly account for a plugin’s local-versus-global scope when defining placement constraints, pinning workloads that need locally-scoped storage to specific nodes rather than letting the orchestrator reschedule them freely and silently lose data continuity.

Small operational habits that separate stable plugin deployments from fragile ones.

The abstract architecture becomes concrete once you see who actually builds on it.

A wide range of storage vendors and open-source projects have built volume plugins on top of this exact architecture, each translating Docker’s fixed vocabulary into their own backend’s language.

No. The built-in local driver handles ordinary host-disk volumes with no plugin involved. Plugins are only needed when you want storage backed by something Docker doesn’t already understand natively.

Containers that are already running and mounted usually keep working, since the mount itself lives at the OS level. However, new Mount, Unmount, or Remove calls for that driver will fail until the plugin process is restored, which can block new containers from starting.

It depends entirely on the plugin and its backend. Some plugins and backends fully support concurrent multi-container access; others enforce single-writer access and will reject or serialize simultaneous mounts.

No. They serve a similar conceptual purpose but use different protocols — Docker’s own Volume Plugin API versus Kubernetes’ Container Storage Interface — even though many vendors offer both.

Mostly for compatibility — some older or highly specialized storage integrations were never repackaged as managed plugins. For new deployments, managed plugins are generally the safer and easier-to-operate default where one is available.

No. Removing a container only triggers an Unmount call, not a Remove call. The volume and its underlying data persist until it is explicitly removed on its own.

The Volume Plugin Architecture is Docker’s answer to a simple but unavoidable problem: no single piece of software can natively understand every storage system a business might want to use. Rather than trying, Docker defines a small, fixed set of operations — create, mount, path, unmount, remove, list, and capabilities — and lets independent plugins translate those operations into whatever a real storage backend actually requires. The Docker Engine never needs vendor-specific knowledge; it only needs to speak this one shared vocabulary, whether the plugin behind it manages a cloud disk, a network file share, or a distributed storage cluster.