配置从虚拟网络 (VNet) 到 Azure Cosmos DB 的访问

项目
11/27/2023

适用对象： NoSQL MongoDB Cassandra Gremlin 表

可将 Azure Cosmos DB 帐户配置为仅允许从虚拟网络 (VNET) 的特定子网进行访问。在虚拟网络中的子网上启用服务终结点，以控制对 Azure Cosmos DB 的访问。来自该子网的流量将发送到具有该子网和虚拟网络的标识的 Azure Cosmos DB。启用 Azure Cosmos DB 服务终结点后，可以通过将子网添加到 Azure Cosmos DB 帐户来限制对该子网的访问。

默认情况下，如果请求附带有效的授权令牌，则可从任何源访问 Azure Cosmos DB 帐户。在 VNet 中添加一个或多个子网后，只有源自这些子网的请求才能获取有效响应。源自其他任何源的请求将收到 403（禁止访问）响应。

可将 Azure Cosmos DB 帐户配置为仅允许从 Azure 虚拟网络的特定子网进行访问。限制使用虚拟网络中子网的连接对 Azure Cosmos DB 帐户的访问：

使 Azure Cosmos DB 的服务终结点能够将子网和虚拟网络标识发送到 Azure Cosmos DB。
在 Azure Cosmos DB 帐户中添加一个规则，以便将此子网指定为可从中访问帐户的源。

注意

在子网中为 Azure Cosmos DB 帐户启用服务终结点之后，抵达 Azure Cosmos DB 的流量的源将从公共 IP 切换到虚拟网络和子网。流量切换适用于从此子网访问的任何 Azure Cosmos DB 帐户。如果 Azure Cosmos DB 帐户包含允许此子网的基于 IP 的防火墙，则已启用服务的子网发出的请求将不再与 IP 防火墙规则相匹配，因此会遭到拒绝。

有关详细信息，请参阅本文的从 IP 防火墙规则迁移到虚拟网络访问控制列表部分所述的步骤。

以下部分介绍如何为 Azure Cosmos DB 帐户配置虚拟网络服务终结点。

使用 Azure 门户配置服务终结点

为现有的 Azure 虚拟网络和子网配置服务终结点

在“所有资源”窗格中，找到想要保护的 Azure Cosmos DB 帐户。
从设置菜单中选择“网络”
选择允许从“所选网络”进行访问。
若要授予对现有虚拟网络子网的访问权限，请在“虚拟网络”下面选择“添加现有的 Azure 虚拟网络”。
选择要从中添加 Azure 虚拟网络的订阅。选择要向其提供 Azure Cosmos DB 帐户访问权限的 Azure 虚拟网络和子网。接下来选择“启用”，以便为“Microsoft.AzureCosmosDB”启用包含服务终结点的选定网络。完成后，选择“添加”。

注意

配置 VNET 服务终结点可能需要长达 15 分钟的时间来传播，终结点在此期间可能会表现出不一致的行为。
允许从虚拟网络访问 Azure Cosmos DB 帐户之后，只允许来自此所选子网的流量。添加的虚拟网络和子网应会显示，如以下屏幕截图所示：

注意

若要启用虚拟网络服务终结点，需要以下订阅权限：

使用虚拟网络的订阅：网络参与者
使用 Azure Cosmos DB 帐户的订阅：DocumentDB 帐户参与者
如果虚拟网络与 Azure Cosmos DB 帐户位于不同的订阅中，请确保包含虚拟网络的订阅还注册了 Microsoft.DocumentDB 资源提供程序。若要注册资源提供程序，请参阅 Azure 资源提供程序和类型一文。

以下是向资源提供程序注册订阅的说明。

为新的 Azure 虚拟网络和子网配置服务终结点

