Konfigurieren von Azure Private Link für ein Azure Cosmos DB-Konto

GILT FÜR: NoSQL MongoDB Cassandra Gremlin Tabelle

Mithilfe von Azure Private Link können Sie über einen privaten Endpunkt eine Verbindung mit einem Azure Cosmos DB-Konto herstellen. Bei einem privaten Endpunkt handelt es sich um eine Gruppe privater IP-Adressen in einem Subnetz innerhalb Ihres virtuellen Netzwerks. Sie können dann den Zugriff auf ein Azure Cosmos DB-Konto über private IP-Adressen einschränken. Durch die Kombination einer privaten Verbindung und eingeschränkten Richtlinien für Netzwerksicherheitsgruppen (NSG) kann das Risiko der Datenexfiltration verringert werden. Weitere Informationen zu privaten Endpunkten finden Sie unter Was ist Azure Private Link?

Private Link ermöglicht Benutzern den Zugriff auf ein Azure Cosmos DB-Konto innerhalb des virtuellen Netzwerks oder über ein mittels Peering verbundenes Netzwerk. Auf Ressourcen, die Private Link zugeordnet sind, kann auch lokal über privates Peering über VPN oder Azure ExpressRoute zugegriffen werden.

Mithilfe der automatischen oder manuellen Genehmigungsmethode können Sie eine Verbindung mit einem Azure Cosmos DB-Konto herstellen, das mit Private Link konfiguriert wurde. Weitere Informationen finden Sie im Abschnitt zum Genehmigungsworkflow in der Dokumentation zu Private Link.

In diesem Artikel wird erläutert, wie Sie private Endpunkte für den Azure Cosmos DB-Transaktionsspeicher einrichten. Dabei wird vorausgesetzt, dass Sie die automatische Genehmigungsmethode verwenden. Wenn Sie den Analysespeicher verwenden, lesen Sie Private Endpunkte für den Analysespeicher konfigurieren.

Erstellen eines privaten Endpunkts über das Azure-Portal

Folgen Sie diesen Schritten, um über das Azure-Portal einen privaten Endpunkt für ein vorhandenes Azure Cosmos DB-Konto zu erstellen:

1. Melden Sie sich beim Azure-Portal an, und wählen Sie dann ein Azure Cosmos DB-Konto aus.

2. Wählen Sie in der Liste der Einstellungen Netzwerk und dann auf der Registerkarte Privater Zugriff die Option + Privater Endpunkt aus:

   

3. Geben Sie im Bereich Privaten Endpunkt erstellen – Grundlagen folgende Informationen ein, oder wählen Sie sie aus:

   Einstellung	Wert
   Projektdetails
   Subscription	Wählen Sie Ihr Abonnement aus.
   Resource group	Wählen Sie eine Ressourcengruppe aus.
   Instanzendetails
   Name	Geben Sie einen beliebigen Namen für Ihren privaten Endpunkt ein. Wenn dieser Name vergeben ist, erstellen Sie einen eindeutigen Namen.
   Region	Wählen Sie die Region aus, in der Sie Private Link bereitstellen möchten. Erstellen Sie den privaten Endpunkt am gleichen Standort, an dem sich auch das virtuelle Netzwerk befindet.

4. Klicken Sie auf Weiter: Ressource aus.

5. Geben Sie im Bereich Privaten Endpunkt erstellen – Ressource diese Informationen ein, oder wählen Sie diese aus:

   Einstellung	Wert
   Verbindungsmethode	Wählen Sie Hiermit wird eine Verbindung mit einer Azure-Ressource im eigenen Verzeichnis hergestellt aus. Sie können dann eine Ihrer Ressourcen zum Einrichten von Private Link auswählen. Sie können aber auch eine Verbindung mit der Ressource eines anderen Benutzers herstellen, indem Sie eine Ressourcen-ID oder einen Alias verwenden, die bzw. der von diesem Benutzer für Sie freigegeben wurde.
   Subscription	Wählen Sie Ihr Abonnement aus.
   Ressourcentyp	Wählen Sie Microsoft.AzureCosmosDB/databaseAccounts aus.
   Resource	Wählen Sie Ihre Azure Cosmos DB-Konto aus.
   Unterressource des Ziels	Wählen Sie den Typ der zuzuordnenden Azure Cosmos DB-API aus. Standardmäßig ist für die APIs für SQL, MongoDB und Cassandra jeweils nur eine Auswahl möglich. Für die APIs für Gremlin und Table können Sie auch NoSQL auswählen, da diese APIs Interoperabilität für die API für NoSQL bieten. Wenn Sie über ein dediziertes Gateway verfügen, das für ein API für NoSQL-Konto bereitgestellt wird, sehen Sie auch eine Option für SqlDedicated.

