0
# Cluster Management
1

2
Cluster-level operations for monitoring health, managing settings, shard allocation, and node management. These operations provide comprehensive control over Elasticsearch cluster behavior and configuration.
3

4
## Capabilities
5

6
### Cluster Health Monitoring
7

8
Monitor cluster health status, index health, and shard allocation.
9

10
```python { .api }
11
def health(
12
    self,
13
    index: Optional[Union[str, List[str]]] = None,
14
    level: Optional[str] = None,
15
    local: Optional[bool] = None,
16
    master_timeout: Optional[str] = None,
17
    timeout: Optional[str] = None,
18
    wait_for_active_shards: Optional[str] = None,
19
    wait_for_events: Optional[str] = None,
20
    wait_for_no_initializing_shards: Optional[bool] = None,
21
    wait_for_no_relocating_shards: Optional[bool] = None,
22
    wait_for_nodes: Optional[str] = None,
23
    wait_for_status: Optional[str] = None,
24
    **kwargs
25
) -> ObjectApiResponse:
26
    """
27
    Get cluster health information.
28
    
29
    Parameters:
30
    - index: Index name(s) to check health for
31
    - level: Level of detail (cluster, indices, shards)
32
    - local: Whether to return local information only
33
    - master_timeout: Timeout for master node response
34
    - timeout: Request timeout
35
    - wait_for_active_shards: Wait for specific number of active shards
36
    - wait_for_events: Wait for specific events to complete
37
    - wait_for_no_initializing_shards: Wait for no initializing shards
38
    - wait_for_no_relocating_shards: Wait for no relocating shards
39
    - wait_for_nodes: Wait for specific number of nodes
40
    - wait_for_status: Wait for specific cluster status (green, yellow, red)
41
    
42
    Returns:
43
    ObjectApiResponse with cluster health information
44
    """
45
```
46

47
### Cluster State Management
48

49
Retrieve and monitor cluster state information.
50

51
```python { .api }
52
def state(
53
    self,
54
    metric: Optional[Union[str, List[str]]] = None,
55
    index: Optional[Union[str, List[str]]] = None,
56
    allow_no_indices: Optional[bool] = None,
57
    expand_wildcards: Optional[str] = None,
58
    flat_settings: Optional[bool] = None,
59
    ignore_unavailable: Optional[bool] = None,
60
    local: Optional[bool] = None,
61
    master_timeout: Optional[str] = None,
62
    wait_for_metadata_version: Optional[int] = None,
63
    wait_for_timeout: Optional[str] = None,
64
    **kwargs
65
) -> ObjectApiResponse:
66
    """
67
    Get cluster state information.
68
    
69
    Parameters:
70
    - metric: Specific metrics to return (metadata, routing_table, etc.)
71
    - index: Index name(s) to include in state
72
    - allow_no_indices: Whether empty index list is acceptable
73
    - expand_wildcards: How to expand wildcard patterns
74
    - flat_settings: Whether to return settings in flat format
75
    - ignore_unavailable: Whether to ignore unavailable indices
76
    - local: Whether to return local information only
77
    - master_timeout: Timeout for master node response
78
    - wait_for_metadata_version: Wait for specific metadata version
79
    - wait_for_timeout: Timeout for wait conditions
80
    
81
    Returns:
82
    ObjectApiResponse with cluster state
83
    """
84
```
85

86
### Cluster Statistics
87

88
Retrieve comprehensive cluster statistics and metrics.
89

90
```python { .api }
91
def stats(
92
    self,
93
    node_id: Optional[Union[str, List[str]]] = None,
94
    flat_settings: Optional[bool] = None,
95
    timeout: Optional[str] = None,
96
    **kwargs
97
) -> ObjectApiResponse:
98
    """
99
    Get cluster statistics.
100
    
101
    Parameters:
102
    - node_id: Node ID(s) to include in statistics
103
    - flat_settings: Whether to return settings in flat format
104
    - timeout: Request timeout
105
    
106
    Returns:
107
    ObjectApiResponse with cluster statistics
108
    """
109
```
110

111
### Cluster Settings Management
112

113
Configure cluster-wide settings for behavior control.
114

