Konfigurieren von Azure Private Link für ein Azure Cosmos-KontoConfigure Azure Private Link for an Azure Cosmos account

Durch Verwendung von Azure Private Link können Sie eine Verbindung mit einem Azure Cosmos-Konto über einen privaten Endpunkt herstellen.By using Azure Private Link, you can connect to an Azure Cosmos account via a private endpoint. Bei einem privaten Endpunkt handelt es sich um eine Gruppe privater IP-Adressen in einem Subnetz innerhalb Ihres virtuellen Netzwerks.The private endpoint is a set of private IP addresses in a subnet within your virtual network. Sie können dann den Zugriff auf ein Azure Cosmos-Konto über private IP-Adressen einschränken.You can then limit access to an Azure Cosmos account over private IP addresses. Durch die Kombination von Private Link und eingeschränkten NSG-Richtlinien kann das Risiko der Datenexfiltration verringert werden.When Private Link is combined with restricted NSG policies, it helps reduce the risk of data exfiltration. Weitere Informationen zu privaten Endpunkten finden Sie im Artikel zu Azure Private Link.To learn more about private endpoints, see the Azure Private Link article.

Private Link ermöglicht Benutzern den Zugriff auf ein Azure Cosmos-Konto innerhalb des virtuellen Netzwerks oder über ein mittels Peering verbundenes Netzwerk.Private Link allows users to access an Azure Cosmos account from within the virtual network or from any peered virtual network. Auf Ressourcen, die Private Link zugeordnet sind, kann auch lokal über privates Peering über VPN oder Azure ExpressRoute zugegriffen werden.Resources mapped to Private Link are also accessible on-premises over private peering through VPN or Azure ExpressRoute.

Mithilfe der automatischen oder manuellen Genehmigungsmethode können Sie eine Verbindung mit einem Azure Cosmos-Konto herstellen, das über Private Link konfiguriert wurde.You can connect to an Azure Cosmos account configured with Private Link by using the automatic or manual approval method. Weitere Informationen finden Sie in der Dokumentation zu Private Link im Abschnitt zum Genehmigungsworkflow.To learn more, see the Approval workflow section of the Private Link documentation.

In diesem Artikel werden die Schritte zum Erstellen eines privaten Endpunkts beschrieben.This article describes the steps to create a private endpoint. Dabei wird vorausgesetzt, dass Sie die automatische Genehmigungsmethode verwenden.It assumes that you're using the automatic approval method.

Erstellen eines privaten Endpunkts über das Azure-PortalCreate a private endpoint by using the Azure portal

