0
# Client APIs
1

2
Comprehensive set of auto-generated API classes providing async access to all Kubernetes API groups and versions. The client module includes 64 API classes and 694 model classes covering the complete Kubernetes API surface.
3

4
## Capabilities
5

6
### Core API Client
7

8
The foundation ApiClient class that handles HTTP communication, authentication, serialization, and deserialization for all Kubernetes API operations.
9

10
```python { .api }
11
class ApiClient:
12
    def __init__(self, configuration=None, header_name=None, header_value=None, 
13
                 cookie=None, pool_threads=1):
14
        """
15
        Initialize API client.
16
        
17
        Parameters:
18
        - configuration: Configuration object with cluster details
19
        - header_name: Custom header name for authentication
20
        - header_value: Custom header value for authentication  
21
        - cookie: Cookie string for authentication
22
        - pool_threads: Number of threads for connection pooling
23
        """
24
    
25
    async def __aenter__(self):
26
        """Async context manager entry."""
27
        
28
    async def __aexit__(self, exc_type, exc_val, exc_tb):
29
        """Async context manager exit with proper cleanup."""
30
        
31
    async def close(self):
32
        """Close all connections and clean up resources."""
33
        
34
    def call_api(self, resource_path, method, path_params=None, query_params=None,
35
                header_params=None, body=None, post_params=None, files=None,
36
                response_type=None, auth_settings=None, collection_formats=None,
37
                _preload_content=True, _request_timeout=None):
38
        """Make HTTP API call with automatic serialization/deserialization."""
39
```
40

41
### Configuration
42

43
Client configuration management for cluster connection details, authentication, and behavior settings.
44

45
```python { .api }
46
class Configuration:
47
    def __init__(self):
48
        """Initialize default configuration."""
49
        
50
    # Connection settings
51
    host: str  # Kubernetes API server URL
52
    ssl_ca_cert: str  # Path to CA certificate file
53
    cert_file: str  # Path to client certificate file
54
    key_file: str  # Path to client private key file
55
    verify_ssl: bool  # Whether to verify SSL certificates
56
    
57
    # Authentication settings  
58
    api_key: dict  # API key authentication mapping
59
    api_key_prefix: dict  # API key prefix mapping
60
    username: str  # Basic auth username
61
    password: str  # Basic auth password
62
    
63
    # Client behavior
64
    client_side_validation: bool  # Enable client-side validation
65
    discard_unknown_keys: bool  # Ignore unknown properties in responses
66
    timeout: int  # Request timeout in seconds
67
```
68

69
### Core V1 API
70

71
Primary API for managing core Kubernetes resources like pods, services, namespaces, nodes, secrets, and config maps.
72

