Docker Config Reference (docker plugin)
We go over creating and using docker plugins! We also show several config.json examples!
What is a Docker Plugin (and 5 Creation Examples)
A Docker plugin constitutes an extension mechanism designed to augment the core capabilities of the Docker Engine, enabling the integration of supplementary features such as advanced storage solutions, networking drivers, logging mechanisms, or authorization controls. These plugins operate as independent components that interface with the Docker daemon through a defined API, facilitating modular enhancements without necessitating modifications to the Docker codebase itself. They are particularly valuable in scenarios requiring customization, such as implementing persistent volume management for cloud storage providers or bespoke network topologies. Plugins must adhere to a structured format, including a configuration file (typically config.json) and a root filesystem (rootfs), and can be managed via the Docker CLI for installation, enablement, or removal.
The creation of a Docker plugin involves preparing the requisite directory structure and employing the docker plugin create command to generate the plugin from a local path. Below are five detailed examples illustrating this process, each focusing on a distinct plugin type or configuration variation. These examples assume a prepared plugin directory containing at least a config.json file (defining the plugin's interface, such as volume or network capabilities) and a rootfs subdirectory (housing the plugin's executable and dependencies). In practice, the plugin's binary must implement the appropriate Docker API endpoints for functionality.
Docker Volume Plugin Creation
docker plugin create myvolumeplugin /path/to/volume/plugin/dir
This command generates a basic volume plugin named "myvolumeplugin" from the specified local directory, which must include a config.json file specifying the "volume" interface and a rootfs containing the plugin executable (e.g., a Go binary implementing the VolumeDriver API). The resulting plugin extends Docker's storage capabilities, such as for custom persistent data handling in cloud environments. Upon creation, the plugin can be installed and used in container volume mounts, providing isolation and modularity for storage operations. A config.json example:
{
"description": "An example volume plugin for Docker",
"documentation": "https://docs.docker.com/engine/extend/plugins_volume/",
"interface": {
"types": ["docker.volumedriver/1.0"],
"socket": "volume.sock"
},
"entrypoint": ["/usr/bin/myvolumeplugin"],
"network": {
"type": "host"
},
"linux": {
"capabilities": ["CAP_SYS_ADMIN", "CAP_MKNOD", "CAP_SYS_MODULE"]
},
"mounts": [
{
"source": "/dev",
"destination": "/dev",
"type": "bind",
"options": ["rbind"]
}
],
"propagatedMount": "/var/lib/docker/plugins/myvolumeplugin/data"
}Docker plugin network creation example:
docker plugin create mynetworkplugin:1.0 /path/to/network/plugin/dir
This command creates a network plugin tagged as version "1.0" from the provided directory path, where config.json defines the "network" interface and rootfs includes the necessary driver logic (e.g., for overlay or custom routing). This plugin enhances Docker's networking features, enabling specialized topologies like VLAN segmentation or integration with external SDN systems. The version tag facilitates management of updates, ensuring compatibility during deployments in multi-host Swarm clusters.
{
"description": "An example network plugin for Docker",
"documentation": "https://docs.docker.com/engine/extend/plugins_network/",
"interface": {
"types": ["docker.networkdriver/1.0"],
"socket": "network.sock"
},
"entrypoint": ["/usr/bin/mynetworkplugin"],
"network": {
"type": "host"
},
"ipam": {
"default": true
},
"linux": {
"capabilities": ["CAP_NET_ADMIN", "CAP_SYS_MODULE", "CAP_NET_RAW"]
},
"mounts": [
{
"source": "/etc/resolv.conf",
"destination": "/etc/resolv.conf",
"type": "bind",
"options": ["ro"]
}
]
}Docker plugin logdriver example:
docker plugin create myloggingplugin /path/to/logging/plugin/dir --alias logdriver
Employing the --alias option, this command creates a logging plugin with an alternative name "logdriver" for easier reference, sourced from the directory containing config.json (specifying the "log" interface) and rootfs (with the logging handler implementation). This plugin customizes container log management, such as forwarding logs to external services like ELK Stack. The alias simplifies configuration in container run commands, promoting usability in monitoring-intensive applications.
{
"description": "An example logging plugin for Docker",
"documentation": "https://docs.docker.com/engine/extend/plugins_logging/",
"interface": {
"types": ["docker.logdriver/1.0"],
"socket": "logging.sock"
},
"entrypoint": ["/usr/bin/myloggingplugin"],
"network": {
"type": "host"
},
"linux": {
"capabilities": ["CAP_SYSLOG", "CAP_SYS_ADMIN"]
},
"mounts": [
{
"source": "/var/log",
"destination": "/var/log",
"type": "bind",
"options": ["rw"]
}
]
}
This configuration file, typically named config.json, defines the essential parameters for a Docker logging plugin. The "description" and "documentation" fields provide metadata for identification and reference. The "interface" section specifies the plugin type as a logging driver and designates the communication socket for interaction with the Docker daemon. The "entrypoint" array indicates the executable command to launch the plugin binary. The "network" configuration sets the plugin to operate within the host's network namespace, ensuring access to system resources. The "linux" object lists required capabilities, such as syslog access, to permit necessary privileges. Finally, the "mounts" array defines bind mounts, here linking the host's log directory to the plugin for read-write access, enabling log collection and processing. When the plugin is created and installed, Docker utilizes this configuration to integrate the custom logging functionality, allowing containers to route logs through the plugin for tasks such as forwarding to external systems or custom formatting.
Docker plugin auth creation example
docker plugin create myauthplugin /path/to/auth/plugin/dir
This command produces an authorization plugin from the designated directory, where config.json outlines the "authz" interface and rootfs houses the authorization logic (e.g., a policy enforcer checking API requests). Such a plugin bolsters security by intercepting and validating Docker API calls, enforcing access controls or compliance rules. It is particularly applicable in enterprise settings requiring fine-grained permissions beyond standard user authentication.
{
"description": "An example authorization plugin for Docker",
"documentation": "https://docs.docker.com/engine/extend/plugins_authorization/",
"interface": {
"types": ["docker.authz/1.0"],
"socket": "authz.sock"
},
"entrypoint": ["/usr/bin/myauthplugin"],
"network": {
"type": "host"
},
"linux": {
"capabilities": ["CAP_SYS_ADMIN"]
},
"mounts": [
{
"source": "/etc/docker",
"destination": "/etc/docker",
"type": "bind",
"options": ["ro"]
}
]
}
This config.json file outlines the configuration for a Docker authorization plugin, which intercepts and evaluates API requests to the Docker daemon, approving or denying them based on defined policies. The "description" and "documentation" fields offer metadata for identification and reference purposes. The "interface" section specifies the plugin as an authorization type with a dedicated socket for communication. The "entrypoint" defines the executable to launch the plugin. The "network" setting integrates it with the host namespace for system access. The "linux" object grants necessary capabilities for administrative functions. The "mounts" array provides read-only access to Docker's configuration directory, enabling policy enforcement without modification risks. When installed, this plugin enhances security by controlling access to Docker operations, such as container creation or image pulls, based on user authentication and command context.
Docker plugin ipam module example
docker plugin create myipamplugin /path/to/ipam/plugin/dir
This command constructs an IP Address Management (IPAM) plugin from the local path, with config.json declaring the "ipam" interface and rootfs implementing custom IP allocation strategies (e.g., integration with external DHCP servers). This extends Docker's networking by providing tailored address assignment, useful in environments with constrained IP spaces or specific routing needs. The plugin can then be referenced in network creation commands for enhanced control over container connectivity.
{
"description": "An example IPAM plugin for Docker",
"documentation": "https://docs.docker.com/engine/extend/plugins_network/#ipam-plugins",
"interface": {
"types": ["docker.ipamdriver/1.0"],
"socket": "ipam.sock"
},
"entrypoint": ["/usr/bin/myipamplugin"],
"network": {
"type": "host"
},
"linux": {
"capabilities": ["CAP_NET_ADMIN"]
},
"mounts": [
{
"source": "/etc/docker",
"destination": "/etc/docker",
"type": "bind",
"options": ["ro"]
}
]
}
This configuration file, named config.json, defines the parameters for a Docker IP Address Management (IPAM) plugin, which manages IP address allocation for networks and containers. The "description" and "documentation" fields supply metadata for reference. The "interface" section identifies the plugin as an IPAM type and specifies the socket for daemon communication. The "entrypoint" indicates the executable to initiate the plugin. The "network" setting integrates the plugin with the host namespace to access networking resources. The "linux" object assigns required capabilities for network administration. The "mounts" array provides read-only access to Docker's configuration directory, supporting the plugin's operations. Upon creation and installation, this plugin enables custom IP assignment strategies, such as integrating with external systems, by responding to Docker's IPAM API requests during network creation or container attachment.
Docker Plugin Usage
docker plugin ls
This command enumerates all Docker plugins installed on the host system, presenting a tabular output that includes the plugin identifier, name, description, enabled status, and version. It serves as a foundational tool for inventory management, enabling administrators to assess the current plugin ecosystem, identify enabled extensions for functionalities such as volume drivers or network integrations, and plan subsequent operations like updates or removals. The output facilitates troubleshooting by highlighting potential conflicts or deprecated plugins, and it supports scripting for automated audits in enterprise environments.
docker plugin install --grant-all-permissions store/pluginname:tag
This command downloads and installs a specified plugin from a registry, such as Docker Hub, using the provided name and tag. The --grant-all-permissions flag authorizes the plugin to access all necessary host resources, which is often required for plugins interacting with system-level components like storage or networking. It is employed to extend Docker's capabilities, for instance, integrating custom volume drivers for persistent data management; however, caution is advised due to the elevated privileges, as it may introduce security risks if the plugin source is untrusted. Post-installation, the plugin becomes available for use in container configurations.
docker plugin disable pluginid
This command deactivates a specified plugin identified by its unique ID or name, preventing its further utilization in new or existing containers without removing it from the system. It is particularly useful for isolating problematic plugins during diagnostics, mitigating performance issues, or preparing for upgrades by ensuring no active dependencies. Disabling does not affect containers already using the plugin but blocks new attachments, thereby allowing controlled rollback or testing in production environments while maintaining system stability.
docker plugin enable pluginid
This command reactivates a previously disabled plugin by its ID or name, restoring its functionality for use in container operations. It is applied after resolving issues identified during a disable phase, such as configuration errors or compatibility conflicts, enabling seamless resumption of extended features like custom authorization or logging. The command ensures that plugins can be toggled without full reinstallation, supporting agile management in dynamic infrastructures where plugin availability needs to align with operational requirements.
docker plugin inspect pluginname
This command retrieves detailed metadata about a specified plugin, outputting information in JSON format including its configuration, capabilities, dependencies, and runtime settings. It is invaluable for verification post-installation, auditing plugin specifications against requirements, or debugging integration failures by examining attributes like supported interfaces (e.g., volume or network). The detailed output aids in compliance checks and informs decisions on plugin suitability for specific use cases, such as ensuring compatibility with the host's Docker version.
docker plugin rm pluginid
This command uninstalls and removes a specified plugin from the host, deleting its associated files and configurations, provided it is disabled and not in use by any containers. It is utilized for cleanup to reclaim disk space, eliminate obsolete extensions, or resolve version conflicts by purging incompatible plugins. Prior to execution, dependencies must be verified to avoid disrupting active services, making it a critical step in plugin lifecycle management for maintaining a streamlined Docker environment.
docker plugin upgrade pluginname store/newpluginname:tag
This command upgrades an existing plugin to a newer version or variant from a registry, replacing the current installation while preserving configurations where possible. It supports seamless enhancements, such as incorporating security patches or feature additions to plugins like IPAM drivers. The process involves downloading the new image, validating compatibility, and restarting dependent services if necessary, thereby ensuring minimal downtime in production setups through careful version control.
docker plugin push pluginname
This command uploads a locally developed or modified plugin to a remote registry, such as Docker Hub, making it distributable for use on other hosts. It is essential for plugin authors or teams sharing custom extensions, like bespoke logging drivers, across distributed systems. The push operation includes manifest and layer validation to ensure integrity, supporting collaborative development and deployment pipelines in containerized ecosystems.
docker plugin set pluginname key=value
This command modifies configuration settings for a specified plugin by assigning key-value pairs, such as adjusting parameters for a volume plugin's mount options. It allows fine-tuning without reinstallation, enabling adaptations to environmental variables or performance optimizations. Changes take effect upon plugin restart or container recreation, providing flexibility in operational tuning while requiring awareness of plugin-specific keys to avoid misconfigurations.
docker plugin create pluginname /path/to/plugin/config
This command generates a new plugin from a local directory containing the plugin's rootfs and configuration files, registering it with the Docker daemon for immediate use. It is employed by developers to build custom plugins, such as experimental network drivers, from source. The creation process validates the plugin's structure and interfaces, facilitating rapid prototyping and integration testing in controlled environments before broader deployment.