Führen Sie die folgenden Schritte aus, um über das Azure-Portal einen privaten Endpunkt für ein vorhandenes Azure Cosmos-Konto zu erstellen:Use the following steps to create a private endpoint for an existing Azure Cosmos account by using the Azure portal:

  1. Wählen Sie im Bereich Alle Ressourcen ein Azure Cosmos-Konto aus.From the All resources pane, choose an Azure Cosmos account.

  2. Wählen Sie in der Liste der Einstellungen die Option Private Endpunktverbindungen und dann Privater Endpunkt aus:Select Private Endpoint Connections from the list of settings, and then select Private endpoint:

    Auswahl zum Erstellen eines privaten Endpunkts über das Azure-Portal

  3. Geben Sie im Bereich Privaten Endpunkt erstellen – Grundlagen folgende Informationen ein, oder wählen Sie sie aus:In the Create a private endpoint - Basics pane, enter or select the following details:

    EinstellungSetting WertValue
    ProjektdetailsProject details
    SubscriptionSubscription Wählen Sie Ihr Abonnement aus.Select your subscription.
    Resource groupResource group Wählen Sie eine Ressourcengruppe aus.Select a resource group.
    InstanzendetailsInstance details
    NameName Geben Sie einen beliebigen Namen für Ihren privaten Endpunkt ein.Enter any name for your private endpoint. Wenn dieser Name vergeben ist, erstellen Sie einen eindeutigen Namen.If this name is taken, create a unique one.
    RegionRegion Wählen Sie die Region aus, in der Sie Private Link bereitstellen möchten.Select the region where you want to deploy Private Link. Erstellen Sie den privaten Endpunkt am gleichen Standort, an dem sich auch das virtuelle Netzwerk befindet.Create the private endpoint in the same location where your virtual network exists.
  4. Klicken Sie auf Weiter: Ressource aus.Select Next: Resource.

  5. Geben Sie unter Privaten Endpunkt erstellen – Ressource diese Informationen ein, oder wählen Sie sie aus:In Create a private endpoint - Resource, enter or select this information:

    EinstellungSetting WertValue
    VerbindungsmethodeConnection method Wählen Sie Hiermit wird eine Verbindung mit einer Azure-Ressource im eigenen Verzeichnis hergestellt aus.Select Connect to an Azure resource in my directory.

    Sie können dann eine Ihrer Ressourcen zum Einrichten von Private Link auswählen.You can then choose one of your resources to set up Private Link. 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.Or you can connect to someone else's resource by using a resource ID or alias that they've shared with you.
    SubscriptionSubscription Wählen Sie Ihr Abonnement aus.Select your subscription.
    RessourcentypResource type Wählen Sie Microsoft.AzureCosmosDB/databaseAccounts aus.Select Microsoft.AzureCosmosDB/databaseAccounts.
    ResourceResource Wählen Sie Ihr Azure Cosmos-Konto aus.Select your Azure Cosmos account.
    ZielunterressourceTarget sub-resource Wählen Sie den Typ der zuzuordnenden Azure Cosmos DB-API aus.Select the Azure Cosmos DB API type that you want to map. Standardmäßig ist für die SQL-, MongoDB- und Cassandra-API jeweils nur eine Auswahl möglich.This defaults to only one choice for the SQL, MongoDB, and Cassandra APIs. Für die Gremlin- und die Tabellen-API können Sie auch SQL auswählen, da diese APIs mit der SQL-API interoperabel sind.For the Gremlin and Table APIs, you can also choose Sql because these APIs are interoperable with the SQL API.
  6. Klicken Sie auf Weiter: Konfiguration aus.Select Next: Configuration.

  7. Geben Sie unter Privaten Endpunkt erstellen – Konfiguration die folgenden Informationen ein, oder wählen Sie sie aus:In Create a private endpoint - Configuration, enter or select this information:

    EinstellungSetting WertValue
    NetzwerkNetworking
    Virtuelles NetzwerkVirtual network Wählen Sie Ihr virtuelles Netzwerk aus.Select your virtual network.
    SubnetSubnet Wählen Sie das Subnetz aus.Select your subnet.
    Private DNS-IntegrationPrivate DNS Integration
    Integration in eine private DNS-ZoneIntegrate with private DNS zone Wählen Sie Ja aus.Select Yes.

    Für die Herstellung einer privaten Verbindung mit Ihrem privaten Endpunkt benötigen Sie einen DNS-Eintrag.To connect privately with your private endpoint, you need a DNS record. Es wird empfohlen, den privaten Endpunkt in eine private DNS-Zone zu integrieren.We recommend that you integrate your private endpoint with a private DNS zone. Sie können auch Ihre eigenen DNS-Server verwenden oder DNS-Einträge mithilfe der Hostdateien auf Ihren virtuellen Computern erstellen.You can also use your own DNS servers or create DNS records by using the host files on your virtual machines.
    Private DNS-ZonePrivate DNS Zone Wählen Sie privatelink.documents.azure.com aus.Select privatelink.documents.azure.com.

    Die private DNS-Zone wird automatisch bestimmt.The private DNS zone is determined automatically. Sie können sie nicht über das Azure-Portal ändern.You can't change it by using the Azure portal.
  8. Klicken Sie auf Überprüfen + erstellen.Select Review + create. Auf der Seite Überprüfen + erstellen überprüft Azure Ihre Konfiguration.On the Review + create page, Azure validates your configuration.

  9. Wenn die Meldung Überprüfung erfolgreich angezeigt wird, wählen Sie Erstellen aus.When you see the Validation passed message, select Create.

Wenn Sie Private Link für ein Azure Cosmos-Konto genehmigt haben, ist die Option Alle Netzwerke im Bereich Firewall und virtuelle Netzwerke im Azure-Portal nicht verfügbar.When you have approved Private Link for an Azure Cosmos account, in the Azure portal, the All networks option in the Firewall and virtual networks pane is unavailable.

Die folgende Tabelle veranschaulicht die Zuordnung zwischen verschiedenen Arten von Azure Cosmos-Konto-APIs, unterstützten Unterressourcen und entsprechenden Namen für die private Zone.The following table shows the mapping between different Azure Cosmos account API types, supported sub-resources, and the corresponding private zone names. Sie können auch über die SQL-API auf das Gremlin- und das Tabellen-API-Konto zugreifen, sodass für diese APIs zwei Einträge vorhanden sind.You can also access the Gremlin and Table API accounts through the SQL API, so there are two entries for these APIs.

