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

APLICA-SE AO: NoSQL MongoDB Cassandra Gremlin Table

Usando o Link Privado do Azure, você pode se conectar a uma conta do Azure Cosmos DB por meio de um ponto de extremidade privado. O ponto de extremidade privado é um conjunto de endereços IP privados em uma sub-rede dentro da rede virtual. Você pode limitar o acesso a uma conta do Azure Cosmos DB por meio de endereços IP privados. Quando o Link Privado é combinado com políticas de NSG (grupo de segurança de rede) restritas, ele ajuda a reduzir o risco de exfiltração dos dados. Para saber mais sobre pontos de extremidade privados, confira O que é o Link Privado do Azure?

Observação

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

O Link Privado 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 o Link Privado também podem ser acessados localmente no emparelhamento privado por meio de VPN ou do Azure ExpressRoute.

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

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, confira Configurar os pontos de extremidade privados do repositório analítico.

Criar um ponto de extremidade privado usando o portal do Azure

Siga essas 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:

   

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

   Configuração	Valor
   Detalhes do projeto
   Subscription	Selecione sua assinatura.
   Resource group	Selecione um grupo de recursos.
   Detalhes da instância
   Nome	Insira qualquer nome para seu ponto de extremidade privado. Se esse nome já estiver sendo usado, crie um exclusivo.
   Região	Selecione a região em que você deseja implantar o Link Privado. Crie o ponto de extremidade privado no mesmo local em que sua rede virtual existe.

4. Selecione Avançar: Recurso.

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

   Configuração	Valor
   Método de conexão	Selecione Conectar-se a um recurso do Azure em meu diretório. Em seguida, você pode escolher um de seus recursos para configurar o Link Privado. Ou você pode se conectar ao recurso de outra pessoa usando uma ID do recurso ou um alias que foi compartilhado com você.
   Subscription	Selecione sua assinatura.
   Tipo de recurso	Selecione Microsoft.AzureCosmosDB/databaseAccounts.
   Recurso	Selecione a conta do Azure Cosmos DB.
   Sub-recurso de destino	Selecione o tipo de API do Azure Cosmos DB que você deseja mapear. Esse padrão é apenas uma opção para as APIs para SQL, MongoDB e Cassandra. Para as APIs do Gremlin e de Tabela, você também pode escolher NoSql, já que essas APIs são interoperáveis com a API para NoSQL. Se você tiver um gateway dedicado provisionado para uma conta da API para NoSQL, também haverá a opção de SqlDedicated.

6. Selecione Próximo: Rede Virtual.

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

   Configuração	Valor
   Rede virtual	Selecione sua rede virtual.
   Sub-rede	Selecione sua sub-rede.

8. Selecione Avançar: DNS.

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

   Configuração	Valor
   Integrar com a zona DNS privado	Selecione Sim na barra superior. Para se conectar em particular com o seu ponto de extremidade privado, você precisa de um registro DNS. Recomendamos que você integre seu ponto de extremidade privado a 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 zona DNS privado também é criado. O grupo de zona DNS é um vínculo entre a zona DNS privado e o ponto de extremidade privado. Esse link ajuda a atualizar automaticamente a zona DNS privado quando houver 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. Você não pode alterá-la usando o portal do Azure.

10. Selecione Avançar: marcas>Revisão + criar. Na página Examinar + criar, o Azure valida 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 ficará disponível.

Tipos de API e nomes de zona privada

Consulte Configuração de DNS do ponto de extremidade privado do Azure para obter uma explicação mais detalhada sobre zonas privadas e configurações de DNS para pontos de extremidade privados. A tabela a seguir mostra o mapeamento entre os diferentes tipos de API de conta do Azure Cosmos DB, os sub-recursos 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. Também há uma entrada extra da API para NoSQL para contas que usam o gateway dedicado.

Tipo de API de conta do Azure Cosmos DB	Sub-recursos com suporte 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
Mongo	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 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 no portal do Azure:

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

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

• Um para o ponto de extremidade independente de região global 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 script do PowerShell a seguir para criar um ponto de extremidade privado chamado MyPrivateEndpoint para uma conta do Azure Cosmos DB existente. Substitua os valores de variável 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 a uma zona DNS privada

Após criar o ponto de extremidade privado, você poderá 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 endereços IP privados

Depois que o ponto de extremidade privado for provisionado, você poderá consultar os endereços IP e o mapeamento de 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 script da CLI do Azure a seguir para criar um ponto de extremidade privado chamado myPrivateEndpoint para uma conta do Azure Cosmos DB existente. Substitua os valores de variável 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 a uma zona DNS privada

Após criar o ponto de extremidade privado, você poderá 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 Resource Manager

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

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

Bicep

@description('Location for all resources.')
param location string = resourceGroup().location
param privateEndpointName string
param resourceId string
param groupId string
param subnetId string

resource privateEndpoint 'Microsoft.Network/privateEndpoints@2019-04-01' = {
  name: privateEndpointName
  location: location
  properties: {
    subnet: {
      id: subnetId
    }
    privateLinkServiceConnections: [
      {
        name: 'MyConnection'
        properties: {
          privateLinkServiceId: resourceId
          groupIds: [
            groupId
          ]
          requestMessage: ''
        }
      }
    ]
  }
}

output privateEndpointNetworkInterface string = privateEndpoint.properties.networkInterfaces[0].id

JSON

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

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

