Manage the Document DB via Powershell

Document DB is one kind of database service in azure (which has been integrated into the Cosmos DB), it is distributed, high scalable and high available. At present, many partners have said they have a demand for batch management of Azure services. While Azure offers a variety of options for managing Azure resources, each option has its advantages and disadvantages. Such as directly to manage Document DB via Azure Portal, although it is easy to use, but it is impossible to use to execute batch management tasks; Moreover, although the Rest API can achieve batch management, for the IT administrators, coding is still a more challenging task; Based on this situation, Azure also provides Powershell to manage Azure resources. Powershell is a kind of  script language, which makes you complete the complex management work with few simple commands. This article focuses on how to use Powershell for batch management of Document DB.

First of all, we need to analyze that what we should do when we manage the Document DB, for example
1: If you need batch deployments of  Document DB account, how to achieve? How do I maintain the created Document DB accounts?
2: Each subscription may have multiple resource groups, each resource group has multiple Document DB test or production accounts, how to manage these resource across resource group?
3: For security reasons, may need to regularly or manually update the Document DB’s key, how to achieve? And how to modify the existing Document DB’s failover policy?

Let’s take a brief look at how to use Powershell to do the work step by step.
# 1: If you want to manage Azure resources via Powershell, firstly , you need to log in to your Azure account using the  following cmdlet

Login-AzureRmAccount

Then you will manually enter the account name password to sign in. Of course, if you want to automateically sign in your azure account, you can try to create a Service Principal as below link:
Https://docs.microsoft.com/en-us/powershell/azure/create-azure-service-principal-azureps?view=azurermps-4.0.0

# 2: After logging in to the Azure account, although you can not find a special cmdlet like which is used to manage virtual machine, we can use the New-AzureRmResource cmdlet to create our Document DB account.
Reference:
Https://docs.microsoft.com/en-us/powershell/module/azurerm.resources/new-azurermresource?view=azurermps-4.0.0

#create document db account
$rsgName = "ericm"
$rsg = Get-AzureRmResourceGroup -Name $rsgName
$rsgLocation = $rsg.Location

$docDBName = "docdb-ericm"
$docDBLocation = $rsgLocation
$apiVersion = "2015-04-08"
$rsType = "Microsoft.DocumentDb/databaseAccounts"
$locations = @(@{"locationName"="West US"; "failoverPriority"=0}, @{"locationName"="East US"; "failoverPriority"=1})
$iprangefilter = "167.220.255.40/24"
$consistencyPolicy = @{"defaultConsistencyLevel"="BoundedStaleness"; "maxIntervalInSeconds"=300; "maxStalenessPrefix"=100000}
$docDBProperties = @{"databaseAccountOfferType"="Standard"; "locations"=$locations; "consistencyPolicy"=$consistencyPolicy; "ipRangeFilter"=$iprangefilter;"enableAutomaticFailover"=$TRUE}
New-AzureRmResource -ResourceType $rsType -ApiVersion $apiVersion -ResourceGroupName $rsgName -Location $docDBLocation -Name $docDBName -PropertyObject $docDBProperties

When creating a Document DB, we mainly need to init these parameters
apiVersion: The version number of the Rest API, you can refer to https://docs.microsoft.com/en-us/rest/api/resources/providers#Providers_List to query the version number supported by each resource provider.
locations: a list of fail over region, 0 for writable region.if  the West US node has failed, Azure can automatically set East US as the writable region to ensure the availability of services.
iprangefilter: firewall filter IP list, Document DB uses firewall settings to ensure  that only valid IPs can access your Document DB service.
consistencyPolicy: Consistency policy, such as  “Eventual”, “Strong”, “Session”, “BoundedStaleness”. In order to ensure balance of  consistency, availability, and latency, the Document DB provides several consistency policies to meet  different service requirements.
Reference
Https://docs.microsoft.com/en-us/azure/documentdb/documentdb-consistency-levels
maxIntervalInSeconds, maxStalenessPrefix please refer to
Https://docs.microsoft.com/en-us/rest/api/documentdbresourceprovider/databaseaccounts#DatabaseAccounts_CreateOrUpdate

enableAutomaticFailover: whether to enable automatic failover. if you set it to true, when Azure detects the current writable node exception, it will change the next node as the writable node so as to ensure availability of the service.

Similarly, you can modify the parameters  using the Set-AzureRmResource cmdlet

#update document db account
$iprangefilter = "167.220.255.41/24"
$consistencyPolicy = @{"defaultConsistencyLevel"="BoundedStaleness"; "maxIntervalInSeconds"=300; "maxStalenessPrefix"=100000}
$docDBProperties = @{"databaseAccountOfferType"="Standard"; "locations"=$locations; "consistencyPolicy"=$consistencyPolicy; "ipRangeFilter"=$iprangefilter;"enableAutomaticFailover"=$FALSE}
Set-AzureRmResource -ResourceType $rsType -ApiVersion $apiVersion -ResourceGroupName $rsgName -Name $docDBName -PropertyObject $docDBProperties

Retrieve the created Document DB account, you can use the Get-AzureRmResource cmdlet

#retrieve the document db account
Get-AzureRmResource -ResourceType $rsType -ApiVersion $apiVersion -ResourceGroupName $rsgName -Name $docDBName

# 3. If you want to classify the Document DB account across the resource group, you can set a Tag for each Document DB account so that you can retrieve specific account with the Find-AzureRmResource cmdlet.

#set tag of document db

#set tag of document db
$tags = @{"dept" = "Finance”; environment = “Production”}
Set-AzureRmResource -ResourceType $rsType -ApiVersion $apiVersion -ResourceGroupName $rsgName -Name $docDBName -Tag $tags

Then  you can retrieve your Document DB account by Tag

(Find-AzureRmResource -TagName Dept -TagValue Finance).Name

# 4. some azure resources support some specific actions, you can view them through the Resource Explorer. These actions can be invoked using the cmdlet Invoke-AzureRmResourceAction.

you can use regenerateKey action to re-generate the key

#regenerate key of document db
Invoke-AzureRmResourceAction -Action regenerateKey -ResourceType $rsType -ApiVersion $apiVersion -ResourceGroupName $rsgName -Name $docDBName -Parameters @{"keyKind"="Primary"}

you can use the listKeys action to list the keys of the Document DB

#list keys of document db
Invoke-AzureRmResourceAction -Action listKeys -ResourceType $rsType -ApiVersion $apiVersion -ResourceGroupName $rsgName -Name $docDBName

you can use the failoverPriorityChange action to update the Document DB’s failover policy

#update the failover policy of document db account
$failoverPolicies = @(@{"locationName"="East US"; "failoverPriority"=0}, @{"locationName"="West US"; "failoverPriority"=1})
Invoke-AzureRmResourceAction -Action failoverPriorityChange -ResourceType $rsType -ApiVersion $apiVersion -ResourceGroupName $rsgName -Name $docDBName -Parameters @{"failoverPolicies"=$failoverPolicies}

Reference:
https://docs.microsoft.com/en-us/rest/api/documentdbresourceprovider/databaseaccounts
https://github.com/Azure/azure-quickstart-templates/blob/master/101-documentdb-account-consistencypolicy-create/azuredeploy.json

Summary:

Powershell is a effective tool, this article is not only for the batch management of Document DB, but for the management of other Azure resources

Leave a Reply

Your email address will not be published. Required fields are marked *