Partilhar via

Configurar o Azure Private Link para uma conta do Azure Cosmos DB

  • Artigo

APLICA-SE A: NoSQL MongoDB Cassandra Gremlin Tabela

Usando o Azure Private Link, você pode se conectar a uma conta do Azure Cosmos DB por meio de um ponto de extremidade privado. O ponto final privado é um conjunto de endereços IP privados numa sub-rede dentro da sua rede virtual. Em seguida, você pode limitar o acesso a uma conta do Azure Cosmos DB em endereços IP privados. Quando o Private Link é combinado com políticas NSG restritivas, ele ajuda a reduzir o risco de exfiltração de dados. Para saber mais sobre pontos de extremidade privados, consulte O que é o Azure Private Link?

Nota

O Private Link não impede que seus pontos de extremidade do Azure Cosmos DB sejam resolvidos pelo DNS público. A filtragem de solicitações de entrada acontece no nível do aplicativo, não no nível do transporte ou da rede.

O Private Link permite que os usuários acessem uma conta do Azure Cosmos DB de dentro da rede virtual ou de qualquer rede virtual emparelhada. Os recursos mapeados para Link Privado também podem ser acessados localmente por meio de emparelhamento privado por meio de VPN ou Rota Expressa do Azure.

Você pode se conectar a uma conta do Azure Cosmos DB configurada com Private Link usando o método de aprovação automática ou manual. Para saber mais, consulte a seção de fluxo de trabalho de aprovação da documentação do Private Link.

Este artigo descreve como configurar pontos de extremidade privados para o repositório transacional do Azure Cosmos DB. Ele pressupõe que você esteja usando o método de aprovação automática. Se você estiver usando o repositório analítico, consulte Configurar pontos de extremidade privados para o repositório analítico.

Criar um ponto de extremidade privado usando o portal do Azure

Siga estas etapas para criar um ponto de extremidade privado para uma conta existente do Azure Cosmos DB usando o portal do Azure:

  1. Entre no portal do Azure e selecione uma conta do Azure Cosmos DB.

  2. Selecione Rede na lista de configurações e, em seguida, selecione + Ponto de extremidade privado na guia Acesso privado:

    Captura de ecrã de seleções para criar um ponto de extremidade privado no portal do Azure

  3. No painel Criar um ponto de extremidade privado - Noções básicas, insira ou selecione os seguintes detalhes:

    Definição Value
    Detalhes do projeto
    Subscrição Selecione a sua subscrição.
    Grupo de recursos Selecione um grupo de recursos.
    Detalhes da instância
    Nome Introduza qualquer nome para o seu ponto de extremidade privado. Se esse nome for usado, crie um exclusivo.
    País/Região Selecione a região onde deseja implantar o Private Link. Crie o ponto de extremidade privado no mesmo local onde sua rede virtual existe.

  4. Selecione Next: Resource.

  5. No painel Criar um ponto de extremidade privado - Recurso, insira ou selecione estas informações:

    Definição Value
    Método de ligação Selecione Conectar a um recurso do Azure em meu diretório.

    Em seguida, você pode escolher um dos seus recursos para configurar o Private Link. Ou você pode se conectar ao recurso de outra pessoa usando um ID de recurso ou alias que ela compartilhou com você.
    Subscrição Selecione a sua subscrição.
    Tipo de recurso Selecione Microsoft.AzureCosmosDB/databaseAccounts.
    Recurso Selecione a sua conta do Azure Cosmos DB.
    Subrecurso de destino Selecione o tipo de API do Azure Cosmos DB que você deseja mapear. O padrão é apenas uma opção para as APIs para SQL, MongoDB e Cassandra. Para as APIs para Gremlin e Table, você também pode escolher NoSQL porque essas APIs são interoperáveis com a API para NoSQL. Se você tiver um gateway dedicado provisionado para uma API para conta NoSQL, também verá uma opção para SqlDedicated.

  6. Selecione Next: Virtual Network.

  7. No painel Criar um ponto de extremidade privado - Rede Virtual, insira ou selecione estas informações:

    Definição Value
    Rede virtual Selecione sua rede virtual.
    Sub-rede Selecione sua sub-rede.

  8. Selecione Next: DNS.

  9. No painel Criar um ponto de extremidade privado - DNS, insira ou selecione estas informações:

    Definição Value
    Integrar com zona DNS privada Selecione Yes (Sim).

    Para estabelecer ligação de forma privada ao ponto final privado, precisa de um registo DNS. Recomendamos que integre o seu ponto de extremidade privado com uma zona DNS privada. Você também pode usar seus próprios servidores DNS ou criar registros DNS usando os arquivos host em suas máquinas virtuais.

    Quando você seleciona sim para essa opção, um grupo de zonas DNS privadas também é criado. O grupo de zonas DNS é um link entre a zona DNS privada e o ponto de extremidade privado. Este link ajuda você a atualizar automaticamente a zona DNS privada quando há uma atualização para o ponto de extremidade privado. Por exemplo, quando você adiciona ou remove regiões, a zona DNS privada é atualizada automaticamente.
    Nome da configuração Selecione sua assinatura e grupo de recursos.

    A zona DNS privada é determinada automaticamente. Não é possível alterá-lo usando o portal do Azure.

  10. Selecione Next: Tags>Review + create. Na página Rever + criar, o Azure valida a sua configuração.

  11. Quando vir a mensagem Validação aprovada , selecione Criar.

