Background
Most of the services in Azure such as Storage Accounts, Key Vaults or AppService Websites must have globally unique names, where the fully qualified domain name (aka FQDN) for the service uses the name you selected and the suffix for the specific service. For example, for Key Vaults its vault.azure.net and for WebApps its azurewebsites.net
The Azure portal can help you determine the name availability during the service creation, but there’s no built-in PowerShell cmdlet or azure cli command to do so for ARM services (in the old ASM days, we had the Test-AzureName PowerShell cmdlet we could use to check for a classic cloud services name availability).
For scenarios where you have an automated deployment and don’t want the deployment failing because of the name availability, you’d want to have a simple command that returns a true/false boolean value that determines if the name is already taken or not.
Proposed solution
Several of the Azure providers have an API that exposes a checkNameAvailability action that you can use the test the name’s availability. Each provider requires and accepts a different set of parameters, where the most important ones are obviously the name you want to check and the service type.
To get a list of the providers that support the checkNameAvailability action, you can use the following PowerShell command:
Get-AzResourceProvider |
Where-Object { $_.ResourceTypes.ResourceTypeName -eq 'checkNameAvailability' } |
Select-Object ProviderNamespace
That outputs the following:
ProviderNamespace
-----------------
Microsoft.Sql
Microsoft.Web
Microsoft.DBforMySQL
Microsoft.Media
Microsoft.Cdn
Microsoft.ApiManagement
Microsoft.BotService
Microsoft.Storage
Microsoft.KeyVault
Microsoft.Management
microsoft.support
Drilling down to one of the providers, we can see the list of API versions that support the action, and we can build the URI string to invoke
Get-AzResourceProvider -ProviderNamespace Microsoft.Web |
Where-Object { $_.ResourceTypes.ResourceTypeName -eq 'checkNameAvailability' } |
Select-Object -ExpandProperty ResourceTypes |
Select-Object -ExpandProperty ApiVersions
Invoking Azure APIs using PowerShell is simple enough, you just need the bearer token, the URI to the API action and the needed parameters for the action. For some of the APIs we need a subscription ID to work with.
The important and main function is Test-AzNameAvailability:
function Test-AzNameAvailability {
param(
[Parameter(Mandatory = $true)] [string] $AuthorizationToken,
[Parameter(Mandatory = $true)] [string] $SubscriptionId,
[Parameter(Mandatory = $true)] [string] $Name,
[Parameter(Mandatory = $true)] [ValidateSet(
'ApiManagement', 'KeyVault', 'ManagementGroup', 'Sql', 'StorageAccount', 'WebApp')]
$ServiceType
)
$uriByServiceType = @{
ApiManagement = 'https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.ApiManagement/checkNameAvailability?api-version=2019-01-01'
KeyVault = 'https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.KeyVault/checkNameAvailability?api-version=2019-09-01'
ManagementGroup = 'https://management.azure.com/providers/Microsoft.Management/checkNameAvailability?api-version=2018-03-01-preview'
Sql = 'https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Sql/checkNameAvailability?api-version=2018-06-01-preview'
StorageAccount = 'https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Storage/checkNameAvailability?api-version=2019-06-01'
WebApp = 'https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Web/checkNameAvailability?api-version=2019-08-01'
}
$typeByServiceType = @{
ApiManagement = 'Microsoft.ApiManagement/service'
KeyVault = 'Microsoft.KeyVault/vaults'
ManagementGroup = '/providers/Microsoft.Management/managementGroups'
Sql = 'Microsoft.Sql/servers'
StorageAccount = 'Microsoft.Storage/storageAccounts'
WebApp = 'Microsoft.Web/sites'
}
$uri = $uriByServiceType[$ServiceType] -replace ([regex]::Escape('{subscriptionId}')), $SubscriptionId
$body = '"name": "{0}", "type": "{1}"' -f $Name, $typeByServiceType[$ServiceType]
$response = (Invoke-WebRequest -Uri $uri -Method Post -Body "{$body}" -ContentType "application/json" -Headers @{Authorization = $AuthorizationToken }).content
$response | ConvertFrom-Json |
Select-Object @{N = 'Name'; E = { $Name } }, @{N = 'Type'; E = { $ServiceType } }, @{N = 'Available'; E = { $_ | Select-Object -ExpandProperty *available } }, Reason, Message
}
To use it, you first have to get a bearer token, for either the current logged on user or for a service principal using one of the two functions Get-AccesTokenFromServicePrincipal or Get-AccesTokenFromCurrentUser:
function Get-AccesTokenFromServicePrincipal {
param(
[string] $TenantID,
[string] $ClientID,
[string] $ClientSecret
)
$TokenEndpoint = 'https://login.windows.net/{0}/oauth2/token' -f $TenantID
$ARMResource = 'https://management.core.windows.net/'
$Body = @{
'resource' = $ARMResource
'client_id' = $ClientID
'grant_type' = 'client_credentials'
'client_secret' = $ClientSecret
}
$params = @{
ContentType = 'application/x-www-form-urlencoded'
Headers = @{'accept' = 'application/json' }
Body = $Body
Method = 'Post'
URI = $TokenEndpoint
}
$token = Invoke-RestMethod @params
('Bearer ' + ($token.access_token).ToString())
}
function Get-AccesTokenFromCurrentUser {
$azContext = Get-AzContext
$azProfile = [Microsoft.Azure.Commands.Common.Authentication.Abstractions.AzureRmProfileProvider]::Instance.Profile
$profileClient = New-Object -TypeName Microsoft.Azure.Commands.ResourceManager.Common.RMProfileClient -ArgumentList $azProfile
$token = $profileClient.AcquireAccessToken($azContext.Subscription.TenantId)
('Bearer ' + $token.AccessToken)
}
To get the current (already logged in) user’s bearer token, use:
$AuthorizationToken = Get-AccesTokenFromCurrentUser
Or to get a Service Principal (App Registration) bearer token, use:
$AuthorizationToken = Get-AccesTokenFromServicePrincipal `
-TenantID '<Directory Tenant ID>' `
-ClientID '<Application Client ID>' `
-ClientSecret '<Application Client Secret>'
And then, to test for the name availability for some of the services you can use:
Test-AzNameAvailability -Name martin -ServiceType ApiManagement -AuthorizationToken $AuthorizationToken -SubscriptionId $subscriptionId
Test-AzNameAvailability -Name kv -ServiceType KeyVault -AuthorizationToken $AuthorizationToken -SubscriptionId $subscriptionId
Test-AzNameAvailability -Name root -ServiceType ManagementGroup -AuthorizationToken $AuthorizationToken -SubscriptionId $subscriptionId
Test-AzNameAvailability -Name sqlsrv1 -ServiceType Sql -AuthorizationToken $AuthorizationToken -SubscriptionId $subscriptionId
Test-AzNameAvailability -Name storage -ServiceType StorageAccount -AuthorizationToken $AuthorizationToken -SubscriptionId $subscriptionId
Test-AzNameAvailability -Name www -ServiceType WebApp -AuthorizationToken $AuthorizationToken -SubscriptionId $subscriptionId
This outputs:
Name : martin
Type : ApiManagement
Available : False
reason : AlreadyExists
message : martin is already in use. Please select a different name.
Name : kv
Type : KeyVault
Available : False
reason : Invalid
message : Vault name must be between 3-24 alphanumeric characters. The name must begin with a letter, end with a letter or digit, and not contain consecutive hyphens.
Name : root
Type : ManagementGroup
Available : False
reason : AlreadyExists
message : The group with the specified name already exists
Name : martin
Type : Sql
Available : False
reason : AlreadyExists
message : Specified server name is already used.
Name : storage
Type : StorageAccount
Available : False
reason : AlreadyExists
message : The storage account named storage is already taken.
Name : www
Type : WebApp
Available : False
reason : AlreadyExists
message : Hostname 'www' already exists. Please select a different name.
So in a full script, you could use something like:
$params = @{
Name = 'myCoolWebSite'
ServiceType = 'WebApp'
AuthorizationToken = Get-AccesTokenFromCurrentUser
SubscriptionId = $subscriptionId
}
if((Test-AzNameAvailability @params).Available) {
# Continue with the deployment
}
Closing notes
The checkNameAvailability API is available in several Azure providers, but because of time constraints I implemented the test only for a few of them (ApiManagement, KeyVault, ManagementGroup, Sql, StorageAccount and WebApp), so you are more than welcome to improve it.
The complete code with the functions and examples is published under my github Azure repository as: https://github.com/martin77s/Azure/blob/master/PS/Test-AzNameAvailability.ps1
