0
# Services and Swarm
1

2
Docker Swarm cluster management and service orchestration capabilities. Provides container orchestration, service scaling, rolling updates, cluster administration, and high availability across multiple Docker hosts with built-in load balancing and service discovery.
3

4
## Capabilities
5

6
### Swarm Cluster Management
7

8
Functions for initializing, joining, and managing Docker Swarm clusters.
9

10
```python { .api }
11
def init_swarm(advertise_addr=None, listen_addr='0.0.0.0:2377', 
12
               force_new_cluster=False, swarm_spec=None):
13
    """
14
    Initialize a new Swarm cluster.
15
    
16
    Parameters:
17
    - advertise_addr (str): IP address to advertise to other nodes
18
    - listen_addr (str): Address to listen for cluster management traffic
19
    - force_new_cluster (bool): Force creation of new cluster
20
    - swarm_spec (SwarmSpec): Swarm configuration specification
21
    
22
    Returns:
23
    dict: Swarm initialization response with node ID and tokens
24
    """
25

26
def join_swarm(remote_addrs, join_token, listen_addr=None, advertise_addr=None):
27
    """
28
    Join an existing Swarm cluster.
29
    
30
    Parameters:
31
    - remote_addrs (list): List of manager node addresses
32
    - join_token (str): Token for joining (worker or manager token)
33
    - listen_addr (str): Address to listen for cluster traffic
34
    - advertise_addr (str): IP address to advertise to cluster
35
    
36
    Returns:
37
    None
38
    """
39

40
def leave_swarm(force=False):
41
    """
42
    Leave the Swarm cluster.
43
    
44
    Parameters:
45
    - force (bool): Force leave even if node is a manager
46
    
47
    Returns:
48
    None
49
    """
50

51
def inspect_swarm():
52
    """
53
    Get detailed information about the Swarm cluster.
54
    
55
    Returns:
56
    dict: Swarm configuration and state information
57
    """
58

59
def update_swarm(version, swarm_spec=None, rotate_worker_token=False, 
60
                 rotate_manager_token=False):
61
    """
62
    Update Swarm cluster configuration.
63
    
64
    Parameters:
65
    - version (int): Current version of swarm object being updated
66
    - swarm_spec (SwarmSpec): New swarm configuration
67
    - rotate_worker_token (bool): Rotate worker join token
68
    - rotate_manager_token (bool): Rotate manager join token
69
    
70
    Returns:
71
    None
72
    """
73
```
74

75
### Node Management
76

77
Functions for managing Swarm cluster nodes.
78

79
```python { .api }
80
def nodes(filters=None):
81
    """
82
    List Swarm nodes.
83
    
84
    Parameters:
85
    - filters (dict): Filters to apply to node list
86
    
87
    Returns:
88
    list: List of node dictionaries with details and status
89
    """
90

91
def inspect_node(node_id):
92
    """
93
    Get detailed information about a Swarm node.
94
    
95
    Parameters:
96
    - node_id (str): Node ID or name
97
    
98
    Returns:
99
    dict: Node configuration, status, and resource information
100
    """
101
```
102

103
### Service Management
104

105
Functions for creating, managing, and scaling Docker services in Swarm mode.
106