73
```python { .api }
74
class CoreV1Api:
75
    def __init__(self, api_client=None):
76
        """Initialize Core V1 API client."""
77
    
78
    # Pod operations
79
    async def list_pod_for_all_namespaces(self, **kwargs):
80
        """List all pods across all namespaces."""
81
        
82
    async def list_namespaced_pod(self, namespace: str, **kwargs):
83
        """List pods in a specific namespace."""
84
        
85
    async def create_namespaced_pod(self, namespace: str, body: V1Pod, **kwargs):
86
        """Create a new pod in the specified namespace."""
87
        
88
    async def read_namespaced_pod(self, name: str, namespace: str, **kwargs):
89
        """Read details of a specific pod."""
90
        
91
    async def patch_namespaced_pod(self, name: str, namespace: str, body: object, **kwargs):
92
        """Partially update a pod."""
93
        
94
    async def delete_namespaced_pod(self, name: str, namespace: str, **kwargs):
95
        """Delete a pod."""
96
        
97
    # Service operations
98
    async def list_namespaced_service(self, namespace: str, **kwargs):
99
        """List services in a namespace."""
100
        
101
    async def create_namespaced_service(self, namespace: str, body: V1Service, **kwargs):
102
        """Create a new service."""
103
        
104
    async def read_namespaced_service(self, name: str, namespace: str, **kwargs):
105
        """Read service details."""
106
        
107
    async def patch_namespaced_service(self, name: str, namespace: str, body: object, **kwargs):
108
        """Update a service."""
109
        
110
    async def delete_namespaced_service(self, name: str, namespace: str, **kwargs):
111
        """Delete a service."""
112
        
113
    # Namespace operations
114
    async def list_namespace(self, **kwargs):
115
        """List all namespaces."""
116
        
117
    async def create_namespace(self, body: V1Namespace, **kwargs):
118
        """Create a new namespace."""
119
        
120
    async def read_namespace(self, name: str, **kwargs):
121
        """Read namespace details."""
122
        
123
    async def delete_namespace(self, name: str, **kwargs):
124
        """Delete a namespace."""
125
        
126
    # Node operations
127
    async def list_node(self, **kwargs):
128
        """List all nodes in the cluster."""
129
        
130
    async def read_node(self, name: str, **kwargs):
131
        """Read node details."""
132
        
133
    async def patch_node(self, name: str, body: object, **kwargs):
134
        """Update node labels, annotations, or spec."""
135
        
136
    # Secret operations
137
    async def list_namespaced_secret(self, namespace: str, **kwargs):
138
        """List secrets in a namespace."""
139
        
140
    async def create_namespaced_secret(self, namespace: str, body: V1Secret, **kwargs):
141
        """Create a new secret."""
142
        
143
    async def read_namespaced_secret(self, name: str, namespace: str, **kwargs):
144
        """Read secret details."""
145
        
146
    async def patch_namespaced_secret(self, name: str, namespace: str, body: object, **kwargs):
147
        """Update a secret."""
148
        
149
    async def delete_namespaced_secret(self, name: str, namespace: str, **kwargs):
150
        """Delete a secret."""
151
        
152
    # ConfigMap operations  
153
    async def list_namespaced_config_map(self, namespace: str, **kwargs):
154
        """List config maps in a namespace."""
155
        
156
    async def create_namespaced_config_map(self, namespace: str, body: V1ConfigMap, **kwargs):
157
        """Create a new config map."""
158
        
159
    async def read_namespaced_config_map(self, name: str, namespace: str, **kwargs):
160
        """Read config map details."""
161
        
162
    async def patch_namespaced_config_map(self, name: str, namespace: str, body: object, **kwargs):
163
        """Update a config map."""
164
        
165
    async def delete_namespaced_config_map(self, name: str, namespace: str, **kwargs):
166
        """Delete a config map."""
167
```
168

169
### Apps V1 API
170

171
API for managing application workloads including deployments, replica sets, daemon sets, and stateful sets.
172

173
```python { .api }
174
class AppsV1Api:
175
    def __init__(self, api_client=None):
176
        """Initialize Apps V1 API client."""
177
    
178
    # Deployment operations
179
    async def list_namespaced_deployment(self, namespace: str, **kwargs):
180
        """List deployments in a namespace."""
181
        
182
    async def create_namespaced_deployment(self, namespace: str, body: V1Deployment, **kwargs):
183
        """Create a new deployment."""
184
        
185
    async def read_namespaced_deployment(self, name: str, namespace: str, **kwargs):
186
        """Read deployment details."""
187
        
188
    async def patch_namespaced_deployment(self, name: str, namespace: str, body: object, **kwargs):
189
        """Update a deployment."""
190
        
191
    async def delete_namespaced_deployment(self, name: str, namespace: str, **kwargs):
192
        """Delete a deployment."""
193
        
194
    # ReplicaSet operations
195
    async def list_namespaced_replica_set(self, namespace: str, **kwargs):
196
        """List replica sets in a namespace."""
197
        
198
    async def create_namespaced_replica_set(self, namespace: str, body: V1ReplicaSet, **kwargs):
199
        """Create a new replica set."""
200
        
201
    # DaemonSet operations
202
    async def list_namespaced_daemon_set(self, namespace: str, **kwargs):
203
        """List daemon sets in a namespace."""
204
        
205
    async def create_namespaced_daemon_set(self, namespace: str, body: V1DaemonSet, **kwargs):
206
        """Create a new daemon set."""
207
        
208
    # StatefulSet operations
209
    async def list_namespaced_stateful_set(self, namespace: str, **kwargs):
210
        """List stateful sets in a namespace."""
211
        
212
    async def create_namespaced_stateful_set(self, namespace: str, body: V1StatefulSet, **kwargs):
213
        """Create a new stateful set."""
214
```
215

