0
# Azure Kusto Management Client
1

2
Microsoft Azure Kusto Management Client Library for Python provides comprehensive management of Azure Data Explorer (Kusto) resources through the Azure Resource Manager API. This library enables developers to programmatically create, configure, and manage Kusto clusters, databases, and related resources including database principal assignments, private endpoints, managed private endpoints, and data connections.
3

4
## Package Information
5

6
- **Package Name**: azure-mgmt-kusto
7
- **Language**: Python
8
- **Installation**: `pip install azure-mgmt-kusto azure-identity`
9
- **Python Requirements**: >=3.8
10
- **API Version**: 2024-04-13
11

12
## Core Imports
13

14
```python
15
from azure.mgmt.kusto import KustoManagementClient
16
from azure.identity import DefaultAzureCredential
17
```
18

19
For async operations:
20

21
```python
22
from azure.mgmt.kusto.aio import KustoManagementClient
23
from azure.identity.aio import DefaultAzureCredential
24
```
25

26
## Basic Usage
27

28
```python
29
import os
30
from azure.identity import DefaultAzureCredential
31
from azure.mgmt.kusto import KustoManagementClient
32

33
# Authentication using environment variables:
34
# AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET, AZURE_SUBSCRIPTION_ID
35
credential = DefaultAzureCredential()
36
subscription_id = os.getenv("AZURE_SUBSCRIPTION_ID")
37

38
# Create the management client
39
client = KustoManagementClient(
40
    credential=credential,
41
    subscription_id=subscription_id
42
)
43

44
# List all Kusto clusters in the subscription
45
clusters = list(client.clusters.list())
46
print(f"Found {len(clusters)} Kusto clusters")
47

48
# Get a specific cluster
49
cluster = client.clusters.get(
50
    resource_group_name="my-resource-group",
51
    cluster_name="my-kusto-cluster"
52
)
53
print(f"Cluster URI: {cluster.uri}")
54

55
# List databases in a cluster
56
databases = list(client.databases.list_by_cluster(
57
    resource_group_name="my-resource-group",
58
    cluster_name="my-kusto-cluster"
59
))
60
print(f"Found {len(databases)} databases")
61

62
# Close the client when done
63
client.close()
64
```
65

66
## Architecture
67

68
The azure-mgmt-kusto library follows Azure SDK design patterns with a layered architecture:
69

70
- **KustoManagementClient**: Main entry point providing access to all operations
71
- **Operations Classes**: 16 specialized operation groups handling different resource types
72
- **Model Classes**: 93+ data models representing Azure resources and request/response objects
73
- **Enumeration Classes**: 41+ enums defining valid values for various properties
74
- **Authentication**: Integration with Azure Identity for credential management
75
- **Long-Running Operations**: Built-in polling for async Azure operations via LROPoller
76

77
Both synchronous and asynchronous versions are available, with the async client providing identical functionality using `async`/`await` patterns.
78

79
## Capabilities
80

81
### Cluster Management
82

83
Complete lifecycle management of Kusto clusters including creation, configuration, scaling, start/stop operations, migration, network diagnostics, and SKU management.
84

85
```python { .api }
86
class ClustersOperations:
87
    def get(self, resource_group_name: str, cluster_name: str, **kwargs) -> Cluster: ...
88
    def begin_create_or_update(self, resource_group_name: str, cluster_name: str, parameters: Cluster, **kwargs) -> LROPoller[Cluster]: ...
89
    def begin_delete(self, resource_group_name: str, cluster_name: str, **kwargs) -> LROPoller[None]: ...
90
    def list(self, **kwargs) -> Iterable[Cluster]: ...
91
    def begin_start(self, resource_group_name: str, cluster_name: str, **kwargs) -> LROPoller[None]: ...
92
    def begin_stop(self, resource_group_name: str, cluster_name: str, **kwargs) -> LROPoller[None]: ...
93
```
94

95
[Cluster Management](./cluster-management.md)
96

97
### Database Management
98

99
Database lifecycle management within Kusto clusters including creation, configuration, principal management, and database sharing through attached database configurations.
100

