0
# Autoscaling
1

2
Horizontal Pod Autoscaler (HPA) management for automatic scaling of deployments, replica sets, and other scalable resources based on CPU, memory, or custom metrics.
3

4
## Capabilities
5

6
### Horizontal Pod Autoscaler V1
7

8
Basic horizontal pod autoscaling based on CPU utilization metrics.
9

10
```python { .api }
11
class AutoscalingV1Api:
12
    def create_namespaced_horizontal_pod_autoscaler(
13
        self,
14
        namespace: str,
15
        body: V1HorizontalPodAutoscaler,
16
        dry_run: str = None,
17
        field_manager: str = None,
18
        pretty: str = None
19
    ) -> V1HorizontalPodAutoscaler:
20
        """Create a horizontal pod autoscaler."""
21
    
22
    def list_namespaced_horizontal_pod_autoscaler(
23
        self,
24
        namespace: str,
25
        pretty: str = None,
26
        field_selector: str = None,
27
        label_selector: str = None,
28
        limit: int = None,
29
        timeout_seconds: int = None,
30
        watch: bool = None
31
    ) -> V1HorizontalPodAutoscalerList:
32
        """List horizontal pod autoscalers in specified namespace."""
33
    
34
    def list_horizontal_pod_autoscaler_for_all_namespaces(
35
        self,
36
        field_selector: str = None,
37
        label_selector: str = None,
38
        limit: int = None,
39
        pretty: str = None,
40
        timeout_seconds: int = None,
41
        watch: bool = None
42
    ) -> V1HorizontalPodAutoscalerList:
43
        """List horizontal pod autoscalers across all namespaces."""
44
    
45
    def read_namespaced_horizontal_pod_autoscaler(
46
        self,
47
        name: str,
48
        namespace: str,
49
        pretty: str = None
50
    ) -> V1HorizontalPodAutoscaler:
51
        """Read specified horizontal pod autoscaler."""
52
    
53
    def read_namespaced_horizontal_pod_autoscaler_status(
54
        self,
55
        name: str,
56
        namespace: str,
57
        pretty: str = None
58
    ) -> V1HorizontalPodAutoscaler:
59
        """Read status of specified horizontal pod autoscaler."""
60
    
61
    def patch_namespaced_horizontal_pod_autoscaler(
62
        self,
63
        name: str,
64
        namespace: str,
65
        body: object,
66
        dry_run: str = None,
67
        field_manager: str = None,
68
        pretty: str = None
69
    ) -> V1HorizontalPodAutoscaler:
70
        """Update specified horizontal pod autoscaler."""
71
    
72
    def replace_namespaced_horizontal_pod_autoscaler(
73
        self,
74
        name: str,
75
        namespace: str,
76
        body: V1HorizontalPodAutoscaler,
77
        dry_run: str = None,
78
        field_manager: str = None,
79
        pretty: str = None
80
    ) -> V1HorizontalPodAutoscaler:
81
        """Replace specified horizontal pod autoscaler."""
82
    
83
    def delete_namespaced_horizontal_pod_autoscaler(
84
        self,
85
        name: str,
86
        namespace: str,
87
        dry_run: str = None,
88
        grace_period_seconds: int = None,
89
        pretty: str = None
90
    ) -> V1Status:
91
        """Delete specified horizontal pod autoscaler."""
92
```
93

94
### Horizontal Pod Autoscaler V2
95

96
Advanced horizontal pod autoscaling with support for multiple metrics including CPU, memory, and custom metrics.
97

