配置从虚拟网络 (VNet) 访问Configure access from virtual networks (VNet)

可将 Azure Cosmos DB 帐户配置为仅允许从 Azure 虚拟网络的特定子网进行访问。You can configure Azure Cosmos DB accounts to allow access from only a specific subnet of an Azure virtual network. 限制使用虚拟网络中子网的连接对 Azure Cosmos DB 帐户的访问:To limit access to an Azure Cosmos DB account with connections from a subnet in a virtual network:

  1. 让该子网将其标识和虚拟网络标识发送到 Azure Cosmos DB。Enable the subnet to send the subnet and virtual network identity to Azure Cosmos DB. 在特定的子网中为 Azure Cosmos DB 启用服务终结点可实现此目的。You can achieve this by enabling a service endpoint for Azure Cosmos DB on the specific subnet.

  2. 在 Azure Cosmos DB 帐户中添加一个规则,以便将此子网指定为可从中访问帐户的源。Add a rule in the Azure Cosmos DB account to specify the subnet as a source from which the account can be accessed.

备注

在子网中为 Azure Cosmos DB 帐户启用服务终结点之后,抵达 Azure Cosmos DB 的流量的源将从公共 IP 切换到虚拟网络和子网。When a service endpoint for your Azure Cosmos DB account is enabled on a subnet, the source of the traffic that reaches Azure Cosmos DB switches from a public IP to a virtual network and subnet. 流量切换适用于从此子网访问的任何 Azure Cosmos DB 帐户。The traffic switching applies for any Azure Cosmos DB account that's accessed from this subnet. 如果 Azure Cosmos DB 帐户包含允许此子网的基于 IP 的防火墙,则已启用服务的子网发出的请求将不再与 IP 防火墙规则相匹配,因此会遭到拒绝。If your Azure Cosmos DB accounts have an IP-based firewall to allow this subnet, requests from the service-enabled subnet no longer match the IP firewall rules, and they're rejected.

有关详细信息,请参阅本文的从 IP 防火墙规则迁移到虚拟网络访问控制列表部分所述的步骤。To learn more, see the steps outlined in the Migrating from an IP firewall rule to a virtual network access control list section of this article.

以下部分介绍如何为 Azure Cosmos DB 帐户配置虚拟网络服务终结点。The following sections describe how to configure a virtual network service endpoint for an Azure Cosmos DB account.

备注

本文进行了更新,以便使用新的 Azure PowerShell Az 模块。This article has been updated to use the new Azure PowerShell Az module. 你仍然可以使用 AzureRM 模块,至少在 2020 年 12 月之前,它将继续接收 bug 修补程序。You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. 若要详细了解新的 Az 模块和 AzureRM 兼容性,请参阅新 Azure Powershell Az 模块简介To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. 有关 Az 模块安装说明,请参阅安装 Azure PowerShellFor Az module installation instructions, see Install Azure PowerShell.

使用 Azure 门户配置服务终结点Configure a service endpoint by using the Azure portal

为现有的 Azure 虚拟网络和子网配置服务终结点Configure a service endpoint for an existing Azure virtual network and subnet

  1. 在“所有资源”边栏选项卡中,找到想要保护的 Azure Cosmos DB 帐户。From the All resources blade, find the Azure Cosmos DB account that you want to secure.

  2. 从设置菜单中选择“防火墙和虚拟网络”,然后选择允许从“选定的网络”进行访问。 Select Firewalls and virtual networks from the settings menu, and choose to allow access from Selected networks.

  3. 若要授予对现有虚拟网络子网的访问权限,请在“虚拟网络”下面选择“添加现有的 Azure 虚拟网络”。 To grant access to an existing virtual network's subnet, under Virtual networks, select Add existing Azure virtual network.

  4. 选择要从中添加 Azure 虚拟网络的订阅Select the Subscription from which you want to add an Azure virtual network. 选择要向其提供 Azure Cosmos DB 帐户访问权限的 Azure 虚拟网络子网Select the Azure Virtual networks and Subnets that you want to provide access to your Azure Cosmos DB account. 接下来选择“启用”,以便为“Microsoft.AzureCosmosDB”启用包含服务终结点的选定网络。Next, select Enable to enable selected networks with service endpoints for "Microsoft.AzureCosmosDB". 完成后,选择“添加”。When it's complete, select Add.

    选择虚拟网络和子网

  5. 允许从虚拟网络访问 Azure Cosmos DB 帐户之后,只允许来自此所选子网的流量。After the Azure Cosmos DB account is enabled for access from a virtual network, it will allow traffic from only this chosen subnet. 添加的虚拟网络和子网应会显示,如以下屏幕截图所示:The virtual network and subnet that you added should appear as shown in the following screenshot:

    已成功配置虚拟网络和子网

备注

若要启用虚拟网络服务终结点,需要以下订阅权限:To enable virtual network service endpoints, you need the following subscription permissions:

  • 使用虚拟网络的订阅:网络参与者Subscription with virtual network: Network contributor
  • 使用 Azure Cosmos DB 帐户的订阅:DocumentDB 帐户参与者Subscription with Azure Cosmos DB account: DocumentDB account contributor
  • 如果虚拟网络与 Azure Cosmos DB 帐户位于不同的订阅中,请确保包含虚拟网络的订阅还注册了 Microsoft.DocumentDB 资源提供程序。If your virtual network and Azure Cosmos DB account are in different subscriptions, make sure that the subscription that has virtual network also has Microsoft.DocumentDB resource provider registered. 若要注册资源提供程序,请参阅 Azure 资源提供程序和类型一文。To register a resource provider, see Azure resource providers and types article.

以下是向资源提供程序注册订阅的说明。Here are the directions for registering subscription with resource provider.

为新的 Azure 虚拟网络和子网配置服务终结点Configure a service endpoint for a new Azure virtual network and subnet

  1. 在“所有资源”边栏选项卡中,找到想要保护的 Azure Cosmos DB 帐户。From the All resources blade, find the Azure Cosmos DB account that you want to secure.

  2. 从设置菜单中选择“防火墙和 Azure 虚拟网络”,然后选择允许从“选定的网络”进行访问。 Select Firewalls and Azure virtual networks from the settings menu, and choose to allow access from Selected networks.

  3. 若要授予对新 Azure 虚拟网络的访问权限,请在“虚拟网络”下面选择“添加新虚拟网络”。 To grant access to a new Azure virtual network, under Virtual networks, select Add new virtual network.

  4. 提供创建新虚拟网络所需的详细信息,然后选择“创建”。Provide the details required to create a new virtual network, and then select Create. 随后将为启用的“Microsoft.AzureCosmosDB”创建包含服务终结点的子网。The subnet will be created with a service endpoint for "Microsoft.AzureCosmosDB" enabled.

    为新虚拟网络选择虚拟网络和子网

如果 Azure Cosmos DB 帐户由其他 Azure 服务(例如 Azure 认知搜索)使用,或者从流分析或 Power BI 进行访问,请选择“接受来自多区域 Azure 数据中心内部的连接”来允许这种访问。If your Azure Cosmos DB account is used by other Azure services like Azure Cognitive Search, or is accessed from Stream analytics or Power BI, you allow access by selecting Accept connections from within multiple-regional Azure datacenters.

为确保能够从门户访问 Azure Cosmos DB 指标,需要启用“允许从 Azure 门户访问”选项。To ensure that you have access to Azure Cosmos DB metrics from the portal, you need to enable Allow access from Azure portal options. 有关这些选项的详细信息,请参阅配置 IP 防火墙一文。To learn more about these options, see the Configure an IP firewall article. 启用访问后,选择“保存”以保存设置。After you enable access, select Save to save the settings.