Quando você tiver um Link Privado aprovado para uma conta do Azure Cosmos DB, no portal do Azure, a opção Todas as redes no painel Firewall e redes virtuais não estará disponível.

Tipos de API e nomes de zonas privadas

Consulte a configuração do DNS do Ponto de Extremidade Privado do Azure para obter uma explicação mais detalhada sobre zonas privadas e configurações de DNS para ponto de extremidade privado. A tabela a seguir mostra o mapeamento entre diferentes tipos de API de conta do Azure Cosmos DB, subrecursos com suporte e os nomes de zona privada correspondentes. Você também pode acessar as contas Gremlin e API for Table por meio da API para NoSQL, portanto, há duas entradas para essas APIs. Há também uma entrada extra para a API para NoSQL para contas que usam o gateway dedicado.

Tipo de API de conta do Azure Cosmos DB Subrecursos suportados ou IDs de grupo Nome da zona privada
NoSQL Sql privatelink.documents.azure.com
NoSQL SqlDedicated privatelink.sqlx.cosmos.azure.com
Cassandra Cassandra privatelink.cassandra.cosmos.azure.com
Retardado MongoDB privatelink.mongo.cosmos.azure.com
Gremlin Gremlin privatelink.gremlin.cosmos.azure.com
Gremlin Sql privatelink.documents.azure.com
Tabela Tabela privatelink.table.cosmos.azure.com
Tabela Sql privatelink.documents.azure.com

Buscar os endereços IP privados

Depois que o ponto de extremidade privado for provisionado, você poderá consultar os endereços IP. Para exibir os endereços IP do portal do Azure:

  1. Procure o ponto de extremidade privado que você criou anteriormente. Neste caso, é cdbPrivateEndpoint3.
  2. Selecione a guia Visão geral para ver as configurações de DNS e endereços IP.

Captura de ecrã de endereços IP privados no portal do Azure

Vários endereços IP são criados por ponto de extremidade privado:

  • Um para o ponto de extremidade global independente de região da conta do Azure Cosmos DB.
  • Um para cada região onde a conta do Azure Cosmos DB é implantada.

Criar um ponto de extremidade privado usando o Azure PowerShell

Execute o seguinte script do PowerShell para criar um ponto de extremidade privado chamado MyPrivateEndpoint para uma conta existente do Azure Cosmos DB. Substitua os valores das variáveis pelos detalhes do seu ambiente.

$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

Integrar o ponto de extremidade privado com uma zona DNS privada

Depois de criar o ponto de extremidade privado, você pode integrá-lo a uma zona DNS privada usando o seguinte script do PowerShell:

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

Buscar os endereços IP privados

Depois que o ponto de extremidade privado for provisionado, você poderá consultar os endereços IP e o mapeamento FQDN usando o seguinte script do PowerShell:

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

Criar um ponto de extremidade privado usando a CLI do Azure

Execute o seguinte script da CLI do Azure para criar um ponto de extremidade privado chamado myPrivateEndpoint para uma conta existente do Azure Cosmos DB. Substitua os valores das variáveis pelos detalhes do seu ambiente.

# 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

Integrar o ponto de extremidade privado com uma zona DNS privada

