Tutorial: Connect to an Azure Cosmos account using an Azure Private Endpoint
Azure Private endpoint is the fundamental building block for Private Link in Azure. It enables Azure resources, like virtual machines (VMs), to communicate with Private Link resources privately.
In this tutorial, you learn how to:
- Create a virtual network and bastion host.
- Create a virtual machine.
- Create a Cosmos DB account with a private endpoint.
- Test connectivity to Cosmos DB account private endpoint.
If you don't have an Azure subscription, create a free account before you begin.
Prerequisites
- An Azure subscription
Sign in to Azure
Sign in to the Azure portal.
Create a virtual network and bastion host
In this section, you'll create a virtual network, subnet, and bastion host.
The bastion host will be used to connect securely to the virtual machine for testing the private endpoint.
On the upper-left side of the screen, select Create a resource > Networking > Virtual network or search for Virtual network in the search box.
In Create virtual network, enter or select this information in the Basics tab:
Setting Value Project Details Subscription Select your Azure subscription Resource Group Select myResourceGroup Instance details Name Enter myVNet Region Select East US Select the IP Addresses tab or select the Next: IP Addresses button at the bottom of the page.
In the IP Addresses tab, enter this information:
Setting Value IPv4 address space Enter 10.1.0.0/16 Under Subnet name, select the word default.
In Edit subnet, enter this information:
Setting Value Subnet name Enter mySubnet Subnet address range Enter 10.1.0.0/24 Select Save.
Select the Security tab.
Under BastionHost, select Enable. Enter this information:
Setting Value Bastion name Enter myBastionHost AzureBastionSubnet address space Enter 10.1.1.0/24 Public IP Address Select Create new. For Name, enter myBastionIP. Select OK. Select the Review + create tab or select the Review + create button.
Select Create.
Create a virtual machine
In this section, you'll create a virtual machine that will be used to test the private endpoint.
On the upper-left side of the portal, select Create a resource > Compute > Virtual machine or search for Virtual machine in the search box.
In Create a virtual machine, type or select the values in the Basics tab:
Setting Value Project Details Subscription Select your Azure subscription Resource Group Select myResourceGroup Instance details Virtual machine name Enter myVM Region Select East US Availability Options Select No infrastructure redundancy required Image Select Windows Server 2019 Datacenter - Gen1 Azure Spot instance Select No Size Choose VM size or take default setting Administrator account Username Enter a username Password Enter a password Confirm password Reenter password Select the Networking tab, or select Next: Disks, then Next: Networking.
In the Networking tab, select or enter:
Setting Value Network interface Virtual network myVNet Subnet mySubnet Public IP Select None. NIC network security group Basic Public inbound ports Select None. Select Review + create.
Review the settings, and then select Create.
Note
Azure provides an default outbound access IP for Azure Virtual Machines which aren't assigned a public IP address, or are in the backend pool of an internal Basic Azure Load Balancer. The default outbound access IP mechanism provides an outbound IP address that isn't configurable.
For more information about default outbound access, see Default outbound access in Azure
The default outbound access IP is disabled when a public IP address is assigned to the virtual machine, or the virtual machine is placed in the backend pool of a Standard Load Balancer with or without outbound rules. If a Azure Virtual Network NAT gateway resource is assigned to the subnet of the virtual machine, the default outbound access IP is disabled.
Virtual machines created by Virtual Machine Scale sets in Flexible Orchestration mode don't have default outbound access.
For more information about outbound connections in Azure, see Using Source Network Address Translation (SNAT) for outbound connections.
Create a Cosmos DB account with a private endpoint
In this section, you'll create a Cosmos DB account and configure the private endpoint.
In the left-hand menu, select Create a resource > Databases > Cosmos DB Account, or search for Cosmos DB account in the search box.
In the Basics tab of Create Cosmos DB account enter or select the following information:
Setting Value Project Details Subscription Select your Azure subscription. Resource Group Select myResourceGroup. Instance details Account name Enter mycosmosdb. If the name is unavailable, enter a unique name. API Select Core (SQL). Location Select East US. Capacity mode Leave the default Provisioned throughput. Apply Free Tier Discount Leave the default Do Not Apply. Geo-Redundancy Leave the default Disable. Multi-region Writes Leave the default Disable. Select the Networking tab or select the Next: Networking button.
In the Networking tab, enter or select the following information:
Setting Value Network connectivity Connectivity method Select Private endpoint. Configure Firewall Allow access from the Azure portal Leave the default Allow. Allow access from my IP Leave the default Deny. In Private endpoint, select + Add.
In Create private endpoint enter or select the following information:
Setting Value Subscription Select your Azure subscription Resource Group Select myResourceGroup Location Select East US Name Enter myPrivateEndpoint Target subresource Leave the default Core (SQL) Networking Virtual network Select myVNet Subnet Select mySubnet Private DNS integration Integrate with private DNS zone Leave the default Yes Private DNS Zone Leave the default (New) privatelink.documents.azure.com Select OK.
Select Review + create.
Select Create.
Add a database and a container
Select Got to resource or in the left-hand menu of the Azure portal, select All Resources > mycosmosdb.
In the left-hand menu, select Data Explorer.
In the Data Explorer window, select New Container.
In Add Container, enter or select the following information:
Setting Value Database ID Leave the default of Create new. Enter mydatabaseid in the text box. Throughput (400 - 100,000 RU/s) Leave the default of Manual. Enter 400 in the text box. Container ID Enter mycontainerid Partition key Enter /mykey Select OK.
In the Settings section of the CosmosDB account, select Keys.
Select copy on the PRIMARY CONNECTION STRING.
Test connectivity to private endpoint
In this section, you'll use the virtual machine you created in the previous step to connect to the Cosmos DB account across the private endpoint.
Select Resource groups in the left-hand navigation pane.
Select myResourceGroup.
Select myVM.
On the overview page for myVM, select Connect then Bastion.
Select the blue Use Bastion button.
Enter the username and password that you entered during the virtual machine creation.
Open Windows PowerShell on the server after you connect.
Enter
nslookup <cosmosdb-account-name>.documents.azure.comand validate the name resolution. Replace <cosmosdb-account-name> with the name of the Cosmos DB account you created in the previous steps.Server: UnKnown Address: 168.63.129.16 Non-authoritative answer: Name: mycosmosdb8675.privatelink.documents.azure.com Address: 10.1.0.5 Aliases: mycosmosdb8675.documents.azure.comA private IP address of 10.1.0.5 is returned for the Cosmos DB account name. This address is in the subnet of the virtual network you created previously.
Get your Azure Cosmos DB primary connection string from portal. A valid connection string is in the format:
For SQL API accounts:
https://<accountName>.documents.azure.com:443/;AccountKey=<accountKey>;For Azure Cosmos DB API for MongoDB:mongodb://<accountName>:<accountKey>@cdbmongo36.mongo.cosmos.azure.com:10255/?ssl=true&replicaSet=globaldb&retrywrites=falseInstall Microsoft Azure Storage Explorer on the virtual machine.
Select Finish after the Microsoft Azure Storage Explorer is installed. Leave the box checked to open the application.
In the Connect to Azure Storage screen, select Cancel.
In Storage Explorer, select the right mouse button on Cosmos DB Accounts and select Connect to Cosmos DB.
Leave the default of SQL under Select API.
In the box under Connection String, paste the connection string from the Cosmos DB account you copied in the previous steps.
Select Next.
Verify the settings are correct in Connection Summary.
Select Connect.
Close the connection to myVM.
Clean up resources
If you're not going to continue to use this application, delete the virtual network, virtual machine, and Cosmos DB account with the following steps:
From the left-hand menu, select Resource groups.
Select myResourceGroup.
Select Delete resource group.
Enter myResourceGroup in TYPE THE RESOURCE GROUP NAME.
Select Delete.
Next steps
In this tutorial, you created a:
- Virtual network and bastion host.
- Virtual Machine.
- Cosmos DB Account.
Learn how to create a Private Link service: