Skip to content

Commit 7b53d35

Browse files
v-albemiv-albemi
authored
Merge pull request #107506 from ThomasWeiss/thweiss-cosmosdb-pe-ga
Made GA changes for private endpoints
2 parents 80a9456 + e1cb6ae commit 7b53d35

File tree

1 file changed

+59
-70
lines changed

1 file changed

+59
-70
lines changed

‎articles/cosmos-db/how-to-configure-private-endpoints.md

Lines changed: 59 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ ms.date: 11/04/2019
88
ms.author: thweiss
99
---
1010

11-
# Configure Azure Private Link for an Azure Cosmos account (preview)
11+
# Configure Azure Private Link for an Azure Cosmos account
1212

1313
By using Azure Private Link, you can connect to an Azure Cosmos account via a private endpoint. The private endpoint is a set of private IP addresses in a subnet within your virtual network. You can then limit access to an Azure Cosmos account over private IP addresses. When Private Link is combined with restricted NSG policies, it helps reduce the risk of data exfiltration. To learn more about private endpoints, see the [Azure Private Link](../private-link/private-link-overview.md) article.
1414

@@ -18,6 +18,9 @@ You can connect to an Azure Cosmos account configured with Private Link by using
1818

1919
This article describes the steps to create a private endpoint. It assumes that you're using the automatic approval method.
2020

21+
> [!NOTE]
22+
> Private endpoint support is currently generally available in supported regions for gateway connection mode only. For direct mode, it is available as a preview feature.
23+
2124
## Create a private endpoint by using the Azure portal
2225

2326
Use the following steps to create a private endpoint for an existing Azure Cosmos account by using the Azure portal:
@@ -28,7 +31,7 @@ Use the following steps to create a private endpoint for an existing Azure Cosmo
2831

2932
![Selections for create a private endpoint in the Azure portal](./media/how-to-configure-private-endpoints/create-private-endpoint-portal.png)
3033

31-
1. In the **Create a private endpoint (Preview) - Basics** pane, enter or select the following details:
34+
1. In the **Create a private endpoint - Basics** pane, enter or select the following details:
3235

3336
| Setting | Value |
3437
| ------- | ----- |
@@ -52,7 +55,7 @@ Use the following steps to create a private endpoint for an existing Azure Cosmo
5255
|||
5356

5457
1. Select **Next: Configuration**.
55-
1. In **Create a private endpoint (Preview) - Configuration**, enter or select this information:
58+
1. In **Create a private endpoint - Configuration**, enter or select this information:
5659