Depois de criar o ponto de extremidade privado, você pode integrá-lo a uma zona DNS privada usando o seguinte script da CLI do Azure:

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

Criar um ponto de extremidade privado usando um modelo do Gerenciador de Recursos

Você pode configurar o Private Link criando um ponto de extremidade privado em uma sub-rede de rede virtual. Você consegue isso usando um modelo do Azure Resource Manager.

Use o código a seguir para criar um modelo do Gerenciador de Recursos chamado PrivateEndpoint_template.json. Este modelo cria um ponto de extremidade privado para uma conta existente do Azure Cosmos DB vAPI for NoSQL em uma rede virtual existente.

@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

Definir o arquivo de parâmetros para o modelo

Crie um arquivo de parâmetros para o modelo e nomeie-o PrivateEndpoint_parameters.json. Adicione o seguinte código ao arquivo de parâmetros:

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

Implantar o modelo usando um script do PowerShell

Crie um script do PowerShell usando o código a seguir. Antes de executar o script, substitua a ID da assinatura, o nome do grupo de recursos e outros valores de variáveis pelos detalhes do seu ambiente.

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

No script do PowerShell, a GroupId variável pode conter apenas um valor. Esse valor é o tipo de API da conta. Os valores permitidos são: Sql, SqlDedicated, , MongoDB, GremlinCassandra, e Table. Alguns tipos de conta do Azure Cosmos DB são acessíveis por meio de várias APIs. Por exemplo:

  • A API para contas NoSQL tem uma opção adicionada para contas configuradas para usar o gateway dedicado.
  • A API para contas Gremlin pode ser acessada a partir de contas Gremlin e API para contas NoSQL.
  • A API para contas de tabela pode ser acessada de Table e API para contas NoSQL.

Para essas contas, você deve criar um ponto de extremidade privado para cada tipo de API. Se você estiver criando um ponto de extremidade privado para SqlDedicatedo , só precisará adicionar um segundo ponto de extremidade para Sql se quiser também se conectar à sua conta usando o gateway padrão. O tipo de API correspondente é especificado na GroupId matriz.

Depois que o modelo for implantado com êxito, você poderá ver uma saída semelhante à que a imagem a seguir mostra. O provisioningState valor é Succeeded se os pontos de extremidade privados estiverem configurados corretamente.

Captura de tela da saída de implantação para o modelo do Gerenciador de Recursos.

Depois que o modelo é implantado, os endereços IP privados são reservados dentro da sub-rede. A regra de firewall da conta do Azure Cosmos DB está configurada para aceitar conexões somente do ponto de extremidade privado.

Integrar o ponto de extremidade privado com uma zona DNS privada

Use o código a seguir para criar um modelo do Gerenciador de Recursos chamado PrivateZone_template.json. Este modelo cria uma zona DNS privada para uma conta existente da API do Azure Cosmos DB para NoSQL em uma rede virtual existente.

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

Definir o arquivo de parâmetros para o modelo

Crie o seguinte arquivo de dois parâmetros para o modelo. Crie o PrivateZone_parameters.json com o seguinte código:

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

Use o código a seguir para criar um modelo do Gerenciador de Recursos chamado PrivateZoneGroup_template.json. Este modelo cria um grupo de zonas DNS privadas para uma conta existente da API do Azure Cosmos DB para NoSQL em uma rede virtual existente.

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

Definir o arquivo de parâmetros para o modelo

Crie o seguinte arquivo de dois parâmetros para o modelo. Crie o PrivateZoneGroup_parameters.json. com o seguinte código:

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

Implantar o modelo usando um script do PowerShell

Crie um script do PowerShell usando o código a seguir. Antes de executar o script, substitua a ID da assinatura, o nome do grupo de recursos e outros valores de variáveis pelos detalhes do seu ambiente.

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

Configurar DNS personalizado

Você deve usar uma zona DNS privada dentro da sub-rede onde criou o ponto de extremidade privado. Configure os pontos de extremidade para que cada endereço IP privado seja mapeado para uma entrada DNS. Consulte a propriedade fqdns na resposta mostrada anteriormente.

Ao criar o ponto final privado, pode integrá-lo numa zona DNS privada no Azure. Se, em vez disso, optar por utilizar uma zona DNS personalizada, terá de configurá-la para adicionar registos DNS para todos os endereços IP privados reservados para o ponto de extremidade privado.