Bicep / JSON

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

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ável por 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 variável GroupId pode conter apenas um valor. Esse valor é o tipo de API da conta. Os valores permitidos são: Sql, SqlDedicated, MongoDB, Cassandra, Gremlin e Table. Alguns tipos de conta do Azure Cosmos DB podem ser acessados por meio de várias APIs. Por exemplo:

• As contas da API para NoSQL têm uma opção adicional para contas configuradas para usar o gateway dedicado.
• As contas da API para Gremlin podem ser acessada de contas do Gremlin e da API para NoSQL.
• As contas da API para Tabela podem ser acessada de contas da Tabela e da API para 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 SqlDedicated, bastará adicionar um segundo ponto de extremidade para Sql se também quiser se conectar à conta usando o gateway padrão. O tipo de API correspondente é especificado na matriz GroupId.

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

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

Integrar o ponto de extremidade privado a uma zona DNS privada

Use o código a seguir para criar um modelo do Resource Manager chamado PrivateZone_template.json. Esse modelo cria uma zona DNS privado para uma conta já existente da API para NoSQL do Azure Cosmos DB 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')]"
                }
            }
        }        
    ]
}

Crie o arquivo de dois parâmetros a seguir 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 Resource Manager chamado PrivateZoneGroup_template.json. Este modelo cria uma zona DNS privado para uma conta existente da API para NoSQL do Azure Cosmos DB 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'))]"
                }
              }
            ]
          }
        }
    ]
}

Crie o arquivo de dois parâmetros a seguir 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": ""
        }
    }
}

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ável por 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 a zona DNS privada dentro da sub-rede em que você criou o ponto de extremidade privado. Configure os pontos de extremidade para que cada endereço IP privado seja mapeado para uma entrada DNS. Confira a propriedade fqdns na resposta mostrada anteriormente.

Ao criar o ponto de extremidade privado, você pode integrá-lo a uma zona DNS privada no Azure. Se você optar por usar uma zona DNS personalizada, precisará configurá-la para adicionar registros 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 assumem a rota pública padrão. Verifique se o DNS local referencia corretamente o IP privado endereçado mapeado pelo seu ponto de extremidade privado.

Link Privado combinado com regras de firewall

As seguintes situações e resultados são possíveis quando você usa o Link Privado 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, os tipos diferentes 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 na qual o ponto de extremidade de serviço também está configurado:

  • o tráfego para a conta de banco de dados mapeada pelo ponto de extremidade privado será roteado por meio do ponto de extremidade privado,
  • o tráfego para outras contas de banco de dados da sub-rede será roteado por meio do ponto de extremidade de serviço.

• Se você não configurar nenhum tráfego público ou ponto de extremidade de serviço e criar pontos de extremidades privados, a conta do Azure Cosmos DB poderá ser acessada somente por meio dos pontos de extremidade privados. Se você não configurar um 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 definido como Desabilitado.

Bloquear o acesso à rede pública durante a criação da conta

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

Para obter um exemplo mostrando como usar esse sinalizador, confira 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, a adição de um ponto de extremidade privado a uma conta resulta em um breve tempo de inatividade de aproximadamente cinco minutos. Siga estas instruções para evitar esse tempo de inatividade:

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

Observação

Se você tiver aplicativos em execução utilizando os SDKs do Azure Cosmos DB, poderá haver tempos limite transitórios durante a atualização da configuração. Verifique se seu aplicativo foi projetado para ser resiliente a falhas transitórias de conectividade e se possui uma lógica de repetição, caso seja necessário.

Intervalo de portas ao usar o modo direto

Quando você usar um Link Privado com uma conta do Azure Cosmos DB por meio de uma conexão de modo direto, será necessário 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: Oeste dos EUA, 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 ponto de extremidade global independente da região. Posteriormente, você poderá adicionar uma nova região à conta do Azure Cosmos DB. A zona DNS privado é atualizada da seguinte maneira:

• Se o grupo de zona DNS privado for usado:

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

• Se o grupo de zona DNS privado não for usado:

  • Se você não usar um grupo de zona DNS privado, adicionar ou remover regiões para uma conta do Azure Cosmos DB exigirá que você adicione ou remova entradas DNS dessa conta. Depois que 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 os endereços IP privados correspondentes delas.

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

Limitações atuais

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

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

• Quando você usa um Link Privado com uma conta do Azure Cosmos DB por meio de uma conexão de modo direto, poderá usar apenas o protocolo TCP. No momento, não há suporte para o protocolo HTTP.

• Quando você usar a API do Azure Cosmos DB para contas do MongoDB, haverá suporte para um ponto de extremidade privado para contas no servidor de versão 3.6 ou superior (ou seja, contas que usam o ponto de extremidade no formato *.mongo.cosmos.azure.com). Não há suporte para o Link Privado em contas na versão 3.2 do servidor (ou seja, contas que usam o ponto de extremidade no formato *.documents.azure.com). Para usar o Link Privado, você deve migrar contas antigas para a nova versão.

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

• Um administrador de rede deve receber pelo menos a permissão Microsoft.DocumentDB/databaseAccounts/PrivateEndpointConnectionsApproval/action 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 rejeitada de ponto de extremidade privado. 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 para a integração da zona DNS privada

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

• Adicionar um novo ponto de extremidade privado vinculado a esta 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, poderão ocorrer problemas inesperados no plano de dados. Esses problemas incluem a interrupção de dados para regiões adicionadas após remoção do ponto de extremidade privado ou a remoção da região.

Conteúdo relacionado

• Suporte a firewall
• Configurar acesso a partir das redes virtuais
• Link Privado do Azure