6. Wählen Sie Weiter: Virtuelles Netzwerk aus.

7. Geben Sie im Bereich Privaten Endpunkt erstellen – Virtual Network diese Informationen ein, oder wählen Sie diese aus:

   Einstellung	Wert
   Virtuelles Netzwerk	Wählen Sie Ihr virtuelles Netzwerk aus.
   Subnet	Wählen Sie das Subnetz aus.

8. Wählen Sie Weiter: DNS aus.

9. Geben Sie im Bereich Privaten Endpunkt erstellen – DNS diese Informationen ein, oder wählen Sie diese aus:

   Einstellung	Wert
   Integration in eine private DNS-Zone	Wählen Sie Ja aus. Für die Herstellung einer privaten Verbindung mit Ihrem privaten Endpunkt benötigen Sie einen DNS-Eintrag. Es wird empfohlen, den privaten Endpunkt in eine private DNS-Zone zu integrieren. Sie können auch Ihre eigenen DNS-Server verwenden oder DNS-Einträge mithilfe der Hostdateien auf Ihren virtuellen Computern erstellen. Wenn Sie für diese Option Ja auswählen, wird ebenfalls eine private DNS-Zonengruppe erstellt. Die DNS-Zonengruppe ist eine Verknüpfung zwischen der privaten DNS-Zone und dem privaten Endpunkt. Mit diesem Link können Sie die private DNS-Zone automatisch aktualisieren, wenn ein Update für den privaten Endpunkt vorliegt. Wenn Sie z. B. Regionen hinzufügen oder entfernen, wird die private DNS-Zone automatisch aktualisiert.
   Konfigurationsname	Wählen Sie Ihr Abonnement und die Ressourcengruppe aus. Die private DNS-Zone wird automatisch bestimmt. Sie können sie nicht über das Azure-Portal ändern.

10. Wählen Sie Weiter: Tags>Überprüfen + erstellen aus. Auf der Seite Überprüfen + erstellen überprüft Azure Ihre Konfiguration.

11. Wenn die Meldung Überprüfung erfolgreich angezeigt wird, wählen Sie Erstellen aus.

Wenn Sie über eine genehmigte Private Link-Instanz für ein Azure Cosmos DB-Konto verfügen, ist die Option Alle Netzwerke im Bereich Firewall und virtuelle Netzwerke im Azure-Portal nicht verfügbar.

API-Typen und private Zonennamen

Eine ausführlichere Erläuterung zu privaten Zonen und DNS-Konfigurationen für private Endpunkte finden Sie unter DNS-Konfiguration für private Azure-Endpunkte. Die folgende Tabelle zeigt die Zuordnung zwischen verschiedenen API-Typen für Azure Cosmos DB-Konten, unterstützten Unterressourcen und entsprechenden Namen für die private Zone. Sie können auch über die API für NoSQL auf das API für Gremlin- und API für Table-Konto zugreifen, sodass für diese APIs zwei Einträge vorhanden sind. Es gibt auch einen zusätzlichen Eintrag für die API für NoSQL für Konten, die das dedizierte Gateway verwenden.

Abrufen der privaten IP-Adressen

Nach der Bereitstellung des privaten Endpunkts können Sie die IP-Adressen abfragen. Zum Anzeigen der IP-Adressen im Azure-Portal führen Sie die folgenden Schritte aus:

1. Suchen Sie nach dem privaten Endpunkt, den Sie zuvor erstellt haben. In diesem Fall ist das cdbPrivateEndpoint3.
2. Wählen Sie die Registerkarte Übersicht aus, um die DNS-Einstellungen und IP-Adressen anzuzeigen.