删除虚拟网络或子网Remove a virtual network or subnet

  1. 在“所有资源”边栏选项卡中,找到为其分配了服务终结点的 Azure Cosmos DB 帐户。From the All resources blade, find the Azure Cosmos DB account for which you assigned service endpoints.

  2. 从设置菜单中选择“防火墙和虚拟网络”。Select Firewalls and virtual networks from the settings menu.

  3. 若要删除某个虚拟网络或子网规则,请选择虚拟网络或子网旁边的“...”,然后选择“删除”。 To remove a virtual network or subnet rule, select ... next to the virtual network or subnet, and select Remove.

    删除虚拟网络

  4. 单击“保存”应用所做的更改。Select Save to apply your changes.

使用 Azure PowerShell 配置服务终结点Configure a service endpoint by using Azure PowerShell

备注

使用 PowerShell 或 Azure CLI 时,请务必在参数中指定 IP 筛选器和虚拟网络 ACL 的完整列表,而不仅仅是需要添加的项。When you're using PowerShell or the Azure CLI, be sure to specify the complete list of IP filters and virtual network ACLs in parameters, not just the ones that need to be added.

在 Azure PowerShell 中使用以下步骤配置 Azure Cosmos DB 帐户的服务终结点:Use the following steps to configure a service endpoint to an Azure Cosmos DB account by using Azure PowerShell:

  1. 安装 Azure PowerShell登录Install Azure PowerShell and sign in.

  2. 为虚拟网络的现有子网启用服务终结点。Enable the service endpoint for an existing subnet of a virtual network.

    $resourceGroupName = "<Resource group name>"
    $vnetName = "<Virtual network name>"
    $subnetName = "<Subnet name>"
    $subnetPrefix = "<Subnet address range>"
    $serviceEndpoint = "Microsoft.AzureCosmosDB"
    
    Get-AzVirtualNetwork `
      -ResourceGroupName $resourceGroupName `
      -Name $vnetName | Set-AzVirtualNetworkSubnetConfig `
      -Name $subnetName `
      -AddressPrefix $subnetPrefix `
      -ServiceEndpoint $serviceEndpoint | Set-AzVirtualNetwork
    
  3. 获取虚拟网络信息。Get virtual network information.

    $vnet = Get-AzVirtualNetwork `
      -ResourceGroupName $resourceGroupName `
      -Name $vnetName
    
    $subnetId = $vnet.Id + "/subnets/" + $subnetName
    
  4. 准备 Cosmos DB 虚拟网络规则Prepare a Cosmos DB Virtual Network Rule

    $vnetRule = New-AzCosmosDBVirtualNetworkRule `
      -Id $subnetId
    
  5. 使用新的虚拟网络终结点配置更新 Azure Cosmos DB 帐户属性:Update Azure Cosmos DB account properties with the new Virtual Network endpoint configuration:

    $accountName = "<Cosmos DB account name>"
    
    Update-AzCosmosDBAccount `
      -ResourceGroupName $resourceGroupName `
      -Name $accountName `
      -EnableVirtualNetwork $true `
      -VirtualNetworkRuleObject @($vnetRule)
    
  6. 运行以下命令,验证是否已使用上一步骤中配置的虚拟网络服务终结点更新 Azure Cosmos DB 帐户:Run the following command to verify that your Azure Cosmos DB account is updated with the virtual network service endpoint that you configured in the previous step:

    $account = Get-AzCosmosDBAccount `
      -ResourceGroupName $resourceGroupName `
      -Name $accountName
    
    $account.IsVirtualNetworkFilterEnabled
    $account.VirtualNetworkRules
    

使用 Azure CLI 配置服务终结点Configure a service endpoint by using the Azure CLI

Azure Cosmos 帐户可以在以后创建或更新服务终结点时针对服务终结点进行配置(如果已经为其配置了子网)。Azure Cosmos accounts can be configured for service endpoints when they are created or updated at a later time if the subnet is already configured for them. 还可以在尚未为其配置子网的 Cosmos 帐户上启用服务终结点,然后这些服务终结点在以后配置子网时开始工作。Service endpoints can also be enabled on the Cosmos account where the subnet is not yet configured for them and then will begin to work when the subnet is configured later. 这种灵活性允许无法同时访问 Cosmos 帐户和虚拟网络资源的管理员将其配置设为彼此独立。This flexibility allows for administrators who do not have access to both the Cosmos account and virtual network resources to make their configurations independent of each other.

创建新的 Cosmos 帐户并将其连接到新虚拟网络的后端子网Create a new Cosmos account and connect it to a back end subnet for a new virtual network

在此示例中,创建虚拟网络和子网时会同时为它们启用服务终结点。In this example the virtual network and subnet is created with service endpoints enabled for both when they are created.

# Create an Azure Cosmos Account with a service endpoint connected to a backend subnet

# Resource group and Cosmos account variables
resourceGroupName='MyResourceGroup'
location='China North 2'
accountName='mycosmosaccount'

# Variables for a new Virtual Network with two subnets
vnetName='myVnet'
frontEnd='FrontEnd'
backEnd='BackEnd'

# Create a resource group
az group create -n $resourceGroupName -l $location

# Create a virtual network with a front-end subnet
az network vnet create \
   -n $vnetName \
   -g $resourceGroupName \
   --address-prefix 10.0.0.0/16 \
   --subnet-name $frontEnd \
   --subnet-prefix 10.0.1.0/24

# Create a back-end subnet with service endpoints enabled for Cosmos DB
az network vnet subnet create \
   -n $backEnd \
   -g $resourceGroupName \
   --address-prefix 10.0.2.0/24 \
   --vnet-name $vnetName \
   --service-endpoints Microsoft.AzureCosmosDB

svcEndpoint=$(az network vnet subnet show -g $resourceGroupName -n $backEnd --vnet-name $vnetName --query 'id' -o tsv)

# Create a Cosmos DB account with default values and service endpoints
az cosmosdb create \
   -n $accountName \
   -g $resourceGroupName \
   --enable-virtual-network true \
   --virtual-network-rules $svcEndpoint

将 Cosmos 帐户独立连接并配置到后端子网Connect and configure a Cosmos account to a back end subnet independently

此示例旨在说明如何将 Azure Cosmos 帐户连接到尚未为服务终结点配置子网的现有新虚拟网络。This sample is intended to show how to connect an Azure Cosmos account to an existing new virtual network where the subnet is not yet configured for service endpoints. 这是通过使用 --ignore-missing-vnet-service-endpoint 参数完成的。This is done by using the --ignore-missing-vnet-service-endpoint parameter. 这样就可以在完成对虚拟网络的子网的配置之前,完成 Cosmos 帐户的配置而不会出现错误。This allows the configuration for the Cosmos account to complete without error before the configuration to the virtual network's subnet is complete. 子网配置完成后,便可通过配置的子网访问 Cosmos 帐户。Once the subnet configuration is complete, the Cosmos account will then be accessible through the configured subnet.

# Create an Azure Cosmos Account with a service endpoint connected to a backend subnet
# that is not yet enabled for service endpoints.

# Resource group and Cosmos account variables
resourceGroupName='MyResourceGroup'
location='China North 2'
accountName='mycosmosaccount'

# Variables for a new Virtual Network with two subnets
vnetName='myVnet'
frontEnd='FrontEnd'
backEnd='BackEnd'

# Create a resource group
az group create -n $resourceGroupName -l $location

# Create a virtual network with a front-end subnet
az network vnet create \
   -n $vnetName \
   -g $resourceGroupName \
   --address-prefix 10.0.0.0/16 \
   --subnet-name $frontEnd \
   --subnet-prefix 10.0.1.0/24

# Create a back-end subnet but without configuring service endpoints (--service-endpoints Microsoft.AzureCosmosDB)
az network vnet subnet create \
   -n $backEnd \
   -g $resourceGroupName \
   --address-prefix 10.0.2.0/24 \
   --vnet-name $vnetName

svcEndpoint=$(az network vnet subnet show -g $resourceGroupName -n $backEnd --vnet-name $vnetName --query 'id' -o tsv)

