0
# Docker API Client
1

2
Low-level Docker API client for direct Docker daemon interactions, connection management, and custom Docker operations. The DockerHook provides a thin wrapper around the docker.APIClient for advanced Docker daemon operations not covered by the operators.
3

4
## Capabilities
5

6
### DockerHook
7

8
Interact with Docker Daemon and Container Registry through the Docker API.
9

10
```python { .api }
11
class DockerHook(BaseHook):
12
    conn_name_attr = "docker_conn_id"
13
    default_conn_name = "docker_default"
14
    conn_type = "docker"
15
    hook_name = "Docker"
16
    
17
    def __init__(
18
        self,
19
        docker_conn_id: str | None = "docker_default",
20
        base_url: str | list[str] | None = None,
21
        version: str | None = None,
22
        tls: TLSConfig | bool | None = None,
23
        timeout: int = 60
24
    ) -> None
25
```
26

27
**Parameters:**
28

29
- `docker_conn_id`: Docker connection ID for authentication (default: "docker_default")
30
- `base_url`: URL or list of URLs to Docker server (required)
31
- `version`: API version to use ("auto" for auto-detection, None for latest)
32
- `tls`: TLS configuration (TLSConfig object, True for default TLS, False for no TLS)
33
- `timeout`: Default timeout for API calls in seconds
34

35
### Connection Methods
36

37
```python { .api }
38
def get_conn(self) -> APIClient:
39
    """Get connection to Docker API."""
40

41
@property
42
def api_client(self) -> APIClient:
43
    """Get Docker API client instance."""
44

45
@property  
46
def client_created(self) -> bool:
47
    """Check if client was successfully created."""
48
```
49

50
### TLS Configuration
51

52
```python { .api }
53
@staticmethod
54
def construct_tls_config(
55
    ca_cert: str | None = None,
56
    client_cert: str | None = None, 
57
    client_key: str | None = None,
58
    verify: bool = True,
59
    assert_hostname: str | bool | None = None,
60
    ssl_version: str | None = None
61
) -> TLSConfig | bool:
62
    """
63
    Construct TLS configuration for secure Docker connections.
64
    
65
    Args:
66
        ca_cert: Path to PEM-encoded CA certificate file
67
        client_cert: Path to PEM-encoded certificate file
68
        client_key: Path to PEM-encoded key file
69
        verify: Verify certificate validity
70
        assert_hostname: Hostname to match against server certificate
71
        ssl_version: SSL version to use
72
        
73
    Returns:
74
        TLSConfig object or boolean for TLS enablement
75
    """
76
```
77

78
### Connection Form Configuration
79

80
```python { .api }
81
@classmethod
82
def get_connection_form_widgets(cls) -> dict[str, Any]:
83
    """Get connection form widgets for Airflow UI."""
84

85
@classmethod
86
def get_ui_field_behaviour(cls) -> dict[str, Any]:
87
    """Get UI field behavior configuration."""
88
```
89

90
## Usage Examples
91

92
### Basic Hook Usage
93

94
```python
95
from airflow.providers.docker.hooks.docker import DockerHook
96

97
# Initialize hook with default connection
98
hook = DockerHook(docker_conn_id='docker_default')
99

100
# Get API client
101
client = hook.get_conn()
102

103
# Use client for Docker operations
104
containers = client.containers()
105
images = client.images()
106
```
107

108
### Custom Docker Daemon Connection
109

110
```python
111
# Connect to custom Docker daemon
112
custom_hook = DockerHook(
113
    base_url=['tcp://docker.example.com:2376'],
114
    version='1.41',
115
    timeout=120
116
)
117

118
client = custom_hook.api_client
119

120
# Check daemon info
121
info = client.info()
122
version = client.version()
123
```
124

125
### TLS Secure Connection
126

127
```python
128
from docker import TLSConfig
129

130
# Configure TLS for secure connection
131
tls_config = DockerHook.construct_tls_config(
132
    ca_cert='/path/to/ca.pem',
133
    client_cert='/path/to/cert.pem', 
134
    client_key='/path/to/key.pem',
135
    verify=True,
136
    assert_hostname='docker.example.com'
137
)
138

139
secure_hook = DockerHook(
140
    base_url=['https://docker.example.com:2376'],
141
    tls=tls_config,
142
    docker_conn_id='secure_docker'
143
)
144

145
client = secure_hook.get_conn()
146
```
147

148
### Container Management
149