98
```python { .api }
99
class AutoscalingV2Api:
100
    def create_namespaced_horizontal_pod_autoscaler(
101
        self,
102
        namespace: str,
103
        body: V2HorizontalPodAutoscaler,
104
        dry_run: str = None,
105
        field_manager: str = None,
106
        pretty: str = None
107
    ) -> V2HorizontalPodAutoscaler:
108
        """Create a horizontal pod autoscaler with advanced metrics."""
109
    
110
    def list_namespaced_horizontal_pod_autoscaler(
111
        self,
112
        namespace: str,
113
        pretty: str = None,
114
        field_selector: str = None,
115
        label_selector: str = None,
116
        limit: int = None,
117
        timeout_seconds: int = None,
118
        watch: bool = None
119
    ) -> V2HorizontalPodAutoscalerList:
120
        """List horizontal pod autoscalers in specified namespace."""
121
    
122
    def list_horizontal_pod_autoscaler_for_all_namespaces(
123
        self,
124
        field_selector: str = None,
125
        label_selector: str = None,
126
        limit: int = None,
127
        pretty: str = None,
128
        timeout_seconds: int = None,
129
        watch: bool = None
130
    ) -> V2HorizontalPodAutoscalerList:
131
        """List horizontal pod autoscalers across all namespaces."""
132
    
133
    def read_namespaced_horizontal_pod_autoscaler(
134
        self,
135
        name: str,
136
        namespace: str,
137
        pretty: str = None
138
    ) -> V2HorizontalPodAutoscaler:
139
        """Read specified horizontal pod autoscaler."""
140
    
141
    def read_namespaced_horizontal_pod_autoscaler_status(
142
        self,
143
        name: str,
144
        namespace: str,
145
        pretty: str = None
146
    ) -> V2HorizontalPodAutoscaler:
147
        """Read status of specified horizontal pod autoscaler."""
148
    
149
    def patch_namespaced_horizontal_pod_autoscaler(
150
        self,
151
        name: str,
152
        namespace: str,
153
        body: object,
154
        dry_run: str = None,
155
        field_manager: str = None,
156
        pretty: str = None
157
    ) -> V2HorizontalPodAutoscaler:
158
        """Update specified horizontal pod autoscaler."""
159
    
160
    def replace_namespaced_horizontal_pod_autoscaler(
161
        self,
162
        name: str,
163
        namespace: str,
164
        body: V2HorizontalPodAutoscaler,
165
        dry_run: str = None,
166
        field_manager: str = None,
167
        pretty: str = None
168
    ) -> V2HorizontalPodAutoscaler:
169
        """Replace specified horizontal pod autoscaler."""
170
    
171
    def delete_namespaced_horizontal_pod_autoscaler(
172
        self,
173
        name: str,
174
        namespace: str,
175
        dry_run: str = None,
176
        grace_period_seconds: int = None,
177
        pretty: str = None
178
    ) -> V1Status:
179
        """Delete specified horizontal pod autoscaler."""
180
```
181

182
## Resource Types
183

184
### V1HorizontalPodAutoscaler (V1 API)
185
```python { .api }
186
class V1HorizontalPodAutoscaler:
187
    api_version: str
188
    kind: str
189
    metadata: V1ObjectMeta
190
    spec: V1HorizontalPodAutoscalerSpec
191
    status: V1HorizontalPodAutoscalerStatus
192

193
class V1HorizontalPodAutoscalerSpec:
194
    max_replicas: int
195
    min_replicas: int
196
    scale_target_ref: V1CrossVersionObjectReference
197
    target_cpu_utilization_percentage: int
198
```
199

200
### V2HorizontalPodAutoscaler (V2 API)
201
```python { .api }
202
class V2HorizontalPodAutoscaler:
203
    api_version: str
204
    kind: str
205
    metadata: V1ObjectMeta
206
    spec: V2HorizontalPodAutoscalerSpec
207
    status: V2HorizontalPodAutoscalerStatus
208

209
class V2HorizontalPodAutoscalerSpec:
210
    max_replicas: int
211
    min_replicas: int
212
    scale_target_ref: V2CrossVersionObjectReference
213
    metrics: list[V2MetricSpec]
214
    behavior: V2HorizontalPodAutoscalerBehavior
215

216
class V2MetricSpec:
217
    type: str  # "Resource", "Pods", "Object", "External"
218
    resource: V2ResourceMetricSource
219
    pods: V2PodsMetricSource
220
    object: V2ObjectMetricSource
221
    external: V2ExternalMetricSource
222
```
223

