Azure Private Endpoint for Cosmos DB isn’t just about blocking public access; it fundamentally changes how your application thinks about reaching your database.
Let’s see it in action. Imagine you have a Cosmos DB account, mycosmosdbaccount, in the West US region, and a virtual network myvnet with a subnet mysubnet.
# Create the private endpoint
az network private-endpoint create \
--name mycosmosdbepp \
--resource-group myresourcegroup \
--vnet-name myvnet \
--subnet mysubnet \
--private-connection-resource-id "/subscriptions/YOUR_SUBSCRIPTION_ID/resourceGroups/myresourcegroup/providers/Microsoft.DocumentDB/databaseAccounts/mycosmosdbaccount" \
--group-ids "Sql" \
--location "westus"
# Create a private DNS zone for the Cosmos DB endpoint
az network private-dns zone create \
--resource-group myresourcegroup \
--name "privatelink.documents.azure.com"
# Link the private DNS zone to your VNet
az network private-dns link vnet create \
--resource-group myresourcegroup \
--name mydnslink \
--zone-name "privatelink.documents.azure.com" \
--virtual-network myvnet
# Create an A record in the private DNS zone for your Cosmos DB account
# The IP address will be provided in the output of the private-endpoint create command
# Let's assume the IP is 10.0.0.5 for this example
az network private-dns record-set a add-record \
--resource-group myresourcegroup \
--zone-name "privatelink.documents.azure.com" \
--record-set-name "mycosmosdbaccount" \
--ipv4-address "10.0.0.5"
Now, any resource within myvnet that tries to resolve mycosmosdbaccount.documents.azure.com will get the private IP address 10.0.0.5 instead of a public IP. Your application, configured to use that FQDN, will automatically start sending traffic over the private endpoint.
The core problem this solves is the security and network isolation of your data. Before private endpoints, accessing Cosmos DB from an Azure VM or AKS cluster typically involved traversing the public internet (even if secured with TLS/SSL) or using service endpoints, which still allowed traffic from the entire VNet. Private Endpoints create a dedicated, private IP address for your Cosmos DB account within your VNet, ensuring traffic never leaves your Azure backbone network.
Internally, a Private Endpoint is a network interface (NIC) resource in your VNet that is assigned a private IP address from your subnet. This NIC is then associated with a specific Azure resource (your Cosmos DB account in this case) via a "connection resource." The magic happens with DNS. When you create a private endpoint, Azure automatically creates a corresponding private DNS zone (privatelink.documents.azure.com for Cosmos DB). You then create an A record within this zone that maps your Cosmos DB account’s fully qualified domain name (FQDN) to the private IP address of the private endpoint NIC. This ensures that when your application looks up mycosmosdbaccount.documents.azure.com, it resolves to the private IP, and traffic is routed directly to the private endpoint NIC, which then forwards it to the Cosmos DB service.
The exact levers you control are the VNet and subnet where the private endpoint resides, the resource ID of the Cosmos DB account it connects to, and the group-ids which specify the type of Azure resource you’re connecting to (e.g., "Sql" for Core SQL API, "MongoDB" for Cosmos DB for MongoDB). You also manage the DNS resolution through the private DNS zone and the A record.
What most people don’t realize is that the group-ids parameter is crucial and must match the API you are using for Cosmos DB. If you’re using the Core SQL API, it’s Sql. If you’re using the MongoDB API, it’s MongoDB. If you get this wrong, the private endpoint will be created, but your client applications won’t be able to authenticate or connect to the database, leading to confusing authentication errors or connection timeouts that seem unrelated to network configuration.
The next conceptual hurdle is understanding how to manage multiple private endpoints for the same Cosmos DB account across different VNets or regions, and the implications for DNS across those environments.