101
```python { .api }
102
class DatabasesOperations:
103
    def get(self, resource_group_name: str, cluster_name: str, database_name: str, **kwargs) -> Database: ...
104
    def begin_create_or_update(self, resource_group_name: str, cluster_name: str, database_name: str, parameters: Database, **kwargs) -> LROPoller[Database]: ...
105
    def list_by_cluster(self, resource_group_name: str, cluster_name: str, **kwargs) -> Iterable[Database]: ...
106
    def add_principals(self, resource_group_name: str, cluster_name: str, database_name: str, database_principals_to_add: DatabasePrincipalListRequest, **kwargs) -> DatabasePrincipalListResult: ...
107
```
108

109
[Database Management](./database-management.md)
110

111
### Data Connections
112

113
Management of data ingestion connections from various Azure services including Event Hub, IoT Hub, Event Grid, and Cosmos DB for streaming data into Kusto databases.
114

115
```python { .api }
116
class DataConnectionsOperations:
117
    def get(self, resource_group_name: str, cluster_name: str, database_name: str, data_connection_name: str, **kwargs) -> DataConnection: ...
118
    def begin_create_or_update(self, resource_group_name: str, cluster_name: str, database_name: str, data_connection_name: str, parameters: DataConnection, **kwargs) -> LROPoller[DataConnection]: ...
119
    def list_by_database(self, resource_group_name: str, cluster_name: str, database_name: str, **kwargs) -> Iterable[DataConnection]: ...
120
    def begin_data_connection_validation(self, resource_group_name: str, cluster_name: str, database_name: str, parameters: DataConnectionValidation, **kwargs) -> LROPoller[DataConnectionValidationListResult]: ...
121
```
122

123
[Data Connections](./data-connections.md)
124

125
### Security Management
126

127
Comprehensive security management including cluster and database-level principal assignments, private endpoints, managed private endpoints, and private link resources.
128

129
```python { .api }
130
class ClusterPrincipalAssignmentsOperations:
131
    def get(self, resource_group_name: str, cluster_name: str, principal_assignment_name: str, **kwargs) -> ClusterPrincipalAssignment: ...
132
    def begin_create_or_update(self, resource_group_name: str, cluster_name: str, principal_assignment_name: str, parameters: ClusterPrincipalAssignment, **kwargs) -> LROPoller[ClusterPrincipalAssignment]: ...
133
    def list(self, resource_group_name: str, cluster_name: str, **kwargs) -> Iterable[ClusterPrincipalAssignment]: ...
134

135
class DatabasePrincipalAssignmentsOperations:
136
    def get(self, resource_group_name: str, cluster_name: str, database_name: str, principal_assignment_name: str, **kwargs) -> DatabasePrincipalAssignment: ...
137
    def begin_create_or_update(self, resource_group_name: str, cluster_name: str, database_name: str, principal_assignment_name: str, parameters: DatabasePrincipalAssignment, **kwargs) -> LROPoller[DatabasePrincipalAssignment]: ...
138
```
139

140
[Security Management](./security-management.md)
141

142
### Scripts and Extensions
143

144
Management of KQL scripts for database automation and language extensions for custom query capabilities including Python, R, and other supported languages.
145

146
```python { .api }
147
class ScriptsOperations:
148
    def get(self, resource_group_name: str, cluster_name: str, database_name: str, script_name: str, **kwargs) -> Script: ...
149
    def begin_create_or_update(self, resource_group_name: str, cluster_name: str, database_name: str, script_name: str, parameters: Script, **kwargs) -> LROPoller[Script]: ...
150
    def list_by_database(self, resource_group_name: str, cluster_name: str, database_name: str, **kwargs) -> Iterable[Script]: ...
151
```
152

153
[Scripts and Extensions](./scripts-extensions.md)
154

155
### Monitoring and Operations
156

157
Monitoring capabilities including operation results tracking, SKU information retrieval, and sandbox custom image management for specialized compute scenarios.
158