216
### Batch V1 API
217

218
API for managing batch workloads including jobs and cron jobs.
219

220
```python { .api }
221
class BatchV1Api:
222
    def __init__(self, api_client=None):
223
        """Initialize Batch V1 API client."""
224
    
225
    # Job operations
226
    async def list_namespaced_job(self, namespace: str, **kwargs):
227
        """List jobs in a namespace."""
228
        
229
    async def create_namespaced_job(self, namespace: str, body: V1Job, **kwargs):
230
        """Create a new job."""
231
        
232
    async def read_namespaced_job(self, name: str, namespace: str, **kwargs):
233
        """Read job details."""
234
        
235
    async def delete_namespaced_job(self, name: str, namespace: str, **kwargs):
236
        """Delete a job."""
237
        
238
    # CronJob operations
239
    async def list_namespaced_cron_job(self, namespace: str, **kwargs):
240
        """List cron jobs in a namespace."""
241
        
242
    async def create_namespaced_cron_job(self, namespace: str, body: V1CronJob, **kwargs):
243
        """Create a new cron job."""
244
        
245
    async def read_namespaced_cron_job(self, name: str, namespace: str, **kwargs):
246
        """Read cron job details."""
247
        
248
    async def patch_namespaced_cron_job(self, name: str, namespace: str, body: object, **kwargs):
249
        """Update a cron job."""
250
        
251
    async def delete_namespaced_cron_job(self, name: str, namespace: str, **kwargs):
252
        """Delete a cron job."""
253
```
254

255
### Custom Objects API
256

257
API for managing custom resources defined by Custom Resource Definitions (CRDs).
258

259
```python { .api }
260
class CustomObjectsApi:
261
    def __init__(self, api_client=None):
262
        """Initialize Custom Objects API client."""
263
    
264
    async def list_cluster_custom_object(self, group: str, version: str, plural: str, **kwargs):
265
        """List custom objects across all namespaces."""
266
        
267
    async def list_namespaced_custom_object(self, group: str, version: str, namespace: str, 
268
                                           plural: str, **kwargs):
269
        """List custom objects in a specific namespace."""
270
        
271
    async def create_namespaced_custom_object(self, group: str, version: str, namespace: str,
272
                                             plural: str, body: object, **kwargs):
273
        """Create a custom object."""
274
        
275
    async def get_namespaced_custom_object(self, group: str, version: str, namespace: str,
276
                                          plural: str, name: str, **kwargs):
277
        """Get a specific custom object."""
278
        
279
    async def patch_namespaced_custom_object(self, group: str, version: str, namespace: str,
280
                                            plural: str, name: str, body: object, **kwargs):
281
        """Update a custom object."""
282
        
283
    async def delete_namespaced_custom_object(self, group: str, version: str, namespace: str,
284
                                             plural: str, name: str, **kwargs):
285
        """Delete a custom object."""
286
```
287

288
## Key Model Classes
289

290
### Core Resource Models
291

