0
# Pod Management
1

2
**Note: This is Podman-specific functionality, not available in Docker.**
3

4
Podman pod management for grouping containers with shared namespaces, networking, and storage. Pods provide a way to run multiple containers together as a cohesive unit, similar to Kubernetes pods.
5

6
## Capabilities
7

8
### Pod Creation
9

10
Create pods with shared namespaces and networking configuration.
11

12
```python { .api }
13
def create(
14
    name: Optional[str] = None,
15
    *,
16
    add_hosts: Optional[List[str]] = None,
17
    cgroup_parent: Optional[str] = None,
18
    cpu_shares: Optional[int] = None,
19
    cpus: Optional[float] = None,
20
    cpuset_cpus: Optional[str] = None,
21
    dns: Optional[List[str]] = None,
22
    dns_options: Optional[List[str]] = None,
23
    dns_search: Optional[List[str]] = None,
24
    gidmap: Optional[List[str]] = None,
25
    hostname: Optional[str] = None,
26
    infra: bool = True,
27
    infra_command: Optional[str] = None,
28
    infra_image: Optional[str] = None,
29
    ip: Optional[str] = None,
30
    labels: Optional[Dict[str, str]] = None,
31
    mac_address: Optional[str] = None,
32
    memory: Optional[str] = None,
33
    network: Optional[str] = None,
34
    no_hosts: bool = False,
35
    pid: Optional[str] = None,
36
    pod_id_file: Optional[str] = None,
37
    publish: Optional[List[str]] = None,
38
    replace: bool = False,
39
    share: Optional[str] = None,
40
    subgidname: Optional[str] = None,
41
    subuidname: Optional[str] = None,
42
    uidmap: Optional[List[str]] = None,
43
    userns: Optional[str] = None,
44
    uts: Optional[str] = None,
45
    volume: Optional[List[str]] = None
46
) -> Pod:
47
    """
48
    Create a new pod with extensive configuration options.
49
    
50
    Parameters:
51
    - name: Pod name (auto-generated if not provided)
52
    - add_hosts: Add host-to-IP mappings
53
    - cgroup_parent: Parent cgroup for the pod
54
    - cpu_shares: CPU shares (relative weight)
55
    - cpus: Number of CPUs  
56
    - cpuset_cpus: CPU set for execution
57
    - dns: DNS servers
58
    - dns_options: DNS options
59
    - dns_search: DNS search domains
60
    - gidmap: GID map for user namespace
61
    - hostname: Pod hostname
62
    - infra: Create infra container (default: True)
63
    - infra_command: Command for infra container
64
    - infra_image: Image for infra container
65
    - ip: IP address for pod
66
    - labels: Metadata labels
67
    - mac_address: MAC address
68
    - memory: Memory limit
69
    - network: Network mode
70
    - no_hosts: Don't create /etc/hosts
71
    - pid: PID namespace mode
72
    - pod_id_file: Write pod ID to file
73
    - publish: Port mappings
74
    - replace: Replace existing pod with same name
75
    - share: Shared namespaces
76
    - subgidname: Name of subordinate GID range
77
    - subuidname: Name of subordinate UID range  
78
    - uidmap: UID map for user namespace
79
    - userns: User namespace mode
80
    - uts: UTS namespace mode
81
    - volume: Volume mounts
82
    
83
    Returns:
84
    Pod object
85
    """
86
```
87

88
### Pod Lifecycle Management
89

90
Start, stop, pause, and restart pods.
91

92
```python { .api }
93
def start(x: Union[str, List[str]]) -> None:
94
    """
95
    Start one or more pods.
96
    
97
    Parameters:
98
    - x: Pod name(s) or ID(s)
99
    """
100

101
def stop(
102
    x: Union[str, List[str]], 
103
    time: Optional[int] = None
104
) -> None:
105
    """
106
    Stop one or more pods.
107
    
108
    Parameters:
109
    - x: Pod name(s) or ID(s)
110
    - time: Timeout in seconds before force kill
111
    """
112

113
def restart(x: Union[str, List[str]]) -> None:
114
    """
115
    Restart one or more pods.
116
    
117
    Parameters:
118
    - x: Pod name(s) or ID(s)
119
    """
120

121
def pause(x: Union[str, List[str]]) -> None:
122
    """
123
    Pause one or more pods.
124
    
125
    Parameters:
126
    - x: Pod name(s) or ID(s)
127
    """
128

129
def unpause(x: Union[str, List[str]]) -> None:
130
    """
131
    Unpause one or more pods.
132
    
133
    Parameters:
134
    - x: Pod name(s) or ID(s)
135
    """
136

137
def kill(
138
    x: Union[str, List[str]], 
139
    signal: Optional[str] = None
140
) -> None:
141
    """
142
    Kill one or more pods.
143
    
144
    Parameters:
145
    - x: Pod name(s) or ID(s)
146
    - signal: Signal to send (default: SIGKILL)
147
    """
148
```
149

150
### Pod Information and Monitoring
151

152
Inspect pods, check existence, and view logs.
153

