Condividi tramite

Configurare Collegamento privato di Azure per un account di Azure Cosmos DB

  • Articolo

SI APPLICA A: NoSQL MongoDB Cassandra Gremlin Tabella

Con il collegamento privato di Azure è possibile connettersi a un account Azure Cosmos DB tramite un endpoint privato. L'endpoint privato è un set di indirizzi IP privati in una subnet all'interno della rete virtuale. È quindi possibile limitare l'accesso a un account Azure Cosmos DB tramite indirizzi IP privati. Quando Collegamento privato viene combinato con i criteri con restrizioni dei gruppi di sicurezza di rete, contribuisce alla riduzione del rischio di esfiltrazione dei dati. Per altre informazioni sugli endpoint privati, vedere Informazioni sul link privato di Azure

Nota

Il collegamento privato non impedisce che gli endpoint di Azure Cosmos DB vengano risolti dal DNS pubblico. Il filtraggio delle richieste in ingresso viene gestito al livello di applicazione, non al livello di trasporto o di rete.

Il collegamento privato consente agli utenti di accedere a un account Azure Cosmos DB dall'interno della rete virtuale o da qualsiasi rete virtuale con peering. Le risorse mappate al collegamento privato sono accessibili anche in locale tramite peering privato attraverso la VPN o Azure ExpressRoute.

È possibile connettersi a un account Azure Cosmos DB configurato con un collegamento privato usando il metodo di approvazione automatica o manuale. Per altre informazioni, vedere la sezione Flusso di lavoro di approvazione della documentazione del collegamento privato.

Questo articolo descrive come configurare endpoint privati per l'archivio transazionale di Azure Cosmos DB. Si presuppone che si stia usando il metodo di approvazione automatica. Se si usa l'archivio analitico, vedere Configurare gli endpoint privati per l'archivio analitico.

Creare un endpoint privato con il portale di Azure

Seguire questa procedura per creare un endpoint privato per un account Azure Cosmos DB esistente usando il portale di Azure:

  1. Accedere al portale di Azure, quindi selezionare un account Azure Cosmos DB.

  2. Selezionare Rete dall'elenco delle impostazioni e quindi selezionare + Endpoint privato nella scheda Accesso privato:

    Screenshot delle selezioni per la creazione di un endpoint privato nel portale di Azure

  3. Nel riquadro Crea un endpoint privato - Generale immettere o selezionare i dettagli seguenti:

    Impostazione Valore
    Dettagli di progetto
    Subscription Selezionare la propria sottoscrizione.
    Gruppo di risorse Selezionare un gruppo di risorse.
    Dettagli istanza
    Nome Immettere un nome per l'endpoint privato. Se il nome è già usato, creare un nome univoco.
    Area Selezionare l'area in cui si vuole distribuire il collegamento privato. Creare l'endpoint privato nella stessa posizione in cui si trova la rete virtuale.

  4. Selezionare Avanti: Risorsa.

  5. Nel riquadro Crea un endpoint privato - Risorsa immettere o selezionare queste informazioni:

    Impostazione Valore
    Metodo di connessione Selezionare Connettersi a una risorsa di Azure nella directory.

    È quindi possibile scegliere una delle risorse per configurare il collegamento privato. Oppure connettersi alla risorsa di un altro utente usando un ID risorsa o un alias condiviso.
    Abbonamento Selezionare la propria sottoscrizione.
    Tipo di risorsa Selezionare Microsoft.AzureCosmosDB/databaseAccounts.
    Conto risorse Selezionare l'account Azure Cosmos DB.
    Sottorisorsa di destinazione Selezionare il tipo di API di Azure Cosmos DB di cui si vuole eseguire il mapping. Per impostazione predefinita viene selezionata un'unica opzione per le API per SQL, MongoDB e Cassandra. Per le API per Gremlin e la Tabella, è anche possibile scegliere NoSQL poiché queste API sono interoperative con l'API per NoSQL. Se è stato effettuato il provisioning di un gateway dedicato per un account API per NoSQL, viene visualizzata anche un'opzione per SqlDedicated.

  6. Selezionare Avanti: Rete virtuale.

  7. Nel riquadro Crea un endpoint privato - Rete virtuale immettere o selezionare queste informazioni:

    Impostazione Valore
    Rete virtuale Selezionare la rete virtuale.
    Subnet Selezionare la subnet.

  8. Selezionare Avanti: DNS.

  9. In Crea un endpoint privato - DNS immettere o selezionare queste informazioni:

    Impostazione Valore
    Integra con la zona DNS privato Selezionare Sì.

    Per connettersi in privato con l'endpoint privato, è necessario un record DNS. È consigliabile integrare l'endpoint privato con una zona DNS privata. È anche possibile usare i propri server DNS o creare record DNS usando i file host delle macchine virtuali.

    Quando si seleziona Sì per questa opzione, viene creato anche un gruppo di zone DNS private. Il gruppo di zone DNS è un collegamento tra la zona DNS privata e l'endpoint privato. Questo collegamento consente di aggiornare automaticamente la zona DNS privata quando viene eseguito un aggiornamento all'endpoint privato. Ad esempio, quando si aggiungono o si rimuovono aree, la zona DNS privata viene aggiornata automaticamente.
    Nome configurazione Selezionare la sottoscrizione e il gruppo di risorse.

    La zona DNS privata viene determinata automaticamente. Non è possibile modificarla usando il portale di Azure.

  10. Selezionare Avanti: Tag>Rivedi e crea. Nella pagina Rivedi e crea Azure convalida la configurazione.

  11. Quando viene visualizzato il messaggio Convalida superata, selezionare Crea.