Für jeden privaten Endpunkt werden mehrere IP-Adressen erstellt:

• Eine IP-Adresse für den globalen, regionsunabhängigen Endpunkt des Azure Cosmos DB-Kontos.
• Eine IP-Adresse für jede Region, in der das Azure Cosmos DB-Konto bereitgestellt wird.

Erstellen eines privaten Endpunkts mit Azure PowerShell

Führen Sie das folgende PowerShell-Skript aus, um den privaten Endpunkt namens MyPrivateEndpoint für ein vorhandenes Azure Cosmos DB-Konto zu erstellen. Ersetzen Sie die Variablenwerte durch die entsprechenden Angaben für Ihre Umgebung.

$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

Integrieren des privaten Endpunkts in eine private DNS-Zone

Nachdem Sie den privaten Endpunkt erstellt haben, können Sie ihn mithilfe des folgenden PowerShell-Skripts in eine private DNS-Zone integrieren:

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

Abrufen der privaten IP-Adressen

Nach der Bereitstellung des privaten Endpunkts können Sie mit dem folgenden PowerShell-Skript die IP-Adressen und die FQDN-Zuordnung abfragen:

$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
}

Erstellen eines privaten Endpunkts mit der Azure CLI

Führen Sie das folgende Azure CLI-Skript aus, um einen privaten Endpunkt namens myPrivateEndpoint für ein vorhandenes Azure Cosmos DB-Konto zu erstellen. Ersetzen Sie die Variablenwerte durch die entsprechenden Angaben für Ihre Umgebung.

# 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

Integrieren des privaten Endpunkts in eine private DNS-Zone

Nachdem Sie den privaten Endpunkt erstellt haben, können Sie ihn mithilfe des folgenden Azure CLI-Skripts in eine private DNS-Zone integrieren:

#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"

Erstellen eines privaten Endpunkts mithilfe einer Resource Manager-Vorlage

Sie können eine private Verknüpfung einrichten, indem Sie einen privaten Endpunkt in einem Subnetz des virtuellen Netzwerks erstellen. Dazu verwenden Sie eine Azure Resource Manager-Vorlage.

Verwenden Sie den folgenden Code, um eine Resource Manager-Vorlage namens PrivateEndpoint_template.json zu erstellen. Mit dieser Vorlage wird ein privater Endpunkt für eine vorhandene Azure Cosmos DB-vAPI für NoSQL-Konto in einem vorhandenen virtuellen Netzwerk erstellt.

@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

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

Erstellen Sie eine Parameterdatei für die Vorlage, und nennen Sie diese PrivateEndpoint_parameters.json“. Fügen Sie in der Parameterdatei den folgenden Code ein:

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

Erstellen Sie mit dem folgenden Code ein PowerShell-Skript. Ersetzen Sie vor dem Ausführen des Skripts zunächst die Abonnement-ID, den Ressourcengruppennamen und andere Variablenwerte durch die entsprechenden Angaben für Ihre Umgebung.

### 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

Im PowerShell-Skript kann die Variable GroupId nur einen Wert enthalten. Dieser Wert ist der API-Typ des Kontos. Zulässige Werte: Sql, SqlDedicated, MongoDB, Cassandra, Gremlin und Table. Einige Azure Cosmos DB-Kontotypen sind über mehrere APIs zugänglich. Zum Beispiel:

• Die API für NoSQL-Konten verfügt über eine zusätzliche Option für Konten, die für die Verwendung des dedizierten Gateways konfiguriert sind.
• Auf die API für Gremlin-Konten kann über sowohl Gremlin- als auch API für NoSQL-Konten zugegriffen werden.
• Auf die API für Tabelle-Konten kann über sowohl Table- als auch API für NoSQL-Konten zugegriffen werden.

Für diese Konten müssen Sie einen privaten Endpunkt für jeden API-Typ erstellen. Wenn Sie einen privaten Endpunkt für SqlDedicated erstellen, müssen Sie nur dann einen zweiten Endpunkt für Sql hinzufügen, wenn Sie auch eine Verbindung mit Ihrem Konto mittels dem Standardgateway herstellen möchten. Der entsprechende API-Typ wird im GroupId-Array angegeben.