# Create a Cosmos DB account with default values
az cosmosdb create -n $accountName -g $resourceGroupName

# Add the virtual network rule but ignore the missing service endpoint on the subnet
az cosmosdb network-rule add \
   -n $accountName \
   -g $resourceGroupName \
   --virtual-network $vnetName \
   --subnet svcEndpoint \
   --ignore-missing-vnet-service-endpoint true

read -p'Press any key to now configure the subnet for service endpoints'

az network vnet subnet update \
   -n $backEnd \
   -g $resourceGroupName \
   --vnet-name $vnetName \
   --service-endpoints Microsoft.AzureCosmosDB

使用直接模式时的端口范围Port range when using direct mode

通过直接模式连接结合使用服务终结点和 Azure Cosmos 帐户时,需要确保启用的 TCP 端口范围为 10000 到 20000。When you're using service endpoints with an Azure Cosmos account through a direct mode connection, you need to ensure that the TCP port range from 10000 to 20000 is open.

从 IP 防火墙规则迁移到虚拟网络 ACLMigrating from an IP firewall rule to a virtual network ACL

若要将 Azure Cosmos DB 帐户从使用 IP 防火墙规则转换为使用虚拟网络服务终结点,请使用以下步骤。To migrate an Azure Cosmos DB account from using IP firewall rules to using virtual network service endpoints, use the following steps.

为子网的服务终结点配置 Azure Cosmos DB 帐户后,来自该子网的请求将使用虚拟网络和子网源信息(而不是源公共 IP 地址)发送到 Azure Cosmos DB。After an Azure Cosmos DB account is configured for a service endpoint for a subnet, requests from that subnet are sent to Azure Cosmos DB with virtual network and subnet source information instead of a source public IP address. 这些请求将不再匹配 Azure Cosmos DB 帐户上配置的 IP 筛选器,所以需要执行以下步骤以避免停机。These requests will no longer match an IP filter configured on the Azure Cosmos DB account, which is why the following steps are necessary to avoid downtime.

继续之前,请使用上面“为虚拟网络的现有子网启用服务终结点”中显示的步骤在虚拟网络和子网上启用 Azure Cosmos DB 服务终结点。Before proceeding, enable the Azure Cosmos DB service endpoint on the virtual network and subnet using the step shown above in "Enable the service endpoint for an existing subnet of a virtual network".

  1. 获取虚拟网络和子网信息:Get virtual network and subnet information:

    $resourceGroupName = "myResourceGroup"
    $accountName = "mycosmosaccount"
    $vnetName = "myVnet"
    $subnetName = "mySubnet"
    
    $vnet = Get-AzVirtualNetwork `
      -ResourceGroupName $resourceGroupName `
      -Name $vnetName
    
    $subnetId = $vnet.Id + "/subnets/" + $subnetName
    
  2. 为 Azure Cosmos DB 帐户准备新的虚拟网络规则对象:Prepare a new Virtual Network rule object for the Azure Cosmos DB account:

    $vnetRule = New-AzCosmosDBVirtualNetworkRule `
      -Id $subnetId
    
  3. 更新 Azure Cosmos DB 帐户以实现从子网访问服务终结点:Update the Azure Cosmos DB account to enable service endpoint access from the subnet:

    Update-AzCosmosDBAccount `
      -ResourceGroupName $resourceGroupName `
      -Name $accountName `
      -EnableVirtualNetwork $true `
      -VirtualNetworkRuleObject @($vnetRule)
    
  4. 对从子网访问的所有 Azure Cosmos DB 帐户重复前面的步骤。Repeat the previous steps for all Azure Cosmos DB accounts accessed from the subnet.

  5. 从 Azure Cosmos DB 帐户的防火墙规则中删除子网的 IP 防火墙规则。Remove the IP firewall rule for the subnet from the Azure Cosmos DB account's Firewall rules.

后续步骤Next steps

  • 若要为 Azure Cosmos DB 配置防火墙,请参阅防火墙支持一文。To configure a firewall for Azure Cosmos DB, see the Firewall support article.