0
# Networking and Security
1

2
Private endpoint connections, private link resources, and security configuration for secure network access to Cosmos DB accounts. These operations enable secure communication through private networks, reducing exposure to the public internet.
3

4
## Capabilities
5

6
### Private Endpoint Connections
7

8
Manage private endpoint connections for secure network access to Cosmos DB accounts through Azure Private Link.
9

10
```python { .api }
11
def list_by_database_account(
12
    self,
13
    resource_group_name: str,
14
    account_name: str
15
) -> ItemPaged[PrivateEndpointConnection]:
16
    """
17
    List private endpoint connections for a database 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[PrivateEndpointConnection]: Paginated list of private endpoint connections
25
    """
26

27
def get(
28
    self,
29
    resource_group_name: str,
30
    account_name: str,
31
    private_endpoint_connection_name: str
32
) -> PrivateEndpointConnection:
33
    """
34
    Get properties of a private endpoint connection.
35
    
36
    Parameters:
37
    - resource_group_name: Name of the resource group
38
    - account_name: Name of the Cosmos DB account
39
    - private_endpoint_connection_name: Name of the private endpoint connection
40
    
41
    Returns:
42
    PrivateEndpointConnection: Private endpoint connection properties and status
43
    """
44

45
def begin_create_or_update(
46
    self,
47
    resource_group_name: str,
48
    account_name: str,
49
    private_endpoint_connection_name: str,
50
    parameters: PrivateEndpointConnection
51
) -> LROPoller[PrivateEndpointConnection]:
52
    """
53
    Create or update a private endpoint connection (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
    - private_endpoint_connection_name: Name of the connection to create/update
59
    - parameters: Private endpoint connection configuration
60
    
61
    Returns:
62
    LROPoller[PrivateEndpointConnection]: Poller for monitoring operation progress
63
    """
64

65
def begin_delete(
66
    self,
67
    resource_group_name: str,
68
    account_name: str,
69
    private_endpoint_connection_name: str
70
) -> LROPoller[None]:
71
    """
72
    Delete a private endpoint connection (Long Running Operation).
73
    
74
    Parameters:
75
    - resource_group_name: Name of the resource group
76
    - account_name: Name of the Cosmos DB account
77
    - private_endpoint_connection_name: Name of the connection to delete
78
    
79
    Returns:
80
    LROPoller[None]: Poller for monitoring operation progress
81
    """
82
```
83

84
### Private Link Resources
85

86
Manage private link resources and discover available sub-resources for private endpoint connections.
87

88
```python { .api }
89
def list_by_database_account(
90
    self,
91
    resource_group_name: str,
92
    account_name: str
93
) -> ItemPaged[PrivateLinkResource]:
94
    """
95
    List private link resources for a database account.
96
    
97
    Parameters:
98
    - resource_group_name: Name of the resource group
99
    - account_name: Name of the Cosmos DB account
100
    
101
    Returns:
102
    ItemPaged[PrivateLinkResource]: Paginated list of private link resources
103
    """
104

105
def get(
106
    self,
107
    resource_group_name: str,
108
    account_name: str,
109
    group_name: str
110
) -> PrivateLinkResource:
111
    """
112
    Get properties of a private link resource.
113
    
114
    Parameters:
115
    - resource_group_name: Name of the resource group
116
    - account_name: Name of the Cosmos DB account
117
    - group_name: Name of the private link resource group
118
    
119
    Returns:
120
    PrivateLinkResource: Private link resource properties and supported sub-resources
121
    """
122
```
123

124
## Usage Examples
125

126
### Setting Up Private Endpoint Connection
127