107
```python { .api }
108
def services(filters=None):
109
    """
110
    List Swarm services.
111
    
112
    Parameters:
113
    - filters (dict): Filters to apply to service list
114
    
115
    Returns:
116
    list: List of service dictionaries with configuration and status
117
    """
118

119
def create_service(task_template, name=None, labels=None, mode=None, 
120
                  update_config=None, networks=None, endpoint_config=None):
121
    """
122
    Create a new Swarm service.
123
    
124
    Parameters:
125
    - task_template (TaskTemplate): Service task specification
126
    - name (str): Service name
127
    - labels (dict): Service labels
128
    - mode (dict): Service mode configuration (replicated/global)
129
    - update_config (UpdateConfig): Update configuration
130
    - networks (list): Networks to attach service to
131
    - endpoint_config (dict): Endpoint configuration for service ports
132
    
133
    Returns:
134
    dict: Service creation response with service ID
135
    """
136

137
def inspect_service(service):
138
    """
139
    Get detailed information about a service.
140
    
141
    Parameters:
142
    - service (str): Service ID or name
143
    
144
    Returns:
145
    dict: Service specification and current state
146
    """
147

148
def update_service(service, version, task_template=None, name=None, 
149
                  labels=None, mode=None, update_config=None, 
150
                  networks=None, endpoint_config=None):
151
    """
152
    Update an existing service.
153
    
154
    Parameters:
155
    - service (str): Service ID or name
156
    - version (int): Current version of service object being updated
157
    - task_template (TaskTemplate): New task specification
158
    - name (str): New service name
159
    - labels (dict): New service labels
160
    - mode (dict): New service mode configuration
161
    - update_config (UpdateConfig): New update configuration
162
    - networks (list): New network attachments
163
    - endpoint_config (dict): New endpoint configuration
164
    
165
    Returns:
166
    dict: Service update response
167
    """
168

169
def remove_service(service):
170
    """
171
    Remove a service.
172
    
173
    Parameters:
174
    - service (str): Service ID or name
175
    
176
    Returns:
177
    None
178
    """
179
```
180

181
### Task Management
182

183
Functions for inspecting and managing service tasks.
184

185
```python { .api }
186
def tasks(filters=None):
187
    """
188
    List Swarm tasks.
189
    
190
    Parameters:
191
    - filters (dict): Filters to apply to task list
192
    
193
    Returns:
194
    list: List of task dictionaries with status and assignment
195
    """
196

197
def inspect_task(task):
198
    """
199
    Get detailed information about a task.
200
    
201
    Parameters:
202
    - task (str): Task ID
203
    
204
    Returns:
205
    dict: Task specification, status, and runtime information
206
    """
207
```
208

209
### Volume Management
210

211
Docker volume operations for persistent data storage in Swarm services.
212

213
```python { .api }
214
def volumes(filters=None):
215
    """
216
    List Docker volumes.
217
    
218
    Parameters:
219
    - filters (dict): Filters to apply to volume list
220
    
221
    Returns:
222
    list: List of volume dictionaries
223
    """
224

225
def create_volume(name, driver=None, driver_opts=None, labels=None):
226
    """
227
    Create a Docker volume.
228
    
229
    Parameters:
230
    - name (str): Volume name
231
    - driver (str): Volume driver
232
    - driver_opts (dict): Driver-specific options
233
    - labels (dict): Volume labels
234
    
235
    Returns:
236
    dict: Volume creation response
237
    """
238

239
def inspect_volume(name):
240
    """
241
    Get detailed information about a volume.
242
    
243
    Parameters:
244
    - name (str): Volume name
245
    
246
    Returns:
247
    dict: Volume configuration and status
248
    """
249

250
def remove_volume(name):
251
    """
252
    Remove a volume.
253
    
254
    Parameters:
255
    - name (str): Volume name
256
    
257
    Returns:
258
    None
259
    """
260
```
261

262
## Service Configuration Types
263

264
### TaskTemplate
265

266
Service task specification defining container configuration and resource requirements.
267

268
```python { .api }
269
class TaskTemplate:
270
    def __init__(self, container_spec, resources=None, restart_policy=None, 
271
                 placement=None, log_driver=None):
272
        """
273
        Create task template for service.
274
        
275
        Parameters:
276
        - container_spec (ContainerSpec): Container specification
277
        - resources (Resources): Resource constraints
278
        - restart_policy (RestartPolicy): Restart policy configuration
279
        - placement (dict): Task placement constraints
280
        - log_driver (dict): Logging driver configuration
281
        """
282

283
    # Properties
284
    container_spec: ContainerSpec  # Container configuration
285
    resources: Resources           # Resource limits and reservations
286
    restart_policy: RestartPolicy  # Restart behavior
287
    placement: dict               # Node placement preferences
288
```
289

290
### ContainerSpec
291

292
Container specification for services defining image, command, and runtime configuration.
293

