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

APLICA-SE A: NoSQL MongoDB Cassandra Gremlin Tabela

Ao utilizar Azure Private Link, pode ligar a uma conta do Azure Cosmos DB através de um ponto final privado. O ponto final privado é um conjunto de endereços IP privados numa sub-rede na sua rede virtual. Em seguida, pode limitar o acesso a uma conta do Azure Cosmos DB através de endereços IP privados. Quando Private Link é combinada com políticas de NSG restritivas, ajuda a reduzir o risco de exfiltração de dados. Para saber mais sobre pontos finais privados, consulte O que é Azure Private Link?

Nota

Private Link não impede que os pontos finais do Azure Cosmos DB sejam resolvidos pelo DNS público. A filtragem de pedidos recebidos ocorre ao nível da aplicação, não ao nível do transporte ou da rede.

Private Link permite que os utilizadores acedam a uma conta do Azure Cosmos DB a partir da rede virtual ou de qualquer rede virtual em modo de peering. Os recursos mapeados para Private Link também são acessíveis no local através do peering privado através da VPN ou do Azure ExpressRoute.

Pode ligar a uma conta do Azure Cosmos DB configurada com Private Link através do método de aprovação automática ou manual. Para saber mais, veja a secção fluxo de trabalho de aprovação da documentação do Private Link.

Este artigo descreve como configurar pontos finais privados para o arquivo transacional do Azure Cosmos DB. Pressupõe que está a utilizar o método de aprovação automática. Se estiver a utilizar o arquivo analítico, veja Configurar pontos finais privados para o arquivo analítico.

Criar um ponto final privado com o portal do Azure

Siga estes passos para criar um ponto final privado para uma conta existente do Azure Cosmos DB com o portal do Azure:

1. Inicie sessão no portal do Azure e, em seguida, selecione uma conta do Azure Cosmos DB.

2. Selecione Rede na lista de definições e, em seguida, selecione + Ponto final privado no separador Acesso privado :

   

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

   Definição	Valor
   Detalhes do projeto
   Subscrição	Selecione a sua subscrição.
   Grupo de recursos	Selecione um grupo de recursos.
   Detalhes da instância
   Name	Introduza qualquer nome para o ponto final privado. Se este nome for tomado, crie um único.
   Region	Selecione a região onde pretende implementar Private Link. Crie o ponto final privado na mesma localização onde existe a sua rede virtual.

4. Selecione Seguinte: Recurso.

5. No painel Criar um ponto final privado – Recurso , introduza ou selecione estas informações:

   Definição	Valor
   Método de ligação	Selecione Ligar a um recurso do Azure no meu diretório. Em seguida, pode escolher um dos seus recursos para configurar Private Link. Em alternativa, pode ligar-se ao recurso de outra pessoa através de um ID de recurso ou alias que tenha partilhado consigo.
   Subscrição	Selecione a sua subscrição.
   Tipo de recurso	Selecione Microsoft.AzureCosmosDB/databaseAccounts.
   Recurso	Selecione a sua conta do Azure Cosmos DB.
   Sub-origem de destino	Selecione o tipo de API do Azure Cosmos DB que pretende mapear. Esta predefinição é apenas uma opção para as APIs para SQL, MongoDB e Cassandra. Para as APIs para Gremlin e Tabela, também pode escolher NoSQL porque estas APIs são interoperáveis com a API para NoSQL. Se tiver um gateway dedicado aprovisionado para uma API para conta NoSQL, também verá uma opção para SqlDedicated.

6. Selecione Seguinte: Rede Virtual.

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

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

8. Selecione Seguinte: DNS.

9. No painel Criar um ponto final privado - DNS , introduza ou selecione estas informações:

   Definição	Valor
   Integrar com zona DNS privada	Selecione Yes (Sim). Para se ligar em privado ao ponto final privado, precisa de um registo DNS. Recomendamos que integre o ponto final privado numa zona DNS privada. Também pode utilizar os seus próprios servidores DNS ou criar registos DNS com os ficheiros de anfitrião nas suas máquinas virtuais. Quando seleciona sim para esta opção, também é criado um grupo de zona DNS privado. O grupo de zona DNS é uma ligação entre a zona DNS privada e o ponto final privado. Esta ligação ajuda-o a atualizar automaticamente a zona DNS privada quando existe uma atualização para o ponto final privado. Por exemplo, quando adiciona ou remove regiões, a zona DNS privada é atualizada automaticamente.
   Nome da configuração	Selecione a sua subscrição e grupo de recursos. A zona DNS privada é determinada automaticamente. Não pode alterá-lo com o portal do Azure.