128
```python
129
from azure.mgmt.cosmosdb import CosmosDBManagementClient
130
from azure.mgmt.cosmosdb.models import (
131
    PrivateEndpointConnection,
132
    PrivateLinkServiceConnectionState,
133
    PrivateEndpoint
134
)
135
from azure.identity import DefaultAzureCredential
136

137
client = CosmosDBManagementClient(DefaultAzureCredential(), "subscription-id")
138

139
# Create private endpoint connection
140
private_endpoint_config = PrivateEndpointConnection(
141
    private_endpoint=PrivateEndpoint(
142
        id="/subscriptions/sub-id/resourceGroups/network-rg/providers/Microsoft.Network/privateEndpoints/my-private-endpoint"
143
    ),
144
    private_link_service_connection_state=PrivateLinkServiceConnectionState(
145
        status="Approved",
146
        description="Approved for production use",
147
        actions_required="None"
148
    )
149
)
150

151
# Create the connection
152
poller = client.private_endpoint_connections.begin_create_or_update(
153
    "my-resource-group",
154
    "my-cosmos-account",
155
    "my-private-endpoint-connection",
156
    private_endpoint_config
157
)
158

159
connection = poller.result()
160
print(f"Private endpoint connection status: {connection.private_link_service_connection_state.status}")
161
```
162

163
### Discovering Available Private Link Resources
164

165
```python
166
# List available private link resources
167
private_link_resources = client.private_link_resources.list_by_database_account(
168
    "my-resource-group",
169
    "my-cosmos-account"
170
)
171

172
for resource in private_link_resources:
173
    print(f"Group ID: {resource.group_id}")
174
    print(f"Required Members: {resource.required_members}")
175
    print(f"Required Zone Names: {resource.required_zone_names}")
176
    print("---")
177

178
# Get specific private link resource details
179
sql_resource = client.private_link_resources.get(
180
    "my-resource-group",
181
    "my-cosmos-account", 
182
    "Sql"  # Common group IDs: "Sql", "MongoDB", "Cassandra", "Gremlin", "Table"
183
)
184

185
print(f"SQL Private Link Resource:")
186
print(f"  Group ID: {sql_resource.group_id}")
187
print(f"  Required Members: {sql_resource.required_members}")
188
print(f"  Required DNS Zone Names: {sql_resource.required_zone_names}")
189
```
190

191
### Managing Private Endpoint Connection Lifecycle
192

193
```python
194
# List all private endpoint connections
195
connections = client.private_endpoint_connections.list_by_database_account(
196
    "my-resource-group",
197
    "my-cosmos-account"
198
)
199

200
for connection in connections:
201
    print(f"Connection: {connection.name}")
202
    print(f"Status: {connection.private_link_service_connection_state.status}")
203
    print(f"Provisioning State: {connection.provisioning_state}")
204
    
205
    # Approve pending connections
206
    if connection.private_link_service_connection_state.status == "Pending":
207
        print(f"Approving connection: {connection.name}")
208
        
209
        # Update connection state to approved
210
        connection.private_link_service_connection_state.status = "Approved"
211
        connection.private_link_service_connection_state.description = "Auto-approved by management script"
212
        
213
        poller = client.private_endpoint_connections.begin_create_or_update(
214
            "my-resource-group",
215
            "my-cosmos-account",
216
            connection.name.split('/')[-1],  # Extract connection name from full resource path
217
            connection
218
        )
219
        
220
        updated_connection = poller.result()
221
        print(f"Updated status: {updated_connection.private_link_service_connection_state.status}")
222

223
print("---")
224
```
225

226
### Rejecting and Cleaning Up Private Endpoint Connections
227