在“所有资源”窗格中，找到想要保护的 Azure Cosmos DB 帐户。
从设置菜单中选择“网络”，然后选择允许从“所选网络”进行访问。
若要授予对新 Azure 虚拟网络的访问权限，请在“虚拟网络”下面选择“添加新虚拟网络”。
提供创建新虚拟网络所需的详细信息，然后选择“创建”。随后将为启用的“Microsoft.AzureCosmosDB”创建包含服务终结点的子网。

如果 Azure Cosmos DB 帐户由其他 Azure 服务（例如 Azure AI 搜索）使用，或者从流分析或 Power BI 进行访问，请选择“接受来自多区域 Azure 数据中心内部的连接”来允许这种访问。

为确保能够从门户访问 Azure Cosmos DB 指标，需要启用“允许从 Azure 门户访问”选项。有关这些选项的详细信息，请参阅配置 IP 防火墙一文。启用访问后，选择“保存”以保存设置。

删除虚拟网络或子网

在“所有资源”窗格中，找到为其分配了服务终结点的 Azure Cosmos DB 帐户。
从设置菜单中选择“网络”。
若要删除某个虚拟网络或子网规则，请选择虚拟网络或子网旁边的“...”，然后选择“删除”。
单击“保存”应用所做的更改。

使用 Azure PowerShell 配置服务终结点

注意

建议使用 Azure Az PowerShell 模块与 Azure 交互。请参阅安装 Azure PowerShell 以开始使用。若要了解如何迁移到 Az PowerShell 模块，请参阅将 Azure PowerShell 从 AzureRM 迁移到 Az。

在 Azure PowerShell 中使用以下步骤配置 Azure Cosmos DB 帐户的服务终结点：

安装 Azure PowerShell 并登录。

为虚拟网络的现有子网启用服务终结点。

$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

注意

使用 PowerShell 或 Azure CLI 时，请务必在参数中指定 IP 筛选器和虚拟网络 ACL 的完整列表，而不仅仅是需要添加的项。

获取虚拟网络信息。

$vnet = Get-AzVirtualNetwork `
   -ResourceGroupName $resourceGroupName `
   -Name $vnetName

$subnetId = $vnet.Id + "/subnets/" + $subnetName

准备 Azure Cosmos DB 虚拟网络规则