Nach der erfolgreichen Bereitstellung der Vorlage wird eine Ausgabe ähnlich der folgenden Abbildung angezeigt. Der Wert für provisioningState lautet Succeeded, wenn die privaten Endpunkte ordnungsgemäß eingerichtet sind.

Nach der Bereitstellung der Vorlage werden die privaten IP-Adressen innerhalb des Subnetzes reserviert. Die Firewallregel für das Azure Cosmos DB-Konto ist so konfiguriert, dass nur Verbindungen über den privaten Endpunkt zugelassen werden.

Integrieren des privaten Endpunkts in eine private DNS-Zone

Verwenden Sie den folgenden Code, um eine Resource Manager-Vorlage namens PrivateZone_template.json zu erstellen. Mit dieser Vorlage wird eine private DNS-Zone für eine vorhandene Azure Cosmos DB-API für NoSQL-Konto in einem vorhandenen virtuellen Netzwerk erstellt.

{
    "$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')]"
                }
            }
        }        
    ]
}

Erstellen Sie die beiden folgenden Parameterdateien für die Vorlage. Erstellen Sie die Datei PrivateZone_parameters.json mit dem folgenden Code:

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

Verwenden Sie den folgenden Code, um die Resource Manager-Vorlage namens PrivateZone_template.json zu erstellen. Mit dieser Vorlage wird eine private DNS-Zonengruppe für eine vorhandene Azure Cosmos DB-API für NoSQL-Konto in einem vorhandenen virtuellen Netzwerk erstellt.

{
    "$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'))]"
                }
              }
            ]
          }
        }
    ]
}

Erstellen Sie die beiden folgenden Parameterdateien für die Vorlage. Erstellen Sie PrivateZoneGroup_parameters.json mit folgendem Code:

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

Erstellen Sie mit dem folgenden Code ein PowerShell-Skript. Ersetzen Sie vor dem Ausführen des Skripts zunächst die Abonnement-ID, den Ressourcengruppennamen und andere Variablenwerte durch die entsprechenden Angaben für Ihre Umgebung.

### 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

Konfigurieren von benutzerdefiniertem DNS

Verwenden Sie möglichst eine private DNS-Zone innerhalb des Subnetzes, in dem Sie den privaten Endpunkt erstellt haben. Konfigurieren Sie die Endpunkte so, dass jede private IP-Adresse einem DNS-Eintrag zugeordnet ist. Siehe die Eigenschaft fqdns in der zuvor gezeigten Antwort.

Wenn Sie den privaten Endpunkt erstellen, können Sie ihn in eine private DNS-Zone in Azure integrieren. Wenn Sie stattdessen eine benutzerdefinierte DNS-Zone verwenden möchten, müssen Sie diese so konfigurieren, dass DNS-Einträge für alle privaten IP-Adressen hinzugefügt werden, die für den privaten Endpunkt reserviert sind.

Private Link in Kombination mit Firewallregeln

Folgende Fälle und Ergebnisse sind bei Verwendung von Private Link in Verbindung mit Firewallregeln möglich:

• Wenn Sie keine Firewallregeln konfigurieren, kann standardmäßig der gesamte Datenverkehr auf ein Azure Cosmos DB-Konto zugreifen.

• Wenn Sie öffentlichen Datenverkehr oder einen Dienstendpunkt konfigurieren und private Endpunkte erstellen, werden verschiedene Arten von eingehendem Datenverkehr durch den entsprechenden Typ der Firewallregel autorisiert. Wenn ein privater Endpunkt in einem Subnetz konfiguriert ist, in dem auch der Dienstendpunkt konfiguriert ist:

  • Datenverkehr zu dem vom privaten Endpunkt zugeordneten Datenbankkonto wird über den privaten Endpunkt geleitet.
  • Datenverkehr zu anderen Datenbankkonten aus dem Subnetz wird über den Dienstendpunkt geleitet.