150
```python
151
# Use hook for direct container operations
152
hook = DockerHook()
153
client = hook.api_client
154

155
# Create container
156
container = client.create_container(
157
    image='alpine:latest',
158
    command=['echo', 'Hello World'],
159
    name='test_container'
160
)
161

162
# Start container
163
client.start(container['Id'])
164

165
# Get logs
166
logs = client.logs(container['Id'])
167

168
# Stop and remove container
169
client.stop(container['Id'])
170
client.remove_container(container['Id'])
171
```
172

173
### Image Management
174

175
```python
176
# Image operations using hook
177
hook = DockerHook()
178
client = hook.api_client
179

180
# Pull image
181
for line in client.pull('python:3.9', stream=True, decode=True):
182
    print(line)
183

184
# List images
185
images = client.images()
186

187
# Build image from Dockerfile
188
buildlogs = client.build(
189
    path='/path/to/dockerfile/dir',
190
    tag='myapp:latest',
191
    rm=True
192
)
193

194
for log in buildlogs:
195
    print(log)
196
```
197

198
### Network Operations
199

200
```python
201
# Network management
202
hook = DockerHook()
203
client = hook.api_client
204

205
# Create network
206
network = client.create_network(
207
    name='custom_network',
208
    driver='bridge',
209
    options={
210
        'com.docker.network.bridge.name': 'custom0'
211
    }
212
)
213

214
# List networks
215
networks = client.networks()
216

217
# Connect container to network
218
client.connect_container_to_network(
219
    container='container_name',
220
    net_id=network['Id']
221
)
222

223
# Remove network
224
client.remove_network(network['Id'])
225
```
226

227
### Volume Management
228

229
```python
230
# Volume operations
231
hook = DockerHook()
232
client = hook.api_client
233

234
# Create volume
235
volume = client.create_volume(
236
    name='data_volume',
237
    driver='local',
238
    driver_opts={
239
        'type': 'nfs',
240
        'o': 'addr=192.168.1.100,rw',
241
        'device': ':/path/to/dir'
242
    }
243
)
244

245
# List volumes
246
volumes = client.volumes()
247

248
# Remove volume
249
client.remove_volume('data_volume')
250
```
251

252
### Registry Authentication
253

254
```python
255
# Authenticate with container registry
256
hook = DockerHook(docker_conn_id='registry_connection')
257
client = hook.api_client
258

259
# Login handled automatically via connection
260
# Push image to registry
261
push_logs = client.push(
262
    repository='registry.example.com/myapp',
263
    tag='v1.0.0',
264
    stream=True,
265
    decode=True
266
)
267

268
for log in push_logs:
269
    print(log.get('status', ''))
270
```
271

272
### Service Discovery
273

274
```python
275
# Swarm service operations
276
hook = DockerHook()
277
client = hook.api_client
278

279
# List services (Swarm mode)
280
services = client.services()
281

282
# Get service details
283
service_info = client.inspect_service('service_id')
284

285
# Update service
286
client.update_service(
287
    service='service_id',
288
    version=service_info['Version']['Index'],
289
    image='myapp:v2.0.0'
290
)
291
```
292

293
## Connection Configuration
294

295
### Airflow Connection Setup
296

297
Configure Docker connections in Airflow UI:
298

299
- **Connection Type**: Docker
300
- **Host**: Docker daemon hostname/IP
301
- **Port**: Docker daemon port (usually 2376 for TLS, 2375 for non-TLS)
302
- **Schema**: Protocol (tcp, unix, ssh)
303
- **Login**: Username for registry authentication
304
- **Password**: Password or token for registry authentication
305

306
### Connection Examples
307

308
**Local Docker daemon:**
309
```
310
Connection Type: Docker
311
Host: unix:///var/run/docker.sock
312
```
313

314
**Remote Docker daemon (non-TLS):**
315
```
316
Connection Type: Docker  
317
Host: tcp://docker.example.com:2375
318
```
319

320
**Remote Docker daemon (TLS):**
321
```
322
Connection Type: Docker
323
Host: tcp://docker.example.com:2376
324
Extra: {"tls": true, "ca_cert": "/path/to/ca.pem"}  
325
```
326

327
**Container registry authentication:**
328
```
329
Connection Type: Docker
330
Host: tcp://localhost:2376
331
Login: username
332
Password: password_or_token
333
```
334

335
## Error Handling
336

337
The hook handles various Docker API errors:
338

339
- **Connection failures**: Network connectivity issues
340
- **Authentication errors**: Invalid credentials or certificates
341
- **API errors**: Docker daemon errors and responses
342
- **Timeout errors**: API call timeouts
343

344
Common exceptions:
345
- `docker.errors.APIError`: Docker API errors
346
- `docker.errors.DockerException`: General Docker client errors
347
- `airflow.exceptions.AirflowException`: Airflow-specific errors