$vnetRule = New-AzCosmosDBVirtualNetworkRule `
   -Id $subnetId

使用新的虚拟网络终结点配置更新 Azure Cosmos DB 帐户属性：

$accountName = "<Azure Cosmos DB account name>"

Update-AzCosmosDBAccount `
   -ResourceGroupName $resourceGroupName `
   -Name $accountName `
   -EnableVirtualNetwork $true `
   -VirtualNetworkRuleObject @($vnetRule)

运行以下命令，验证是否已使用上一步骤中配置的虚拟网络服务终结点更新 Azure Cosmos DB 帐户：

$account = Get-AzCosmosDBAccount `
   -ResourceGroupName $resourceGroupName `
   -Name $accountName

$account.IsVirtualNetworkFilterEnabled
$account.VirtualNetworkRules

使用 Azure CLI 配置服务终结点

Azure Cosmos DB 帐户可以在以后创建或更新服务终结点时针对服务终结点进行配置（如果已经为其配置了子网）。还可以在尚未配置子网的 Azure Cosmos DB 帐户上启用服务终结点。服务终结点就会在以后配置子网时开始工作。这种灵活性使无法同时访问 Azure Cosmos DB 帐户和虚拟网络资源的管理员可以将其配置设为彼此独立。

创建新的 Azure Cosmos DB 帐户并将其连接到新虚拟网络的后端子网

在此示例中，创建虚拟网络和子网时会同时为它们启用服务终结点。

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

# Resource group and Azure Cosmos DB 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 Azure 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 an Azure Cosmos DB account with default values and service endpoints
az cosmosdb create \
   -n $accountName \
   -g $resourceGroupName \
   --enable-virtual-network true \
   --virtual-network-rules $svcEndpoint

将 Azure Cosmos DB 帐户独立连接并配置到后端子网

此示例旨在说明如何将 Azure Cosmos DB 帐户连接到现有的或新的虚拟网络。在此示例中，尚未为服务终结点配置子网。使用 --ignore-missing-vnet-service-endpoint 参数配置服务终结点。使用此配置，就可以在完成对虚拟网络的子网的配置之前完成 Azure Cosmos DB 帐户而不会出现错误。子网配置完成后，便可通过配置的子网访问 Azure Cosmos DB 帐户。

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

# Resource group and Azure Cosmos DB 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 an Azure 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

使用直接模式时的端口范围

通过直接模式连接结合使用服务终结点和 Azure Cosmos DB 帐户时，需要确保启用的 TCP 端口范围为 10000 到 20000。

从 IP 防火墙规则迁移到虚拟网络 ACL

若要将 Azure Cosmos DB 帐户从使用 IP 防火墙规则转换为使用虚拟网络服务终结点，请使用以下步骤。

为子网的服务终结点配置 Azure Cosmos DB 帐户后，来自该子网的每个请求将以不同方式发送到 Azure Cosmos DB。这些请求通过虚拟网络和子网源信息而非源公共 IP 地址进行发送。这些请求将不再匹配 Azure Cosmos DB 帐户上配置的 IP 筛选器，所以需要执行以下步骤以避免停机。

获取虚拟网络和子网信息：

$resourceGroupName = "myResourceGroup"
$accountName = "mycosmosaccount"
$vnetName = "myVnet"
$subnetName = "mySubnet"

$vnet = Get-AzVirtualNetwork `
   -ResourceGroupName $resourceGroupName `
   -Name $vnetName

$subnetId = $vnet.Id + "/subnets/" + $subnetName

为 Azure Cosmos DB 帐户准备新的虚拟网络规则对象：

$vnetRule = New-AzCosmosDBVirtualNetworkRule `
   -Id $subnetId

更新 Azure Cosmos DB 帐户以实现从子网访问服务终结点：

Update-AzCosmosDBAccount `
   -ResourceGroupName $resourceGroupName `
   -Name $accountName `
   -EnableVirtualNetwork $true `
   -VirtualNetworkRuleObject @($vnetRule)

对从子网访问的所有 Azure Cosmos DB 帐户重复前面的步骤。
使用本文的为虚拟网络的现有子网启用服务终结点部分显示的步骤在虚拟网络和子网上启用 Azure Cosmos DB 服务终结点。
从 Azure Cosmos DB 帐户的防火墙规则中删除子网的 IP 防火墙规则。

常见问题

下面是有关配置从虚拟网络进行访问的一些常见问题：

Notebooks 和 Mongo/Cassandra Shell 目前是否与已启用虚拟网络的帐户兼容？

目前，不支持通过 VNET 访问 Azure Cosmos DB 数据资源管理器中的 Mongo shell 和 Cassandra shell 集成。此集成目前正在积极开发中。

是否可以在 Azure Cosmos DB 帐户中同时指定虚拟网络服务终结点和 IP 访问控制策略？

可以在 Azure Cosmos DB 帐户中同时启用虚拟网络服务终结点和 IP 访问控制策略（也称为防火墙）。这两个功能是互补的，共同确保 Azure Cosmos DB 帐户的隔离性和安全性。使用 IP 防火墙可确保静态 IP 能够访问你的帐户。

如何限制对虚拟网络中子网的访问？

需要执行两个步骤来限制从子网对 Azure Cosmos DB 帐户的访问。首先，允许来自子网的流量将其子网和虚拟网络标识传递给 Azure Cosmos DB。通过为子网上的 Azure Cosmos DB 启用服务终结点，可以更改流量的标识。接下来，在 Azure Cosmos DB 帐户中添加一个规则，以便将此子网指定为可从中访问帐户的源。

虚拟网络 ACL 和 IP 防火墙是否会拒绝请求或连接？