Quando si dispone di un link privato approvato per un account Azure Cosmos DB, nel portale di Azure l'opzione Tutte le reti nel riquadro Firewall e reti virtuali non è disponibile.

Tipi di API e nomi di zona privata

Vedere Configurazione DNS dell'endpoint privato di Azure per una spiegazione più dettagliata delle zone private e delle configurazioni DNS per l'endpoint privato. La tabella seguente illustra il mapping tra i diversi tipi di API dell'account Azure Cosmos DB, le risorse secondarie supportate e i nomi di zona privata corrispondenti. Poiché è anche possibile accedere agli account Gremlin e API per Tabella tramite l'API per NoSQL, sono disponibili due voci per queste API. È disponibile anche una voce aggiuntiva per l'API per NoSQL per gli account che usano il gateway dedicato.

Tipo di API dell'account Azure Cosmos DB Risorse secondarie supportate o ID gruppo Nome della zona privata
NoSQL Sql privatelink.documents.azure.com
NoSQL SqlDedicated privatelink.sqlx.cosmos.azure.com
Cassandra Cassandra privatelink.cassandra.cosmos.azure.com
Mongo MongoDB privatelink.mongo.cosmos.azure.com
Gremlin Gremlin privatelink.gremlin.cosmos.azure.com
Gremlin Sql privatelink.documents.azure.com
Tabella Tabella privatelink.table.cosmos.azure.com
Tabella Sql privatelink.documents.azure.com

Recuperare gli indirizzi IP privati

Dopo aver eseguito il provisioning dell'endpoint privato, è possibile eseguire una query sugli indirizzi IP. Per visualizzare gli indirizzi IP dal portale di Azure:

  1. Cercare l'endpoint privato creato in precedenza. In questo caso, si tratta di cdbPrivateEndpoint3.
  2. Selezionare la scheda Panoramica per visualizzare le impostazioni DNS e gli indirizzi IP.

Screenshot degli indirizzi IP privati nel portale di Azure

Per ogni endpoint privato vengono creati più indirizzi IP:

  • Uno per l'endpoint globale (indipendente dall'area) dell'account Azure Cosmos DB.
  • Uno per ogni area in cui è distribuito l'account Azure Cosmos DB.

Creare un endpoint privato con Azure PowerShell

Eseguire lo script di PowerShell seguente per creare un endpoint privato denominato MyPrivateEndpoint per un account Azure Cosmos DB esistente. Sostituire i valori delle variabili con i dettagli dell'ambiente in uso.

$SubscriptionId = "<your Azure subscription ID>"
# Resource group where the Azure Cosmos DB account and virtual network resources are located
$ResourceGroupName = "myResourceGroup"
# Name of the Azure Cosmos DB account
$CosmosDbAccountName = "mycosmosaccount"

# Resource for the Azure Cosmos DB account: Sql, SqlDedicated, MongoDB, Cassandra, Gremlin, or Table
$CosmosDbSubResourceType = "Sql"
# Name of the existing virtual network
$VNetName = "myVnet"
# Name of the target subnet in the virtual network
$SubnetName = "mySubnet"
# Name of the private endpoint to create
$PrivateEndpointName = "MyPrivateEndpoint"
# Location where the private endpoint can be created. The private endpoint should be created in the same location where your subnet or the virtual network exists
$Location = "westcentralus"

$cosmosDbResourceId = "/subscriptions/$($SubscriptionId)/resourceGroups/$($ResourceGroupName)/providers/Microsoft.DocumentDB/databaseAccounts/$($CosmosDbAccountName)"