5760
| Setting | Value |
5861
| ------- | ----- |
@@ -306,13 +309,13 @@ $virtualNetwork | Set-AzVirtualNetwork
306309
## Step 4: Create the private endpoint.
307310
Write-Output "Deploying private endpoint on $($resourceGroupName)"
308311
$deploymentOutput = New-AzResourceGroupDeployment -Name "PrivateCosmosDbEndpointDeployment" `
309-
-ResourceGroupName $resourceGroupName `
310-
-TemplateFile $PrivateEndpointTemplateFilePath `
311-
-TemplateParameterFile $PrivateEndpointParametersFilePath `
312-
-SubnetId $SubnetResourceId `
313-
-ResourceId $CosmosDbResourceId `
314-
-GroupId $CosmosDbApiType `
315-
-PrivateEndpointName $PrivateEndpointName
312+
-ResourceGroupName $resourceGroupName `
313+
-TemplateFile $PrivateEndpointTemplateFilePath `
314+
-TemplateParameterFile $PrivateEndpointParametersFilePath `
315+
-SubnetId $SubnetResourceId `
316+
-ResourceId $CosmosDbResourceId `
317+
-GroupId $CosmosDbApiType `
318+
-PrivateEndpointName $PrivateEndpointName
316319
317320
$deploymentOutput
318321
```
@@ -342,20 +345,20 @@ Use the following code to create a Resource Manager template named "PrivateZone_
342345
"privateZoneName": {
343346
"type": "string"
344347
},
345-
"VNetId": {
348+
"VNetId": {
346349
"type": "string"
347-
}
350+
}
348351
},
349-
"resources": [
350-
{
352+
"resources": [
353+
{
351354
"name": "[parameters('privateZoneName')]",
352355
"type": "Microsoft.Network/privateDnsZones",
353356
"apiVersion": "2018-09-01",
354357
"location": "global",
355-
"properties": {
358+
"properties": {
356359
}
357360
},
358-
{
361+
{
359362
"type": "Microsoft.Network/privateDnsZones/virtualNetworkLinks",
360363
"apiVersion": "2018-09-01",
361364
"name": "[concat(parameters('privateZoneName'), '/myvnetlink')]",
@@ -369,7 +372,7 @@ Use the following code to create a Resource Manager template named "PrivateZone_
369372
"id": "[parameters('VNetId')]"
370373
}
371374
}
372-
}
375+
}
373376
]
374377
}
375378
```
@@ -384,12 +387,12 @@ Use the following code to create a Resource Manager template named "PrivateZoneR
384387
"DNSRecordName": {
385388
"type": "string"
386389
},
387-
"IPAddress": {
388-
"type":"string"
389-
}
390+
"IPAddress": {
391+
"type":"string"
392+
}
390393
},
391-
"resources": [
392-
{
394+
"resources": [
395+
{
393396
"type": "Microsoft.Network/privateDnsZones/A",
394397
"apiVersion": "2018-09-01",
395398
"name": "[parameters('DNSRecordName')]",
@@ -401,7 +404,7 @@ Use the following code to create a Resource Manager template named "PrivateZoneR
401404
}
402405
]
403406
}
404-
}
407+
}
405408
]
406409
}
407410
```
@@ -418,8 +421,8 @@ Create the following two parameters file for the template. Create the "PrivateZo
418421
"privateZoneName": {
419422
"value": ""
420423
},
421-
"VNetId": {
422-
"value": ""
424+
"VNetId": {
425+
"value": ""
423426
}
424427
}
425428
}
@@ -435,9 +438,9 @@ Create the "PrivateZoneRecords_parameters.json." with the following code:
435438
"DNSRecordName": {
436439
"value": ""
437440
},
438-
"IPAddress": {
439-
"type":"object"
440-
}
441+
"IPAddress": {
442+
"type":"object"
443+
}
441444
}
442445
}
443446
```
@@ -490,38 +493,38 @@ $virtualNetwork | Set-AzVirtualNetwork
490493
491494
## Step 4: Create the private zone
492495
New-AzResourceGroupDeployment -Name "PrivateZoneDeployment" `
493-
-ResourceGroupName $ResourceGroupName `
494-
-TemplateFile $PrivateZoneTemplateFilePath `
495-
-TemplateParameterFile $PrivateZoneParametersFilePath `
496-
-PrivateZoneName $PrivateZoneName `
497-
-VNetId $VNetResourceId
496+
-ResourceGroupName $ResourceGroupName `
497+
-TemplateFile $PrivateZoneTemplateFilePath `
498+
-TemplateParameterFile $PrivateZoneParametersFilePath `
499+
-PrivateZoneName $PrivateZoneName `
500+
-VNetId $VNetResourceId
498501
499502
## Step 5: Create the private endpoint
500503
Write-Output "Deploying private endpoint on $($resourceGroupName)"
501504
$deploymentOutput = New-AzResourceGroupDeployment -Name "PrivateCosmosDbEndpointDeployment" `
502-
-ResourceGroupName $resourceGroupName `
503-
-TemplateFile $PrivateEndpointTemplateFilePath `
504-
-TemplateParameterFile $PrivateEndpointParametersFilePath `
505-
-SubnetId $SubnetResourceId `
506-
-ResourceId $CosmosDbResourceId `
507-
-GroupId $CosmosDbApiType `
508-
-PrivateEndpointName $PrivateEndpointName
505+
-ResourceGroupName $resourceGroupName `
506+
-TemplateFile $PrivateEndpointTemplateFilePath `
507+
-TemplateParameterFile $PrivateEndpointParametersFilePath `
508+
-SubnetId $SubnetResourceId `
509+
-ResourceId $CosmosDbResourceId `
510+
-GroupId $CosmosDbApiType `
511+
-PrivateEndpointName $PrivateEndpointName
509512
$deploymentOutput
510513
511514
## Step 6: Map the private endpoint to the private zone
512515
$networkInterface = Get-AzResource -ResourceId $deploymentOutput.Outputs.privateEndpointNetworkInterface.Value -ApiVersion "2019-04-01"
513516
foreach ($ipconfig in $networkInterface.properties.ipConfigurations) {
514-
foreach ($fqdn in $ipconfig.properties.privateLinkConnectionProperties.fqdns) {
515-
$recordName = $fqdn.split('.',2)[0]
516-
$dnsZone = $fqdn.split('.',2)[1]
517-
Write-Output "Deploying PrivateEndpoint DNS Record $($PrivateZoneName)/$($recordName) Template on $($resourceGroupName)"
518-
New-AzResourceGroupDeployment -Name "PrivateEndpointDNSDeployment" `
519-
-ResourceGroupName $ResourceGroupName `
520-
-TemplateFile $PrivateZoneRecordsTemplateFilePath `
521-
-TemplateParameterFile $PrivateZoneRecordsParametersFilePath `
522-
-DNSRecordName "$($PrivateZoneName)/$($RecordName)" `
523-
-IPAddress $ipconfig.properties.privateIPAddress
524-
}
517+
foreach ($fqdn in $ipconfig.properties.privateLinkConnectionProperties.fqdns) {
518+
$recordName = $fqdn.split('.',2)[0]
519+
$dnsZone = $fqdn.split('.',2)[1]
520+
Write-Output "Deploying PrivateEndpoint DNS Record $($PrivateZoneName)/$($recordName) Template on $($resourceGroupName)"
521+
New-AzResourceGroupDeployment -Name "PrivateEndpointDNSDeployment" `
522+
-ResourceGroupName $ResourceGroupName `
523+
-TemplateFile $PrivateZoneRecordsTemplateFilePath `
524+
-TemplateParameterFile $PrivateZoneRecordsParametersFilePath `
525+
-DNSRecordName "$($PrivateZoneName)/$($RecordName)" `
526+
-IPAddress $ipconfig.properties.privateIPAddress
527+
}
525528
}
526529
```
527530

@@ -543,29 +546,13 @@ The following situations and outcomes are possible when you use Private Link in
543546

544547
## Update a private endpoint when you add or remove a region
545548

546-
Adding or removing regions to an Azure Cosmos account requires you to add or remove DNS entries for that account. Update these changes accordingly in the private endpoint by using the following steps:
547-
548-
1. When the Azure Cosmos DB administrator adds or removes regions, the network administrator gets a notification about the pending changes. For the private endpoint mapped to an Azure Cosmos account, the value of the `ActionsRequired` property changes from `None` to `Recreate`. Then the network administrator updates the private endpoint by issuing a PUT request with the same Resource Manager payload that was used to create it.
549-
550-
1. After the private endpoint is updated, you can update the subnet's private DNS zone to reflect the added or removed DNS entries and their corresponding private IP addresses.
549+
Adding or removing regions to an Azure Cosmos account requires you to add or remove DNS entries for that account. After regions have been added or removed, you can update the subnet's private DNS zone to reflect the added or removed DNS entries and their corresponding private IP addresses.
551550

552551
For example, imagine that you deploy an Azure Cosmos account in three regions: "West US," "Central US," and "West Europe." When you create a private endpoint for your account, four private IPs are reserved in the subnet. There's one IP for each of the three regions, and there's one IP for the global/region-agnostic endpoint.
553552

554-
Later, you might add a new region (for example, "East US") to the Azure Cosmos account. By default, the new region is not accessible from the existing private endpoint. The Azure Cosmos account administrator should refresh the private endpoint connection before accessing it from the new region.
555-
556-
When you run the ` Get-AzPrivateEndpoint -Name <your private endpoint name> -ResourceGroupName <your resource group name>` command, the output of the command contains the `actionsRequired` parameter. This parameter is set to `Recreate`. This value indicates that the private endpoint should be refreshed. Next, the Azure Cosmos account administrator runs the `Set-AzPrivateEndpoint` command to trigger the private endpoint refresh.
557-
558-
```powershell
559-
$pe = Get-AzPrivateEndpoint -Name <your private endpoint name> -ResourceGroupName <your resource group name>
560-
561-
Set-AzPrivateEndpoint -PrivateEndpoint $pe
562-
```
563-
564-
A new private IP is automatically reserved in the subnet under this private endpoint. The value for `actionsRequired` becomes `None`. If you don't have any private DNZ zone integration (in other words, if you're using a custom private DNS zone), you have to configure your private DNS zone to add a new DNS record for the private IP that corresponds to the new region.
553+
Later, you might add a new region (for example, "East US") to the Azure Cosmos account. After adding the new region, you need to add a corresponding DNS record to either your private DNS zone or your custom DNS.
565554