Art der Azure Cosmos-Konto-APIAzure Cosmos account API type Unterstützte Unterressourcen (oder Gruppen-IDs)Supported sub-resources (or group IDs) Name der privaten ZonePrivate zone name
SqlSql SqlSql privatelink.documents.azure.comprivatelink.documents.azure.com
CassandraCassandra CassandraCassandra privatelink.cassandra.cosmos.azure.comprivatelink.cassandra.cosmos.azure.com
MongoMongo MongoDBMongoDB privatelink.mongo.cosmos.azure.comprivatelink.mongo.cosmos.azure.com
GremlinGremlin GremlinGremlin privatelink.gremlin.cosmos.azure.comprivatelink.gremlin.cosmos.azure.com
GremlinGremlin SqlSql privatelink.documents.azure.comprivatelink.documents.azure.com
TabelleTable TabelleTable privatelink.table.cosmos.azure.comprivatelink.table.cosmos.azure.com
TabelleTable SqlSql privatelink.documents.azure.comprivatelink.documents.azure.com

Abrufen der privaten IP-AdressenFetch the private IP addresses

Nach der Bereitstellung des privaten Endpunkts können Sie die IP-Adressen abfragen.After the private endpoint is provisioned, you can query the IP addresses. Zum Anzeigen der IP-Adressen im Azure-Portal führen Sie die folgenden Schritte aus:To view the IP addresses from the Azure portal:

  1. Wählen Sie Alle Ressourcen.Select All resources.
  2. Suchen Sie nach dem privaten Endpunkt, den Sie zuvor erstellt haben.Search for the private endpoint that you created earlier. In diesem Fall ist das cdbPrivateEndpoint3.In this case, it's cdbPrivateEndpoint3.
  3. Wählen Sie die Registerkarte Übersicht aus, um die DNS-Einstellungen und IP-Adressen anzuzeigen.Select the Overview tab to see the DNS settings and IP addresses.

Private IP-Adressen im Azure-Portal

Für jeden privaten Endpunkt werden mehrere IP-Adressen erstellt:Multiple IP addresses are created per private endpoint:

  • Eine IP-Adresse für den globalen (regionsunabhängigen) Endpunkt des Azure Cosmos-KontosOne for the global (region-agnostic) endpoint of the Azure Cosmos account
  • Eine IP-Adresse für jede Region, in der das Azure Cosmos-Konto bereitgestellt wirdOne for each region where the Azure Cosmos account is deployed

Erstellen eines privaten Endpunkts mit Azure PowerShellCreate a private endpoint by using Azure PowerShell

Führen Sie das folgende PowerShell-Skript aus, um den privaten Endpunkt „MyPrivateEndpoint“ für ein vorhandenes Azure Cosmos-Konto zu erstellen.Run the following PowerShell script to create a private endpoint named "MyPrivateEndpoint" for an existing Azure Cosmos account. Ersetzen Sie die Variablenwerte durch die entsprechenden Angaben für Ihre Umgebung.Replace the variable values with the details for your environment.

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

# API type of the Azure Cosmos account: Sql, MongoDB, Cassandra, Gremlin, or Table
$CosmosDbApiType = "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 $CosmosDbApiType
 
$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 "westcentralus" -Subnet  $subnet -PrivateLinkServiceConnection $privateEndpointConnection

Integrieren des privaten Endpunkts in eine private DNS-ZoneIntegrate the private endpoint with a 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:After you create the private endpoint, you can integrate it with a private DNS zone by using the following PowerShell script:

Import-Module Az.PrivateDns
$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"
 
foreach ($ipconfig in $networkInterface.properties.ipConfigurations) { 
foreach ($fqdn in $ipconfig.properties.privateLinkConnectionProperties.fqdns) { 
Write-Host "$($ipconfig.properties.privateIPAddress) $($fqdn)"  
$recordName = $fqdn.split('.',2)[0] 
$dnsZone = $fqdn.split('.',2)[1] 
New-AzPrivateDnsRecordSet -Name $recordName `
  -RecordType A -ZoneName $zoneName  `
  -ResourceGroupName $ResourceGroupName -Ttl 600 `
  -PrivateDnsRecords (New-AzPrivateDnsRecordConfig `
  -IPv4Address $ipconfig.properties.privateIPAddress)  
}
}