Importante

É a resolução DNS de suas solicitações que determina se essas solicitações passam por seus pontos de extremidade privados ou se seguem a rota pública padrão. Certifique-se de que o DNS local faz referência correta ao endereço IP privado mapeado pelo ponto de extremidade privado.

As seguintes situações e resultados são possíveis quando você usa o Private Link em combinação com regras de firewall:

  • Se você não configurar nenhuma regra de firewall, por padrão, todo o tráfego poderá acessar uma conta do Azure Cosmos DB.

  • Se você configurar o tráfego público ou um ponto de extremidade de serviço e criar pontos de extremidade privados, diferentes tipos de tráfego de entrada serão autorizados pelo tipo correspondente de regra de firewall. Se um ponto de extremidade privado estiver configurado em uma sub-rede onde o ponto de extremidade de serviço também estiver configurado:

    • o tráfego para a conta de banco de dados mapeada pelo ponto de extremidade privado é roteado via ponto de extremidade privado,
    • O tráfego para outras contas de banco de dados da sub-rede é roteado via ponto de extremidade de serviço.

  • Se você não configurar nenhum ponto de extremidade de serviço ou tráfego público e criar pontos de extremidade privados, a conta do Azure Cosmos DB estará acessível somente por meio dos pontos de extremidade privados. Se você não configurar o tráfego público ou um ponto de extremidade de serviço, depois que todos os pontos de extremidade privados aprovados forem rejeitados ou excluídos, a conta estará aberta para toda a rede, a menos que PublicNetworkAccess esteja definida como Desabilitada.

Bloquear o acesso à rede pública durante a criação de contas

Conforme descrito na seção anterior, e a menos que regras de firewall específicas tenham sido definidas, adicionar um ponto de extremidade privado torna sua conta do Azure Cosmos DB acessível somente por meio de pontos de extremidade privados. Isso significa que a conta do Azure Cosmos DB pode ser acessada a partir do tráfego público depois de criada e antes que um ponto de extremidade privado seja adicionado. Para se certificar de que o acesso à rede pública está desativado mesmo antes da criação de pontos de extremidade privados, pode definir o sinalizador como Desativado durante a publicNetworkAccess criação da conta. Observe que esse sinalizador tem precedência sobre qualquer IP ou regra de rede virtual. Todo o tráfego de rede pública e virtual é bloqueado quando o sinalizador é definido como Desativado, mesmo que o IP de origem ou a rede virtual seja permitido na configuração do firewall.

Para obter um exemplo mostrando como usar esse sinalizador, consulte este modelo do Azure Resource Manager.

Adicionar pontos de extremidade privados a uma conta existente do Azure Cosmos DB sem tempo de inatividade

Por padrão, adicionar um ponto de extremidade privado a uma conta existente resulta em um curto tempo de inatividade de aproximadamente cinco minutos. Siga estas instruções para evitar esse tempo de inatividade:

  1. Adicione regras de IP ou de rede virtual à configuração do firewall para permitir explicitamente as conexões do cliente.
  2. Aguarde 10 minutos para garantir que a atualização de configuração seja aplicada.
  3. Configure seu novo ponto de extremidade privado.
  4. Remova as regras de firewall definidas na etapa 1.

Nota

Se você tiver aplicativos em execução usando os SDKs do Azure Cosmos DB, pode haver tempos limite transitórios durante a atualização de configuração. Certifique-se de que seu aplicativo foi projetado para ser resiliente a falhas de conectividade transitórias e ter lógica de repetição em vigor caso seja necessário.

Intervalo de portas ao usar o modo direto

Ao usar o Private Link com uma conta do Azure Cosmos DB por meio de uma conexão de modo direto, você precisa garantir que o intervalo completo de portas TCP (0 - 65535) esteja aberto.

Atualizar um ponto de extremidade privado ao adicionar ou remover uma região