10. Selecione Seguinte: Revisão de Etiquetas>+ criar. Na página Rever + criar , o Azure valida a sua configuração.

11. Quando vir a mensagem A validação passou, selecione Criar.

Quando tiver uma Private Link aprovada para uma conta do Azure Cosmos DB, na portal do Azure, a opção Todas as redes no painel Firewall e redes virtuais não está disponível.

Tipos de API e nomes de zonas privadas

Veja a configuração do DNS do Ponto Final Privado do Azure para obter uma explicação mais detalhada sobre as zonas privadas e as configurações de DNS para o ponto final privado. A tabela seguinte mostra o mapeamento entre diferentes tipos de API de conta do Azure Cosmos DB, sub-origens suportadas e os nomes de zona privada correspondentes. Também pode aceder ao Gremlin e à API para contas de Tabela através da API para NoSQL, pelo que existem duas entradas para estas APIs. Também existe uma entrada adicional para a API para NoSQL para contas com o gateway dedicado.

Tipo de API de conta do Azure Cosmos DB	Sub-origens ou IDs de grupo suportados	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

Obter os endereços IP privados

Depois de o ponto final privado ser aprovisionado, pode consultar os endereços IP. Para ver os endereços IP da portal do Azure:

1. Procure o ponto final privado que criou anteriormente. Neste caso, é cdbPrivateEndpoint3.
2. Selecione o separador Descrição geral para ver as definições de DNS e os endereços IP.

São criados vários endereços IP por ponto final privado:

• Um para o ponto final agnóstico de região global da conta do Azure Cosmos DB.
• Uma para cada região onde a conta do Azure Cosmos DB é implementada.

Criar um ponto final privado com Azure PowerShell

Execute o seguinte script do PowerShell para criar um ponto final privado com o nome 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 final privado numa zona DNS privada

Depois de criar o ponto final privado, pode integrá-lo numa zona DNS privada com 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

Obter os endereços IP privados

Depois de o ponto final privado ser aprovisionado, pode consultar os endereços IP e o mapeamento do FQDN com 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 final privado com a CLI do Azure

Execute o seguinte script da CLI do Azure para criar um ponto final privado com o nome 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 final privado numa zona DNS privada

Depois de criar o ponto final privado, pode integrá-lo numa zona DNS privada com 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 final privado com um modelo de Resource Manager

Pode configurar Private Link ao criar um ponto final privado numa sub-rede de rede virtual. Pode fazê-lo com um modelo do Azure Resource Manager.

Utilize o seguinte código para criar um modelo de Resource Manager com o nome PrivateEndpoint_template.json. Este modelo cria um ponto final privado para uma vAPI do Azure Cosmos DB existente para uma conta NoSQL numa 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]"
        }
    }
}

Definir o ficheiro de parâmetros para o modelo

Crie um ficheiro de parâmetros para o modelo e dê-lhe o nome PrivateEndpoint_parameters.json. Adicione o seguinte código ao ficheiro 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": ""
        }
    }
}

Implementar o modelo com um script do PowerShell

Crie um script do PowerShell com o seguinte código. Antes de executar o script, substitua o ID da subscrição, 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: , , , , e TableGremlin. CassandraMongoDBSqlDedicatedSql Alguns tipos de conta do Azure Cosmos DB são acessíveis através de várias APIs. Por exemplo:

• A API para contas NoSQL tem uma opção adicional para contas configuradas para utilizar o gateway dedicado.
• A API para contas Gremlin pode ser acedida a partir do Gremlin e da API para contas NoSQL.
• A API para contas de Tabela pode ser acedida a partir da Tabela e da API para contas NoSQL.

Para essas contas, tem de criar um ponto final privado para cada tipo de API. Se estiver a criar um ponto final privado para SqlDedicatedo , só terá de adicionar um segundo ponto final para Sql o caso de também pretender ligar à sua conta através do gateway padrão. O tipo de API correspondente é especificado na GroupId matriz.

