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

SI APPLICA A: Nosql Mongodb Cassandra Gremlin Tabella

Usando 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 criteri NSG restrittivi, consente di ridurre il rischio di esfiltrazione dei dati. Per altre informazioni sugli endpoint privati, vedere Che cos'è collegamento privato di Azure?

Nota

collegamento privato non impedisce che gli endpoint di Azure Cosmos DB vengano risolti da DNS pubblici. 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 automatico o manuale. Per altre informazioni, vedere la sezione Flusso di lavoro di approvazione della documentazione di collegamento privato.

Questo articolo descrive come configurare gli 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 :

   

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

   Impostazione	valore
   Dettagli del progetto
   Subscription	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.
   Subscription	Selezionare la propria sottoscrizione.
   Tipo di risorsa	Selezionare 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. Questo valore predefinito è una sola scelta per le API per 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. Nel riquadro 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 è presente un aggiornamento all'endpoint privato. Ad esempio, quando si aggiungono o si rimuoveno 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: Verifica tag>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, nella portale di Azure l'opzione Tutte le reti nel riquadro Firewall e reti virtuali non è disponibile.

Tipi di API e nomi di zona privati

Per una spiegazione più dettagliata sulle zone private e sulle configurazioni DNS per l'endpoint privato, vedere Configurazione DNS dell'endpoint privato. Nella tabella seguente viene illustrato il mapping tra diversi tipi di API dell'account Azure Cosmos DB, sottoresource supportate e i nomi delle zone private corrispondenti. È 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	ID di sottorisorse o gruppi 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.

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.

Bicep

@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

JSON

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "location": {
          "type": "string",
          "defaultValue": "[resourceGroup().location]",
          "metadata": {
            "description": "Location for all resources."
          }
        },
        "privateEndpointName": {
            "type": "string"
        },
        "resourceId": {
            "type": "string"
        },
        "groupId": {
            "type": "string"
        },
        "subnetId": {
            "type": "string"
        }
    },
    "resources": [
        {
            "name": "[parameters('privateEndpointName')]",
            "type": "Microsoft.Network/privateEndpoints",
            "apiVersion": "2019-04-01",
            "location": "[parameters('location')]",
            "properties": {
                "subnet": {
                    "id": "[parameters('subnetId')]"
                },
                "privateLinkServiceConnections": [
                    {
                        "name": "MyConnection",
                        "properties": {
                            "privateLinkServiceId": "[parameters('resourceId')]",
                            "groupIds": [ "[parameters('groupId')]" ],
                            "requestMessage": ""
                        }
                    }
                ]
            }
        }
    ],
    "outputs": {
        "privateEndpointNetworkInterface": {
          "type": "string",
          "value": "[reference(concat('Microsoft.Network/privateEndpoints/', parameters('privateEndpointName'))).networkInterfaces[0].id]"
        }
    }
}

Definire il file di parametri per il modello

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

Bicep/JSON

{
    "$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": ""
        }
    }
}

Distribuire il modello usando uno script di PowerShell

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, CassandraMongoDB, , Gremline Table. Alcuni tipi di account Azure Cosmos DB sono accessibili tramite più API. Ad esempio:

• L'API per gli account NoSQL offre un'opzione aggiuntiva 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.
• È possibile accedere all'API per gli account di tabella sia da tabelle che dall'API per gli account 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 anche connettersi 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.

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 le connessioni solo 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 Di Azure Cosmos DB esistente per NoSQL 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')]"
                }
            }
        }        
    ]
}

Definire il file di parametri per il modello

Creare i due file di parametri seguenti per il modello. Creare il file 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 API Di Azure Cosmos DB 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"
        },
        "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'))]"
                }
              }
            ]
          }
        }
    ]
}

Definire il file di parametri per il modello

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": ""
        }
    }
}

Distribuire il modello usando uno script di PowerShell

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 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 agli endpoint privati o accettano la route pubblica standard. Assicurarsi che il DNS locale faccia riferimento correttamente all'indirizzo IP privato mappato dall'endpoint privato.

Collegamento privato combinato con le regole del firewall

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 del servizio:

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

• Se non si configura alcun traffico pubblico o endpoint di servizio e si creano endpoint privati, l'account Azure Cosmos DB è 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 all'intera rete, a meno PublicNetworkAccess che non sia 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 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 l'account Azure Cosmos DB può essere raggiunto dal traffico pubblico dopo la creazione 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 su Disabilitato durante la creazione dell'accountpublicNetworkAccess. Si noti che questo flag ha la precedenza su qualsiasi regola di rete IP o virtuale. Tutto il traffico di rete pubblica e virtuale viene bloccato quando il flag è impostato su Disabilitato, anche se l'INDIRIZZO IP di origine o la rete virtuale è consentita nella configurazione del firewall.

Per un esempio che mostra 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. Seguire queste istruzioni per evitare questo tempo di inattività:

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 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 in caso di necessità.

Intervallo di porte quando si usa la modalità diretta

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

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

Sono disponibili tre aree per le distribuzioni dell'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. C'è un indirizzo IP per ognuna delle tre aree e c'è un indirizzo IP per l'endpoint globale agnostico. In un secondo momento, è possibile aggiungere una nuova area all'account Azure Cosmos DB. La zona DNS privata viene aggiornata come segue:

• Se viene usato il gruppo di zone DNS privato:

  Se si usa un gruppo di zone DNS privato, la zona DNS privata viene aggiornata automaticamente quando l'endpoint privato viene aggiornato. 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, aggiungere o rimuovere aree a un account Azure Cosmos DB richiede di aggiungere o rimuovere 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

Le limitazioni seguenti si applicano quando si usa collegamento privato con un account Azure Cosmos DB:

• Non è possibile disporre di 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, un endpoint privato è supportato per gli account nella versione 3.6 o successiva del server, ovvero gli account che usano l'endpoint nel formato *.mongo.cosmos.azure.com. 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 un collegamento privato, gli strumenti e le librerie devono supportare L'identificazione dei nomi del servizio o passare il appName parametro dalla stringa di connessione per connettersi correttamente. Alcuni strumenti e librerie precedenti potrebbero non essere compatibili con la funzionalità di collegamento privato.

• Un amministratore di rete deve essere concesso almeno l'autorizzazione Microsoft.DocumentDB/databaseAccounts/PrivateEndpointConnectionsApproval/action nell'ambito dell'account Azure Cosmos DB per creare endpoint privati approvati automaticamente.

• Attualmente non è possibile approvare una connessione endpoint privato rifiutata. Ricreare invece l'endpoint privato per riprendere la connettività privata. Il servizio di 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.

Passaggi successivi

Per altre informazioni sulle funzioni di sicurezza di Azure Cosmos DB, vedere gli articoli seguenti:

• Per configurare un firewall per Azure Cosmos DB, vedere Supporto del firewall.

• Per informazioni su come configurare un endpoint del servizio di rete virtuale per l'account Azure Cosmos DB, vedere Configurare l'accesso dalle reti virtuali.

• Per altre informazioni sul collegamento privato, vedere la documentazione sul collegamento privato di Azure.