115
```python { .api }
116
def put_settings(
117
    self,
118
    persistent: Optional[Dict[str, Any]] = None,
119
    transient: Optional[Dict[str, Any]] = None,
120
    flat_settings: Optional[bool] = None,
121
    master_timeout: Optional[str] = None,
122
    timeout: Optional[str] = None,
123
    **kwargs
124
) -> ObjectApiResponse:
125
    """
126
    Update cluster settings.
127
    
128
    Parameters:
129
    - persistent: Persistent cluster settings (survive cluster restart)
130
    - transient: Transient cluster settings (reset on restart)
131
    - flat_settings: Whether settings are in flat format
132
    - master_timeout: Timeout for master node response
133
    - timeout: Request timeout
134
    
135
    Returns:
136
    ObjectApiResponse with settings update result
137
    """
138

139
def get_settings(
140
    self,
141
    flat_settings: Optional[bool] = None,
142
    include_defaults: Optional[bool] = None,
143
    master_timeout: Optional[str] = None,
144
    timeout: Optional[str] = None,
145
    **kwargs
146
) -> ObjectApiResponse:
147
    """
148
    Get cluster settings.
149
    
150
    Parameters:
151
    - flat_settings: Whether to return settings in flat format
152
    - include_defaults: Whether to include default settings
153
    - master_timeout: Timeout for master node response
154
    - timeout: Request timeout
155
    
156
    Returns:
157
    ObjectApiResponse with cluster settings
158
    """
159
```
160

161
### Shard Allocation Management
162

163
Control and monitor shard allocation across cluster nodes.
164

165
```python { .api }
166
def allocation_explain(
167
    self,
168
    current_node: Optional[str] = None,
169
    index: Optional[str] = None,
170
    primary: Optional[bool] = None,
171
    shard: Optional[int] = None,
172
    include_disk_info: Optional[bool] = None,
173
    include_yes_decisions: Optional[bool] = None,
174
    **kwargs
175
) -> ObjectApiResponse:
176
    """
177
    Explain shard allocation decisions.
178
    
179
    Parameters:
180
    - current_node: Node where shard currently resides
181
    - index: Index name for shard
182
    - primary: Whether to explain primary shard allocation
183
    - shard: Shard number to explain
184
    - include_disk_info: Whether to include disk usage information
185
    - include_yes_decisions: Whether to include positive decisions
186
    
187
    Returns:
188
    ObjectApiResponse with allocation explanation
189
    """
190

191
def reroute(
192
    self,
193
    commands: Optional[List[Dict[str, Any]]] = None,
194
    dry_run: Optional[bool] = None,
195
    explain: Optional[bool] = None,
196
    master_timeout: Optional[str] = None,
197
    metric: Optional[Union[str, List[str]]] = None,
198
    retry_failed: Optional[bool] = None,
199
    timeout: Optional[str] = None,
200
    **kwargs
201
) -> ObjectApiResponse:
202
    """
203
    Manually reroute shards in the cluster.
204
    
205
    Parameters:
206
    - commands: List of reroute commands to execute
207
    - dry_run: Whether to perform dry run without executing
208
    - explain: Whether to return explanation of routing
209
    - master_timeout: Timeout for master node response
210
    - metric: Specific metrics to return
211
    - retry_failed: Whether to retry failed shard allocations
212
    - timeout: Request timeout
213
    
214
    Returns:
215
    ObjectApiResponse with reroute result
216
    """
217
```
218

219
### Task Management
220

221
Monitor and manage cluster-level tasks.
222

223
```python { .api }
224
def pending_tasks(
225
    self,
226
    local: Optional[bool] = None,
227
    master_timeout: Optional[str] = None,
228
    **kwargs
229
) -> ObjectApiResponse:
230
    """
231
    Get pending cluster tasks.
232
    
233
    Parameters:
234
    - local: Whether to return local information only
235
    - master_timeout: Timeout for master node response
236
    
237
    Returns:
238
    ObjectApiResponse with pending tasks
239
    """
240
```
241

242
### Component Template Management
243

244
Manage component templates for composable index templates.
245

246
```python { .api }
247
def put_component_template(
248
    self,
249
    name: str,
250
    template: Dict[str, Any],
251
    create: Optional[bool] = None,
252
    master_timeout: Optional[str] = None,
253
    **kwargs
254
) -> ObjectApiResponse:
255
    """
256
    Create or update a component template.
257
    
258
    Parameters:
259
    - name: Component template name
260
    - template: Template definition with settings, mappings, aliases
261
    - create: Whether to fail if template already exists
262
    - master_timeout: Timeout for master node response
263
    
264
    Returns:
265
    ObjectApiResponse with template creation result
266
    """
267

268
def get_component_template(
269
    self,
270
    name: Optional[str] = None,
271
    local: Optional[bool] = None,
272
    master_timeout: Optional[str] = None,
273
    **kwargs
274
) -> ObjectApiResponse:
275
    """
276
    Get component templates.
277
    
278
    Parameters:
279
    - name: Component template name (or pattern)
280
    - local: Whether to return local information only
281
    - master_timeout: Timeout for master node response
282
    
283
    Returns:
284
    ObjectApiResponse with component templates
285
    """
286

287
def delete_component_template(
288
    self,
289
    name: str,
290
    master_timeout: Optional[str] = None,
291
    timeout: Optional[str] = None,
292
    **kwargs
293
) -> ObjectApiResponse:
294
    """
295
    Delete a component template.
296
    
297
    Parameters:
298
    - name: Component template name
299
    - master_timeout: Timeout for master node response
300
    - timeout: Request timeout
301
    
302
    Returns:
303
    ObjectApiResponse with deletion result
304
    """
305
```
306

