Connect to a cluster with private access in Azure Cosmos DB for PostgreSQL
APPLIES TO: Azure Cosmos DB for PostgreSQL (powered by the Citus database extension to PostgreSQL)
This tutorial creates a virtual machine (VM) and an Azure Cosmos DB for PostgreSQL cluster, and establishes private access between them.
Prerequisites
- An Azure account with an active subscription. If you don't have one, create a trial subscription.
- If you want to run the code locally, Azure CLI installed.
Create a virtual network
First, set up a resource group and virtual network to hold your cluster and VM.
az group create \
--name link-demo \
--location chinanorth3
az network vnet create \
--resource-group link-demo \
--name link-demo-net \
--address-prefix 10.0.0.0/16
az network nsg create \
--resource-group link-demo \
--name link-demo-nsg
az network vnet subnet create \
--resource-group link-demo \
--vnet-name link-demo-net \
--name link-demo-subnet \
--address-prefixes 10.0.1.0/24 \
--network-security-group link-demo-nsg
Create a virtual machine
For demonstration, create a VM running Debian Linux and the psql
PostgreSQL client.
# provision the VM
az vm create \
--resource-group link-demo \
--name link-demo-vm \
--vnet-name link-demo-net \
--subnet link-demo-subnet \
--nsg link-demo-nsg \
--public-ip-address link-demo-net-ip \
--image Debian11 \
--admin-username azureuser \
--generate-ssh-keys
# install psql database client
az vm run-command invoke \
--resource-group link-demo \
--name link-demo-vm \
--command-id RunShellScript \
--scripts \
"sudo touch /home/azureuser/.hushlogin" \
"sudo DEBIAN_FRONTEND=noninteractive apt-get update" \
"sudo DEBIAN_FRONTEND=noninteractive apt-get install -q -y postgresql-client"
Create a cluster with a private link
Create your Azure Cosmos DB for PostgreSQL cluster in the Azure portal.
In the portal, select Create a resource in the upper left-hand corner.
On the Create a resource page, select Databases, and then select Azure Cosmos DB.
On the Select API option page, on the PostgreSQL tile, select Create.
On the Create an Azure Cosmos DB for PostgreSQL cluster page, fill out the following information:
Resource group: Select New, then enter link-demo.
Cluster name: Enter link-demo-sg.
Note
The cluster name must be multiple-regionally unique across Azure because it creates a DNS entry. If
link-demo-sg
is unavailable, enter another name and adjust the following steps accordingly.Location: Select China North3.
Password: Enter and then confirm a password.
Select Next: Networking.
On the Networking tab, for Connectivity method, select Private access.
On the Create private endpoint screen, enter or select the following values:
- Resource group:
link-demo
- Location:
China North3
- Name:
link-demo-sg-c-pe1
- Target sub-resource:
coordinator
- Virtual network:
link-demo-net
- Subnet:
link-demo-subnet
- Integrate with private DNS zone: Yes
- Resource group:
Select OK.
After you create the private endpoint, select Review + create and then select Create to create your cluster.
Access the cluster privately from the VM
The private link allows the VM to connect to the cluster, and prevents external hosts from doing so. In this step, you check that the psql database client on your VM can communicate with the coordinator node of the cluster. In the code, replace {your_password}
with your cluster password.
# replace {your_password} in the string with your actual password
PG_URI='host=c-link-demo-sg.12345678901234.postgres.cosmos.chinacloudapi.cn port=5432 dbname=citus user=citus password={your_password} sslmode=require'
# Attempt to connect to cluster with psql in the VM
az vm run-command invoke \
--resource-group link-demo \
--name link-demo-vm \
--command-id RunShellScript \
--scripts "psql '$PG_URI' -c 'SHOW citus.version;'" \
--query 'value[0].message' \
| xargs printf
You should see a version number for Citus in the output. If you do, then psql was able to execute the command, and the private link worked.
Clean up resources
You've seen how to create a private link between a VM and a cluster. Now you can deprovision the resources.
Delete the resource group, and the resources inside will be deprovisioned:
az group delete --resource-group link-demo
# press y to confirm
Next steps
- Learn more about private access
- Learn about private endpoints
- Learn about virtual networks
- Learn about private DNS zones