添加 IP 防火墙或虚拟网络访问规则后，只有来自受允许源的请求才能获取有效响应。将拒绝其他请求并返回 403（禁止访问）错误。必须将 Azure Cosmos DB 帐户的防火墙与连接级别的防火墙区分开来。源仍可连接到服务，连接本身不会遭到拒绝。

在子网中为 Azure Cosmos DB 启用服务终结点后，我的请求开始遭到阻止。发生了什么情况？

在子网中为 Azure Cosmos DB 启用服务终结点后，抵达帐户的流量源将从公共 IP 切换到虚拟网络和子网。如果 Azure Cosmos DB 帐户仅包含基于 IP 的防火墙，则已启用服务的子网发出的流量将不再与 IP 防火墙规则相匹配，因此遭到拒绝。请重温有关从基于 IP 的防火墙无缝迁移到基于虚拟网络的访问控制的步骤。

对于使用 VNET 服务终结点的 Azure Cosmos DB 帐户，是否需要额外的基于 Azure 角色的访问控制权限？

在将 VNet 服务终结点添加到 Azure Cosmos DB 帐户后，若要对帐户设置进行任何更改，需要访问 Azure Cosmos DB 帐户上配置的所有 VNET 的 Microsoft.Network/virtualNetworks/subnets/joinViaServiceEndpoint/action 操作。此权限是必需的，因为授权过程会先验证对资源（例如数据库和虚拟网络资源）的访问权限，然后再对所有属性进行评估。

即使用户没有使用 Azure CLI 指定 VNET ACL，授权也会验证对 VNet 资源操作的权限。目前，Azure Cosmos DB 帐户的控制平面支持设置 Azure Cosmos DB 帐户的完整状态。控制平面调用的其中一个参数是 virtualNetworkRules。如果未指定此参数，Azure CLI 将执行 get 数据库调用来检索 virtualNetworkRules，并在 update 调用中使用此值。

对等互连的虚拟网络是否也有权访问 Azure Cosmos DB 帐户？

只有已添加到 Azure Cosmos DB 帐户的虚拟网络及其子网才拥有此访问权限。将对等互连的虚拟网络中的子网添加到帐户之后，对等互连的 VNet 才可以访问该帐户。

最多允许多少个子网访问单个 Azure Cosmos DB 帐户？

目前，一个 Azure Cosmos DB 帐户最多允许 256 个子网。

是否可以启用从 VPN 和 Express Route 进行访问？

若要在本地通过 Express Route 访问 Azure Cosmos DB 帐户，需要启用 Azure 对等互连。放置 IP 防火墙或虚拟网络访问规则后，可以在 Azure Cosmos DB 帐户 IP 防火墙中添加用于 Azure 对等互连的公共 IP 地址，以允许本地服务访问 Azure Cosmos DB 帐户。

是否需要更新网络安全组 (NSG) 规则？

NSG 规则用于限制与虚拟网络中子网之间的连接。将 Azure Cosmos DB 的服务终结点添加到子网时，无需在 NSG 中为 Azure Cosmos DB 帐户打开出站连接。

服务终结点是否适用于所有 VNet？

否，只能为 Azure 资源管理器虚拟网络启用服务终结点。经典虚拟网络不支持服务终结点。

何时应该为 Azure Cosmos DB 帐户接受来自多区域 Azure 数据中心内的连接？

仅在需要 Azure Cosmos DB 帐户可供任何 Azure 区域的任何 Azure 服务访问时，才应启用此设置。其他 Azure 第一方服务（例如 Azure 数据工厂和 Azure AI 搜索）提供了有关如何保护对数据源（包括 Azure Cosmos DB 帐户）的访问的文档，例如：

Azure 数据工厂托管虚拟网络
Azure AI 搜索索引器对受保护资源的访问

后续步骤

若要为 Azure Cosmos DB 配置防火墙，请参阅防火墙支持一文。