Abrufen der privaten IP-AdressenFetch the private IP addresses

Nach der Bereitstellung des privaten Endpunkts können Sie mit dem folgenden PowerShell-Skript die IP-Adressen und die FQDN-Zuordnung abfragen:After the private endpoint is provisioned, you can query the IP addresses and the FQDN mapping by using the following PowerShell script:

$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 CLICreate a private endpoint by using Azure CLI

Führen Sie das folgende Azure CLI-Skript aus, um einen privaten Endpunkt namens „myPrivateEndpoint“ für ein vorhandenes Azure Cosmos-Konto zu erstellen.Run the following Azure CLI script to create a private endpoint named "myPrivateEndpoint" for an existing Azure Cosmos account. Ersetzen Sie die Variablenwerte durch die entsprechenden Angaben für Ihre Umgebung.Replace the variable values with the details for your environment.

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

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

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

# API type of your Azure Cosmos account: Sql, MongoDB, Cassandra, Gremlin, or Table
CosmosDbApiType="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 $CosmosDbApiType \
    --connection-name $PrivateConnectionName

Integrieren des privaten Endpunkts in eine private DNS-ZoneIntegrate the private endpoint with a 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:After you create the private endpoint, you can integrate it with a private DNS zone by using the following Azure CLI script:

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 

#Query for the network interface ID  
networkInterfaceId=$(az network private-endpoint show --name $PrivateEndpointName --resource-group $ResourceGroupName --query 'networkInterfaces[0].id' -o tsv)
 
# Copy the content for privateIPAddress and FQDN matching the Azure Cosmos account 
az resource show --ids $networkInterfaceId --api-version 2019-04-01 -o json 
 
#Create DNS records 
az network private-dns record-set a create --name recordSet1 --zone-name privatelink.documents.azure.com --resource-group $ResourceGroupName
az network private-dns record-set a add-record --record-set-name recordSet2 --zone-name privatelink.documents.azure.com --resource-group $ResourceGroupName -a <Private IP Address>

Erstellen eines privaten Endpunkts mithilfe einer Resource Manager-VorlageCreate a private endpoint by using a Resource Manager template

Sie können eine private Verknüpfung einrichten, indem Sie einen privaten Endpunkt in einem Subnetz des virtuellen Netzwerks erstellen.You can set up Private Link by creating a private endpoint in a virtual network subnet. Dazu verwenden Sie eine Azure Resource Manager-Vorlage.You achieve this by using an Azure Resource Manager template.

Erstellen Sie mit dem folgenden Code die Resource Manager-Vorlage „PrivateEndpoint_template.json“.Use the following code to create a Resource Manager template named "PrivateEndpoint_template.json." Mit dieser Vorlage wird ein privater Endpunkt für ein vorhandenes Azure Cosmos-SQL-API-Konto in einem vorhandenen virtuellen Netzwerk erstellt.This template creates a private endpoint for an existing Azure Cosmos SQL API account in an existing virtual network.

{
    "$schema": "http://schema.management.azure.com/schemas/2015-01-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]"
        }
    }
}

Definieren der Parameterdatei für die VorlageDefine the parameters file for the template

Erstellen Sie eine Parameterdatei für die Vorlage, und nennen Sie sie „PrivateEndpoint_parameters.json“.Create a parameters file for the template, and name it "PrivateEndpoint_parameters.json." Fügen Sie in der Parameterdatei den folgenden Code ein:Add the following code to the parameters file:

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

Bereitstellen der Vorlage mithilfe eines PowerShell-SkriptsDeploy the template by using a PowerShell script

Erstellen Sie mit dem folgenden Code ein PowerShell-Skript.Create a PowerShell script by using the following code. 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.Before you run the script, replace the subscription ID, resource group name, and other variable values with the details for your environment.

### This script creates a private endpoint for an existing Azure Cosmos 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 account and virtual network resources are located
$ResourceGroupName = "myResourceGroup"
# Name of the Azure Cosmos account
$CosmosDbAccountName = "mycosmosaccount"
# API type of the Azure Cosmos account. It can be one of the following: "Sql", "MongoDB", "Cassandra", "Gremlin", "Table"
$CosmosDbApiType = "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 $CosmosDbApiType `
    -PrivateEndpointName $PrivateEndpointName

$deploymentOutput