228
```python
229
# Reject a specific private endpoint connection
230
connection_name = "unwanted-private-endpoint-connection"
231

232
try:
233
    connection = client.private_endpoint_connections.get(
234
        "my-resource-group",
235
        "my-cosmos-account",
236
        connection_name
237
    )
238
    
239
    # Reject the connection
240
    connection.private_link_service_connection_state.status = "Rejected"
241
    connection.private_link_service_connection_state.description = "Connection rejected due to security policy"
242
    
243
    poller = client.private_endpoint_connections.begin_create_or_update(
244
        "my-resource-group",
245
        "my-cosmos-account",
246
        connection_name,
247
        connection
248
    )
249
    
250
    rejected_connection = poller.result()
251
    print(f"Connection rejected: {rejected_connection.private_link_service_connection_state.status}")
252
    
253
    # Optionally delete the rejected connection
254
    delete_poller = client.private_endpoint_connections.begin_delete(
255
        "my-resource-group",
256
        "my-cosmos-account", 
257
        connection_name
258
    )
259
    
260
    delete_poller.result()
261
    print(f"Connection {connection_name} deleted")
262
    
263
except Exception as e:
264
    print(f"Connection {connection_name} not found or error occurred: {e}")
265
```
266

267
### Monitoring Private Endpoint Connection Health
268

269
```python
270
# Monitor connection health and troubleshoot issues
271
connections = client.private_endpoint_connections.list_by_database_account(
272
    "my-resource-group",
273
    "my-cosmos-account"
274
)
275

276
print("Private Endpoint Connection Health Report:")
277
print("=" * 50)
278

279
for connection in connections:
280
    print(f"Connection: {connection.name}")
281
    print(f"  Private Endpoint ID: {connection.private_endpoint.id if connection.private_endpoint else 'None'}")
282
    print(f"  Connection Status: {connection.private_link_service_connection_state.status}")
283
    print(f"  Provisioning State: {connection.provisioning_state}")
284
    print(f"  Description: {connection.private_link_service_connection_state.description}")
285
    print(f"  Actions Required: {connection.private_link_service_connection_state.actions_required}")
286
    
287
    # Check for any issues
288
    if connection.provisioning_state != "Succeeded":
289
        print(f"  ⚠️  WARNING: Provisioning state is {connection.provisioning_state}")
290
    
291
    if connection.private_link_service_connection_state.status == "Rejected":
292
        print(f"  ❌ ERROR: Connection is rejected")
293
    elif connection.private_link_service_connection_state.status == "Pending":
294
        print(f"  ⏳ PENDING: Connection requires approval")
295
    elif connection.private_link_service_connection_state.status == "Approved":
296
        print(f"  ✅ SUCCESS: Connection is approved and active")
297
    
298
    print("---")
299
```
300

301
## Key Types
302

303
```python { .api }
304
class PrivateEndpointConnection:
305
    """Private endpoint connection configuration and status."""
306
    id: str  # Resource ID of the connection
307
    name: str  # Connection name
308
    type: str  # Resource type
309
    private_endpoint: PrivateEndpoint  # Private endpoint details
310
    private_link_service_connection_state: PrivateLinkServiceConnectionState  # Connection state
311
    group_id: str  # Private link sub-resource group ID
312
    provisioning_state: str  # Provisioning state ("Succeeded", "Failed", "Creating", etc.)
313

314
class PrivateEndpoint:
315
    """Private endpoint resource reference."""
316
    id: str  # Resource ID of the private endpoint
317

318
class PrivateLinkServiceConnectionState:
319
    """Private link service connection state and status."""
320
    status: str  # Connection status ("Pending", "Approved", "Rejected")
321
    description: str  # Human-readable description of the connection state
322
    actions_required: str  # Required actions (if any) to complete the connection
323

324
class PrivateLinkResource:
325
    """Private link resource definition and capabilities."""
326
    id: str  # Resource ID
327
    name: str  # Resource name
328
    type: str  # Resource type
329
    group_id: str  # Private link resource group identifier
330
    required_members: List[str]  # Required members for the private link resource
331
    required_zone_names: List[str]  # Required private DNS zone names for the resource
332

333
# Common Private Link Group IDs
334
class PrivateLinkGroupIds:
335
    """Common private link group identifiers for different Cosmos DB APIs."""
336
    SQL = "Sql"  # SQL (Core) API
337
    MONGODB = "MongoDB"  # MongoDB API
338
    CASSANDRA = "Cassandra"  # Cassandra API
339
    GREMLIN = "Gremlin"  # Gremlin (Graph) API
340
    TABLE = "Table"  # Table API
341
    ANALYTICAL_STORAGE = "AnalyticalStorage"  # Azure Synapse Link analytical storage
342

343
# Connection Status Values
344
class ConnectionStatus:
345
    """Private endpoint connection status values."""
346
    PENDING = "Pending"  # Connection awaiting approval
347
    APPROVED = "Approved"  # Connection approved and active
348
    REJECTED = "Rejected"  # Connection rejected
349

350
# Provisioning States
351
class ProvisioningState:
352
    """Private endpoint connection provisioning states."""
353
    SUCCEEDED = "Succeeded"  # Successfully provisioned
354
    FAILED = "Failed"  # Provisioning failed
355
    CREATING = "Creating"  # Currently being created
356
    UPDATING = "Updating"  # Currently being updated
357
    DELETING = "Deleting"  # Currently being deleted
358
    CANCELED = "Canceled"  # Operation was canceled
359
```
360