$privateEndpointConnection = New-AzPrivateLinkServiceConnection -Name "myConnectionPS" -PrivateLinkServiceId $cosmosDbResourceId -GroupId $CosmosDbSubResourceType
 
$virtualNetwork = Get-AzVirtualNetwork -ResourceGroupName  $ResourceGroupName -Name $VNetName  
 
$subnet = $virtualNetwork | Select -ExpandProperty subnets | Where-Object  {$_.Name -eq $SubnetName}  
 
$privateEndpoint = New-AzPrivateEndpoint -ResourceGroupName $ResourceGroupName -Name $PrivateEndpointName -Location $Location -Subnet  $subnet -PrivateLinkServiceConnection $privateEndpointConnection

Integrare l'endpoint privato con una zona DNS privata

Dopo aver creato l'endpoint privato, è possibile integrarlo con una zona DNS privata usando lo script di PowerShell seguente:

Import-Module Az.PrivateDns

# Zone name differs based on the API type and group ID you are using. 
$zoneName = "privatelink.documents.azure.com"
$zone = New-AzPrivateDnsZone -ResourceGroupName $ResourceGroupName `
  -Name $zoneName

$link  = New-AzPrivateDnsVirtualNetworkLink -ResourceGroupName $ResourceGroupName `
  -ZoneName $zoneName `
  -Name "myzonelink" `
  -VirtualNetworkId $virtualNetwork.Id  
 
$pe = Get-AzPrivateEndpoint -Name $PrivateEndpointName `
  -ResourceGroupName $ResourceGroupName

$networkInterface = Get-AzResource -ResourceId $pe.NetworkInterfaces[0].Id `
  -ApiVersion "2019-04-01"

# Create DNS configuration

$PrivateDnsZoneId = $zone.ResourceId

$config = New-AzPrivateDnsZoneConfig -Name $zoneName `
 -PrivateDnsZoneId $PrivateDnsZoneId

## Create a DNS zone group
New-AzPrivateDnsZoneGroup -ResourceGroupName $ResourceGroupName `
 -PrivateEndpointName $PrivateEndpointName `
 -Name "MyPrivateZoneGroup" `
 -PrivateDnsZoneConfig $config

Recuperare gli indirizzi IP privati

Dopo aver effettuato il provisioning dell'endpoint privato, è possibile eseguire una query sugli indirizzi IP e sul mapping FQDN usando lo script di PowerShell seguente:

$pe = Get-AzPrivateEndpoint -Name MyPrivateEndpoint -ResourceGroupName myResourceGroup
$networkInterface = Get-AzNetworkInterface -ResourceId $pe.NetworkInterfaces[0].Id
foreach ($IPConfiguration in $networkInterface.IpConfigurations)
{
    Write-Host $IPConfiguration.PrivateIpAddress ":" $IPConfiguration.PrivateLinkConnectionProperties.Fqdns
}

Creare un endpoint privato con l'interfaccia della riga di comando di Azure

Eseguire lo script dell'interfaccia della riga di comando di Azure seguente per creare un endpoint privato denominato myPrivateEndpoint per un account Azure Cosmos DB esistente. Sostituire i valori delle variabili con i dettagli dell'ambiente in uso.

# Resource group where the Azure Cosmos DB account and virtual network resources are located
ResourceGroupName="myResourceGroup"

# Subscription ID where the Azure Cosmos DB account and virtual network resources are located
SubscriptionId="<your Azure subscription ID>"

# Name of the existing Azure Cosmos DB account
CosmosDbAccountName="mycosmosaccount"

# API type of your Azure Cosmos DB account: Sql, SqlDedicated, MongoDB, Cassandra, Gremlin, or Table
CosmosDbSubResourceType="Sql"

# Name of the virtual network to create
VNetName="myVnet"

# Name of the subnet to create
SubnetName="mySubnet"

# Name of the private endpoint to create
PrivateEndpointName="myPrivateEndpoint"

# Name of the private endpoint connection to create
PrivateConnectionName="myConnection"

az network vnet create \
 --name $VNetName \
 --resource-group $ResourceGroupName \
 --subnet-name $SubnetName

az network vnet subnet update \
 --name $SubnetName \
 --resource-group $ResourceGroupName \
 --vnet-name $VNetName \
 --disable-private-endpoint-network-policies true

az network private-endpoint create \
    --name $PrivateEndpointName \
    --resource-group $ResourceGroupName \
    --vnet-name $VNetName  \
    --subnet $SubnetName \
    --private-connection-resource-id "/subscriptions/$SubscriptionId/resourceGroups/$ResourceGroupName/providers/Microsoft.DocumentDB/databaseAccounts/$CosmosDbAccountName" \
    --group-ids $CosmosDbSubResourceType \
    --connection-name $PrivateConnectionName