292
```python { .api }
293
class V1Pod:
294
    def __init__(self, api_version=None, kind=None, metadata=None, spec=None, status=None):
295
        """Pod resource model."""
296
        
297
class V1PodSpec:
298
    def __init__(self, containers, volumes=None, restart_policy=None, node_name=None, 
299
                 service_account_name=None, **kwargs):
300
        """Pod specification."""
301
        
302
class V1Container:
303
    def __init__(self, name: str, image: str, ports=None, env=None, volume_mounts=None,
304
                 resources=None, **kwargs):
305
        """Container specification."""
306
        
307
class V1Service:
308
    def __init__(self, api_version=None, kind=None, metadata=None, spec=None, status=None):
309
        """Service resource model."""
310
        
311
class V1ServiceSpec:
312
    def __init__(self, ports=None, selector=None, type=None, cluster_ip=None, **kwargs):
313
        """Service specification."""
314
        
315
class V1Deployment:
316
    def __init__(self, api_version=None, kind=None, metadata=None, spec=None, status=None):
317
        """Deployment resource model."""
318
        
319
class V1DeploymentSpec:
320
    def __init__(self, replicas=None, selector=None, template=None, strategy=None, **kwargs):
321
        """Deployment specification."""
322
```
323

324
### Common Types
325

326
```python { .api }
327
class V1ObjectMeta:
328
    def __init__(self, name=None, namespace=None, labels=None, annotations=None, **kwargs):
329
        """Object metadata common to all resources."""
330
        
331
class V1LabelSelector:
332
    def __init__(self, match_labels=None, match_expressions=None):
333
        """Label selector for identifying resources."""
334
        
335
class V1Status:
336
    def __init__(self, kind=None, api_version=None, metadata=None, status=None,
337
                 message=None, reason=None, code=None, **kwargs):
338
        """Status response from API operations."""
339
        
340
class V1DeleteOptions:
341
    def __init__(self, grace_period_seconds=None, propagation_policy=None, **kwargs):
342
        """Options for delete operations."""
343
```
344

345
## Usage Examples
346

347
### Basic Resource Management
348

349
```python
350
import asyncio
351
from kubernetes_asyncio import client, config
352

353
async def manage_pods():
354
    await config.load_config()
355
    v1 = client.CoreV1Api()
356
    
357
    try:
358
        # Create a pod
359
        pod = client.V1Pod(
360
            api_version="v1",
361
            kind="Pod", 
362
            metadata=client.V1ObjectMeta(name="test-pod", namespace="default"),
363
            spec=client.V1PodSpec(
364
                containers=[
365
                    client.V1Container(
366
                        name="test-container",
367
                        image="nginx:latest",
368
                        ports=[client.V1ContainerPort(container_port=80)]
369
                    )
370
                ]
371
            )
372
        )
373
        
374
        result = await v1.create_namespaced_pod(namespace="default", body=pod)
375
        print(f"Pod created: {result.metadata.name}")
376
        
377
        # List pods
378
        pod_list = await v1.list_namespaced_pod(namespace="default")
379
        for pod in pod_list.items:
380
            print(f"Found pod: {pod.metadata.name} - {pod.status.phase}")
381
            
382
    finally:
383
        await v1.api_client.close()
384

385
asyncio.run(manage_pods())
386
```
387

388
### Working with Deployments
389

390
```python
391
async def manage_deployment():
392
    await config.load_config()
393
    apps_v1 = client.AppsV1Api()
394
    
395
    try:
396
        # Create deployment
397
        deployment = client.V1Deployment(
398
            api_version="apps/v1",
399
            kind="Deployment",
400
            metadata=client.V1ObjectMeta(name="nginx-deployment", namespace="default"),
401
            spec=client.V1DeploymentSpec(
402
                replicas=3,
403
                selector=client.V1LabelSelector(
404
                    match_labels={"app": "nginx"}
405
                ),
406
                template=client.V1PodTemplateSpec(
407
                    metadata=client.V1ObjectMeta(labels={"app": "nginx"}),
408
                    spec=client.V1PodSpec(
409
                        containers=[
410
                            client.V1Container(
411
                                name="nginx",
412
                                image="nginx:1.20",
413
                                ports=[client.V1ContainerPort(container_port=80)]
414
                            )
415
                        ]
416
                    )
417
                )
418
            )
419
        )
420
        
421
        result = await apps_v1.create_namespaced_deployment(namespace="default", body=deployment)
422
        print(f"Deployment created: {result.metadata.name}")
423
        
424
    finally:
425
        await apps_v1.api_client.close()
426
```