Depois de o modelo ser implementado com êxito, pode ver um resultado semelhante ao que a imagem seguinte mostra. O provisioningState valor é Succeeded se os pontos finais privados estiverem configurados corretamente.

Após a implementação do modelo, os endereços IP privados são reservados na sub-rede. A regra de firewall da conta do Azure Cosmos DB está configurada para aceitar apenas ligações do ponto final privado.

Integrar o ponto final privado numa zona DNS privada

Utilize o seguinte código para criar um modelo de Resource Manager com o nome PrivateZone_template.json. Este modelo cria uma zona DNS privada para uma API do Azure Cosmos DB existente para uma conta NoSQL numa 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 ficheiro de parâmetros para o modelo

Crie o seguinte ficheiro 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": ""
        }
    }
}

Utilize o seguinte código para criar um modelo de Resource Manager com o nome PrivateZoneGroup_template.json. Este modelo cria um grupo de zona DNS privado para uma API do Azure Cosmos DB existente para uma conta NoSQL numa 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 ficheiro de parâmetros para o modelo

Crie o seguinte ficheiro 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": ""
        }
    }
}

Implementar o modelo com um script do PowerShell

Crie um script do PowerShell com o seguinte código. Antes de executar o script, substitua o ID da subscrição, 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

Deve utilizar uma zona DNS privada na sub-rede onde criou o ponto final privado. Configure os pontos finais para que cada endereço IP privado seja mapeado para uma entrada DNS. Veja a propriedade fqdns na resposta mostrada anteriormente.

Quando estiver a criar o ponto final privado, pode integrá-lo numa zona DNS privada no Azure. Se optar por utilizar uma zona DNS personalizada, terá de a configurar para adicionar registos DNS para todos os endereços IP privados reservados para o ponto final privado.

Importante

É a resolução DNS dos seus pedidos que determina se estes pedidos passam por cima dos pontos finais privados ou se seguem a rota pública padrão. Certifique-se de que o DNS local referencia corretamente o IP privado mapeado pelo ponto final privado.

Private Link combinado com regras da firewall

As seguintes situações e resultados são possíveis quando utiliza Private Link em combinação com as regras da firewall:

• Se não configurar nenhuma regra de firewall, por predefinição, todo o tráfego pode aceder a uma conta do Azure Cosmos DB.

• Se configurar o tráfego público ou um ponto final de serviço e criar pontos finais privados, os diferentes tipos de tráfego de entrada são autorizados pelo tipo de regra de firewall correspondente. Se um ponto final privado estiver configurado numa sub-rede onde o ponto final de serviço também está configurado:

  • o tráfego para a conta de base de dados mapeada pelo ponto final privado é encaminhado através do ponto final privado,
  • o tráfego para outras contas de base de dados da sub-rede é encaminhado através do ponto final de serviço.

• Se não configurar nenhum ponto final de serviço ou tráfego público e criar pontos finais privados, a conta do Azure Cosmos DB só estará acessível através dos pontos finais privados. Se não configurar o tráfego público ou um ponto final de serviço, depois de todos os pontos finais privados aprovados serem rejeitados ou eliminados, a conta estará aberta a toda a rede, a menos que PublicNetworkAccess esteja definida como Desativada.

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

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

Para obter um exemplo que mostra como utilizar este sinalizador, veja este modelo do Azure Resource Manager.

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

Por predefinição, adicionar um ponto final privado a uma conta existente resulta num curto período de indisponibilidade de aproximadamente cinco minutos. Siga estas instruções para evitar este período de indisponibilidade:

1. Adicione regras de IP ou de rede virtual à configuração da firewall para permitir explicitamente as ligações do cliente.
2. Aguarde 10 minutos para garantir que a atualização de configuração é aplicada.
3. Configure o novo ponto final privado.
4. Remova as regras de firewall definidas no passo 1.

Nota

Se tiver aplicações em execução com os SDKs do Azure Cosmos DB, poderão existir tempos limite transitórios durante a atualização de configuração. Certifique-se de que a aplicação foi concebida para ser resiliente a falhas de conectividade transitórias e que tem a lógica de repetição implementada no caso de ser necessária.

Intervalo de portas ao utilizar o modo direto