Im PowerShell-Skript kann die Variable GroupId nur einen Wert enthalten.In the PowerShell script, the GroupId variable can contain only one value. Dieser Wert ist der API-Typ des Kontos.That value is the API type of the account. Zulässige Werte sind Sql, MongoDB, Cassandra, Gremlin und Table.Allowed values are: Sql, MongoDB, Cassandra, Gremlin, and Table. Einige Azure Cosmos-Kontotypen sind über mehrere APIs zugänglich.Some Azure Cosmos account types are accessible through multiple APIs. Beispiel:For example:

  • Auf ein Gremlin-API-Konto kann über Gremlin-API- sowie über SQL-API-Konten zugegriffen werden.A Gremlin API account can be accessed from both Gremlin and SQL API accounts.
  • Auf ein Tabellen-API-Konto kann über Tabellen-API- sowie über SQL-API-Konten zugegriffen werden.A Table API account can be accessed from both Table and SQL API accounts.

Für diese Konten müssen Sie einen privaten Endpunkt für jeden API-Typ erstellen.For those accounts, you must create one private endpoint for each API type. Der entsprechende API-Typ wird im GroupId-Array angegeben.The corresponding API type is specified in the GroupId array.

Nach der erfolgreichen Bereitstellung der Vorlage wird eine Ausgabe ähnlich der folgenden Abbildung angezeigt.After the template is deployed successfully, you can see an output similar to what the following image shows. Der Wert für provisioningState lautet Succeeded, wenn die privaten Endpunkte ordnungsgemäß eingerichtet sind.The provisioningState value is Succeeded if the private endpoints are set up correctly.

Bereitstellungsausgabe für die Resource Manager-Vorlage

Nach der Bereitstellung der Vorlage werden die privaten IP-Adressen innerhalb des Subnetzes reserviert.After the template is deployed, the private IP addresses are reserved within the subnet. Die Firewallregel für das Azure Cosmos-Konto ist so konfiguriert, dass nur Verbindungen über den privaten Endpunkt angenommen werden.The firewall rule of the Azure Cosmos account is configured to accept connections from the private endpoint only.

Integrieren des privaten Endpunkts in eine private DNS-ZoneIntegrate the private endpoint with a Private DNS Zone

Erstellen Sie mit dem folgenden Code die Resource Manager-Vorlage „PrivateZone_template.json“.Use the following code to create a Resource Manager template named "PrivateZone_template.json." Mit dieser Vorlage wird eine private DNS-Zone für ein vorhandenes Azure Cosmos-SQL-API-Konto in einem vorhandenen virtuellen Netzwerk erstellt.This template creates a private DNS zone for an existing Azure Cosmos SQL API account in an existing virtual network.

{
    "$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 mit dem folgenden Code die Resource Manager-Vorlage „PrivateZoneRecords_template.json“.Use the following code to create a Resource Manager template named "PrivateZoneRecords_template.json."

{
    "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "DNSRecordName": {
            "type": "string"
        },
        "IPAddress": {
            "type":"string"
        }        
    },
    "resources": [
         {
            "type": "Microsoft.Network/privateDnsZones/A",
            "apiVersion": "2018-09-01",
            "name": "[parameters('DNSRecordName')]",
            "properties": {
                "ttl": 300,
                "aRecords": [
                    {
                        "ipv4Address": "[parameters('IPAddress')]"
                    }
                ]
            }
        }    
    ]
}

Definieren der Parameterdatei für die VorlageDefine the parameters file for the template

Erstellen Sie die beiden folgenden Parameterdateien für die Vorlage.Create the following two parameters file for the template. Erstellen Sie die Datei „PrivateZone_parameters.json“.Create the "PrivateZone_parameters.json." durch den folgenden Code:with the following code:

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

Erstellen Sie die Datei „PrivateZoneRecords_parameters.json“.Create the "PrivateZoneRecords_parameters.json." durch den folgenden Code:with the following code:

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

Bereitstellen der Vorlage mithilfe eines PowerShell-SkriptsDeploy the template by using a PowerShell script

Erstellen Sie mit dem folgenden Code ein PowerShell-Skript.Create a PowerShell script by using the following code. 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.Before you run the script, replace the subscription ID, resource group name, and other variable values with the details for your environment.

### This script:
### - creates a private zone
### - creates a private endpoint for an existing 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 account and virtual network resources are located
$ResourceGroupName = "myResourceGroup"
# Name of the Azure Cosmos account
$CosmosDbAccountName = "mycosmosaccount"
# API type of the Azure Cosmos account. It can be one of the following: "Sql", "MongoDB", "Cassandra", "Gremlin", "Table"
$CosmosDbApiType = "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"