224
### Status Types
225
```python { .api }
226
class V1HorizontalPodAutoscalerStatus:
227
    current_cpu_utilization_percentage: int
228
    current_replicas: int
229
    desired_replicas: int
230
    last_scale_time: datetime
231

232
class V2HorizontalPodAutoscalerStatus:
233
    conditions: list[V2HorizontalPodAutoscalerCondition]
234
    current_metrics: list[V2MetricStatus]
235
    current_replicas: int
236
    desired_replicas: int
237
    last_scale_time: datetime
238
```
239

240
## Usage Examples
241

242
### Basic CPU-based Autoscaling (V1)
243

244
```python
245
from kubernetes import client, config
246

247
# Load configuration
248
config.load_kube_config()
249

250
# Create autoscaling V1 API client
251
autoscaling_v1 = client.AutoscalingV1Api()
252

253
# Create basic HPA for CPU scaling
254
hpa_spec = client.V1HorizontalPodAutoscalerSpec(
255
    scale_target_ref=client.V1CrossVersionObjectReference(
256
        api_version="apps/v1",
257
        kind="Deployment",
258
        name="web-app"
259
    ),
260
    min_replicas=2,
261
    max_replicas=10,
262
    target_cpu_utilization_percentage=70
263
)
264

265
hpa = client.V1HorizontalPodAutoscaler(
266
    api_version="autoscaling/v1",
267
    kind="HorizontalPodAutoscaler",
268
    metadata=client.V1ObjectMeta(name="web-app-hpa"),
269
    spec=hpa_spec
270
)
271

272
# Create HPA
273
result = autoscaling_v1.create_namespaced_horizontal_pod_autoscaler(
274
    namespace="default",
275
    body=hpa
276
)
277
print(f"HPA created: {result.metadata.name}")
278
```
279

280
### Advanced Multi-Metric Autoscaling (V2)
281

282
```python
283
# Create autoscaling V2 API client
284
autoscaling_v2 = client.AutoscalingV2Api()
285

286
# Define multiple metrics for scaling decisions
287
metrics = [
288
    # CPU utilization metric
289
    client.V2MetricSpec(
290
        type="Resource",
291
        resource=client.V2ResourceMetricSource(
292
            name="cpu",
293
            target=client.V2MetricTarget(
294
                type="Utilization",
295
                average_utilization=70
296
            )
297
        )
298
    ),
299
    # Memory utilization metric
300
    client.V2MetricSpec(
301
        type="Resource",
302
        resource=client.V2ResourceMetricSource(
303
            name="memory",
304
            target=client.V2MetricTarget(
305
                type="Utilization",
306
                average_utilization=80
307
            )
308
        )
309
    ),
310
    # Custom metric example
311
    client.V2MetricSpec(
312
        type="Pods",
313
        pods=client.V2PodsMetricSource(
314
            metric=client.V2MetricIdentifier(
315
                name="requests_per_second"
316
            ),
317
            target=client.V2MetricTarget(
318
                type="AverageValue",
319
                average_value="100"
320
            )
321
        )
322
    )
323
]
324

325
# Define scaling behavior
326
behavior = client.V2HorizontalPodAutoscalerBehavior(
327
    scale_up=client.V2HPAScalingRules(
328
        stabilization_window_seconds=60,
329
        policies=[
330
            client.V2HPAScalingPolicy(
331
                type="Percent",
332
                value=100,
333
                period_seconds=60
334
            )
335
        ]
336
    ),
337
    scale_down=client.V2HPAScalingRules(
338
        stabilization_window_seconds=300,
339
        policies=[
340
            client.V2HPAScalingPolicy(
341
                type="Percent",
342
                value=10,
343
                period_seconds=60
344
            )
345
        ]
346
    )
347
)
348

349
# Create advanced HPA specification
350
hpa_v2_spec = client.V2HorizontalPodAutoscalerSpec(
351
    scale_target_ref=client.V2CrossVersionObjectReference(
352
        api_version="apps/v1",
353
        kind="Deployment",
354
        name="web-app"
355
    ),
356
    min_replicas=3,
357
    max_replicas=50,
358
    metrics=metrics,
359
    behavior=behavior
360
)
361

362
hpa_v2 = client.V2HorizontalPodAutoscaler(
363
    api_version="autoscaling/v2",
364
    kind="HorizontalPodAutoscaler",
365
    metadata=client.V1ObjectMeta(name="web-app-advanced-hpa"),
366
    spec=hpa_v2_spec
367
)
368

369
# Create advanced HPA
370
result = autoscaling_v2.create_namespaced_horizontal_pod_autoscaler(
371
    namespace="default",
372
    body=hpa_v2
373
)
374
print(f"Advanced HPA created: {result.metadata.name}")
375
```
376