294
```python { .api }
295
class ContainerSpec:
296
    def __init__(self, image, command=None, args=None, env=None, 
297
                 workdir=None, user=None, labels=None, mounts=None, 
298
                 stop_grace_period=None):
299
        """
300
        Create container specification for service tasks.
301
        
302
        Parameters:
303
        - image (str): Container image
304
        - command (list): Command to run
305
        - args (list): Command arguments
306
        - env (list): Environment variables
307
        - workdir (str): Working directory
308
        - user (str): User to run as
309
        - labels (dict): Container labels
310
        - mounts (list): Volume mounts
311
        - stop_grace_period (int): Grace period before force kill
312
        """
313
```
314

315
### Resources
316

317
Resource constraints for service tasks including CPU and memory limits.
318

319
```python { .api }
320
class Resources:
321
    def __init__(self, cpu_limit=None, mem_limit=None, cpu_reservation=None, 
322
                 mem_reservation=None):
323
        """
324
        Create resource constraints for service tasks.
325
        
326
        Parameters:
327
        - cpu_limit (int): CPU limit in nanocpus
328
        - mem_limit (int): Memory limit in bytes
329
        - cpu_reservation (int): CPU reservation in nanocpus
330
        - mem_reservation (int): Memory reservation in bytes
331
        """
332
```
333

334
### UpdateConfig
335

336
Configuration for service rolling updates and deployment strategy.
337

338
```python { .api }
339
class UpdateConfig:
340
    def __init__(self, parallelism=0, delay=None, failure_action='continue'):
341
        """
342
        Create update configuration for service updates.
343
        
344
        Parameters:
345
        - parallelism (int): Number of tasks to update simultaneously
346
        - delay (int): Delay between task updates in nanoseconds
347
        - failure_action (str): Action on update failure ('continue', 'pause')
348
        """
349
```
350

351
### RestartPolicy
352

353
Container restart policy configuration for service tasks.
354

355
```python { .api }
356
class RestartPolicy:
357
    def __init__(self, condition='none', delay=0, max_attempts=0, window=0):
358
        """
359
        Create restart policy for service tasks.
360
        
361
        Parameters:
362
        - condition (str): When to restart ('none', 'on-failure', 'any')
363
        - delay (int): Delay between restart attempts in nanoseconds
364
        - max_attempts (int): Maximum restart attempts
365
        - window (int): Window to evaluate restart policy
366
        """
367

368
# Restart condition constants
369
class RestartConditionTypesEnum:
370
    NONE = 'none'
371
    ON_FAILURE = 'on-failure'  
372
    ANY = 'any'
373
```
374

375
### SwarmSpec
376

377
Swarm cluster configuration specification.
378

379
```python { .api }
380
class SwarmSpec:
381
    def __init__(self, task_history_retention_limit=None, snapshot_interval=None, 
382
                 keep_old_snapshots=None, log_entries_for_slow_followers=None, 
383
                 heartbeat_tick=None, election_tick=None, 
384
                 dispatcher_heartbeat_period=None, node_cert_expiry=None, 
385
                 external_ca=None, name=None):
386
        """
387
        Create Swarm cluster specification.
388
        
389
        Parameters:
390
        - task_history_retention_limit (int): Task history retention limit
391
        - snapshot_interval (int): Raft snapshot interval
392
        - keep_old_snapshots (int): Old snapshots to keep
393
        - log_entries_for_slow_followers (int): Log entries for slow followers
394
        - heartbeat_tick (int): Heartbeat tick interval
395
        - election_tick (int): Election tick interval
396
        - dispatcher_heartbeat_period (int): Dispatcher heartbeat period
397
        - node_cert_expiry (int): Node certificate expiry time
398
        - external_ca (SwarmExternalCA): External certificate authority
399
        - name (str): Swarm cluster name
400
        """
401

402
def create_swarm_spec(*args, **kwargs):
403
    """
404
    Create SwarmSpec object with given parameters.
405
    
406
    Returns:
407
    SwarmSpec: Swarm specification object
408
    """
409
```
410

411
### SwarmExternalCA
412

413
External certificate authority configuration for Swarm cluster security.
414

415
```python { .api }
416
class SwarmExternalCA:
417
    def __init__(self, url, protocol=None, options=None):
418
        """
419
        Create external CA configuration.
420
        
421
        Parameters:
422
        - url (str): CA server URL
423
        - protocol (str): Protocol to use
424
        - options (dict): Additional CA options
425
        """
426
```
427