• Wenn Sie keinen öffentlichen Datenverkehr oder Dienstendpunkt konfigurieren und private Endpunkte erstellen, ist das Azure Cosmos DB-Konto nur über die privaten Endpunkte zugänglich. Wenn Sie keinen öffentlichen Datenverkehr und keinen Dienstendpunkt konfigurieren, ist das Konto nach dem Ablehnen oder Löschen aller genehmigten privaten Endpunkte für das gesamte Netzwerk offen, es sein denn, PublicNetworkAccess ist auf Deaktiviert festgelegt.

Blockieren des Zugriffs auf öffentliche Netzwerke während der Kontoerstellung

Wie im vorherigen Abschnitt beschrieben wurde und sofern keine bestimmten Firewallregeln festgelegt wurden, kann durch das Hinzufügen eines privaten Endpunkts nur über private Endpunkte auf Ihr Azure Cosmos DB-Konto zugegriffen werden. Dies bedeutet, dass das Azure Cosmos DB-Konto über öffentlichen Datenverkehr erreicht werden könnte, nachdem es erstellt wurde und bevor ein privater Endpunkt hinzugefügt wird. Wenn Sie sicherstellen möchten, dass der Zugriff auf öffentliche Netzwerke sogar vor der Erstellung von privaten Endpunkten deaktiviert ist, können Sie das Flag publicNetworkAccess während der Kontoerstellung auf Deaktiviert festlegen. Dieses Flag hat Vorrang vor jeder IP- oder VNET-Regel. Der gesamte Datenverkehr in öffentlichen und virtuellen Netzwerken wird blockiert, wenn das Flag auf Deaktiviert festgelegt ist, selbst wenn die Quell-IP-Adresse oder das virtuelle Netzwerk in der Firewallkonfiguration zugelassen sind.

Ein Beispiel, das die Verwendung dieses Flags zeigt, finden Sie in dieser Azure Resource Manager-Vorlage.

Hinzufügen privater Endpunkte zu einem vorhandenen Azure Cosmos DB-Konto ohne Ausfallzeit

Wenn einem vorhandenen Konto ein privater Endpunkt hinzugefügt wird, führt dies standardmäßig zu einer kurzen Downtime von etwa 5 Minuten. Befolgen Sie diese Anweisungen, um diese Downtime zu vermeiden:

1. Fügen Sie Ihrer Firewallkonfiguration IP- oder VNET-Regeln hinzu, um die Clientverbindungen explizit zuzulassen.
2. Warten Sie 10 Minuten, um sicherzustellen, dass das Konfigurationsupdate angewandt wurde.
3. Konfigurieren Sie den neuen privaten Endpunkt.
4. Entfernen Sie den in Schritt 1 festgelegten Firewallregelsatz.

Portbereich bei Verwendung des direkten Modus

Wenn Sie Private Link mit einem Azure Cosmos DB-Konto über eine Verbindung im direkten Modus verwenden, müssen Sie sicherstellen, dass der gesamte Bereich der TCP-Ports (0 bis 65535) geöffnet ist.

Aktualisieren eines privaten Endpunkts beim Hinzufügen oder Entfernen einer Region

Es gibt drei Regionen für Azure Cosmos DB-Kontobereitstellungen: USA, Westen, USA, Mitte und Europa, Westen. Wenn Sie einen privaten Endpunkt für das Konto erstellen, werden vier private IP-Adressen im Subnetz reserviert. Es gibt eine IP-Adresse für jede der drei Regionen, und es gibt eine IP-Adresse für den globalen, regionsunabhängigen Endpunkt. Später können Sie dem Azure Cosmos DB-Konto eine neue Region hinzufügen. Die private DNS-Zone wird wie folgt aktualisiert:

• Wenn private DNS-Zonengruppe verwendet wird:

  • Wenn Sie eine private DNS-Zonengruppe verwenden, wird die private DNS-Zone automatisch aktualisiert, wenn der private Endpunkt aktualisiert wird. Im vorherigen Beispiel wird die private DNS-Zone nach dem Hinzufügen einer neuen Region automatisch aktualisiert.