154
```python { .api }
155
def inspect(x: Union[str, List[str]]) -> Union[Pod, List[Pod]]:
156
    """
157
    Inspect one or more pods.
158
    
159
    Parameters:
160
    - x: Pod name(s) or ID(s)
161
    
162
    Returns:
163
    Pod object(s) with detailed information
164
    """
165

166
def exists(pod: Union[str, Pod]) -> bool:
167
    """
168
    Check if a pod exists.
169
    
170
    Parameters:
171
    - pod: Pod name/ID or Pod object
172
    
173
    Returns:
174
    True if pod exists, False otherwise
175
    """
176

177
def list(filters: Sequence[str] = ()) -> List[Pod]:
178
    """
179
    List pods with optional filters.
180
    
181
    Parameters:
182
    - filters: Filter conditions
183
    
184
    Returns:
185
    List of Pod objects
186
    """
187

188
def logs(
189
    pod: Union[str, Pod],
190
    container: Optional[str] = None,
191
    *,
192
    names: bool = False,
193
    since: Optional[str] = None,
194
    tail: Optional[int] = None,
195
    timestamps: bool = False,
196
    until: Optional[str] = None,
197
    follow: bool = False,
198
    stream: bool = False
199
) -> Union[str, Iterable[Tuple[str, bytes]]]:
200
    """
201
    Get pod or container logs.
202
    
203
    Parameters:
204
    - pod: Pod name/ID or Pod object
205
    - container: Specific container in pod
206
    - names: Show container names in output
207
    - since: Show logs since timestamp
208
    - tail: Number of lines from end
209
    - timestamps: Show timestamps
210
    - until: Show logs until timestamp
211
    - follow: Follow log output
212
    - stream: Return streaming iterator
213
    
214
    Returns:
215
    Log output as string or streaming iterator
216
    """
217
```
218

219
### Pod Cleanup
220

221
Remove pods and prune unused pods.
222

223
```python { .api }
224
def remove(
225
    x: Union[str, List[str]], 
226
    force: bool = False,
227
    ignore: bool = False,
228
    time: Optional[int] = None
229
) -> None:
230
    """
231
    Remove one or more pods.
232
    
233
    Parameters:
234
    - x: Pod name(s) or ID(s)
235
    - force: Force removal
236
    - ignore: Ignore errors
237
    - time: Timeout before force kill
238
    """
239

240
def prune() -> None:
241
    """
242
    Remove all non-running pods.
243
    """
244
```
245

246
**Usage Examples:**
247

248
```python
249
from python_on_whales import docker  # Note: This requires Podman backend
250

251
# Create a pod with shared networking
252
pod = docker.pod.create(
253
    "web-app-pod",
254
    hostname="web-server",
255
    publish=["8080:80", "8443:443"],
256
    labels={"app": "web", "environment": "production"}
257
)
258

259
# Start the pod
260
docker.pod.start("web-app-pod")
261

262
# Add containers to the pod (using regular container create with --pod option)
263
web_container = docker.create(
264
    "nginx:alpine",
265
    pod=pod.name,
266
    name="web-server"
267
)
268

269
app_container = docker.create(
270
    "python:3.9",
271
    ["python", "app.py"],
272
    pod=pod.name,
273
    name="app-server"
274
)
275

276
# Get pod logs
277
logs = docker.pod.logs("web-app-pod", follow=True, stream=True)
278
for source, line in logs:
279
    print(f"{source}: {line.decode()}")
280

281
# Stop and remove pod
282
docker.pod.stop("web-app-pod")
283
docker.pod.remove("web-app-pod")
284
```
285

286
## Types
287

288
```python { .api }
289
class Pod:
290
    id: str
291
    name: str
292
    created: str
293
    create_command: List[str]
294
    exit_policy: str
295
    state: str
296
    hostname: str
297
    labels: Dict[str, str]
298
    create_cgroup: bool
299
    cgroup_parent: str
300
    cgroup_path: str
301
    create_infra: bool  
302
    infra_container_id: str
303
    infra_config: Dict[str, Any]
304
    shared_namespaces: List[str]
305
    num_containers: int
306
    containers: List[Dict[str, Any]]
307
    
308
    def exists(self) -> bool:
309
        """Check if this pod exists."""
310
    
311
    def kill(self, signal: Optional[str] = None) -> None:
312
        """Kill this pod."""
313
    
314
    def logs(
315
        self,
316
        container: Optional[str] = None,
317
        names: bool = False,
318
        since: Optional[str] = None,
319
        tail: Optional[int] = None,
320
        timestamps: bool = False,
321
        until: Optional[str] = None,
322
        follow: bool = False,
323
        stream: bool = False
324
    ) -> Union[str, Iterable[Tuple[str, bytes]]]:
325
        """Get logs for this pod."""
326
    
327
    def pause(self) -> None:
328
        """Pause this pod."""
329
    
330
    def unpause(self) -> None:
331
        """Unpause this pod."""
332
    
333
    def restart(self) -> None:
334
        """Restart this pod."""
335
    
336
    def remove(
337
        self, 
338
        force: bool = False, 
339
        time: Optional[int] = None
340
    ) -> None:
341
        """Remove this pod."""
342
    
343
    def start(self) -> None:
344
        """Start this pod."""
345
    
346
    def stop(self, time: Optional[int] = None) -> None:
347
        """Stop this pod."""
348
```