Integrare l'endpoint privato con una zona DNS privata

Dopo aver creato l'endpoint privato, è possibile integrarlo con una zona DNS privata usando lo script dell'interfaccia della riga di comando di Azure seguente:

#Zone name differs based on the API type and group ID you are using. 
zoneName="privatelink.documents.azure.com"

az network private-dns zone create --resource-group $ResourceGroupName \
   --name  $zoneName

az network private-dns link vnet create --resource-group $ResourceGroupName \
   --zone-name  $zoneName\
   --name myzonelink \
   --virtual-network $VNetName \
   --registration-enabled false 

#Create a DNS zone group
az network private-endpoint dns-zone-group create \
   --resource-group $ResourceGroupName \
   --endpoint-name $PrivateEndpointName \
   --name "MyPrivateZoneGroup" \
   --private-dns-zone $zoneName \
   --zone-name "myzone"

Creare un endpoint privato con un modello di Resource Manager

È possibile configurare il collegamento privato creando un endpoint privato in una subnet di rete virtuale. L'operazione può essere eseguita usando un modello di Azure Resource Manager.

Usare il codice seguente per creare un modello di Resource Manager denominato PrivateEndpoint_template.json. Questo modello crea un endpoint privato per un account Azure Cosmos DB vAPI per NoSQL esistente in una rete virtuale esistente.

@description('Location for all resources.')
param location string = resourceGroup().location
param privateEndpointName string
param resourceId string
param groupId string
param subnetId string

resource privateEndpoint 'Microsoft.Network/privateEndpoints@2019-04-01' = {
  name: privateEndpointName
  location: location
  properties: {
    subnet: {
      id: subnetId
    }
    privateLinkServiceConnections: [
      {
        name: 'MyConnection'
        properties: {
          privateLinkServiceId: resourceId
          groupIds: [
            groupId
          ]
          requestMessage: ''
        }
      }
    ]
  }
}

output privateEndpointNetworkInterface string = privateEndpoint.properties.networkInterfaces[0].id

Creare un file di parametri per il modello e denominarlo PrivateEndpoint_parameters.json. Aggiungere il codice seguente al file di parametri:

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "privateEndpointName": {
            "value": ""
        },
        "resourceId": {
            "value": ""
        },
        "groupId": {
            "value": ""
        },
        "subnetId": {
            "value": ""
        }
    }
}

Creare uno script di PowerShell usando il codice seguente. Prima di eseguire lo script, sostituire l'ID sottoscrizione, il nome del gruppo di risorse e altri valori delle variabili con i dettagli per l'ambiente in uso.

### This script creates a private endpoint for an existing Azure Cosmos DB account in an existing virtual network

## Step 1: Fill in these details. Replace the variable values with the details for your environment.
$SubscriptionId = "<your Azure subscription ID>"
# Resource group where the Azure Cosmos DB account and virtual network resources are located
$ResourceGroupName = "myResourceGroup"
# Name of the Azure Cosmos DB account
$CosmosDbAccountName = "mycosmosaccount"
# API type of the Azure Cosmos DB account. It can be one of the following: "Sql", "SqlDedicated", "MongoDB", "Cassandra", "Gremlin", "Table"
$CosmosDbSubResourceType = "Sql"
# Name of the existing virtual network
$VNetName = "myVnet"
# Name of the target subnet in the virtual network
$SubnetName = "mySubnet"
# Name of the private endpoint to create
$PrivateEndpointName = "myPrivateEndpoint"

$cosmosDbResourceId = "/subscriptions/$($SubscriptionId)/resourceGroups/$($ResourceGroupName)/providers/Microsoft.DocumentDB/databaseAccounts/$($CosmosDbAccountName)"
$VNetResourceId = "/subscriptions/$($SubscriptionId)/resourceGroups/$($ResourceGroupName)/providers/Microsoft.Network/virtualNetworks/$($VNetName)"
$SubnetResourceId = "$($VNetResourceId)/subnets/$($SubnetName)"
$PrivateEndpointTemplateFilePath = "PrivateEndpoint_template.json"
$PrivateEndpointParametersFilePath = "PrivateEndpoint_parameters.json"

## Step 2: Sign in to your Azure account and select the target subscription.
Login-AzAccount
Select-AzSubscription -SubscriptionId $subscriptionId

## Step 3: Make sure private endpoint network policies are disabled in the subnet.
$VirtualNetwork= Get-AzVirtualNetwork -Name "$VNetName" -ResourceGroupName "$ResourceGroupName"
($virtualNetwork | Select -ExpandProperty subnets | Where-Object  {$_.Name -eq "$SubnetName"} ).PrivateEndpointNetworkPolicies = "Disabled"
$virtualNetwork | Set-AzVirtualNetwork

## Step 4: Create the private endpoint.
Write-Output "Deploying private endpoint on $($resourceGroupName)"
$deploymentOutput = New-AzResourceGroupDeployment -Name "PrivateCosmosDbEndpointDeployment" `
    -ResourceGroupName $resourceGroupName `
    -TemplateFile $PrivateEndpointTemplateFilePath `
    -TemplateParameterFile $PrivateEndpointParametersFilePath `
    -SubnetId $SubnetResourceId `
    -ResourceId $CosmosDbResourceId `
    -GroupId $CosmosDbSubResourceType `
    -PrivateEndpointName $PrivateEndpointName

$deploymentOutput

Nello script di PowerShell la variabile GroupId può contenere un solo valore. Il valore è il tipo di API dell'account. I valori consentiti sono: Sql, SqlDedicated, MongoDB, Cassandra, Gremlin e Table. Alcuni tipi di account Azure Cosmos DB sono accessibili tramite più API. Ad esempio:

  • L'API per gli account NoSQL ha un'opzione aggiunta per gli account configurati per l'uso del gateway dedicato.
  • È possibile accedere all’API per gli account Gremlin dagli account Gremlin e API per NoSQL.
  • È possibile accedere all’API per gli account Tabella dagli account Tabella e API per NoSQL.

Per questi account, è necessario creare un endpoint privato per ogni tipo di API. Se si sta creando un endpoint privato per SqlDedicated, è sufficiente aggiungere un secondo endpoint per Sql se si vuole connettersi anche all'account usando il gateway standard. Il tipo di API corrispondente è specificato nella matrice GroupId.

Al termine della distribuzione del modello, è possibile visualizzare un output simile a quello illustrato nell'immagine seguente. Il valore provisioningState è Succeeded se gli endpoint privati sono configurati correttamente.

Screenshot dell’output della distribuzione per il modello di Resource Manager.

Dopo aver distribuito il modello, gli indirizzi IP privati vengono riservati all'interno della subnet. La regola del firewall dell'account Azure Cosmos DB è configurata per accettare solo connessioni dall'endpoint privato.

Integrare l'endpoint privato con una zona DNS privata

Usare il codice seguente per creare un modello di Resource Manager denominato PrivateZone_template.json. Questo modello crea una zona DNS privata per un account API NoSQL Azure Cosmos DB esistente in una rete virtuale esistente.

{
    "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "privateZoneName": {
            "type": "string"
        },
        "VNetId": {
            "type": "string"
        }        
    },
    "resources": [
        {
            "name": "[parameters('privateZoneName')]",
            "type": "Microsoft.Network/privateDnsZones",
            "apiVersion": "2018-09-01",
            "location": "global",
            "properties": {                
            }
        },
        {
            "type": "Microsoft.Network/privateDnsZones/virtualNetworkLinks",
            "apiVersion": "2018-09-01",
            "name": "[concat(parameters('privateZoneName'), '/myvnetlink')]",
            "location": "global",
            "dependsOn": [
                "[resourceId('Microsoft.Network/privateDnsZones', parameters('privateZoneName'))]"
            ],
            "properties": {
                "registrationEnabled": false,
                "virtualNetwork": {
                    "id": "[parameters('VNetId')]"
                }
            }
        }        
    ]
}

Creare i due file di parametri seguenti per il modello. Creare il PrivateZone_parameters.json con il codice seguente:

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "privateZoneName": {
            "value": ""
        },
        "VNetId": {
            "value": ""
        }
    }
}

Usare il codice seguente per creare un modello di Resource Manager denominato PrivateZoneGroup_template.json. Questo modello crea un gruppo di zone DNS private per un account API per NoSQL Azure Cosmos DB esistente in una rete virtuale esistente.

{
    "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "privateZoneName": {
            "type": "string"
        },
        "PrivateEndpointDnsGroupName": {
            "value": "string"
        },
        "privateEndpointName":{
            "value": "string"
        }        
    },
    "resources": [
        {
            "type": "Microsoft.Network/privateEndpoints/privateDnsZoneGroups",
            "apiVersion": "2020-06-01",
            "name": "[parameters('PrivateEndpointDnsGroupName')]",
            "location": "global",
            "dependsOn": [
                "[resourceId('Microsoft.Network/privateDnsZones', parameters('privateZoneName'))]",
                "[variables('privateEndpointName')]"
            ],
          "properties": {
            "privateDnsZoneConfigs": [
              {
                "name": "config1",
                "properties": {
                  "privateDnsZoneId": "[resourceId('Microsoft.Network/privateDnsZones', parameters('privateZoneName'))]"
                }
              }
            ]
          }
        }
    ]
}

Creare i due file di parametri seguenti per il modello. Creare il PrivateZoneGroup_parameters.json con il codice seguente:

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "privateZoneName": {
            "value": ""
        },
        "PrivateEndpointDnsGroupName": {
            "value": ""
        },
        "privateEndpointName":{
            "value": ""
        }
    }
}

Creare uno script di PowerShell usando il codice seguente. Prima di eseguire lo script, sostituire l'ID sottoscrizione, il nome del gruppo di risorse e altri valori delle variabili con i dettagli per l'ambiente in uso.

### This script:
### - creates a private zone
### - creates a private endpoint for an existing Azure Cosmos DB account in an existing VNet
### - maps the private endpoint to the private zone

## Step 1: Fill in these details. Replace the variable values with the details for your environment.
$SubscriptionId = "<your Azure subscription ID>"
# Resource group where the Azure Cosmos DB account and virtual network resources are located
$ResourceGroupName = "myResourceGroup"
# Name of the Azure Cosmos DB account
$CosmosDbAccountName = "mycosmosaccount"
# API type of the Azure Cosmos DB account. It can be one of the following: "Sql", "SqlDedicated", "MongoDB", "Cassandra", "Gremlin", "Table"
$CosmosDbSubResourceType = "Sql"
# Name of the existing virtual network
$VNetName = "myVnet"
# Name of the target subnet in the virtual network
$SubnetName = "mySubnet"
# Name of the private zone to create
$PrivateZoneName = "myPrivateZone.documents.azure.com"
# Name of the private endpoint to create
$PrivateEndpointName = "myPrivateEndpoint"

# Name of the DNS zone group to create
$PrivateEndpointDnsGroupName = "myPrivateDNSZoneGroup"

$cosmosDbResourceId = "/subscriptions/$($SubscriptionId)/resourceGroups/$($ResourceGroupName)/providers/Microsoft.DocumentDB/databaseAccounts/$($CosmosDbAccountName)"
$VNetResourceId = "/subscriptions/$($SubscriptionId)/resourceGroups/$($ResourceGroupName)/providers/Microsoft.Network/virtualNetworks/$($VNetName)"
$SubnetResourceId = "$($VNetResourceId)/subnets/$($SubnetName)"
$PrivateZoneTemplateFilePath = "PrivateZone_template.json"
$PrivateZoneParametersFilePath = "PrivateZone_parameters.json"
$PrivateEndpointTemplateFilePath = "PrivateEndpoint_template.json"
$PrivateEndpointParametersFilePath = "PrivateEndpoint_parameters.json"
$PrivateZoneGroupTemplateFilePath = "PrivateZoneGroup_template.json"
$PrivateZoneGroupParametersFilePath = "PrivateZoneGroup_parameters.json"

## Step 2: Login your Azure account and select the target subscription
Login-AzAccount 
Select-AzSubscription -SubscriptionId $subscriptionId

## Step 3: Make sure private endpoint network policies are disabled in the subnet
$VirtualNetwork= Get-AzVirtualNetwork -Name "$VNetName" -ResourceGroupName "$ResourceGroupName"
($virtualNetwork | Select -ExpandProperty subnets | Where-Object  {$_.Name -eq "$SubnetName"} ).PrivateEndpointNetworkPolicies = "Disabled"
$virtualNetwork | Set-AzVirtualNetwork

## Step 4: Create the private zone
New-AzResourceGroupDeployment -Name "PrivateZoneDeployment" `
    -ResourceGroupName $ResourceGroupName `
    -TemplateFile $PrivateZoneTemplateFilePath `
    -TemplateParameterFile $PrivateZoneParametersFilePath `
    -PrivateZoneName $PrivateZoneName `
    -VNetId $VNetResourceId

## Step 5: Create the private endpoint
Write-Output "Deploying private endpoint on $($resourceGroupName)"
$deploymentOutput = New-AzResourceGroupDeployment -Name "PrivateCosmosDbEndpointDeployment" `
    -ResourceGroupName $resourceGroupName `
    -TemplateFile $PrivateEndpointTemplateFilePath `
    -TemplateParameterFile $PrivateEndpointParametersFilePath `
    -SubnetId $SubnetResourceId `
    -ResourceId $CosmosDbResourceId `
    -GroupId $CosmosDbSubResourceType `
    -PrivateEndpointName $PrivateEndpointName
$deploymentOutput

## Step 6: Create the private zone
New-AzResourceGroupDeployment -Name "PrivateZoneGroupDeployment" `
    -ResourceGroupName $ResourceGroupName `
    -TemplateFile $PrivateZoneGroupTemplateFilePath `
    -TemplateParameterFile $PrivateZoneGroupParametersFilePath `
    -PrivateZoneName $PrivateZoneName `
    -PrivateEndpointName $PrivateEndpointName`
    -PrivateEndpointDnsGroupName $PrivateEndpointDnsGroupName

configurare un DNS personalizzato

È consigliabile usare una zona DNS privata all'interno della subnet in cui è stato creato l'endpoint privato. Configurare gli endpoint in modo che ogni indirizzo IP privato venga mappato a una voce DNS. Vedere la proprietà fqdns nella risposta illustrata in precedenza.

Quando si crea l'endpoint privato, è possibile integrarlo con una zona DNS privata in Azure. Se si sceglie di usare invece una zona DNS personalizzata, è necessario configurarla per aggiungere i record DNS per tutti gli indirizzi IP privati riservati per l'endpoint privato.

Importante

Si tratta della risoluzione DNS delle richieste che determina se queste richieste passano sugli endpoint privati o accettano la route pubblica standard. Assicurarsi che il DNS locale faccia riferimento correttamente all'indirizzo IP privato mappato dall'endpoint privato.

Quando si usa il collegamento privato in combinazione con le regole del firewall, sono possibili le situazioni e i risultati seguenti:

  • Se non si configura alcuna regola del firewall, per impostazione predefinita tutto il traffico può accedere a un account Azure Cosmos DB.

  • Se si configura il traffico pubblico o un endpoint di servizio e si creano endpoint privati, i diversi tipi di traffico in ingresso sono autorizzati in base al tipo corrispondente di regola del firewall. Se un endpoint privato è configurato in una subnet in cui è configurato anche l'endpoint di servizio:

    • il traffico verso l'account del database mappato dall'endpoint privato viene instradato tramite endpoint privato,
    • il traffico verso altri account di database dalla subnet viene instradato tramite l'endpoint di servizio.

  • Se non si configura alcun traffico pubblico o endpoint di servizio e si creano endpoint privati, l'account Azure Cosmos DB sarà accessibile solo tramite gli endpoint privati. Se non si configura il traffico pubblico o un endpoint di servizio, dopo che tutti gli endpoint privati approvati vengono rifiutati o eliminati, l'account è aperto per l'intera rete a meno che PublicNetworkAccess sia impostato su Disabilitato.

Blocco dell'accesso alla rete pubblica durante la creazione dell'account

Come descritto nella sezione precedente, se non sono state impostate regole del firewall specifiche, l'aggiunta di un endpoint privato rende l'account Azure Cosmos DB accessibile solo tramite endpoint privati. Ciò significa che è possibile raggiungere l'account Azure Cosmos DB dal traffico pubblico dopo che è stato creato e prima che venga aggiunto un endpoint privato. Per assicurarsi che l'accesso alla rete pubblica sia disabilitato anche prima della creazione di endpoint privati, è possibile impostare il flag publicNetworkAccess su Disabilitato durante la creazione dell'account. Questo flag ha la precedenza su qualsiasi regola di rete virtuale o IP. Tutto il traffico di rete pubblica e virtuale viene bloccato quando il flag è impostato su Disabilitato, anche se nella configurazione del firewall è consentito l'indirizzo IP di origine o la rete virtuale.

Per un esempio che illustra come usare questo flag, vedere questo modello di Azure Resource Manager.

Aggiunta di endpoint privati a un account Azure Cosmos DB esistente senza tempi di inattività

Per impostazione predefinita, l'aggiunta di un endpoint privato a un account esistente comporta un breve tempo di inattività di circa cinque minuti. Per evitare questo tempo inattivo, seguire queste istruzioni:

  1. Aggiungere regole di rete virtuale o IP alla configurazione del firewall per consentire in modo esplicito le connessioni client.
  2. Attendere 10 minuti per assicurarsi che venga applicato l'aggiornamento della configurazione.
  3. Configurare il nuovo endpoint privato.
  4. Rimuovere le regole del firewall impostate nel passaggio 1.

Nota

Se sono in esecuzione applicazioni che usano gli SDK di Azure Cosmos DB, potrebbero verificarsi dei timeout temporanei durante l'aggiornamento della configurazione. Assicurarsi che l'applicazione sia progettata per essere resiliente agli errori di connettività temporanei e avere la logica di ripetizione dei tentativi nel caso sia necessaria.

Intervallo di porte quando si usa la modalità diretta

Quando si usa un link privato con un account Azure Cosmos DB tramite una connessione in modalità diretta, è necessario assicurarsi che l’intervallo completo delle porte TCP (0 - 65535) sia aperto.

Aggiornare un endpoint privato quando si aggiunge o si rimuove un'area

Esistono tre aree per le distribuzioni di account Azure Cosmos DB: Stati Uniti occidentali, Stati Uniti centrali ed Europa occidentale. Quando si crea un endpoint privato per l'account, nella subnet vengono riservati quattro indirizzi IP privati. Esiste un solo IP per ognuna delle tre aree ed esiste un solo IP per l'endpoint globale o indipendente dall'area. Successivamente, è possibile aggiungere una nuova area all'account Azure Cosmos DB. La zona DNS privata viene aggiornata come segue:

  • Se si usa il gruppo di zone DNS privato:

    • Se si usa un gruppo di zone DNS privato, la zona DNS privata viene aggiornata automaticamente quando viene aggiornato l'endpoint privato. Nell'esempio precedente, dopo aver aggiunto una nuova area, la zona DNS privata viene aggiornata automaticamente.

  • Se il gruppo di zone DNS privato non viene usato:

    • Se non si usa un gruppo di zone DNS privato, aggiungendo o rimuovendo aree in un account Azure Cosmos DB è necessario aggiungere o rimuovere le voci DNS per l'account. Dopo l'aggiunta o la rimozione delle aree, è possibile aggiornare la zona DNS privata della subnet in modo da riflettere le voci DNS aggiunte o rimosse e i rispettivi indirizzi IP privati.

    • Nell’esempio precedente, dopo aver aggiunto la nuova area, è necessario aggiungere un record DNS corrispondente alla zona DNS privata o al DNS personalizzato. Quando si rimuove un'area, è possibile usare la stessa procedura. Dopo aver rimosso l'area, è necessario rimuovere il record DNS corrispondente dalla zona DNS privata o dal DNS personalizzato.

Limitazioni correnti

Quando si usa il collegamento privato con un account Azure Cosmos DB, si applicano le limitazioni seguenti:

  • Non è possibile avere più di 200 endpoint privati in un singolo account Azure Cosmos DB.

  • Quando si usa il collegamento privato con un account Azure Cosmos DB attraverso una connessione in modalità diretta, è possibile usare solo il protocollo TCP. Il protocollo HTTP non è attualmente supportato.

  • Quando si usa l'API di Azure Cosmos DB per un account MongoDB, un endpoint privato è supportato per gli account nella versione del server 3.6 o versione successiva, ovvero gli account che usano l'endpoint nel formato *.mongo.cosmos.azure.com. Il collegamento privato non è supportato per gli account nella versione del server 3.2 (ovvero gli account che usano l'endpoint nel formato *.documents.azure.com). Per usare il collegamento privato, è necessario eseguire la migrazione degli account precedenti alla nuova versione.

  • Quando si usa l'API di Azure Cosmos DB per un account MongoDB con un collegamento privato, gli strumenti e le librerie devono supportare l'identificazione del nome del servizio (SNI) o passare il parametro appName dal stringa di connessione per connettersi correttamente. Alcuni strumenti e librerie meno recenti potrebbero non essere compatibili con la funzionalità di collegamento privato.

  • È necessario concedere a un amministratore di rete almeno l'autorizzazione Microsoft.DocumentDB/databaseAccounts/PrivateEndpointConnectionsApproval/action nell'ambito dell'account Azure Cosmos DB per creare automaticamente endpoint privati approvati.

  • Attualmente non è possibile approvare una connessione endpoint privato rifiutata. Ricreare invece l'endpoint privato per riprendere la connettività privata. Il servizio collegamento privato di Azure Cosmos DB approva automaticamente l'endpoint privato ricreato.

Limitazioni per l'integrazione della zona DNS privata

A meno che non si stia usando un gruppo di zone DNS privato, i record DNS nella zona DNS privata non vengono rimossi automaticamente quando si elimina un endpoint privato o si rimuove un'area dall'account Azure Cosmos DB. È necessario rimuovere manualmente i record DNS prima di:

  • Aggiungere un nuovo endpoint privato collegato alla zona DNS privata.
  • Aggiungere una nuova area a un account di database con endpoint privati collegati alla zona DNS privata.

Se non si puliscono i record DNS, potrebbero verificarsi problemi imprevisti del piano dati. Questi problemi includono l'interruzione dei dati per le aree aggiunte dopo la rimozione dell'endpoint privato o la rimozione dell'area.

Contenuto correlato