Cosmos DB private endpoint

Understand the concept

In plain English

A Cosmos DB private endpoint gives applications a private network path to a Cosmos DB account instead of sending database traffic to the public endpoint. It creates a private IP address in a subnet and uses Private Link so clients inside approved networks can reach the account through that address. Teams use it when a database should be reachable from workloads in a virtual network, peered network, hub, or on-premises path without leaving the private network design.

Why it matters

Cosmos DB private endpoint matters because database exposure is one of the easiest cloud risks to misunderstand. Disabling public network access is not enough if clients still resolve DNS incorrectly, use the wrong region, or bypass the private path with old configuration. A good private endpoint design reduces public attack surface, supports regulated network boundaries, and gives security teams a concrete artifact to audit. It also changes operations: subnet capacity, DNS zones, regional account changes, SDK endpoints, and firewall policies must be managed together. For learners, this term explains why private connectivity is not only a checkbox; it is a routed, resolvable, monitored path to a production database.

Technical context

Technically, a Cosmos DB private endpoint is an Azure Private Endpoint resource connected to a Cosmos DB account subresource. It depends on a subnet, network interface, private DNS zone, virtual network links, and the Cosmos DB account network configuration. The Cosmos DB API, region, failover settings, consistency, request units, and SDK behavior still belong to the database design; the private endpoint controls the network path. Operators must validate DNS resolution because clients need the account name to resolve to private IP addresses from the right networks.

Exam context

Compare with

Where it is used

Where you see it

1. In the Cosmos DB networking blade, private endpoint connections show approval state, target subresource, private IP, virtual network, DNS integration, and whether public network access remains enabled.
2. In Private DNS zones, records for the Cosmos DB account must resolve to private addresses from every linked virtual network that hosts consuming applications and test agents.
3. In SDK diagnostics and application logs, connection failures, DNS mismatches, timeouts, retry storms, resolver differences, or unexpected public endpoint attempts reveal private endpoint configuration problems.

Common situations

• Lock down a production Cosmos DB account so application traffic reaches it only through approved virtual networks and Private Link.
• Support regulated workloads where auditors require evidence that database access does not depend on public network exposure.
• Connect AKS, App Service, Functions, or virtual machines to Cosmos DB through hub-spoke private networking and private DNS.
• Prepare a public-access shutdown by proving DNS, endpoint approval, and application connectivity from every consuming subnet.
• Reduce data-exfiltration risk by combining private endpoints with restrictive keys, RBAC, policy, logging, and change approval.

Illustrative Azure scenarios

These examples show how the concept can affect design and operations. They are illustrative scenarios, not customer claims.

Azure CLI

I use Azure CLI for Cosmos DB private endpoints because the portal hides too many moving parts across different blades. In a real outage, I need to prove the Cosmos DB account setting, endpoint approval state, subnet, private IP, DNS zone records, virtual network links, and public network access quickly. CLI gives repeatable evidence that can be pasted into a change ticket or incident timeline. After ten years of Azure operations, I have seen private endpoint issues caused by DNS more often than by the endpoint resource itself. Command-line checks force the team to inspect the full path instead of arguing from memory.

az cosmosdb show --name <account-name> --resource-group <resource-group>

az network private-endpoint list --resource-group <resource-group>

az network private-dns zone list --resource-group <resource-group>

az cosmosdb update --name <account-name> --resource-group <resource-group> --public-network-access Disabled

Architecture context

Architecturally, I treat a Cosmos DB private endpoint as the data access boundary between application networks and a globally distributed database account. It belongs in the same conversation as hub-spoke routing, private DNS, AKS or App Service integration, on-premises connectivity, region failover, and public network access. The endpoint itself does not make queries faster or fix partition design, but it defines where the database can be reached. In mature environments, every private endpoint has an owner, subnet plan, DNS registration, monitoring signal, and disaster-recovery story. The design must also account for multiple APIs, multiple regions, and client libraries that cache or resolve endpoints differently during incidents.

Security

Security is the main reason to use a Cosmos DB private endpoint. It lets teams keep database traffic on private IP paths and combine that with public network access restrictions, Azure RBAC or keys, managed identities where supported, diagnostic logs, and policy controls. The biggest mistakes are leaving public access open, misconfiguring private DNS, granting broad account keys, and assuming subnet presence equals authorization. Operators should know who can create endpoints, approve connections, change DNS links, list keys, or modify account networking. Sensitive workloads should monitor denied requests, unexpected public endpoint attempts, and private endpoint changes as security events. Review every exception.

Cost

The private endpoint itself adds networking cost, and the surrounding design can also affect spend through private DNS, network traffic paths, duplicate endpoints, and operational effort. Cosmos DB cost still mainly comes from request units, storage, indexing, regions, backups, and throughput choices, so private connectivity should not hide poor data design. However, a misconfigured endpoint can generate expensive investigation time, failed deployments, and duplicate nonproduction infrastructure. FinOps reviews should track private endpoints per account and environment, unused endpoints, data transfer patterns, and whether public access exceptions are being kept alive because private DNS was never fixed. Review this during architecture governance.

Reliability

Reliability depends on DNS, regional design, subnet availability, and failover behavior. A private endpoint can be healthy while clients fail because their resolver returns public addresses or a stale private zone. Global Cosmos DB accounts need careful planning when regions are added, removed, or failed over, because private endpoint and DNS coverage must match the client access pattern. Operators should test from every consuming subnet, not just from a jump box. During incidents, separate database throttling, DNS failures, route issues, and private endpoint approval problems. Recovery plans should include DNS validation, connection-string review, SDK retry behavior, and fallback expectations. Rehearse failover carefully.

Performance

A private endpoint does not change Cosmos DB partitioning, RU consumption, or query engine behavior, but it can affect perceived performance through DNS, routing, connection reuse, and network path length. Clients that resolve inconsistently may show intermittent latency or failures that look like database throttling. Operators should compare SDK diagnostics, request charge, status codes, retry counts, DNS answers, and network timing before blaming Private Link. Regional placement matters because a private path from one virtual network to a distant account region can still be slow. Performance tests should run from the same subnet, resolver, and application runtime used in production.

Operations

Operators manage Cosmos DB private endpoints by inspecting the account networking blade, private endpoint connections, subnet configuration, private DNS zones, virtual network links, and client-side name resolution. Routine work includes confirming approval state, checking public network access, validating DNS from workload subnets, exporting endpoint evidence for audits, and reviewing logs for failed requests. Changes require coordination between database owners, network teams, security engineers, and application teams. A good runbook includes the account name, API, regions, private DNS zone, endpoint IPs, affected apps, rollback path, and tests to run before and after disabling public access. Keep ownership visible in diagrams and support tickets.

Common mistakes

• Disabling public access before private DNS works from every application subnet and on-premises resolver.
• Creating the private endpoint in the wrong virtual network or subnet because names look similar across environments.
• Assuming Private Link replaces database authorization, key rotation, RBAC review, or application authentication.
• Forgetting to update private endpoint and DNS planning when Cosmos DB regions or APIs change.
• Troubleshooting RU throttling as a network issue, or troubleshooting DNS failure as a database performance issue.