$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"
$PrivateZoneRecordsTemplateFilePath = "PrivateZoneRecords_template.json"
$PrivateZoneRecordsParametersFilePath = "PrivateZoneRecords_parameters.json"
$PrivateEndpointTemplateFilePath = "PrivateEndpoint_template.json"
$PrivateEndpointParametersFilePath = "PrivateEndpoint_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 $CosmosDbApiType `
    -PrivateEndpointName $PrivateEndpointName
$deploymentOutput

## Step 6: Map the private endpoint to the private zone
$networkInterface = Get-AzResource -ResourceId $deploymentOutput.Outputs.privateEndpointNetworkInterface.Value -ApiVersion "2019-04-01"
foreach ($ipconfig in $networkInterface.properties.ipConfigurations) {
    foreach ($fqdn in $ipconfig.properties.privateLinkConnectionProperties.fqdns) {
        $recordName = $fqdn.split('.',2)[0]
        $dnsZone = $fqdn.split('.',2)[1]
        Write-Output "Deploying PrivateEndpoint DNS Record $($PrivateZoneName)/$($recordName) Template on $($resourceGroupName)"
        New-AzResourceGroupDeployment -Name "PrivateEndpointDNSDeployment" `
            -ResourceGroupName $ResourceGroupName `
            -TemplateFile $PrivateZoneRecordsTemplateFilePath `
            -TemplateParameterFile $PrivateZoneRecordsParametersFilePath `
            -DNSRecordName "$($PrivateZoneName)/$($RecordName)" `
            -IPAddress $ipconfig.properties.privateIPAddress
    }
}

Konfigurieren von benutzerdefiniertem DNSConfigure custom DNS

Verwenden Sie möglichst eine private DNS-Zone innerhalb des Subnetzes, in dem Sie den privaten Endpunkt erstellt haben.You should use a private DNS zone within the subnet where you've created the private endpoint. Konfigurieren Sie die Endpunkte so, dass jede private IP-Adresse einem DNS-Eintrag zugeordnet ist.Configure the endpoints so that each private IP address is mapped to a DNS entry. (Siehe fqdns-Eigenschaft in der zuvor gezeigten Antwort.)(See the fqdns property in the response shown earlier.)

Wenn Sie den privaten Endpunkt erstellen, können Sie ihn in eine private DNS-Zone in Azure integrieren.When you're creating the private endpoint, you can integrate it with a private DNS zone in Azure. 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.If you choose to instead use a custom DNS zone, you have to configure it to add DNS records for all private IP addresses reserved for the private endpoint.

Folgende Fälle und Ergebnisse sind bei Verwendung von Private Link in Verbindung mit Firewallregeln möglich:The following situations and outcomes are possible when you use Private Link in combination with firewall rules:

  • Wenn Sie keine Firewallregeln konfigurieren, kann standardmäßig der gesamte Datenverkehr auf ein Azure Cosmos-Konto zugreifen.If you don't configure any firewall rules, then by default, all traffic can access an Azure Cosmos account.

  • 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.If you configure public traffic or a service endpoint and you create private endpoints, then different types of incoming traffic are authorized by the corresponding type of firewall rule. Wenn ein privater Endpunkt in einem Subnetz konfiguriert ist, in dem auch der Dienstendpunkt konfiguriert ist:If a private endpoint is configured in a subnet where service endpoint is also configured:

    • Datenverkehr zu dem vom privaten Endpunkt zugeordneten Datenbankkonto wird über den privaten Endpunkt geleitet.traffic to the database account mapped by the private endpoint is routed via private endpoint,
    • Datenverkehr zu anderen Datenbankkonten aus dem Subnetz wird über den Dienstendpunkt geleitet.traffic to other database accounts from the subnet is routed via service endpoint.
  • Wenn Sie keinen öffentlichen Datenverkehr oder Dienstendpunkt konfigurieren und private Endpunkte erstellen, ist das Azure Cosmos-Konto nur über die privaten Endpunkte zugänglich.If you don't configure any public traffic or service endpoint and you create private endpoints, then the Azure Cosmos account is accessible only through the private endpoints. Wenn Sie keinen öffentlichen Datenverkehr oder einen Dienstendpunkt konfigurieren, ist das Konto nach dem Ablehnen oder Löschen aller genehmigten privaten Endpunkte für das gesamte Netzwerk offen, es sei denn, PublicNetworkAccess wurde deaktiviert (siehe Abschnitt unten).If you don't configure public traffic or a service endpoint, after all approved private endpoints are rejected or deleted, the account is open to the entire network unless PublicNetworkAccess is set to Disabled (see section below).

Blockieren des Zugriffs auf öffentliche Netzwerke während der KontoerstellungBlocking public network access during account creation

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-Konto zugegriffen werden.As described in the previous section, and unless specific firewall rules have been set, adding a private endpoint makes your Azure Cosmos account accessible through private endpoints only. Dies bedeutet, dass das Azure Cosmos-Konto über öffentlichen Datenverkehr erreicht werden könnte, nachdem es erstellt wurde und bevor ein privater Endpunkt hinzugefügt wird.This means that the Azure Cosmos account could be reached from public traffic after it is created and before a private endpoint gets added. Wenn Sie sicherstellen möchten, dass der Zugriff auf öffentliche Netzwerke sogar vor der Erstellung von privaten Endpunkten deaktiviert wird, können Sie das Flag publicNetworkAccess während der Kontoerstellung auf Disabled festlegen.To make sure that public network access is disabled even before the creation of private endpoints, you can set the publicNetworkAccess flag to Disabled during account creation. Ein Beispiel für die Verwendung dieses Flags finden Sie in dieser Azure Resource Manager-Vorlage.See this Azure Resource Manager template for an example showing how to use this flag.

Portbereich bei Verwendung des direkten ModusPort range when using direct mode

Wenn Sie Private Link mit einem Azure Cosmos-Konto über eine Verbindung im direkten Modus verwenden, müssen Sie sicherstellen, dass der gesamte TCP-Portbereich (0 bis 65535) geöffnet ist.When you're using Private Link with an Azure Cosmos account through a direct mode connection, you need to ensure that the full range of TCP ports (0 - 65535) is open.

Aktualisieren eines privaten Endpunkts beim Hinzufügen oder Entfernen einer RegionUpdate a private endpoint when you add or remove a region

Beim Hinzufügen oder Entfernen von Regionen in einem Azure Cosmos-Konto müssen Sie die DNS-Einträge für dieses Konto hinzufügen oder entfernen.Adding or removing regions to an Azure Cosmos account requires you to add or remove DNS entries for that account. 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.After regions have been added or removed, you can update the subnet's private DNS zone to reflect the added or removed DNS entries and their corresponding private IP addresses.

Angenommen, Sie stellen ein Azure Cosmos-Konto in drei Regionen bereit: „USA, Westen“, „USA, Mitte“ und „Europa, Westen“.For example, imagine that you deploy an Azure Cosmos account in three regions: "West US," "Central US," and "West Europe." Wenn Sie einen privaten Endpunkt für das Konto erstellen, werden vier private IP-Adressen im Subnetz reserviert.When you create a private endpoint for your account, four private IPs are reserved in the subnet. Es gibt eine IP-Adresse für jede der drei Regionen, und es gibt eine IP-Adresse für den globalen/regionsunabhängigen Endpunkt.There's one IP for each of the three regions, and there's one IP for the global/region-agnostic endpoint.

Später fügen Sie dem Azure Cosmos-Konto möglicherweise eine neue Region hinzu (z. B. „USA, Osten“).Later, you might add a new region (for example, "East US") to the Azure Cosmos account. Nach dem Hinzufügen der neuen Region müssen Sie einen entsprechenden DNS-Eintrag zu Ihrer privaten DNS-Zone oder zu Ihrem benutzerdefinierten DNS hinzufügen.After adding the new region, you need to add a corresponding DNS record to either your private DNS zone or your custom DNS.

Beim Entfernen einer Region können die gleichen Schritte verwendet werden.You can use the same steps when you remove a region. Nach dem Entfernen der Region müssen Sie den entsprechenden DNS-Eintrag aus Ihrer privaten DNS-Zone oder Ihrem benutzerdefinierten DNS entfernen.After removing the region, you need to remove the corresponding DNS record from either your private DNS zone or your custom DNS.

Aktuelle EinschränkungenCurrent limitations

Bei Verwendung von Private Link mit einem Azure Cosmos-Konto gelten die folgenden Einschränkungen:The following limitations apply when you're using Private Link with an Azure Cosmos account:

  • Es können nicht mehr als 200 private Endpunkte in einem einzelnen Azure Cosmos-Konto vorhanden sein.You can't have more than 200 private endpoints on a single Azure Cosmos account.

  • Wenn Sie Private Link mit einem Azure Cosmos-Konto über eine Verbindung im direkten Modus verwenden, können Sie lediglich das TCP-Protokoll verwenden.When you're using Private Link with an Azure Cosmos account through a direct mode connection, you can use only the TCP protocol. Das HTTP-Protokoll wird derzeit nicht unterstützt.The HTTP protocol is not currently supported.

  • Wenn Sie die Azure Cosmos DB-API für MongoDB-Konten verwenden, wird ein privater Endpunkt nur für Konten unter Serverversion 3.6 unterstützt (d. h. Konten mit Endpunkt im Format *.mongo.cosmos.azure.com).When you're using Azure Cosmos DB's API for MongoDB accounts, a private endpoint is supported for accounts on server version 3.6 only (that is, accounts using the endpoint in the format *.mongo.cosmos.azure.com). Private Link wird nicht für Konten unter Serverversion 3.2 unterstützt (d. h. Konten mit Endpunkt im Format *.documents.azure.com).Private Link is not supported for accounts on server version 3.2 (that is, accounts using the endpoint in the format *.documents.azure.com). Zur Verwendung von Private Link sollten Sie alte Konten zur neuen Version migrieren.To use Private Link, you should migrate old accounts to the new version.

  • Wenn Sie eine Azure Cosmos DB-API für ein MongoDB-Konto verwenden, das Private Link beinhaltet, funktionieren einige Tools oder Bibliotheken unter Umständen nicht, da sie automatisch den Parameter appName aus der Verbindungszeichenfolge entfernen.When you're using an Azure Cosmos DB's API for MongoDB account that has Private Link, some tools or libraries may not work as they automatically strip out the appName parameter from the connection string. Dieser Parameter ist erforderlich, um über einen privaten Endpunkt eine Verbindung mit dem Konto herzustellen.This parameter is required to connect to the account over a private endpoint. Einige Tools wie Visual Studio Code entfernen diesen Parameter nicht aus der Verbindungszeichenfolge und sind daher kompatibel.Some tools, like Visual Studio Code, do not remove this parameter from the connection string and are therefore compatible.

  • Einem Netzwerkadministrator muss mindestens die Berechtigung Microsoft.DocumentDB/databaseAccounts/PrivateEndpointConnectionsApproval/action im Azure Cosmos-Kontobereich erteilt werden, damit er automatisch genehmigte private Endpunkte erstellen kann.A network administrator should be granted at least the Microsoft.DocumentDB/databaseAccounts/PrivateEndpointConnectionsApproval/action permission at the Azure Cosmos account scope to create automatically approved private endpoints.

Einschränkungen bei der Integration für eine private DNS-ZoneLimitations to private DNS zone integration

DNS-Einträge in der privaten DNS-Zone werden nicht automatisch entfernt, wenn Sie einen privaten Endpunkt löschen oder eine Region aus dem Azure Cosmos-Konto entfernen.DNS records in the private DNS zone are not removed automatically when you delete a private endpoint or you remove a region from the Azure Cosmos account. Entfernen Sie die DNS-Einträge manuell, bevor Sie einen der folgenden Schritte ausführen:You must manually remove the DNS records before:

  • Hinzufügen eines neuen privaten Endpunkts, der mit dieser privaten DNS-Zone verknüpft istAdding a new private endpoint linked to this private DNS zone.
  • Hinzufügen einer neuen Region zu einem Datenbankkonto mit privaten Endpunkten, die mit dieser privaten DNS-Zone verknüpft sindAdding a new region to any database account that has private endpoints linked to this private DNS zone.

Wenn Sie die DNS-Einträge nicht bereinigen, können unerwartete Probleme mit der Datenebene auftreten.If you don't clean up the DNS records, unexpected data plane issues might happen. Zu diesen Problemen gehören Datenausfälle in Regionen, die nach dem Entfernen des privaten Endpunkts oder dem Entfernung der Region hinzugefügt wurden.These issues include data outage to regions added after private endpoint removal or region removal.

Nächste SchritteNext steps

Weitere Informationen zu Sicherheitsfunktionen in Azure Cosmos DB finden Sie in folgenden Artikeln:To learn more about Azure Cosmos DB security features, see the following articles: