Function to obtain the paired/failover region

[Gijsreyn]

As a user, I would like the ability to pick the zone related to the redunacy. It's better to explain it by example. Imagine the following Bicep file:

module cosmosDb 'br/public:avm/res/document-db/database-account:0.10.1' = {
  name: 'cosmosDb'
  params: {
    name: cosmosDbName
    location: 'westus'
    disableLocalAuth: true
    networkRestrictions: {
      publicNetworkAccess: 'Enabled'
      networkAclBypass: 'AzureServices'
      ipRules: [
        '13.91.105.215'
        '4.210.172.107'
        '13.88.56.148'
        '40.91.218.243'
        '0.0.0.0'
      ]
    }
    locations: [
        {
            failoverPriority: 0
            locationName: 'West US'
            isZoneRedundant: false
        }
        {
            failoverPriority: 1
            locationName: 'Central US'
            isZoneRedundant: false
        }
    ]
    enableFreeTier: false
    databaseAccountOfferType: 'Standard'
    backupPolicyType: 'Periodic'
    backupIntervalInMinutes: 240
    backupRetentionIntervalInHours: 720
    backupStorageRedundancy: 'Geo'
    defaultConsistencyLevel: 'Session'
    maxStalenessPrefix: 100
    maxIntervalInSeconds: 5
    sqlDatabases: [
      {
        name: 'test'
          }
        ]
      }
    ]
  }
}

The location parameter can be set, which takes me to the locations parameter. For the failover priority, I can use: pickZones('Microsoft.DocumentDB', 'databaseAccounts', location). The challenge is in the second part. It would be beneficial if there were a function like: pickZoneReferenceName('Microsoft.DocumentDB', 'databaseAccounts', location).

If this issue has already been captured or if such a function exists, I hope you can steer me in the right direction.

[jeskew]

@Gijsreyn what value would pickZoneReferenceName return? Is it the location name?

[Gijsreyn]

Hey @jeskew, depending on the scenario, it should be able to return the location name in short or long e.g. westus or West US.

[majastrz]

@Gijsreyn It seems we may be mixing up logical availability zone names (1, 2, 3, ...) and location/region names such as westus. Are you asking for a function that will return the "long" location name (West US 2, for example) given a short location name (westus2, for example)?

[Gijsreyn]

@majastrz Marcin, you're totally correct! In the above example, there are three locations:

1. The first one is simple, the location property. Of course, this could have been parameterized, but you get the point.
2. The second and third ones are in the locations property.

What I'm looking for in this case is that if a user passes in the 'westus' location as a parameter, it is able to resolve the redundant "long" name, so I don't have to explicitly create three separate parameters and mess up the configuration if a user, say, puts in 'westeurope'.

[majastrz]

@Gijsreyn Yeah, the feature request makes sense. Until the solution is available, my suggestion would be to use the "long" name convention in all your parameters and convert to short name as needed. The conversion from long to short name can be done reliably for all regions by removing whitespace in the location name and converting to lowercase.

Here's an example UDF that you could use to perform this conversion in Bicep:

func toShortName(longLocation string) string => toLower(replace(longLocation, ' ', ''))

output weu string = toShortName('West Europe')
output wus2 string = toShortName('West US 2')

This file produces the following outputs when deployed:

DeploymentName          : test
ResourceGroupName       : majastrz-test
ProvisioningState       : Succeeded
Timestamp               : 1/16/2025 1:53:50 AM
Mode                    : Incremental
TemplateLink            :
Parameters              :
Outputs                 :
                          Name             Type                       Value
                          ===============  =========================  ==========
                          weu              String                     "westeurope"
                          wus2             String                     "westus2"

DeploymentDebugLogLevel :

[Gijsreyn]

@majastrz Wow, thanks Marcin! That was done quickly! The only thing that's missing is the difficulty of determining the right region in this use case. By that, I mean how can I be certain what the 'redundant' location is going to be? It would still require two (or even three) parameters to be defined.

[majastrz]

@Gijsreyn By "redundant" location, do you mean the paired region to where storage and other services may fail over during a region outage?

[Gijsreyn]

@majastrz Correct. So in it's basic form, let's take this as example with a fictional function:

param location string = 'westeurope'

var primaryRegion string = getRegionShortName(location)[0] // <--- This should return 'West EU'
var seconaRegion string = getRegionShortName(location)[1] // <--- This should return 'North EU'

I can imagine that there are some complications whenever you create such a function, as you've to know the key pairs between the regions, as well as other regions within the same boundary?

Note

I guessed the short names in this example, but you get the point (I was a bit tired).

[majastrz]

I understand now. Currently, we do not have any functions to figure out the failover/secondary/paired region given another region, but the ask absolutely makes sense. I'm going to update the title to match this.

The only way today to find out the paired region in Bicep is to populate that information via parameters like you're doing.

It can be scripted via the Locations API. We also support it in PS via the Get-AzLocation cmdlet and its CLI equivalent.