0
# Service Management
1
2
Management of Cosmos DB services, Cassandra clusters, data centers, and notebook workspaces for advanced scenarios and specialized deployments. These operations enable management of additional Cosmos DB features and managed services.
3
4
## Capabilities
5
6
### Cosmos DB Service Management
7
8
Manage additional services and features associated with Cosmos DB accounts.
9
10
```python { .api }
11
def list(
12
self,
13
resource_group_name: str,
14
account_name: str
15
) -> ItemPaged[ServiceResource]:
16
"""
17
List services associated with a Cosmos DB account.
18
19
Parameters:
20
- resource_group_name: Name of the resource group
21
- account_name: Name of the Cosmos DB account
22
23
Returns:
24
ItemPaged[ServiceResource]: Paginated list of services
25
"""
26
27
def get(
28
self,
29
resource_group_name: str,
30
account_name: str,
31
service_name: str
32
) -> ServiceResource:
33
"""
34
Get properties of a Cosmos DB service.
35
36
Parameters:
37
- resource_group_name: Name of the resource group
38
- account_name: Name of the Cosmos DB account
39
- service_name: Name of the service
40
41
Returns:
42
ServiceResource: Service properties and configuration
43
"""
44
45
def begin_create(
46
self,
47
resource_group_name: str,
48
account_name: str,
49
service_name: str,
50
create_service_parameters: ServiceResourceCreateUpdateParameters
51
) -> LROPoller[ServiceResource]:
52
"""
53
Create a new service for a Cosmos DB account (Long Running Operation).
54
55
Parameters:
56
- resource_group_name: Name of the resource group
57
- account_name: Name of the Cosmos DB account
58
- service_name: Name of the service to create
59
- create_service_parameters: Service configuration parameters
60
61
Returns:
62
LROPoller[ServiceResource]: Poller for monitoring operation progress
63
"""
64
65
def begin_update(
66
self,
67
resource_group_name: str,
68
account_name: str,
69
service_name: str,
70
update_service_parameters: ServiceResourceCreateUpdateParameters
71
) -> LROPoller[ServiceResource]:
72
"""
73
Update a service configuration (Long Running Operation).
74
75
Parameters:
76
- resource_group_name: Name of the resource group
77
- account_name: Name of the Cosmos DB account
78
- service_name: Name of the service to update
79
- update_service_parameters: Updated service configuration
80
81
Returns:
82
LROPoller[ServiceResource]: Poller for monitoring operation progress
83
"""
84
85
def begin_delete(
86
self,
87
resource_group_name: str,
88
account_name: str,
89
service_name: str
90
) -> LROPoller[None]:
91
"""
92
Delete a service (Long Running Operation).
93
94
Parameters:
95
- resource_group_name: Name of the resource group
96
- account_name: Name of the Cosmos DB account
97
- service_name: Name of the service to delete
98
99
Returns:
100
LROPoller[None]: Poller for monitoring operation progress
101
"""
102
```
103
104
### Managed Cassandra Cluster Management
105
106
Manage Azure Managed Instance for Apache Cassandra clusters with full lifecycle operations.
107
108
```python { .api }
109
def list_by_subscription(self) -> ItemPaged[ClusterResource]:
110
"""
111
List all Cassandra clusters in the subscription.
112
113
Returns:
114
ItemPaged[ClusterResource]: Paginated list of all Cassandra clusters
115
"""
116
117
def list_by_resource_group(
118
self,
119
resource_group_name: str
120
) -> ItemPaged[ClusterResource]:
121
"""
122
List Cassandra clusters in a resource group.
123
124
Parameters:
125
- resource_group_name: Name of the resource group
126
127
Returns:
128
ItemPaged[ClusterResource]: Paginated list of clusters in the resource group
129
"""
130
131
def get(
132
self,
133
resource_group_name: str,
134
cluster_name: str
135
) -> ClusterResource:
136
"""
137
Get properties of a Cassandra cluster.
138
139
Parameters:
140
- resource_group_name: Name of the resource group
141
- cluster_name: Name of the Cassandra cluster
142
143
Returns:
144
ClusterResource: Cluster properties, status, and configuration
145
"""
146
147
def begin_create_update(
148
self,
149
resource_group_name: str,
150
cluster_name: str,
151
body: ClusterResource
152
) -> LROPoller[ClusterResource]:
153
"""
154
Create or update a Cassandra cluster (Long Running Operation).
155
156
Parameters:
157
- resource_group_name: Name of the resource group
158
- cluster_name: Name of the cluster to create/update
159
- body: Cluster configuration and properties
160
161
Returns:
162
LROPoller[ClusterResource]: Poller for monitoring operation progress
163
"""
164
165
def begin_delete(
166
self,
167
resource_group_name: str,
168
cluster_name: str
169
) -> LROPoller[None]:
170
"""
171
Delete a Cassandra cluster (Long Running Operation).
172
173
Parameters:
174
- resource_group_name: Name of the resource group
175
- cluster_name: Name of the cluster to delete
176
177
Returns:
178
LROPoller[None]: Poller for monitoring operation progress
179
"""
180
181
def begin_update(
182
self,
183
resource_group_name: str,
184
cluster_name: str,
185
body: ClusterResource
186
) -> LROPoller[ClusterResource]:
187
"""
188
Update a Cassandra cluster configuration (Long Running Operation).
189
190
Parameters:
191
- resource_group_name: Name of the resource group
192
- cluster_name: Name of the cluster to update
193
- body: Updated cluster configuration
194
195
Returns:
196
LROPoller[ClusterResource]: Poller for monitoring operation progress
197
"""
198
199
def begin_invoke_command(
200
self,
201
resource_group_name: str,
202
cluster_name: str,
203
body: CommandPostBody
204
) -> LROPoller[CommandOutput]:
205
"""
206
Invoke a command on the Cassandra cluster (Long Running Operation).
207
208
Parameters:
209
- resource_group_name: Name of the resource group
210
- cluster_name: Name of the Cassandra cluster
211
- body: Command to execute and parameters
212
213
Returns:
214
LROPoller[CommandOutput]: Poller for monitoring command execution
215
"""
216
```
217
218
### Cassandra Data Center Management
219
220
Manage data centers within Cassandra clusters for multi-region deployments.
221
222
```python { .api }
223
def list(
224
self,
225
resource_group_name: str,
226
cluster_name: str
227
) -> ItemPaged[DataCenterResource]:
228
"""
229
List data centers in a Cassandra cluster.
230
231
Parameters:
232
- resource_group_name: Name of the resource group
233
- cluster_name: Name of the Cassandra cluster
234
235
Returns:
236
ItemPaged[DataCenterResource]: Paginated list of data centers
237
"""
238
239
def get(
240
self,
241
resource_group_name: str,
242
cluster_name: str,
243
data_center_name: str
244
) -> DataCenterResource:
245
"""
246
Get properties of a Cassandra data center.
247
248
Parameters:
249
- resource_group_name: Name of the resource group
250
- cluster_name: Name of the Cassandra cluster
251
- data_center_name: Name of the data center
252
253
Returns:
254
DataCenterResource: Data center properties and configuration
255
"""
256
257
def begin_create_update(
258
self,
259
resource_group_name: str,
260
cluster_name: str,
261
data_center_name: str,
262
body: DataCenterResource
263
) -> LROPoller[DataCenterResource]:
264
"""
265
Create or update a data center (Long Running Operation).
266
267
Parameters:
268
- resource_group_name: Name of the resource group
269
- cluster_name: Name of the Cassandra cluster
270
- data_center_name: Name of the data center to create/update
271
- body: Data center configuration
272
273
Returns:
274
LROPoller[DataCenterResource]: Poller for monitoring operation progress
275
"""
276
277
def begin_delete(
278
self,
279
resource_group_name: str,
280
cluster_name: str,
281
data_center_name: str
282
) -> LROPoller[None]:
283
"""
284
Delete a data center (Long Running Operation).
285
286
Parameters:
287
- resource_group_name: Name of the resource group
288
- cluster_name: Name of the Cassandra cluster
289
- data_center_name: Name of the data center to delete
290
291
Returns:
292
LROPoller[None]: Poller for monitoring operation progress
293
"""
294
295
def begin_update(
296
self,
297
resource_group_name: str,
298
cluster_name: str,
299
data_center_name: str,
300
body: DataCenterResource
301
) -> LROPoller[DataCenterResource]:
302
"""
303
Update a data center configuration (Long Running Operation).
304
305
Parameters:
306
- resource_group_name: Name of the resource group
307
- cluster_name: Name of the Cassandra cluster
308
- data_center_name: Name of the data center to update
309
- body: Updated data center configuration
310
311
Returns:
312
LROPoller[DataCenterResource]: Poller for monitoring operation progress
313
"""
314
```
315
316
### Notebook Workspace Management
317
318
Manage Jupyter notebook workspaces for data exploration and analytics with Cosmos DB.
319
320
```python { .api }
321
def list_by_database_account(
322
self,
323
resource_group_name: str,
324
account_name: str
325
) -> ItemPaged[NotebookWorkspace]:
326
"""
327
List notebook workspaces for a Cosmos DB account.
328
329
Parameters:
330
- resource_group_name: Name of the resource group
331
- account_name: Name of the Cosmos DB account
332
333
Returns:
334
ItemPaged[NotebookWorkspace]: Paginated list of notebook workspaces
335
"""
336
337
def get(
338
self,
339
resource_group_name: str,
340
account_name: str,
341
notebook_workspace_name: str
342
) -> NotebookWorkspace:
343
"""
344
Get properties of a notebook workspace.
345
346
Parameters:
347
- resource_group_name: Name of the resource group
348
- account_name: Name of the Cosmos DB account
349
- notebook_workspace_name: Name of the notebook workspace
350
351
Returns:
352
NotebookWorkspace: Notebook workspace properties and status
353
"""
354
355
def begin_create_or_update(
356
self,
357
resource_group_name: str,
358
account_name: str,
359
notebook_workspace_name: str,
360
notebook_create_update_parameters: NotebookWorkspaceCreateUpdateParameters
361
) -> LROPoller[NotebookWorkspace]:
362
"""
363
Create or update a notebook workspace (Long Running Operation).
364
365
Parameters:
366
- resource_group_name: Name of the resource group
367
- account_name: Name of the Cosmos DB account
368
- notebook_workspace_name: Name of the workspace to create/update
369
- notebook_create_update_parameters: Workspace configuration parameters
370
371
Returns:
372
LROPoller[NotebookWorkspace]: Poller for monitoring operation progress
373
"""
374
375
def begin_delete(
376
self,
377
resource_group_name: str,
378
account_name: str,
379
notebook_workspace_name: str
380
) -> LROPoller[None]:
381
"""
382
Delete a notebook workspace (Long Running Operation).
383
384
Parameters:
385
- resource_group_name: Name of the resource group
386
- account_name: Name of the Cosmos DB account
387
- notebook_workspace_name: Name of the workspace to delete
388
389
Returns:
390
LROPoller[None]: Poller for monitoring operation progress
391
"""
392
393
def begin_start(
394
self,
395
resource_group_name: str,
396
account_name: str,
397
notebook_workspace_name: str
398
) -> LROPoller[None]:
399
"""
400
Start a notebook workspace (Long Running Operation).
401
402
Parameters:
403
- resource_group_name: Name of the resource group
404
- account_name: Name of the Cosmos DB account
405
- notebook_workspace_name: Name of the workspace to start
406
407
Returns:
408
LROPoller[None]: Poller for monitoring operation progress
409
"""
410
411
def list_connection_info(
412
self,
413
resource_group_name: str,
414
account_name: str,
415
notebook_workspace_name: str
416
) -> NotebookWorkspaceConnectionInfoResult:
417
"""
418
Get connection information for a notebook workspace.
419
420
Parameters:
421
- resource_group_name: Name of the resource group
422
- account_name: Name of the Cosmos DB account
423
- notebook_workspace_name: Name of the notebook workspace
424
425
Returns:
426
NotebookWorkspaceConnectionInfoResult: Connection URLs and authentication tokens
427
"""
428
429
def regenerate_auth_token(
430
self,
431
resource_group_name: str,
432
account_name: str,
433
notebook_workspace_name: str
434
) -> None:
435
"""
436
Regenerate authentication token for a notebook workspace.
437
438
Parameters:
439
- resource_group_name: Name of the resource group
440
- account_name: Name of the Cosmos DB account
441
- notebook_workspace_name: Name of the notebook workspace
442
"""
443
```
444
445
## Usage Examples
446
447
### Creating a Managed Cassandra Cluster
448
449
```python
450
from azure.mgmt.cosmosdb import CosmosDBManagementClient
451
from azure.mgmt.cosmosdb.models import (
452
ClusterResource,
453
ClusterResourceProperties,
454
AuthenticationMethod,
455
CassandraAuditLoggingPolicy,
456
SeedNode
457
)
458
from azure.identity import DefaultAzureCredential
459
460
client = CosmosDBManagementClient(DefaultAzureCredential(), "subscription-id")
461
462
# Create managed Cassandra cluster
463
cluster_config = ClusterResource(
464
location="East US",
465
properties=ClusterResourceProperties(
466
delegated_management_subnet_id="/subscriptions/sub-id/resourceGroups/network-rg/providers/Microsoft.Network/virtualNetworks/vnet/subnets/cassandra-subnet",
467
cassandra_version="3.11",
468
cluster_name_override="my-cassandra-cluster",
469
authentication_method=AuthenticationMethod.CASSANDRA,
470
initial_cassandra_admin_password="SecurePassword123!",
471
hourly_based_backup_options={
472
"retention_period_in_hours": 168 # 7 days
473
},
474
audit_logging_enabled=True,
475
repair_enabled=True,
476
client_certificates=[]
477
)
478
)
479
480
poller = client.cassandra_clusters.begin_create_update(
481
"my-resource-group",
482
"my-cassandra-cluster",
483
cluster_config
484
)
485
486
cluster = poller.result()
487
print(f"Created cluster: {cluster.name}")
488
print(f"Cluster status: {cluster.properties.provisioning_state}")
489
print(f"Seed nodes: {cluster.properties.seed_nodes}")
490
```
491
492
### Adding Data Centers to Cassandra Cluster
493
494
```python
495
from azure.mgmt.cosmosdb.models import DataCenterResource, DataCenterResourceProperties
496
497
# Add data center in West US
498
datacenter_config = DataCenterResource(
499
properties=DataCenterResourceProperties(
500
data_center_location="West US",
501
delegated_management_subnet_id="/subscriptions/sub-id/resourceGroups/network-rg-west/providers/Microsoft.Network/virtualNetworks/vnet-west/subnets/cassandra-subnet",
502
node_count=3,
503
sku="Standard_DS14_v2",
504
disk_sku="P50",
505
availability_zone=True,
506
backup_storage_customer_key_uri=None,
507
managed_disk_customer_key_uri=None
508
)
509
)
510
511
poller = client.cassandra_data_centers.begin_create_update(
512
"my-resource-group",
513
"my-cassandra-cluster",
514
"dc-west",
515
datacenter_config
516
)
517
518
datacenter = poller.result()
519
print(f"Created data center: {datacenter.name}")
520
print(f"Node count: {datacenter.properties.node_count}")
521
print(f"Data center location: {datacenter.properties.data_center_location}")
522
```
523
524
### Setting Up Notebook Workspace
525
526
```python
527
from azure.mgmt.cosmosdb.models import NotebookWorkspaceCreateUpdateParameters
528
529
# Create notebook workspace
530
notebook_config = NotebookWorkspaceCreateUpdateParameters()
531
532
poller = client.notebook_workspaces.begin_create_or_update(
533
"my-resource-group",
534
"my-cosmos-account",
535
"default", # Standard workspace name
536
notebook_config
537
)
538
539
workspace = poller.result()
540
print(f"Created notebook workspace: {workspace.name}")
541
542
# Start the workspace
543
start_poller = client.notebook_workspaces.begin_start(
544
"my-resource-group",
545
"my-cosmos-account",
546
"default"
547
)
548
start_poller.result()
549
550
# Get connection information
551
connection_info = client.notebook_workspaces.list_connection_info(
552
"my-resource-group",
553
"my-cosmos-account",
554
"default"
555
)
556
557
print(f"Notebook server endpoint: {connection_info.notebook_server_endpoint}")
558
print(f"Auth token: {connection_info.auth_token}")
559
```
560
561
### Managing Cosmos DB Services
562
563
```python
564
from azure.mgmt.cosmosdb.models import (
565
ServiceResourceCreateUpdateParameters,
566
DataTransferServiceResourceProperties
567
)
568
569
# Create a data transfer service
570
service_config = ServiceResourceCreateUpdateParameters(
571
properties=DataTransferServiceResourceProperties(
572
service_type="DataTransfer",
573
instance_count=1,
574
instance_size="Cosmos.D4s"
575
)
576
)
577
578
poller = client.service.begin_create(
579
"my-resource-group",
580
"my-cosmos-account",
581
"DataTransfer",
582
service_config
583
)
584
585
service = poller.result()
586
print(f"Created service: {service.name}")
587
print(f"Service type: {service.properties.service_type}")
588
print(f"Status: {service.properties.status}")
589
590
# List all services
591
services = client.service.list("my-resource-group", "my-cosmos-account")
592
for svc in services:
593
print(f"Service: {svc.name}, Type: {svc.properties.service_type}, Status: {svc.properties.status}")
594
```
595
596
### Executing Commands on Cassandra Cluster
597
598
```python
599
from azure.mgmt.cosmosdb.models import CommandPostBody
600
601
# Execute nodetool status command
602
command_body = CommandPostBody(
603
command="nodetool status",
604
arguments={},
605
host="10.0.0.4" # Specific node IP
606
)
607
608
poller = client.cassandra_clusters.begin_invoke_command(
609
"my-resource-group",
610
"my-cassandra-cluster",
611
command_body
612
)
613
614
command_result = poller.result()
615
print(f"Command output: {command_result.result}")
616
```
617
618
## Key Types
619
620
```python { .api }
621
class ServiceResource:
622
"""Cosmos DB service resource configuration and status."""
623
id: str # Resource ID
624
name: str # Service name
625
type: str # Resource type
626
properties: ServiceResourceProperties # Service-specific properties
627
628
class ServiceResourceProperties:
629
"""Base properties for Cosmos DB services."""
630
service_type: str # Type of service ("DataTransfer", "SqlDedicatedGateway", etc.)
631
instance_size: str # Instance size (e.g., "Cosmos.D4s", "Cosmos.D8s")
632
instance_count: int # Number of instances
633
status: str # Service status ("Creating", "Running", "Updating", "Deleting", "Error")
634
creation_time: str # Service creation timestamp
635
636
class ClusterResource:
637
"""Managed Cassandra cluster configuration and status."""
638
id: str # Resource ID
639
name: str # Cluster name
640
type: str # Resource type
641
location: str # Azure region
642
tags: Dict[str, str] # Resource tags
643
properties: ClusterResourceProperties # Cluster properties
644
645
class ClusterResourceProperties:
646
"""Managed Cassandra cluster properties."""
647
provisioning_state: str # Provisioning status
648
cluster_name_override: str # Custom cluster name
649
authentication_method: str # Authentication method ("None", "Cassandra", "Ldap")
650
initial_cassandra_admin_password: str # Initial admin password
651
client_certificates: List[Certificate] # Client certificates for authentication
652
external_gossip_certificates: List[Certificate] # Gossip certificates
653
external_seed_nodes: List[SeedNode] # External seed nodes
654
seed_nodes: List[SeedNode] # Current seed nodes
655
hours_between_backups: int # Backup frequency in hours
656
cassandra_version: str # Cassandra version
657
repair_enabled: bool # Whether automatic repair is enabled
658
deallocated: bool # Whether cluster is deallocated
659
660
class DataCenterResource:
661
"""Cassandra data center configuration and status."""
662
id: str # Resource ID
663
name: str # Data center name
664
type: str # Resource type
665
properties: DataCenterResourceProperties # Data center properties
666
667
class DataCenterResourceProperties:
668
"""Cassandra data center properties."""
669
provisioning_state: str # Provisioning status
670
data_center_location: str # Azure region for the data center
671
delegated_management_subnet_id: str # Subnet ID for management traffic
672
node_count: int # Number of Cassandra nodes
673
seed_nodes: List[SeedNode] # Seed nodes in this data center
674
base64_encoded_cassandra_yaml_fragment: str # Cassandra.yaml configuration fragment
675
managed_disk_customer_key_uri: str # Customer-managed key for disk encryption
676
backup_storage_customer_key_uri: str # Customer-managed key for backup encryption
677
sku: str # VM SKU for nodes
678
disk_sku: str # Managed disk SKU
679
disk_capacity: int # Disk capacity in GB
680
availability_zone: bool # Whether to use availability zones
681
682
class NotebookWorkspace:
683
"""Notebook workspace configuration and status."""
684
id: str # Resource ID
685
name: str # Workspace name
686
type: str # Resource type
687
status: str # Workspace status ("Creating", "Online", "Offline", "Updating", "Deleting")
688
689
class NotebookWorkspaceConnectionInfoResult:
690
"""Notebook workspace connection information."""
691
auth_token: str # Authentication token for accessing the workspace
692
notebook_server_endpoint: str # Jupyter notebook server URL
693
694
class SeedNode:
695
"""Cassandra seed node information."""
696
ip_address: str # IP address of the seed node
697
698
class Certificate:
699
"""Certificate for authentication."""
700
pem: str # PEM-encoded certificate content
701
702
class CommandPostBody:
703
"""Command execution request for Cassandra clusters."""
704
command: str # Command to execute (e.g., "nodetool status")
705
arguments: Dict[str, str] # Command arguments
706
host: str # Target host IP address
707
708
class CommandOutput:
709
"""Result of command execution on Cassandra cluster."""
710
result: str # Command output
711
exit_code: int # Command exit code
712
```
713
714
## Advanced Management Scenarios
715
716
### Multi-Region Cassandra Deployment
717
718
```python
719
def deploy_multi_region_cassandra():
720
"""Deploy a Cassandra cluster across multiple regions."""
721
722
# Create primary cluster in East US
723
primary_cluster = create_cassandra_cluster("East US", "primary-dc")
724
725
# Wait for primary cluster to be ready
726
while primary_cluster.properties.provisioning_state != "Succeeded":
727
time.sleep(30)
728
primary_cluster = client.cassandra_clusters.get("my-rg", "my-cluster")
729
730
# Add data centers in other regions
731
regions = ["West US", "North Europe", "Southeast Asia"]
732
733
for i, region in enumerate(regions):
734
dc_name = f"dc-{i+2}"
735
datacenter_config = DataCenterResource(
736
properties=DataCenterResourceProperties(
737
data_center_location=region,
738
delegated_management_subnet_id=get_subnet_for_region(region),
739
node_count=3,
740
sku="Standard_DS14_v2",
741
disk_sku="P50",
742
availability_zone=True
743
)
744
)
745
746
poller = client.cassandra_data_centers.begin_create_update(
747
"my-rg", "my-cluster", dc_name, datacenter_config
748
)
749
750
datacenter = poller.result()
751
print(f"Added data center in {region}: {datacenter.name}")
752
753
def get_subnet_for_region(region: str) -> str:
754
"""Get the appropriate subnet ID for a region."""
755
subnet_mapping = {
756
"West US": "/subscriptions/sub/resourceGroups/rg-west/providers/Microsoft.Network/virtualNetworks/vnet-west/subnets/cassandra",
757
"North Europe": "/subscriptions/sub/resourceGroups/rg-eu/providers/Microsoft.Network/virtualNetworks/vnet-eu/subnets/cassandra",
758
"Southeast Asia": "/subscriptions/sub/resourceGroups/rg-asia/providers/Microsoft.Network/virtualNetworks/vnet-asia/subnets/cassandra"
759
}
760
return subnet_mapping.get(region)
761
```