0
# Plugin Management
1

2
Docker plugin management for extending Docker functionality with third-party plugins. Plugins provide additional capabilities like storage drivers, network drivers, and authorization mechanisms that integrate seamlessly with Docker.
3

4
## Capabilities
5

6
### Plugin Installation
7

8
Install plugins from Docker Hub or custom registries with automatic permission granting.
9

10
```python { .api }
11
def install(
12
    plugin_name: str,
13
    configuration: Optional[List[str]] = None,
14
    alias: Optional[str] = None,
15
    disable: bool = False,
16
    disable_content_trust: bool = True
17
) -> Plugin:
18
    """
19
    Install a plugin with automatic permission granting.
20
    
21
    Parameters:
22
    - plugin_name: Plugin name (e.g., "store/sumologic/docker-logging-driver")
23
    - configuration: Configuration options as key=value pairs
24
    - alias: Local alias for the plugin
25
    - disable: Install but leave disabled
26
    - disable_content_trust: Skip content trust verification
27
    
28
    Returns:
29
    Plugin object
30
    """
31
```
32

33
### Plugin Creation
34

35
Create plugins from rootfs directories.
36

37
```python { .api }
38
def create(
39
    plugin_name: str,
40
    plugin_data_directory: str,
41
    compress: bool = False
42
) -> Plugin:
43
    """
44
    Create a plugin from a rootfs directory.
45
    
46
    Parameters:
47
    - plugin_name: Name for the new plugin
48
    - plugin_data_directory: Path to plugin rootfs directory
49
    - compress: Compress plugin data
50
    
51
    Returns:
52
    Plugin object
53
    """
54
```
55

56
### Plugin State Management
57

58
Enable and disable plugins dynamically.
59

60
```python { .api }
61
def enable(
62
    plugin: Union[str, Plugin],
63
    timeout: Optional[int] = None
64
) -> None:
65
    """
66
    Enable a plugin.
67
    
68
    Parameters:
69
    - plugin: Plugin name/ID or Plugin object
70
    - timeout: Timeout in seconds
71
    """
72

73
def disable(
74
    plugin: Union[str, Plugin],
75
    force: bool = False
76
) -> None:
77
    """
78
    Disable a plugin.
79
    
80
    Parameters:
81
    - plugin: Plugin name/ID or Plugin object  
82
    - force: Force disable even if in use
83
    """
84
```
85

86
### Plugin Configuration
87

88
Update plugin settings after installation.
89

90
```python { .api }
91
def set(
92
    plugin: Union[str, Plugin],
93
    configuration: List[str]
94
) -> None:
95
    """
96
    Change plugin configuration settings.
97
    
98
    Parameters:
99
    - plugin: Plugin name/ID or Plugin object
100
    - configuration: Configuration options as key=value pairs
101
    """
102
```
103

104
### Plugin Inspection
105

106
Inspect plugin details including configuration and capabilities.
107

108
```python { .api }
109
def inspect(x: Union[str, List[str]]) -> Union[Plugin, List[Plugin]]:
110
    """
111
    Inspect one or more plugins.
112
    
113
    Parameters:
114
    - x: Plugin name(s) or ID(s)
115
    
116
    Returns:
117
    Plugin object(s) with detailed information
118
    """
119
```
120

121
### Plugin Listing
122

123
List all installed plugins.
124

125
```python { .api }
126
def list() -> List[Plugin]:
127
    """
128
    List all installed plugins.
129
    
130
    Returns:
131
    List of Plugin objects
132
    """
133
```
134

135
### Plugin Registry Operations
136

137
Push plugins to registries and upgrade installed plugins.
138

139
```python { .api }
140
def push(
141
    plugin: Union[str, Plugin],
142
    disable_content_trust: bool = True
143
) -> None:
144
    """
145
    Push plugin to registry.
146
    
147
    Parameters:
148
    - plugin: Plugin name/ID or Plugin object
149
    - disable_content_trust: Skip content trust verification
150
    """
151

152
def upgrade(
153
    plugin: Union[str, Plugin],
154
    remote: Optional[str] = None,
155
    disable_content_trust: bool = True,
156
    skip_remote_check: bool = False
157
) -> None:
158
    """
159
    Upgrade a plugin.
160
    
161
    Parameters:
162
    - plugin: Plugin name/ID or Plugin object
163
    - remote: Remote plugin reference to upgrade to
164
    - disable_content_trust: Skip content trust verification
165
    - skip_remote_check: Skip remote existence check
166
    """
167
```
168

169
### Plugin Removal
170

171
Remove plugins from the system.
172

173
```python { .api }
174
def remove(
175
    x: Union[str, List[str]],
176
    force: bool = False
177
) -> None:
178
    """
179
    Remove one or more plugins.
180
    
181
    Parameters:
182
    - x: Plugin name(s) or ID(s) to remove
183
    - force: Force removal even if plugin is enabled
184
    """
185
```
186

187
**Usage Examples:**
188

189
```python
190
from python_on_whales import docker
191

192
# Install logging plugin
193
plugin = docker.plugin.install(
194
    "store/sumologic/docker-logging-driver:1.0.0",
195
    alias="sumologic"
196
)
197

198
# Configure plugin
199
docker.plugin.set("sumologic", ["SUMO_URL=https://collectors.sumologic.com"])
200

201
# Enable plugin
202
docker.plugin.enable("sumologic")
203

204
# List all plugins
205
plugins = docker.plugin.list()
206
for plugin in plugins:
207
    print(f"Plugin: {plugin.name} - Enabled: {plugin.enabled}")
208

209
# Disable and remove plugin
210
docker.plugin.disable("sumologic")
211
docker.plugin.remove("sumologic")
212
```
213

214
## Types
215

216
```python { .api }
217
class Plugin:
218
    id: str
219
    name: str
220
    enabled: bool
221
    settings: PluginSettings
222
    plugin_reference: str
223
    config: PluginConfig
224
    
225
    def disable(self, force: bool = False) -> None:
226
        """Disable this plugin."""
227
    
228
    def enable(self, timeout: Optional[int] = None) -> None:
229
        """Enable this plugin."""
230
    
231
    def push(self, disable_content_trust: bool = True) -> None:
232
        """Push this plugin to registry."""
233
    
234
    def remove(self, force: bool = False) -> None:
235
        """Remove this plugin."""
236
    
237
    def set(self, configuration: List[str]) -> None:
238
        """Update this plugin's configuration."""
239
    
240
    def upgrade(
241
        self,
242
        remote: Optional[str] = None,
243
        disable_content_trust: bool = True,
244
        skip_remote_check: bool = False
245
    ) -> None:
246
        """Upgrade this plugin."""
247

248
class PluginSettings:
249
    mounts: List[Dict[str, Any]]
250
    env: List[str]
251
    args: List[str]
252
    devices: List[Dict[str, Any]]
253

254
class PluginConfig:
255
    docker_version: str
256
    description: str
257
    documentation: str
258
    interface: Dict[str, Any]
259
    entrypoint: List[str]
260
    work_dir: str
261
    user: Dict[str, Any]
262
    network: Dict[str, str]
263
    linux: Dict[str, Any]
264
    propagated_mount: str
265
    ipc_host: bool
266
    pid_host: bool
267
    mounts: List[Dict[str, Any]]
268
    env: List[Dict[str, str]]
269
    args: Dict[str, Any]
270
```