159
```python { .api }
160
class Operations:
161
    def list(self, **kwargs) -> Iterable[Operation]: ...
162

163
class OperationsResultsOperations:
164
    def get(self, location: str, operation_id: str, **kwargs) -> OperationResult: ...
165

166
class SkusOperations:
167
    def list(self, **kwargs) -> Iterable[SkuDescription]: ...
168
```
169

170
[Monitoring and Operations](./monitoring-operations.md)
171

172
## Core Types
173

174
```python { .api }
175
class KustoManagementClient:
176
    """Main management client for Azure Kusto services."""
177
    def __init__(
178
        self,
179
        credential: TokenCredential,
180
        subscription_id: str,
181
        base_url: str = "https://management.azure.com",
182
        **kwargs
183
    ): ...
184
    def close(self) -> None: ...
185

186
class Cluster:
187
    """Represents a Kusto cluster resource."""
188
    id: str  # Read-only resource ID
189
    name: str  # Read-only cluster name
190
    type: str  # Read-only resource type
191
    location: str  # Resource location
192
    tags: Dict[str, str]  # Resource tags
193
    sku: AzureSku  # Cluster SKU configuration
194
    zones: List[str]  # Availability zones
195
    identity: Identity  # Managed identity
196
    state: State  # Cluster state
197
    provisioning_state: ProvisioningState  # Provisioning state
198
    uri: str  # Cluster URI
199
    data_ingestion_uri: str  # Data ingestion URI
200

201
class Database:
202
    """Base class for database resources."""
203
    id: str  # Read-only resource ID
204
    name: str  # Read-only database name
205
    type: str  # Read-only resource type
206
    location: str  # Resource location
207
    kind: Kind  # Database kind (ReadWrite or ReadOnlyFollowing)
208

209
class DataConnection:
210
    """Base class for data connection resources."""
211
    id: str  # Read-only resource ID
212
    name: str  # Read-only data connection name  
213
    type: str  # Read-only resource type
214
    location: str  # Resource location
215
    kind: DataConnectionKind  # Data connection type
216

217
# Additional supporting types
218
class CheckNameRequest:
219
    """Request to check resource name availability."""
220
    name: str  # Name to check
221
    type: str  # Resource type
222

223
class CheckNameResult:
224
    """Result of name availability check."""
225
    name_available: bool  # Whether name is available
226
    reason: str  # Reason if not available
227
    message: str  # Additional message
228

229
class Identity:
230
    """Managed identity configuration."""
231
    type: IdentityType  # Identity type
232
    principal_id: str  # Principal ID (read-only)
233
    tenant_id: str  # Tenant ID (read-only)
234
    user_assigned_identities: Dict[str, Any]  # User assigned identities
235

236
class AzureSku:
237
    """Azure SKU configuration."""
238
    name: AzureSkuName  # SKU name
239
    tier: AzureSkuTier  # SKU tier
240
    capacity: int  # Instance capacity
241

242
class VirtualNetworkConfiguration:
243
    """Virtual network configuration."""
244
    subnet_id: str  # Subnet resource ID
245
    engine_public_ip_id: str  # Engine public IP resource ID
246
    data_management_public_ip_id: str  # Data management public IP resource ID
247

248
class KeyVaultProperties:
249
    """Key vault configuration for encryption."""
250
    key_name: str  # Key name
251
    key_version: str  # Key version
252
    key_vault_uri: str  # Key vault URI
253
    user_identity: str  # User identity for key access
254

255
class OptimizedAutoscale:
256
    """Auto-scaling configuration."""
257
    version: int  # Configuration version
258
    is_enabled: bool  # Whether auto-scaling is enabled
259
    minimum: int  # Minimum instance count
260
    maximum: int  # Maximum instance count
261

262
class AcceptedAudiences:
263
    """Accepted audience for authentication."""
264
    value: str  # Audience value (GUID or URL)
265

266
class ErrorDetail:
267
    """Error detail information."""
268
    code: str  # Error code
269
    message: str  # Error message
270
    target: str  # Error target
271
    details: List['ErrorDetail']  # Additional error details
272

273
class OperationResult:
274
    """Result of a long-running operation."""
275
    id: str  # Operation ID
276
    name: str  # Operation name
277
    status: str  # Operation status
278
    start_time: datetime  # Start time
279
    end_time: datetime  # End time
280
    percent_complete: float  # Completion percentage
281
    error: ErrorDetail  # Error details if failed
282

283
class SkuDescription:
284
    """Description of available SKU."""
285
    resource_type: str  # Resource type
286
    name: str  # SKU name
287
    tier: str  # SKU tier
288
    locations: List[str]  # Available locations
289
    capabilities: List[Dict[str, str]]  # SKU capabilities
290

291
from enum import Enum
292

293
class State(str, Enum):
294
    """Cluster state values."""
295
    CREATING = "Creating"
296
    UNAVAILABLE = "Unavailable"
297
    RUNNING = "Running"
298
    DELETING = "Deleting"
299
    DELETED = "Deleted"
300
    STOPPING = "Stopping"
301
    STOPPED = "Stopped"
302
    STARTING = "Starting"
303
    UPDATING = "Updating"
304
    MIGRATED = "Migrated"
305

306
class ProvisioningState(str, Enum):
307
    """Provisioning state values."""
308
    RUNNING = "Running"
309
    CREATING = "Creating"
310
    DELETING = "Deleting"
311
    SUCCEEDED = "Succeeded"
312
    FAILED = "Failed"
313
    MOVING = "Moving"
314
    CANCELED = "Canceled"
315

316
class DataConnectionKind(str, Enum):
317
    """Data connection type values."""
318
    EVENT_HUB = "EventHub"
319
    IOT_HUB = "IotHub"
320
    EVENT_GRID = "EventGrid"
321
    COSMOS_DB = "CosmosDb"
322

323
class Kind(str, Enum):
324
    """Database kind values."""
325
    READ_WRITE = "ReadWrite"
326
    READ_ONLY_FOLLOWING = "ReadOnlyFollowing"
327

328
class AzureSkuName(str, Enum):
329
    """SKU name values."""
330
    STANDARD_D13_V2 = "Standard_D13_v2"
331
    STANDARD_D14_V2 = "Standard_D14_v2"
332
    STANDARD_L4_S = "Standard_L4s"
333
    STANDARD_L8_S = "Standard_L8s"
334
    STANDARD_L16_S = "Standard_L16s"
335

336
class AzureSkuTier(str, Enum):
337
    """SKU tier values."""
338
    BASIC = "Basic"
339
    STANDARD = "Standard"
340

341
class IdentityType(str, Enum):
342
    """Identity type values."""
343
    NONE = "None"
344
    SYSTEM_ASSIGNED = "SystemAssigned"
345
    USER_ASSIGNED = "UserAssigned"
346
    SYSTEM_ASSIGNED_USER_ASSIGNED = "SystemAssigned, UserAssigned"
347

348
from typing import Union, Dict, List, Any
349
from datetime import datetime
350
from azure.core.polling import LROPoller  
351
from azure.core.paging import ItemPaged
352
from azure.core.credentials import TokenCredential
353

354
# Type aliases for better readability
355
Iterable = ItemPaged
356
```
357

358
## Error Handling
359

360
All operations can raise Azure SDK exceptions. Common error handling pattern:
361

362
```python
363
from azure.core.exceptions import HttpResponseError
364

365
try:
366
    cluster = client.clusters.get(
367
        resource_group_name="my-rg",
368
        cluster_name="my-cluster"
369
    )
370
except HttpResponseError as e:
371
    print(f"Request failed: {e.status_code} - {e.message}")
372
```
373

374
Long-running operations return `LROPoller` objects that can be used to track progress and handle failures:
375

376
```python 
377
try:
378
    poller = client.clusters.begin_create_or_update(
379
        resource_group_name="my-rg",
380
        cluster_name="my-cluster", 
381
        parameters=cluster_params
382
    )
383
    result = poller.result()  # Blocks until completion
384
except HttpResponseError as e:
385
    print(f"Operation failed: {e}")
386
```