307
## Usage Examples
308

309
### Basic Cluster Monitoring
310

311
```python
312
from elasticsearch import Elasticsearch
313

314
client = Elasticsearch(hosts=['http://localhost:9200'])
315

316
# Check cluster health
317
health = client.cluster.health()
318
print(f"Cluster status: {health.body['status']}")
319
print(f"Active shards: {health.body['active_shards']}")
320
print(f"Number of nodes: {health.body['number_of_nodes']}")
321

322
# Wait for yellow status
323
health = client.cluster.health(
324
    wait_for_status='yellow',
325
    timeout='30s'
326
)
327

328
# Check specific index health
329
index_health = client.cluster.health(
330
    index='products',
331
    level='indices'
332
)
333
print(f"Products index status: {index_health.body['indices']['products']['status']}")
334
```
335

336
### Cluster Settings Management
337

338
```python
339
# Update cluster settings
340
client.cluster.put_settings(
341
    persistent={
342
        "cluster.routing.allocation.enable": "all",
343
        "cluster.max_shards_per_node": 2000
344
    },
345
    transient={
346
        "indices.recovery.max_bytes_per_sec": "100mb"
347
    }
348
)
349

350
# Get current settings
351
settings = client.cluster.get_settings(include_defaults=True)
352
print(f"Current routing allocation: {settings.body['persistent']}")
353

354
# Reset transient settings
355
client.cluster.put_settings(
356
    transient={
357
        "indices.recovery.max_bytes_per_sec": None
358
    }
359
)
360
```
361

362
### Shard Allocation Analysis
363

364
```python
365
# Get allocation explanation for unassigned shard
366
explanation = client.cluster.allocation_explain(
367
    index="my_index",
368
    shard=0,
369
    primary=True,
370
    include_disk_info=True
371
)
372

373
print(f"Allocation decision: {explanation.body['allocation_delay']}")
374
for decision in explanation.body['node_allocation_decisions']:
375
    node_name = decision['node_name']
376
    decision_type = decision['deciders'][0]['decision']
377
    print(f"Node {node_name}: {decision_type}")
378

379
# Manual shard reroute
380
reroute_result = client.cluster.reroute(
381
    commands=[
382
        {
383
            "move": {
384
                "index": "my_index",
385
                "shard": 0,
386
                "from_node": "node-1",
387
                "to_node": "node-2"
388
            }
389
        }
390
    ],
391
    explain=True
392
)
393
```
394

395
### Advanced Cluster Management
396

397
```python
398
# Monitor cluster state changes
399
current_state = client.cluster.state(
400
    metric=['metadata', 'routing_table'],
401
    wait_for_metadata_version=10,
402
    wait_for_timeout='30s'
403
)
404

405
# Get detailed cluster statistics
406
stats = client.cluster.stats()
407
print(f"Total documents: {stats.body['indices']['docs']['count']}")
408
print(f"Total store size: {stats.body['indices']['store']['size_in_bytes']}")
409
print(f"Available nodes: {stats.body['nodes']['count']['total']}")
410

411
# Check pending tasks
412
pending = client.cluster.pending_tasks()
413
if pending.body['tasks']:
414
    for task in pending.body['tasks']:
415
        print(f"Pending task: {task['source']} - {task['time_in_queue']}")
416
else:
417
    print("No pending cluster tasks")
418
```
419

420
### Component Template Management
421

422
```python
423
# Create a component template
424
client.cluster.put_component_template(
425
    name="logs_settings",
426
    template={
427
        "settings": {
428
            "number_of_shards": 1,
429
            "number_of_replicas": 0,
430
            "index.lifecycle.name": "logs_policy"
431
        }
432
    }
433
)
434

435
client.cluster.put_component_template(
436
    name="logs_mappings", 
437
    template={
438
        "mappings": {
439
            "properties": {
440
                "@timestamp": {"type": "date"},
441
                "level": {"type": "keyword"},
442
                "message": {"type": "text"},
443
                "service": {"type": "keyword"}
444
            }
445
        }
446
    }
447
)
448

449
# Create composable index template using components
450
client.indices.put_index_template(
451
    name="logs_template",
452
    index_patterns=["logs-*"],
453
    composed_of=["logs_settings", "logs_mappings"],
454
    priority=200
455
)
456

457
# List component templates
458
templates = client.cluster.get_component_template()
459
for template_name in templates.body['component_templates']:
460
    print(f"Component template: {template_name['name']}")
461
```