428
## Usage Examples
429

430
### Basic Swarm Setup
431

432
```python
433
import docker
434
from docker.types import TaskTemplate, ContainerSpec, Resources
435

436
client = docker.Client()
437

438
# Initialize Swarm cluster
439
swarm_info = client.init_swarm(
440
    advertise_addr='192.168.1.100',
441
    listen_addr='0.0.0.0:2377'
442
)
443

444
print(f"Swarm initialized with Node ID: {swarm_info['NodeID']}")
445
print(f"Worker token: {swarm_info['Tokens']['Worker']}")
446
print(f"Manager token: {swarm_info['Tokens']['Manager']}")
447

448
# Get Swarm information
449
swarm_details = client.inspect_swarm()
450
print(f"Swarm ID: {swarm_details['ID']}")
451
print(f"Node count: {len(client.nodes())}")
452
```
453

454
### Creating and Managing Services
455

456
```python
457
# Create container specification
458
container_spec = ContainerSpec(
459
    image='nginx:latest',
460
    env=['NGINX_PORT=80'],
461
    mounts=[
462
        {
463
            'Type': 'volume',
464
            'Source': 'nginx-data',
465
            'Target': '/usr/share/nginx/html'
466
        }
467
    ]
468
)
469

470
# Create resource constraints  
471
resources = Resources(
472
    cpu_limit=1000000000,  # 1 CPU (1 billion nanocpus)
473
    mem_limit=512 * 1024 * 1024,  # 512MB
474
    cpu_reservation=500000000,  # 0.5 CPU reservation
475
    mem_reservation=256 * 1024 * 1024  # 256MB reservation
476
)
477

478
# Create task template
479
task_template = TaskTemplate(
480
    container_spec=container_spec,
481
    resources=resources,
482
    restart_policy=docker.types.RestartPolicy(
483
        condition='on-failure',
484
        max_attempts=3
485
    )
486
)
487

488
# Create service
489
service = client.create_service(
490
    task_template=task_template,
491
    name='web-service',
492
    mode={'Replicated': {'Replicas': 3}},  # 3 replicas
493
    endpoint_config={
494
        'Ports': [
495
            {
496
                'Protocol': 'tcp',
497
                'PublishedPort': 80,
498
                'TargetPort': 80
499
            }
500
        ]
501
    },
502
    labels={'app': 'web', 'version': '1.0'}
503
)
504

505
print(f"Created service: {service['ID']}")
506
```
507

508
### Service Scaling and Updates
509

510
```python
511
# List services
512
services = client.services()
513
for service in services:
514
    print(f"Service: {service['Spec']['Name']}, Replicas: {service['Spec']['Mode']['Replicated']['Replicas']}")
515

516
# Update service to scale to 5 replicas
517
service_info = client.inspect_service('web-service')
518
version = service_info['Version']['Index']
519

520
client.update_service(
521
    'web-service',
522
    version=version,
523
    mode={'Replicated': {'Replicas': 5}}
524
)
525

526
# Update service with new image
527
updated_container_spec = ContainerSpec(
528
    image='nginx:1.21-alpine',  # New image version
529
    env=['NGINX_PORT=80']
530
)
531

532
updated_task_template = TaskTemplate(
533
    container_spec=updated_container_spec,
534
    resources=resources
535
)
536

537
service_info = client.inspect_service('web-service')
538
version = service_info['Version']['Index']
539

540
client.update_service(
541
    'web-service',
542
    version=version,
543
    task_template=updated_task_template,
544
    update_config=docker.types.UpdateConfig(
545
        parallelism=1,  # Update one task at a time
546
        delay=5000000000,  # 5 second delay between updates
547
        failure_action='pause'
548
    )
549
)
550
```
551

552
### Advanced Service Configuration
553