566-
You can use the same steps when you remove a region. The private IP of the removed region is automatically reclaimed, and the `actionsRequired` flag becomes `None`. If you don't have any private DNZ zone integration, you must configure your private DNS zone to remove the DNS record for the removed region.
567-
568-
DNS records in the private DNS zone are not removed automatically when a private endpoint is deleted or a region from the Azure Cosmos account is removed. You must manually remove the DNS records.
555+
You can use the same steps when you remove a region. After removing the region, you need to remove the corresponding DNS record from either your private DNS zone or your custom DNS.
569556

570557
## Current limitations
571558

@@ -578,6 +565,8 @@ The following limitations apply when you're using Private Link with an Azure Cos
578565
579566
* When you're using Private Link with an Azure Cosmos account by using a direct mode connection, you can use only the TCP protocol. The HTTP protocol is not yet supported.
580567

568+
* Private endpoint support is currently generally available in supported regions for gateway connection mode only. For direct mode, it is available as a preview feature.
569+
581570
* When you're using Azure Cosmos DB's API for MongoDB accounts, a private endpoint is supported for accounts on server version 3.6 only (that is, accounts using the endpoint in the format `*.mongo.cosmos.azure.com`). Private Link is not supported for accounts on server version 3.2 (that is, accounts using the endpoint in the format `*.documents.azure.com`). To use Private Link, you should migrate old accounts to the new version.
582571

583572
* When you're using the Azure Cosmos DB's API for MongoDB accounts that have Private Link, you can't use tools such as Robo 3T, Studio 3T, and Mongoose. The endpoint can have Private Link support only if the `appName=<account name>` parameter is specified. An example is `replicaSet=globaldb&appName=mydbaccountname`. Because these tools don't pass the app name in the connection string to the service, you can't use Private Link. But you can still access these accounts by using SDK drivers with the 3.6 version.

0 commit comments

Comments
 (0)