Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
In this quickstart, you use Azure CLI to create and manage an Azure DocumentDB cluster. You also configure a firewall rule, get the cluster connection strings, and update the cluster configuration.
Prerequisites
- An Azure subscription. If you don't have an Azure subscription, create a free account.
Use the Bash environment in Azure Cloud Shell. For more information, see Get started with Azure Cloud Shell.
If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.
If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Authenticate to Azure using Azure CLI.
When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use and manage extensions with the Azure CLI.
Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.
Install or update the Azure DocumentDB extension for Azure CLI.
az extension add --name documentdb --upgrade
Create an Azure DocumentDB cluster
Create a resource group with az group create. Replace the placeholders with values for your environment.
az group create \
--name <resource-group> \
--location <azure-region>
Check whether a cluster name is available in the target region.
az documentdb mongocluster check-name-availability \
--name <cluster-name> \
--location <azure-region>
Create a cluster with az documentdb mongocluster create. The cluster name must be globally unique. The GeoReplicas preview feature makes the cluster eligible to be a source for same-region or cross-region replicas. It doesn't create a replica.
az documentdb mongocluster create \
--name <cluster-name> \
--resource-group <resource-group> \
--location <azure-region> \
--admin-user <admin-user> \
--admin-password <admin-password> \
--server-version 8.0 \
--tier M30 \
--storage-size 128 \
--storage-type PremiumSSDv2 \
--shard-count 1 \
--high-availability Disabled \
--auth-allowed-modes NativeAuth \
--public-network-access Enabled \
--preview-features GeoReplicas \
--no-wait
Wait for the cluster to finish provisioning.
az documentdb mongocluster wait \
--name <cluster-name> \
--resource-group <resource-group> \
--created
Enable GeoReplicas when you create the source cluster because you can't add the feature later. After the cluster finishes provisioning, use az documentdb mongocluster replica create to create a replica. The service assigns the AsyncReplica role to a same-region replica and the GeoAsyncReplica role to a cross-region replica.
For a production cluster, set --high-availability to ZoneRedundantPreferred. High availability is separate from replica support. For more information, see High availability in Azure DocumentDB.
Configure a firewall rule
Create a firewall rule that allows connections from a specific IPv4 address. Use the same address for the start and end of the range to allow one address.
az documentdb mongocluster firewall-rule create \
--name <firewall-rule-name> \
--cluster-name <cluster-name> \
--resource-group <resource-group> \
--start-ip-address <client-ip-address> \
--end-ip-address <client-ip-address>
For production workloads, use a private endpoint instead of public network access.
View the cluster
Show the properties of the new cluster.
az documentdb mongocluster show \
--name <cluster-name> \
--resource-group <resource-group>
List all clusters in the resource group.
az documentdb mongocluster list \
--resource-group <resource-group> \
--output table
Get connection strings
Get the connection strings for the cluster.
az documentdb mongocluster list-connection-strings \
--cluster-name <cluster-name> \
--resource-group <resource-group>
Treat connection strings as secrets. Don't store them in source code or commit them to source control.
View all arguments
View all arguments and examples for a command by using the --help argument.
az documentdb mongocluster create --help
Update the cluster
Update only the properties that you want to change. The following command changes the compute tier.
az documentdb mongocluster update \
--name <cluster-name> \
--resource-group <resource-group> \
--tier M40
Reset the administrator password
Reset the native administrator password with az documentdb mongocluster reset-password.
az documentdb mongocluster reset-password \
--name <cluster-name> \
--resource-group <resource-group> \
--admin-password <new-admin-password>
Clean up resources
Delete the cluster when you no longer need it.
az documentdb mongocluster delete \
--name <cluster-name> \
--resource-group <resource-group> \
--yes