0
# Configuration and Utilities
1
2
Comprehensive utility functions, type classes, and configuration helpers that support Docker-py's core functionality. Includes data conversion utilities, authentication management, TLS configuration, and transport adapters for specialized connection types.
3
4
## Capabilities
5
6
### Configuration Creation Utilities
7
8
Helper functions for building complex Docker API configurations with proper validation and formatting.
9
10
```python { .api }
11
def create_host_config(binds=None, port_bindings=None, lxc_conf=None,
12
publish_all_ports=False, links=None, privileged=False,
13
dns=None, dns_search=None, volumes_from=None,
14
network_mode=None, restart_policy=None, cap_add=None,
15
cap_drop=None, devices=None, extra_hosts=None,
16
read_only=None, pid_mode=None, ipc_mode=None,
17
security_opt=None, ulimits=None, log_config=None,
18
mem_limit=None, memswap_limit=None, cpu_shares=None,
19
cpuset_cpus=None, cpuset_mems=None, **kwargs):
20
"""
21
Create host configuration for containers.
22
23
Parameters:
24
- binds (dict|list): Volume bindings
25
- port_bindings (dict): Port bindings mapping
26
- lxc_conf (dict): LXC configuration options
27
- publish_all_ports (bool): Publish all exposed ports to random host ports
28
- links (list): Container links (deprecated)
29
- privileged (bool): Run container in privileged mode
30
- dns (list): Custom DNS servers
31
- dns_search (list): Custom DNS search domains
32
- volumes_from (list): Mount volumes from other containers
33
- network_mode (str): Network mode ('bridge', 'host', 'none', etc.)
34
- restart_policy (dict): Restart policy configuration
35
- cap_add (list): Linux capabilities to add
36
- cap_drop (list): Linux capabilities to drop
37
- devices (list): Device mappings
38
- extra_hosts (list): Extra host entries for /etc/hosts
39
- read_only (bool): Mount root filesystem as read-only
40
- pid_mode (str): PID namespace mode
41
- ipc_mode (str): IPC namespace mode
42
- security_opt (list): Security options
43
- ulimits (list): Resource limits (Ulimit objects)
44
- log_config (LogConfig): Logging configuration
45
- mem_limit (int|str): Memory limit
46
- memswap_limit (int|str): Memory + swap limit
47
- cpu_shares (int): CPU shares (relative weight)
48
- cpuset_cpus (str): CPUs to use
49
- cpuset_mems (str): Memory nodes to use
50
51
Returns:
52
dict: Host configuration dictionary
53
"""
54
55
def create_container_config(image, command=None, hostname=None, user=None,
56
detach=False, stdin_open=False, tty=False,
57
mem_limit=None, ports=None, environment=None,
58
dns=None, volumes=None, volumes_from=None,
59
network_disabled=False, name=None, entrypoint=None,
60
cpu_shares=None, working_dir=None, domainname=None,
61
memswap_limit=None, cpuset=None, host_config=None,
62
mac_address=None, labels=None, volume_driver=None,
63
stop_signal=None, networking_config=None, **kwargs):
64
"""
65
Create container configuration dictionary.
66
67
Parameters:
68
- image (str): Image name or ID
69
- command (str|list): Command to run
70
- hostname (str): Container hostname
71
- user (str): Username or UID
72
- detach (bool): Run in detached mode
73
- stdin_open (bool): Keep STDIN open
74
- tty (bool): Allocate pseudo-TTY
75
- mem_limit (int|str): Memory limit
76
- ports (list): Ports to expose
77
- environment (dict|list): Environment variables
78
- dns (list): DNS servers
79
- volumes (list): Volume mount points
80
- volumes_from (list): Volumes from other containers
81
- network_disabled (bool): Disable networking
82
- name (str): Container name
83
- entrypoint (str|list): Override default entrypoint
84
- cpu_shares (int): CPU shares
85
- working_dir (str): Working directory
86
- domainname (str): Domain name
87
- memswap_limit (int): Memory + swap limit
88
- cpuset (str): CPUs to use
89
- host_config (dict): Host configuration
90
- mac_address (str): MAC address
91
- labels (dict): Container labels
92
- volume_driver (str): Volume driver
93
- stop_signal (str): Stop signal
94
- networking_config (dict): Network configuration
95
96
Returns:
97
dict: Container configuration dictionary
98
"""
99
100
def create_networking_config(endpoints_config=None):
101
"""
102
Create networking configuration for containers.
103
104
Parameters:
105
- endpoints_config (dict): Endpoint configurations by network name
106
107
Returns:
108
dict: Networking configuration dictionary
109
"""
110
111
def create_endpoint_config(version, aliases=None, links=None,
112
ipv4_address=None, ipv6_address=None,
113
link_local_ips=None):
114
"""
115
Create endpoint configuration for network connections.
116
117
Parameters:
118
- version (str): API version
119
- aliases (list): Network-scoped aliases
120
- links (list): Container links (deprecated)
121
- ipv4_address (str): Static IPv4 address
122
- ipv6_address (str): Static IPv6 address
123
- link_local_ips (list): Link-local IP addresses
124
125
Returns:
126
dict: Endpoint configuration dictionary
127
"""
128
```
129
130
### Data Conversion Functions
131
132
Functions for converting data between different formats required by the Docker API.
133
134
```python { .api }
135
def convert_port_bindings(port_bindings):
136
"""
137
Convert port bindings to Docker API format.
138
139
Parameters:
140
- port_bindings (dict): Port bindings mapping
141
142
Returns:
143
dict: Formatted port bindings for API
144
"""
145
146
def convert_volume_binds(binds):
147
"""
148
Convert volume bindings to Docker API format.
149
150
Parameters:
151
- binds (dict|list): Volume bindings
152
153
Returns:
154
list: Formatted volume bindings for API
155
"""
156
157
def convert_filters(filters):
158
"""
159
Convert filter dictionary to Docker API format.
160
161
Parameters:
162
- filters (dict): Filter conditions
163
164
Returns:
165
str: JSON-encoded filters for API
166
"""
167
168
def format_environment(environment):
169
"""
170
Format environment variables for Docker API.
171
172
Parameters:
173
- environment (dict|list): Environment variables
174
175
Returns:
176
list: Formatted environment variables
177
"""
178
```
179
180
### Parsing Functions
181
182
Functions for parsing various Docker-related data formats and specifications.
183
184
```python { .api }
185
def parse_repository_tag(repo_name):
186
"""
187
Parse repository name and tag from image specification.
188
189
Parameters:
190
- repo_name (str): Repository name with optional tag
191
192
Returns:
193
tuple: (repository, tag) where tag defaults to 'latest'
194
"""
195
196
def parse_host(addr, is_win32=False, tls=False):
197
"""
198
Parse Docker host address into connection components.
199
200
Parameters:
201
- addr (str): Docker host address (tcp://, unix://, npipe://)
202
- is_win32 (bool): Windows platform flag
203
- tls (bool): TLS enabled flag
204
205
Returns:
206
tuple: (protocol, host, port, base_url)
207
"""
208
209
def parse_devices(devices):
210
"""
211
Parse device specifications into Docker API format.
212
213
Parameters:
214
- devices (list): Device specifications
215
216
Returns:
217
list: Formatted device mappings
218
"""
219
220
def parse_bytes(s):
221
"""
222
Parse byte size string into integer bytes.
223
224
Parameters:
225
- s (str): Size string (e.g., '512m', '1g', '2048k')
226
227
Returns:
228
int: Size in bytes
229
"""
230
231
def parse_env_file(env_file):
232
"""
233
Parse environment file into environment variables.
234
235
Parameters:
236
- env_file (str): Path to environment file
237
238
Returns:
239
dict: Environment variables from file
240
"""
241
242
def split_command(command):
243
"""
244
Split command string into array of arguments.
245
246
Parameters:
247
- command (str): Command string
248
249
Returns:
250
list: Command arguments array
251
"""
252
253
def normalize_links(links):
254
"""
255
Normalize container links to standard format.
256
257
Parameters:
258
- links (list): Container links
259
260
Returns:
261
list: Normalized link specifications
262
"""
263
```
264
265
### Build and Archive Utilities
266
267
Functions for creating build contexts, tar archives, and handling Dockerfiles.
268
269
```python { .api }
270
def mkbuildcontext(dockerfile):
271
"""
272
Create build context from Dockerfile content.
273
274
Parameters:
275
- dockerfile (str): Dockerfile content
276
277
Returns:
278
file: File-like object containing build context
279
"""
280
281
def tar(path, exclude=None, dockerfile=None, fileobj=None, gzip=False):
282
"""
283
Create tar archive from directory path.
284
285
Parameters:
286
- path (str): Directory path to archive
287
- exclude (list): Patterns to exclude (from .dockerignore)
288
- dockerfile (str): Custom Dockerfile content
289
- fileobj (file): File-like object to write to
290
- gzip (bool): Use gzip compression
291
292
Returns:
293
file: Tar archive file-like object
294
"""
295
296
def exclude_paths(root, patterns, dockerfile=None):
297
"""
298
Get list of paths that should be excluded from build context.
299
300
Parameters:
301
- root (str): Root directory path
302
- patterns (list): Exclusion patterns from .dockerignore
303
- dockerfile (str): Dockerfile name
304
305
Returns:
306
set: Set of paths to exclude
307
"""
308
```
309
310
### Version Comparison Utilities
311
312
Functions for comparing Docker API versions.
313
314
```python { .api }
315
def compare_version(v1, v2):
316
"""
317
Compare two Docker API version strings.
318
319
Parameters:
320
- v1 (str): First version
321
- v2 (str): Second version
322
323
Returns:
324
int: -1 if v1 < v2, 0 if equal, 1 if v1 > v2
325
"""
326
327
def version_lt(v1, v2):
328
"""
329
Check if version v1 is less than v2.
330
331
Parameters:
332
- v1 (str): First version
333
- v2 (str): Second version
334
335
Returns:
336
bool: True if v1 < v2
337
"""
338
339
def version_gte(v1, v2):
340
"""
341
Check if version v1 is greater than or equal to v2.
342
343
Parameters:
344
- v1 (str): First version
345
- v2 (str): Second version
346
347
Returns:
348
bool: True if v1 >= v2
349
"""
350
```
351
352
### Environment and Configuration
353
354
Functions for working with Docker environment configuration.
355
356
```python { .api }
357
def kwargs_from_env(ssl_version=None, assert_hostname=None, environment=None):
358
"""
359
Get Docker client configuration from environment variables.
360
361
Parameters:
362
- ssl_version (str): SSL version for TLS connections
363
- assert_hostname (bool): Verify hostname in TLS certificates
364
- environment (dict): Environment variables dict (defaults to os.environ)
365
366
Returns:
367
dict: Client configuration parameters
368
"""
369
370
def datetime_to_timestamp(dt):
371
"""
372
Convert datetime object to Unix timestamp.
373
374
Parameters:
375
- dt (datetime): Datetime object
376
377
Returns:
378
int: Unix timestamp
379
"""
380
381
def decode_json_header(header):
382
"""
383
Decode base64 JSON header.
384
385
Parameters:
386
- header (str): Base64-encoded JSON header
387
388
Returns:
389
dict: Decoded JSON data
390
"""
391
```
392
393
## Authentication Functions
394
395
Docker registry authentication utilities for managing credentials and login tokens.
396
397
```python { .api }
398
def resolve_repository_name(repo_name):
399
"""
400
Parse repository name and determine registry.
401
402
Parameters:
403
- repo_name (str): Repository name
404
405
Returns:
406
tuple: (registry_name, repository_name)
407
"""
408
409
def resolve_authconfig(authconfig, registry=None):
410
"""
411
Resolve authentication configuration for a registry.
412
413
Parameters:
414
- authconfig (dict): Authentication configurations
415
- registry (str): Registry URL
416
417
Returns:
418
dict: Authentication configuration for registry
419
"""
420
421
def load_config(config_path=None):
422
"""
423
Load Docker configuration file.
424
425
Parameters:
426
- config_path (str): Path to config file (defaults to ~/.docker/config.json)
427
428
Returns:
429
dict: Docker configuration data
430
"""
431
432
def encode_header(auth_config):
433
"""
434
Encode authentication configuration for HTTP header.
435
436
Parameters:
437
- auth_config (dict): Authentication configuration
438
439
Returns:
440
str: Base64-encoded authentication header
441
"""
442
443
def get_config_header(client, registry):
444
"""
445
Get authentication header for registry from client configuration.
446
447
Parameters:
448
- client: Docker client instance
449
- registry (str): Registry URL
450
451
Returns:
452
str: Authentication header value
453
"""
454
```
455
456
## TLS Configuration
457
458
Comprehensive TLS/SSL configuration for secure Docker daemon connections.
459
460
```python { .api }
461
class TLSConfig:
462
def __init__(self, client_cert=None, ca_cert=None, verify=None,
463
ssl_version=None, assert_hostname=None, assert_fingerprint=None):
464
"""
465
Create TLS configuration for Docker client.
466
467
Parameters:
468
- client_cert (tuple): (cert_file, key_file) for client authentication
469
- ca_cert (str): Path to CA certificate file
470
- verify (bool|str): Verify server certificate (True/False or CA path)
471
- ssl_version (int): SSL version constant
472
- assert_hostname (bool): Verify hostname in certificate
473
- assert_fingerprint (str): Expected certificate fingerprint
474
"""
475
476
def configure_client(self, client):
477
"""
478
Configure requests client for TLS connections.
479
480
Parameters:
481
- client: Requests session client
482
483
Returns:
484
None
485
"""
486
487
# Properties
488
cert: tuple # Client certificate tuple
489
ca_cert: str # CA certificate path
490
verify: bool|str # Certificate verification setting
491
ssl_version: int # SSL version
492
assert_hostname: bool # Hostname verification
493
assert_fingerprint: str # Certificate fingerprint
494
```
495
496
## Transport Adapters
497
498
Specialized HTTP adapters for different connection types and platforms.
499
500
### UnixAdapter
501
502
HTTP adapter for Unix socket connections on Linux/macOS systems.
503
504
```python { .api }
505
class UnixAdapter:
506
def __init__(self, socket_url, timeout=60, num_pools=25):
507
"""
508
Create Unix socket HTTP adapter.
509
510
Parameters:
511
- socket_url (str): Unix socket URL
512
- timeout (int): Connection timeout
513
- num_pools (int): Connection pool size
514
"""
515
516
class UnixHTTPConnection:
517
"""HTTP connection over Unix socket"""
518
519
class UnixHTTPConnectionPool:
520
"""Connection pool for Unix socket connections"""
521
```
522
523
### NpipeAdapter (Windows)
524
525
HTTP adapter for Windows named pipes.
526
527
```python { .api }
528
class NpipeAdapter:
529
def __init__(self, socket_url, timeout=60, num_pools=25):
530
"""
531
Create named pipe HTTP adapter (Windows only).
532
533
Parameters:
534
- socket_url (str): Named pipe URL
535
- timeout (int): Connection timeout
536
- num_pools (int): Connection pool size
537
"""
538
```
539
540
### SSLAdapter
541
542
HTTPS adapter with configurable SSL/TLS settings.
543
544
```python { .api }
545
class SSLAdapter:
546
def __init__(self, ssl_version=None, assert_hostname=None,
547
assert_fingerprint=None, **kwargs):
548
"""
549
Create SSL/TLS HTTP adapter.
550
551
Parameters:
552
- ssl_version (int): SSL version to use
553
- assert_hostname (bool): Verify hostname
554
- assert_fingerprint (str): Expected certificate fingerprint
555
"""
556
```
557
558
## Decorator Functions
559
560
Decorators for API method enhancement and validation.
561
562
```python { .api }
563
def check_resource(f):
564
"""
565
Decorator to extract resource ID from function arguments.
566
567
Parameters:
568
- f (function): Function to decorate
569
570
Returns:
571
function: Decorated function
572
"""
573
574
def minimum_version(version):
575
"""
576
Decorator to require minimum Docker API version.
577
578
Parameters:
579
- version (str): Minimum required API version
580
581
Returns:
582
function: Decorator function
583
"""
584
585
def update_headers(f):
586
"""
587
Decorator to automatically add authentication headers.
588
589
Parameters:
590
- f (function): Function to decorate
591
592
Returns:
593
function: Decorated function
594
"""
595
```
596
597
## Socket Utilities
598
599
Low-level socket operations for Docker API communication.
600
601
```python { .api }
602
def read(socket, n=4096):
603
"""
604
Read bytes from socket with error handling.
605
606
Parameters:
607
- socket: Socket object
608
- n (int): Number of bytes to read
609
610
Returns:
611
bytes: Data read from socket
612
"""
613
614
def read_exactly(socket, n):
615
"""
616
Read exact number of bytes from socket.
617
618
Parameters:
619
- socket: Socket object
620
- n (int): Exact number of bytes to read
621
622
Returns:
623
bytes: Exactly n bytes of data
624
"""
625
626
def next_frame_size(socket):
627
"""
628
Get size of next frame from multiplexed stream.
629
630
Parameters:
631
- socket: Socket object
632
633
Returns:
634
int: Size of next frame
635
"""
636
637
def frames_iter(socket):
638
"""
639
Iterator over frames from multiplexed socket stream.
640
641
Parameters:
642
- socket: Socket object
643
644
Yields:
645
bytes: Frame data
646
"""
647
648
class SocketError(Exception):
649
"""Exception for socket operation errors"""
650
```
651
652
## Port Utilities
653
654
Functions for handling Docker port specifications and bindings.
655
656
```python { .api }
657
def split_port(port):
658
"""
659
Parse port specification string.
660
661
Parameters:
662
- port (str): Port specification (e.g., '8080:80/tcp')
663
664
Returns:
665
tuple: (host_port, container_port, protocol)
666
"""
667
668
def build_port_bindings(ports):
669
"""
670
Build port bindings dictionary from port list.
671
672
Parameters:
673
- ports (list): List of port specifications
674
675
Returns:
676
dict: Port bindings mapping
677
"""
678
```
679
680
## Usage Examples
681
682
### Using Configuration Helpers
683
684
```python
685
import docker
686
from docker.types import LogConfig, Ulimit
687
688
client = docker.Client()
689
690
# Create comprehensive host configuration
691
host_config = client.create_host_config(
692
# Volume bindings
693
binds={
694
'/host/data': {'bind': '/container/data', 'mode': 'rw'},
695
'/host/logs': {'bind': '/container/logs', 'mode': 'rw'}
696
},
697
698
# Port bindings
699
port_bindings={
700
'8080/tcp': 8080,
701
'9000/tcp': ('127.0.0.1', 9000)
702
},
703
704
# Resource limits
705
mem_limit='512m',
706
cpu_shares=512,
707
ulimits=[
708
Ulimit(name='nofile', soft=1024, hard=2048),
709
Ulimit(name='nproc', soft=128, hard=256)
710
],
711
712
# Security settings
713
privileged=False,
714
cap_add=['NET_ADMIN'],
715
cap_drop=['MKNOD'],
716
717
# Network settings
718
dns=['8.8.8.8', '8.8.4.4'],
719
extra_hosts=['api.example.com:192.168.1.100'],
720
721
# Logging configuration
722
log_config=LogConfig(
723
type=LogConfig.types.JSON,
724
config={'max-size': '10m', 'max-file': '3'}
725
),
726
727
# Restart policy
728
restart_policy={'Name': 'unless-stopped'}
729
)
730
731
# Create container with configuration
732
container = client.create_container(
733
image='myapp:latest',
734
command=['python', 'app.py'],
735
environment={'ENV': 'production'},
736
host_config=host_config,
737
labels={'app': 'myservice', 'version': '1.0'}
738
)
739
```
740
741
### Working with Authentication
742
743
```python
744
from docker.auth import auth
745
746
# Load Docker configuration
747
config = auth.load_config()
748
print(f"Loaded config with {len(config.get('auths', {}))} registries")
749
750
# Resolve authentication for specific registry
751
auth_config = auth.resolve_authconfig(
752
config.get('auths', {}),
753
'registry.example.com'
754
)
755
756
# Use authentication for image operations
757
client.pull(
758
'registry.example.com/private/image:latest',
759
auth_config=auth_config
760
)
761
762
# Manual authentication configuration
763
manual_auth = {
764
'username': 'myuser',
765
'password': 'mypass',
766
'serveraddress': 'https://registry.example.com'
767
}
768
769
# Encode for header use
770
auth_header = auth.encode_header(manual_auth)
771
```
772
773
### TLS Configuration
774
775
```python
776
from docker.tls import TLSConfig
777
import ssl
778
779
# Create TLS configuration for secure connection
780
tls_config = TLSConfig(
781
client_cert=('/path/to/client-cert.pem', '/path/to/client-key.pem'),
782
ca_cert='/path/to/ca.pem',
783
verify=True,
784
ssl_version=ssl.PROTOCOL_TLSv1_2,
785
assert_hostname=False
786
)
787
788
# Create client with TLS
789
client = docker.Client(
790
base_url='https://docker-daemon:2376',
791
tls=tls_config
792
)
793
794
# Verify connection
795
print(client.ping())
796
```
797
798
### Environment Configuration
799
800
```python
801
import os
802
from docker.utils.utils import kwargs_from_env
803
804
# Set environment variables
805
os.environ['DOCKER_HOST'] = 'tcp://192.168.1.100:2376'
806
os.environ['DOCKER_TLS_VERIFY'] = '1'
807
os.environ['DOCKER_CERT_PATH'] = '/path/to/certs'
808
809
# Get client configuration from environment
810
client_kwargs = kwargs_from_env()
811
print(f"Client config: {client_kwargs}")
812
813
# Create client from environment
814
client = docker.Client(**client_kwargs)
815
816
# Alternative: use from_env convenience function
817
client = docker.from_env()
818
```
819
820
### Advanced Parsing and Conversion
821
822
```python
823
from docker.utils.utils import (
824
parse_repository_tag, parse_bytes, convert_port_bindings,
825
convert_volume_binds, split_command
826
)
827
828
# Parse repository and tag
829
repo, tag = parse_repository_tag('nginx:1.21-alpine')
830
print(f"Repository: {repo}, Tag: {tag}")
831
832
# Parse byte sizes
833
memory_limit = parse_bytes('512m') # Returns 536870912
834
cpu_limit = parse_bytes('1g') # Returns 1073741824
835
836
# Convert port bindings
837
port_bindings = convert_port_bindings({
838
'8080/tcp': 8080,
839
'9000/tcp': ('0.0.0.0', 9000),
840
'3306/tcp': None # Random port
841
})
842
843
# Convert volume bindings
844
volume_binds = convert_volume_binds({
845
'/host/data': {'bind': '/app/data', 'mode': 'rw'},
846
'/host/config': {'bind': '/app/config', 'mode': 'ro'}
847
})
848
849
# Split command strings
850
cmd_array = split_command('python -m http.server 8000')
851
print(f"Command array: {cmd_array}")
852
```
853
854
### Build Context Creation
855
856
```python
857
from docker.utils.utils import tar, exclude_paths
858
import tempfile
859
860
# Create build context from directory
861
with tar('/path/to/build/context', gzip=True) as build_context:
862
# Build image using context
863
for line in client.build(
864
fileobj=build_context,
865
tag='myapp:latest',
866
custom_context=True,
867
stream=True,
868
decode=True
869
):
870
if 'stream' in line:
871
print(line['stream'].strip())
872
873
# Handle .dockerignore patterns
874
root_path = '/path/to/project'
875
dockerignore_patterns = [
876
'*.pyc',
877
'__pycache__/',
878
'.git/',
879
'node_modules/',
880
'*.log'
881
]
882
883
excluded_paths = exclude_paths(root_path, dockerignore_patterns)
884
print(f"Excluding {len(excluded_paths)} paths from build context")
885
```