Quando utiliza Private Link com uma conta do Azure Cosmos DB através de uma ligação de modo direto, tem de garantir que o intervalo completo de portas TCP (0 - 65535) está aberto.

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

Existem três regiões para implementações de contas do Azure Cosmos DB: E.U.A. Oeste, E.U.A. Central e Europa Ocidental. Quando cria um ponto final privado para a sua conta, são reservados quatro IPs privados na sub-rede. Existe um IP para cada uma das três regiões e existe um IP para o ponto final agnóstico da região global. Mais tarde, poderá adicionar uma nova região à conta do Azure Cosmos DB. A zona DNS privado é atualizada da seguinte forma:

• Se for utilizado um grupo de zona DNS privado:

  Se utilizar um grupo de zona DNS privado, a zona DNS privada é atualizada automaticamente quando o ponto final privado é atualizado. No exemplo anterior, depois de adicionar uma nova região, a zona DNS privada é atualizada automaticamente.

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

  Se não utilizar um grupo de zona DNS privado, adicionar ou remover regiões numa conta do Azure Cosmos DB requer que adicione ou remova entradas DNS para essa conta. Depois de as regiões terem sido adicionadas ou removidas, pode atualizar a zona DNS privada da sub-rede para refletir as entradas DNS adicionadas ou removidas e os endereços IP privados correspondentes.

  No exemplo anterior, depois de adicionar a nova região, tem de adicionar um registo DNS correspondente à zona DNS privada ou ao DNS personalizado. Pode utilizar os mesmos passos quando remove uma região. Depois de remover a região, tem de remover o registo DNS correspondente da zona DNS privada ou do DNS personalizado.

Limitações atuais

As seguintes limitações aplicam-se quando utiliza Private Link com uma conta do Azure Cosmos DB:

• Não pode ter mais de 200 pontos finais privados numa única conta do Azure Cosmos DB.

• Quando utiliza Private Link com uma conta do Azure Cosmos DB através de uma ligação de modo direto, só pode utilizar o protocolo TCP. O protocolo HTTP não é atualmente suportado.

• Quando utiliza a API do Azure Cosmos DB para uma conta do MongoDB, é suportado um ponto final privado para contas na versão 3.6 ou superior do servidor (ou seja, contas que utilizam o ponto final no formato *.mongo.cosmos.azure.com). Private Link não é suportado para contas na versão 3.2 do servidor (ou seja, contas que utilizam o ponto final no formato *.documents.azure.com). Para utilizar Private Link, deve migrar contas antigas para a nova versão.

• Quando utiliza a API do Azure Cosmos DB para uma conta do MongoDB que tem uma Private Link, as ferramentas e bibliotecas têm de suportar a Identificação de Nomes de Serviço (SNI) ou transmitir o appName parâmetro da cadeia de ligação para ligar corretamente. Algumas ferramentas e bibliotecas mais antigas podem não ser compatíveis com a funcionalidade Private Link.

• Deve ser concedida a um administrador de rede, pelo menos, a Microsoft.DocumentDB/databaseAccounts/PrivateEndpointConnectionsApproval/action permissão no âmbito da conta do Azure Cosmos DB para criar pontos finais privados aprovados automaticamente.

• Atualmente, não pode aprovar uma ligação de ponto final privado rejeitada. Em vez disso, recrie o ponto final privado para retomar a conectividade privada. O serviço de ligação privada do Azure Cosmos DB aprova automaticamente o ponto final privado recriado.

Limitações à integração da zona DNS privada

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

• Adicionar um novo ponto final privado ligado a esta zona DNS privada.
• Adicionar uma nova região a qualquer conta de base de dados que tenha pontos finais privados ligados a esta zona DNS privada.

Se não limpar os registos DNS, poderão ocorrer problemas inesperados no plano de dados. Estes problemas incluem a indisponibilidade de dados para regiões adicionadas após a remoção do ponto final privado ou a remoção da região.

Passos seguintes

Para saber mais sobre as funcionalidades de segurança do Azure Cosmos DB, veja os seguintes artigos:

• Para configurar uma firewall para o Azure Cosmos DB, veja Suporte da firewall.

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

• Para saber mais sobre Private Link, veja a documentação do Azure Private Link.