361
## Security Best Practices
362

363
### Network Isolation
364

365
```python
366
# Configure Cosmos DB account for private endpoint only access
367
from azure.mgmt.cosmosdb.models import DatabaseAccountUpdateParameters
368

369
# Disable public network access
370
update_params = DatabaseAccountUpdateParameters(
371
    public_network_access="Disabled",
372
    network_acl_bypass="None"  # Disable bypass for Azure services
373
)
374

375
poller = client.database_accounts.begin_update(
376
    "my-resource-group",
377
    "my-cosmos-account",
378
    update_params
379
)
380

381
updated_account = poller.result()
382
print(f"Public network access: {updated_account.public_network_access}")
383
```
384

385
### DNS Configuration
386

387
When using private endpoints, ensure proper DNS configuration:
388

389
1. **Private DNS Zones**: Create private DNS zones for Cosmos DB endpoints
390
   - `privatelink.documents.azure.com` for SQL API
391
   - `privatelink.mongo.cosmos.azure.com` for MongoDB API
392
   - `privatelink.cassandra.cosmos.azure.com` for Cassandra API
393
   - `privatelink.gremlin.cosmos.azure.com` for Gremlin API
394
   - `privatelink.table.cosmos.azure.com` for Table API
395

396
2. **DNS Records**: Create A records pointing to private endpoint IP addresses
397

398
3. **Virtual Network Links**: Link private DNS zones to virtual networks using private endpoints
399

400
### Connection Validation
401

402
```python
403
def validate_private_endpoint_setup(resource_group: str, account_name: str):
404
    """Validate private endpoint configuration for a Cosmos DB account."""
405
    
406
    # Check account network access settings
407
    account = client.database_accounts.get(resource_group, account_name)
408
    
409
    if account.public_network_access == "Enabled":
410
        print("⚠️  WARNING: Public network access is enabled")
411
    else:
412
        print("✅ Public network access is disabled")
413
    
414
    # Check private endpoint connections
415
    connections = client.private_endpoint_connections.list_by_database_account(
416
        resource_group, account_name
417
    )
418
    
419
    approved_connections = []
420
    for connection in connections:
421
        if connection.private_link_service_connection_state.status == "Approved":
422
            approved_connections.append(connection)
423
    
424
    if len(approved_connections) == 0:
425
        print("❌ ERROR: No approved private endpoint connections found")
426
    else:
427
        print(f"✅ Found {len(approved_connections)} approved private endpoint connections")
428
    
429
    # Check available private link resources
430
    private_link_resources = client.private_link_resources.list_by_database_account(
431
        resource_group, account_name
432
    )
433
    
434
    print(f"Available private link resources: {[r.group_id for r in private_link_resources]}")
435

436
# Run validation
437
validate_private_endpoint_setup("my-resource-group", "my-cosmos-account")
438
```