554
```python
555
# Create service with complex configuration
556
container_spec = ContainerSpec(
557
    image='myapp:latest',
558
    command=['python', 'app.py'],
559
    env=[
560
        'DATABASE_URL=postgresql://user:pass@db:5432/myapp',
561
        'REDIS_URL=redis://cache:6379'
562
    ],
563
    labels={'service': 'api'},
564
    mounts=[
565
        {
566
            'Type': 'volume',
567
            'Source': 'app-data',
568
            'Target': '/app/data'
569
        }
570
    ],
571
    user='1000:1000',
572
    workdir='/app'
573
)
574

575
# Create with placement constraints
576
task_template = TaskTemplate(
577
    container_spec=container_spec,
578
    resources=Resources(
579
        cpu_limit=2000000000,  # 2 CPUs
580
        mem_limit=1024 * 1024 * 1024,  # 1GB
581
        cpu_reservation=1000000000,  # 1 CPU reserved
582
        mem_reservation=512 * 1024 * 1024  # 512MB reserved
583
    ),
584
    placement={
585
        'Constraints': ['node.role==worker'],
586
        'Preferences': [
587
            {
588
                'Spread': {'SpreadDescriptor': 'node.labels.zone'}
589
            }
590
        ]
591
    },
592
    restart_policy=docker.types.RestartPolicy(
593
        condition='any',
594
        delay=5000000000,  # 5 seconds
595
        max_attempts=5
596
    )
597
)
598

599
# Create service with networks
600
service = client.create_service(
601
    task_template=task_template,
602
    name='api-service',
603
    mode={'Replicated': {'Replicas': 3}},
604
    networks=[
605
        {'Target': 'frontend-network'},
606
        {'Target': 'backend-network'}
607
    ],
608
    endpoint_config={
609
        'Ports': [
610
            {
611
                'Protocol': 'tcp',
612
                'PublishedPort': 8000,
613
                'TargetPort': 8000,
614
                'PublishMode': 'ingress'
615
            }
616
        ]
617
    },
618
    labels={
619
        'app': 'myapp',
620
        'tier': 'api',
621
        'environment': 'production'
622
    }
623
)
624
```
625

626
### Service Monitoring and Management
627

628
```python
629
# Monitor service tasks
630
tasks = client.tasks(filters={'service': 'web-service'})
631
for task in tasks:
632
    print(f"Task: {task['ID'][:12]}")
633
    print(f"  State: {task['Status']['State']}")
634
    print(f"  Node: {task['NodeID'][:12]}")
635
    if 'ContainerStatus' in task['Status']:
636
        print(f"  Container: {task['Status']['ContainerStatus']['ContainerID'][:12]}")
637

638
# Get detailed task information
639
if tasks:
640
    task_detail = client.inspect_task(tasks[0]['ID'])
641
    print(f"Task created: {task_detail['CreatedAt']}")
642
    print(f"Task updated: {task_detail['UpdatedAt']}")
643

644
# Service logs (requires newer API versions)
645
try:
646
    logs = client.logs('web-service', stdout=True, stderr=True)
647
    print("Service logs:", logs.decode('utf-8')[:200])
648
except Exception as e:
649
    print(f"Logs not available: {e}")
650

651
# Remove service
652
client.remove_service('web-service')
653
```
654

655
### Node Management
656

657
```python
658
# List all nodes in the swarm
659
nodes = client.nodes()
660
for node in nodes:
661
    print(f"Node: {node['Description']['Hostname']}")
662
    print(f"  ID: {node['ID'][:12]}")
663
    print(f"  Role: {node['Spec']['Role']}")
664
    print(f"  Status: {node['Status']['State']}")
665
    print(f"  Availability: {node['Spec']['Availability']}")
666

667
# Get detailed node information
668
if nodes:
669
    node_detail = client.inspect_node(nodes[0]['ID'])
670
    resources = node_detail['Description']['Resources']
671
    print(f"Node Resources:")
672
    print(f"  CPUs: {resources['NanoCPUs'] / 1000000000}")
673
    print(f"  Memory: {resources['MemoryBytes'] / (1024**3):.2f} GB")
674
```
675

676
### Swarm Leave and Cleanup
677

678
```python
679
# Leave swarm (on worker node)
680
try:
681
    client.leave_swarm()
682
    print("Left swarm successfully")
683
except Exception as e:
684
    print(f"Error leaving swarm: {e}")
685

686
# Force leave swarm (on manager node)
687
try:
688
    client.leave_swarm(force=True)
689
    print("Force left swarm successfully")  
690
except Exception as e:
691
    print(f"Error force leaving swarm: {e}")
692
```