377
### Monitoring HPA Status
378

379
```python
380
# Get HPA status
381
hpa_status = autoscaling_v2.read_namespaced_horizontal_pod_autoscaler_status(
382
    name="web-app-advanced-hpa",
383
    namespace="default"
384
)
385

386
print(f"Current replicas: {hpa_status.status.current_replicas}")
387
print(f"Desired replicas: {hpa_status.status.desired_replicas}")
388

389
# Check current metrics
390
if hpa_status.status.current_metrics:
391
    for metric in hpa_status.status.current_metrics:
392
        if metric.type == "Resource":
393
            resource_name = metric.resource.name
394
            current_value = metric.resource.current.average_utilization
395
            print(f"{resource_name} utilization: {current_value}%")
396

397
# Check conditions
398
if hpa_status.status.conditions:
399
    for condition in hpa_status.status.conditions:
400
        print(f"Condition {condition.type}: {condition.status}")
401
        if condition.reason:
402
            print(f"  Reason: {condition.reason}")
403
        if condition.message:
404
            print(f"  Message: {condition.message}")
405
```
406

407
### List and Manage HPAs
408

409
```python
410
# List all HPAs in namespace
411
hpas = autoscaling_v2.list_namespaced_horizontal_pod_autoscaler(
412
    namespace="default"
413
)
414

415
for hpa in hpas.items:
416
    print(f"HPA: {hpa.metadata.name}")
417
    print(f"  Target: {hpa.spec.scale_target_ref.kind}/{hpa.spec.scale_target_ref.name}")
418
    print(f"  Replicas: {hpa.spec.min_replicas}-{hpa.spec.max_replicas}")
419
    if hpa.status:
420
        print(f"  Current: {hpa.status.current_replicas} replicas")
421

422
# Update HPA
423
hpa.spec.max_replicas = 20
424
updated_hpa = autoscaling_v2.replace_namespaced_horizontal_pod_autoscaler(
425
    name="web-app-advanced-hpa",
426
    namespace="default",
427
    body=hpa
428
)
429
print(f"HPA updated, new max replicas: {updated_hpa.spec.max_replicas}")
430

431
# Delete HPA
432
autoscaling_v2.delete_namespaced_horizontal_pod_autoscaler(
433
    name="web-app-advanced-hpa",
434
    namespace="default"
435
)
436
print("HPA deleted")
437
```
438

439
## Import Statements
440

441
```python
442
from kubernetes import client
443
from kubernetes.client import AutoscalingV1Api, AutoscalingV2Api
444
from kubernetes.client import V1HorizontalPodAutoscaler, V1HorizontalPodAutoscalerSpec
445
from kubernetes.client import V2HorizontalPodAutoscaler, V2HorizontalPodAutoscalerSpec
446
from kubernetes.client import V2MetricSpec, V2ResourceMetricSource, V2MetricTarget
447
from kubernetes.client import V2HorizontalPodAutoscalerBehavior, V2HPAScalingRules
448
```