Há três regiões para implantações de conta do Azure Cosmos DB: EUA Ocidental, EUA Central e Europa Ocidental. Quando você cria um ponto de extremidade privado para sua conta, quatro IPs privados são reservados na sub-rede. Há um IP para cada uma das três regiões, e há um IP para o endpoint global independente da região. Mais tarde, você pode adicionar uma nova região à conta do Azure Cosmos DB. A zona DNS privada é atualizada da seguinte forma:

  • Se for utilizado um grupo de zonas DNS privado:

    Se você usar um grupo de zonas DNS privadas, a zona DNS privada será atualizada automaticamente quando o ponto de extremidade privado for atualizado. No exemplo anterior, depois de adicionar uma nova região, a zona DNS privada é atualizada automaticamente.

  • Se o grupo de zonas DNS privadas não for usado:

    Se você não usar um grupo de zonas DNS privadas, adicionar ou remover regiões a uma conta do Azure Cosmos DB exigirá que você adicione ou remova entradas DNS dessa conta. Depois que as regiões forem adicionadas ou removidas, você poderá atualizar a zona DNS privada da sub-rede para refletir as entradas DNS adicionadas ou removidas e seus endereços IP privados correspondentes.

    No exemplo anterior, depois de adicionar a nova região, você precisa adicionar um registro DNS correspondente à sua zona DNS privada ou ao seu DNS personalizado. Você pode usar as mesmas etapas ao remover uma região. Depois de remover a região, você precisa remover o registro DNS correspondente da zona DNS privada ou do DNS personalizado.

Limitações atuais

As limitações a seguir se aplicam quando você usa o Private Link com uma conta do Azure Cosmos DB:

  • Você não pode ter mais de 200 pontos de extremidade privados em uma única conta do Azure Cosmos DB.

  • Quando utiliza a ligação privada com uma conta do Azure Cosmos DB através de uma ligação de modo direto, pode utilizar apenas o protocolo TCP. O protocolo HTTP não é suportado no momento.

  • Quando você usa a API do Azure Cosmos DB para uma conta MongoDB, um ponto de extremidade privado é suportado para contas no servidor versão 3.6 ou superior (ou seja, contas que usam o ponto de extremidade no formato *.mongo.cosmos.azure.com). O Private Link não é suportado para contas no servidor versão 3.2 (ou seja, contas que usam o ponto de extremidade no formato *.documents.azure.com). Para usar o Private Link, você deve migrar contas antigas para a nova versão.

  • Quando você usa a API do Azure Cosmos DB para uma conta do MongoDB que tem um Link Privado, as ferramentas e bibliotecas devem oferecer suporte à Identificação de Nome de Serviço (SNI) ou passar o appName parâmetro da cadeia de conexão para se conectar corretamente. Algumas ferramentas e bibliotecas mais antigas podem não ser compatíveis com o recurso Private Link.

  • Um administrador de rede deve receber pelo menos a Microsoft.DocumentDB/databaseAccounts/PrivateEndpointConnectionsApproval/action permissão no escopo da conta do Azure Cosmos DB para criar pontos de extremidade privados aprovados automaticamente.

  • Atualmente, não é possível aprovar uma conexão de ponto de extremidade privada rejeitada. Em vez disso, recrie o ponto de extremidade privado para retomar a conectividade privada. O serviço de link privado do Azure Cosmos DB aprova automaticamente o ponto de extremidade privado recriado.

Limitações à integração de zonas DNS privadas

A menos que esteja a utilizar um grupo de zonas DNS privadas, os registos DNS na zona DNS privada não são removidos automaticamente quando elimina um ponto de extremidade privado ou remove uma região da conta do Azure Cosmos DB. Você deve remover manualmente os registros DNS antes:

  • Adicionar um novo ponto de extremidade privado vinculado a essa zona DNS privada.
  • Adicionar uma nova região a qualquer conta de banco de dados que tenha pontos de extremidade privados vinculados a essa zona DNS privada.

Se você não limpar os registros DNS, problemas inesperados de plano de dados podem acontecer. Esses problemas incluem interrupção de dados para regiões adicionadas após a remoção de ponto final privado ou remoção de região.

Próximos passos

Para saber mais sobre os recursos de segurança do Azure Cosmos DB, consulte os seguintes artigos:

  • Para configurar um firewall para o Azure Cosmos DB, consulte Suporte a firewall.

  • Para saber como configurar um ponto de extremidade de serviço de rede virtual para sua conta do Azure Cosmos DB, consulte Configurar o acesso de redes virtuais.

  • Para saber mais sobre o Link Privado, consulte a documentação do Link Privado do Azure.