Condividi tramite

Configurare collegamento privato di Azure per un account Azure Cosmos DB

SI APPLICA A: NoSQL MongoDB Cassandra Gremlin Table

Con 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 il collegamento privato viene combinato con criteri restrittivi dei gruppi di sicurezza di rete (NSG), contribuisce a ridurre il rischio di esfiltrazione dei dati. Per altre informazioni sugli endpoint privati, vedere Che cos'è collegamento privato di Azure?

Note

Collegamento privato non impedisce che gli endpoint di Azure Cosmos DB vengano risolti dal DNS pubblico. Il filtro delle richieste in ingresso avviene a livello di applicazione, non a livello di trasporto o di rete.

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 collegamento privato usando il metodo di approvazione automatica o manuale. Per altre informazioni, vedere la sezione flusso di lavoro di approvazione della documentazione di 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 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, quindi selezionare+ Endpoint privato nella scheda Accesso privato:

    Screenshot delle selezioni per creare un endpoint privato nel portale di Azure

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

    Impostazione valore
    Dettagli del progetto
    Abbonamento Selezionare la propria sottoscrizione.
    Resource group Selezionare un gruppo di risorse.
    Dettagli istanza
    Nome Immettere un nome per l'endpoint privato. Se il nome è già usato, creare un nome univoco.
    Region 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 Seleziona Microsoft.AzureCosmosDB/databaseAccounts.
    Risorsa 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, questa opzione prevede una sola scelta per le API relative a SQL, MongoDB e Cassandra. Per le API per Gremlin e Table, è anche possibile scegliere NoSQL perché queste API sono interoperabili 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 privato. 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 collegamento 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

Rivedere la configurazione DNS di Azure Private Endpoint per una spiegazione più dettagliata sulle zone private e le configurazioni DNS per l'endpoint privato. La tabella seguente illustra il mapping tra i diversi tipi di API degli account Azure Cosmos DB, le sottorisorse supportate e i corrispondenti nomi di zona privata. È anche possibile accedere all'API Gremlin e all'API per gli account Table tramite l'API per NoSQL, quindi 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 Sottorisorse o ID gruppo supportati 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 indipendente dall'area globale dell'account Azure Cosmos DB.
  • Una per ogni area in cui viene 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 vAPI di Azure Cosmos DB 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 sia da Gremlin che dall'API per gli account NoSQL.
  • L'API per gli account Table è accessibile sia dagli account Table che dagli account API for 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 ci si vuole connettere anche all'account tramite 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 le connessioni provenienti 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 Azure Cosmos DB API per NoSQL 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 privato per un account Azure Cosmos DB API per NoSQL esistente in una rete virtuale già 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 file 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 valore 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 fqdns proprietà 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

È la risoluzione DNS delle vostre richieste a determinare se queste vengono instradate attraverso gli endpoint privati o seguono il percorso pubblico standard. Assicurarsi che il DNS locale faccia correttamente riferimento 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 configurano regole 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 database mappato dall'endpoint privato viene instradato tramite l'endpoint privato.
    • Il traffico verso altri account di database dalla subnet viene instradato tramite l'endpoint di servizio.

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

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

Come descritto nella sezione precedente, e a meno che non siano state configurate regole firewall specifiche, l'aggiunta di un endpoint privato rende l'account Azure Cosmos DB accessibile solo tramite endpoint privati. Ciò significa che l'account Azure Cosmos DB potrebbe essere raggiungibile dal traffico pubblico dopo la sua creazione e prima che venga aggiunto un endpoint privato. Per garantire che l'accesso dalla rete pubblica sia disabilitato ancora prima della creazione degli endpoint privati, è possibile impostare il flag publicNetworkAccess su Disabilitato durante la creazione dell'account. Questo flag ha la precedenza su qualsiasi regola IP o di rete virtuale. Tutto il traffico di rete pubblico e virtuale viene bloccato quando il flag è impostato su Disabilitato anche se l'IP di origine o la rete virtuale sono consentiti nella configurazione del firewall.

Per un esempio che illustra come usare questo flag, vedere il modello in Creare un account Azure Cosmos DB con un endpoint privato.

Aggiungere endpoint privati a un account Azure Cosmos DB esistente senza interruzione del servizio

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

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

Note

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

Intervallo di porte quando si usa la modalità diretta

Quando si un collegamento privato con un account Azure Cosmos DB tramite una connessione in modalità diretta, è necessario assicurarsi che l'intera gamma di porte TCP (0 - 65535) sia aperta.

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

Sono disponibili tre aree per la distribuzione degli account Azure Cosmos DB: Stati Uniti occidentali, Stati Uniti centrali, e Europa occidentale. Quando si crea un endpoint privato per l'account, nella subnet vengono riservati quattro indirizzi IP privati. È presente un indirizzo IP per ciascuna delle tre aree e un indirizzo IP per l'endpoint globale indipendente dall'area. In seguito, potresti aggiungere una nuova area all'account Azure Cosmos DB. La zona DNS privata viene aggiornata come segue:

  • Se viene usato un gruppo di zone DNS privato:

    • Se si usa un gruppo di zone DNS privato, la zona DNS privato 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, l'aggiunta o la rimozione di aree a un account Azure Cosmos DB richiede l'aggiunta o la rimozione di voci DNS per tale 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 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 collegamento privato con un account Azure Cosmos DB tramite 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, per gli account nella versione 3.6 o successiva del server è supportato un endpoint privato (ovvero gli account che usano l'endpoint nel formato *.mongo.cosmos.azure.com). Il collegamento privato non è supportato per gli account nella versione 3.2 del server (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 Collegamento Privato, gli strumenti e le librerie devono supportare l'identificazione del nome del servizio (SNI) oppure trasmettere il parametro appName dalla stringa di connessione per stabilire correttamente la connessione. Alcuni strumenti e librerie meno recenti potrebbero non essere compatibili con la funzionalità di collegamento privato.

  • A un amministratore di rete dovrebbe essere concessa almeno l'autorizzazione Microsoft.DocumentDB/databaseAccounts/PrivateEndpointConnectionsApproval/action nell'ambito dell'account Azure Cosmos DB per creare endpoint privati con approvazione automatica.

  • Attualmente non è possibile approvare una connessione a un endpoint privato che è stata rifiutata. Ricreare invece l'endpoint privato per ripristinare 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 usi 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.

Contenuti correlati

  • Last updated on