• Wenn die private DNS-Zonengruppe nicht verwendet wird:

  • Wenn Sie keine private DNS-Zonengruppe verwenden, müssen Sie beim Hinzufügen oder Entfernen von Regionen in einem Azure Cosmos DB-Konto die DNS-Einträge für dieses Konto hinzufügen oder entfernen. Nachdem Regionen hinzugefügt oder entfernt wurden, können Sie die private DNS-Zone des Subnetzes aktualisieren, damit diese den hinzugefügten oder entfernten DNS-Einträgen und den zugehörigen privaten IP-Adressen entspricht.

  • Nach dem Hinzufügen der neuen Region müssen Sie einen entsprechenden DNS-Eintrag zu Ihrer privaten DNS-Zonen oder zu Ihrem benutzerdefinierten DNS hinzufügen. Beim Entfernen einer Region können die gleichen Schritte verwendet werden. Nach dem Entfernen der Region müssen Sie den entsprechenden DNS-Eintrag aus Ihrer privaten DNS-Zone oder Ihrem benutzerdefinierten DNS entfernen.

Aktuelle Einschränkungen

Wenn Sie Private Link mit einem Azure Cosmos DB-Konto verwenden, gelten die folgenden Einschränkungen:

• Es können nicht mehr als 200 private Endpunkte in einem einzelnen Azure Cosmos DB-Konto vorhanden sein.

• Wenn Sie Private Link mit einem Azure Cosmos DB-Konto über eine Verbindung im direkten Modus verwenden, können Sie nur das TCP-Protokoll verwenden. Das HTTP-Protokoll wird derzeit nicht unterstützt.

• Wenn Sie die API von Azure Cosmos DB für ein MongoDB-Konto verwenden, wird ein privater Endpunkt für Konten unter Serverversion 3.6 oder höher unterstützt (d. h. Konten, die den Endpunkt im Format *.mongo.cosmos.azure.com verwenden). Private Link wird nicht für Konten unter Serverversion 3.2 unterstützt (d. h. Konten, die Endpunkt im Format *.documents.azure.com verwenden). Zur Verwendung von Private Link sollten Sie alte Konten zur neuen Version migrieren.

• Wenn Sie die API von Azure Cosmos DB für ein MongoDB-Konto verwenden, das über eine Private Link-Instanz verfügt, müssen die Tools und Bibliotheken SNI (Service Name Identification, Identifikation des Dienstnamens) unterstützen oder den Parameter appName aus der Verbindungszeichenfolge übergeben, um eine ordnungsgemäße Verbindung zu ermöglichen. Einige ältere Tools und Bibliotheken sind möglicherweise nicht mit der Private Link-Funktion kompatibel.

• Einem Netzwerkadministrator muss mindestens die Berechtigung Microsoft.DocumentDB/databaseAccounts/PrivateEndpointConnectionsApproval/action im Azure Cosmos DB-Kontobereich erteilt werden, damit er automatisch genehmigte private Endpunkte erstellen kann.

• Derzeit können Sie eine abgelehnte private Endpunktverbindung nicht genehmigen. Erstellen Sie stattdessen den privaten Endpunkt neu, um die private Konnektivität wiederherzustellen. Der Azure Cosmos DB-Dienst für private Verbindungen genehmigt automatisch den neu erstellten privaten Endpunkt.

Einschränkungen bei der Integration für eine private DNS-Zone

Sofern Sie keine private DNS-Zonengruppe verwenden, werden DNS-Einträge in der privaten DNS-Zone nicht automatisch entfernt, wenn Sie einen privaten Endpunkt löschen oder eine Region aus dem Azure Cosmos DB-Konto entfernen. Entfernen Sie die DNS-Einträge manuell, bevor Sie einen der folgenden Schritte ausführen:

• Hinzufügen eines neuen privaten Endpunkts, der mit dieser privaten DNS-Zone verknüpft ist
• Hinzufügen einer neuen Region zu einem Datenbankkonto mit privaten Endpunkten, die mit dieser privaten DNS-Zone verknüpft sind

Wenn Sie die DNS-Einträge nicht bereinigen, können unerwartete Probleme mit der Datenebene auftreten. Zu diesen Problemen gehören Datenausfälle in Regionen, die nach dem Entfernen des privaten Endpunkts oder dem Entfernung der Region hinzugefügt wurden.

Zugehöriger Inhalt

• Firewallunterstützung
• Konfigurieren des Zugriffs über virtuelle Netzwerke
• Azure Private Link