AzureCAF.psm1
|
function Export-CafResourceType { <# .SYNOPSIS Exports the Cloud Adoption Framework naming rules for one or more resource types to a CSV or Markdown file. .DESCRIPTION Writes the ResourceType/Resource/Slug/TerraformResourceType/Scope/length/casing fields from Get-CafResourceType to a CSV or Markdown file (format chosen from -Path's extension), as a reference table to share outside PowerShell. Accepts the same objects on the pipeline to export a filtered subset; defaults to every resource type if nothing is piped in. TerraformResourceType is joined with '; ' in the export when a resource type has more than one real azurerm equivalent (e.g. a VM's Linux/Windows variants), since neither CSV nor Markdown cells hold a list natively. .PARAMETER Path Where to write the export. Must end in .csv, .md or .markdown. .PARAMETER InputObject Resource type definitions to export, as returned by Get-CafResourceType. Defaults to every resource type the module knows about (equivalent to piping in `Get-CafResourceType`) if nothing is supplied. .PARAMETER Force Overwrite -Path if it already exists. .EXAMPLE Export-CafResourceType -Path ./resource-types.md Writes a Markdown table of every resource type the module knows about. .EXAMPLE Get-CafResourceType -ResourceType *storage* | Export-CafResourceType -Path ./storage-types.csv Exports just the storage-related resource types to CSV. .LINK https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/resource-abbreviations #> [CmdletBinding(SupportsShouldProcess)] param( [Parameter(Mandatory, Position = 0)] [ValidateNotNullOrEmpty()] [string] $Path, [Parameter(ValueFromPipeline)] [object[]] $InputObject, [switch] $Force ) begin { $Items = [System.Collections.Generic.List[object]]::new() } process { foreach ($Item in $InputObject) { $Items.Add($Item) } } end { $Extension = [System.IO.Path]::GetExtension($Path).ToLowerInvariant() if ($Extension -notin '.csv', '.md', '.markdown') { Write-Error "'$Path' must end in .csv, .md or .markdown." return } if ($Items.Count -eq 0) { $Items.AddRange(@(Get-CafResourceType)) } if ((Test-Path -Path $Path) -and -not $Force) { Write-Error "'$Path' already exists. Specify -Force to overwrite it." return } if (-not $PSCmdlet.ShouldProcess($Path, "Export $($Items.Count) resource type(s)")) { return } $Properties = 'ResourceType', 'Resource', 'Slug', 'TerraformResourceType', 'Scope', 'MinLength', 'MaxLength', 'Lowercase', 'Dashes' # TerraformResourceType is a single string for most resource types, but an array for the # handful where more than one real azurerm resource applies (e.g. a VM's Linux/Windows # variants) - joined here so both export formats get a readable, delimited cell instead of # Export-Csv's literal 'System.Object[]' or Markdown's default space-joined interpolation. $ExportItems = $Items | Select-Object -Property $Properties | ForEach-Object { $_.TerraformResourceType = $_.TerraformResourceType -join '; ' $_ } if ($Extension -eq '.csv') { $ExportItems | Export-Csv -Path $Path -NoTypeInformation } else { $Lines = [System.Collections.Generic.List[string]]::new() $Lines.Add("| $($Properties -join ' | ') |") $Lines.Add("| $(($Properties | ForEach-Object { '---' }) -join ' | ') |") foreach ($Item in $ExportItems) { $Cells = foreach ($Property in $Properties) { "$($Item.$Property)".Replace('|', '\|') } $Lines.Add("| $($Cells -join ' | ') |") } Set-Content -Path $Path -Value $Lines } Get-Item -Path $Path } } function Get-CafRegion { <# .SYNOPSIS Looks up the abbreviation for one or more Azure regions. .DESCRIPTION Searches the module's bundled regionDefinition.json and returns the abbreviation Get-CafResourceName's -Region resolves to (e.g. 'eastus' -> 'eus'), along with its Azure-paired region if it has one. A local, offline lookup against static data - not a replacement for Get-AzLocation, which reports live region availability from Azure. Abbreviations aren't officially published by Microsoft for every region, so coverage may lag newly-announced ones. PairedRegion is informational only ($null where a region has moved to availability zones instead) - -Region doesn't resolve against it. .PARAMETER Region The ARM region name (e.g. 'eastus'), display name (e.g. 'East US') or CAF slug (e.g. 'eus') to search for. The name/display name match as a substring; the slug matches exactly only, since partial matching on it would mostly just be ambiguous. If omitted, every region is returned. .EXAMPLE Get-CafRegion -Region eastus Returns the 'eus' abbreviation for East US, along with its paired region, 'westus'. .EXAMPLE Get-CafRegion -Region 'East US' Looks up the same region by its display name instead of its ARM name. .EXAMPLE Get-CafRegion -Region eus Looks up the same region by its slug instead. .EXAMPLE Get-CafRegion Lists every region known to the module. .LINK https://www.jlaundry.nz/2022/azure_region_abbreviations/ #> [CmdletBinding()] param( [Parameter(Position = 0)] [string] $Region ) $AllDefinitions = @(Get-CafRegionDefinition) $definitions = $AllDefinitions if ($Region) { $definitions = @($AllDefinitions | Where-Object Slug -EQ $Region) if ($definitions.Count -eq 0) { $definitions = Select-CafMatch -InputObject $AllDefinitions -Property Region -Value $Region } if ($definitions.Count -eq 0) { $definitions = Select-CafMatch -InputObject $AllDefinitions -Property DisplayName -Value $Region } } $definitions | Select-Object Region, DisplayName, Slug, PairedRegion } function Get-CafResourceName { <# .SYNOPSIS Generates an Azure resource name that follows the Cloud Adoption Framework naming convention, returning just the name as a string. .DESCRIPTION A thin wrapper around New-CafResourceName that returns just the generated Name string, for callers who don't need the ResourceType/Resource/Slug/InstanceNumber/RandomSuffix that produced it - every parameter here behaves exactly as it does there; see its help for the full length-budget/trimming/cleaning/-ConventionPath behaviour. Use New-CafResourceName directly instead if you need to trace which input produced which name, e.g. when batch-generating. .PARAMETER ResourceType The ARM resource type to generate a name for, e.g. 'Microsoft.Compute/virtualMachines'. Matches as a substring; use -Resource to disambiguate if needed. Tab-completable, and takes precedence over -Alias/-Resource if more than one is specified. .PARAMETER Alias The CAF abbreviation to generate a name for, e.g. 'vmss' - a shorter alternative to -ResourceType (also accepts -Slug). Can also disambiguate an ambiguous -ResourceType, the same way -Resource does. .PARAMETER Resource The resource's friendly name, e.g. 'Key vault' - a third alternative to -ResourceType/-Alias. Required alongside either when an ARM type covers more than one kind of resource, e.g. 'Microsoft.Web/sites' (Web app vs Function app). .PARAMETER TerraformResourceType The Terraform azurerm resource type to generate a name for, e.g. 'azurerm_storage_account' - a fourth alternative to -ResourceType/-Alias/-Resource. A resource type with more than one current real azurerm equivalent (e.g. a virtual machine's Linux/Windows variants) resolves from either one; $null for resource types Terraform doesn't model distinctly. Use Get-CafResourceType to check coverage. .PARAMETER Prefix One or more strings to prepend to the resource name, in order. Falls back to -ConventionPath's value if not specified. .PARAMETER Suffix One or more strings to append to the resource name, in order. Falls back to -ConventionPath's value if not specified. .PARAMETER Region An Azure region (ARM name, display name or CAF slug, e.g. 'eastus'/'East US'/'eus') to resolve and append after any -Suffix. Falls back to -ConventionPath's value if not specified. Use Get-CafRegion to look up supported regions. .PARAMETER Separator The character(s) used to join the prefix/slug/suffix segments. Ignored for resource types that don't permit one. Defaults to '-', or to -ConventionPath's value if it specifies one. .PARAMETER Casing Re-cases every segment of the generated name - -Prefix/-Suffix, the slug and -Region: 'Lower', 'Upper' or 'Title'. Defaults to 'None', or to -ConventionPath's value. Overridden by a resource type that requires an all-lowercase name. .PARAMETER InstanceNumber An instance number to append, for differentiating otherwise-identical resources (e.g. 'vm-sql-test-001'). Zero-padded to -InstanceNumberPadding digits. Also accepts -In. .PARAMETER InstanceNumberPadding Minimum digits to zero-pad -InstanceNumber to (default 3). Falls back to -ConventionPath's value if not specified. Also accepts -Inp. .PARAMETER Count Generates this many names in one call, with sequential instance numbers starting from -InstanceNumber (or 1). Each name gets its own random suffix if -RandomSuffixLength is used. .PARAMETER RandomSuffixLength Appends this many random lowercase alphanumeric characters, for resource types that need a globally-unique name. Falls back to -ConventionPath's value if not specified. Also accepts -Rsl. .PARAMETER RandomSuffixSeed Seeds -RandomSuffixLength's randomness, so the same seed reproduces the same name every time. Also accepts -Rss. .PARAMETER ConventionPath Path to a JSON file of organizational naming-convention defaults (created with New-CafNamingConvention) for -Prefix/-Suffix/-Region/-Separator/-Casing/-InstanceNumberPadding/ -RandomSuffixLength. Anything also specified explicitly takes precedence over the file. .PARAMETER NoClean Skip stripping characters that aren't valid for the resource type from -Prefix/-Suffix (the generated name will then fail validation if any remain). .EXAMPLE Get-CafResourceName -ResourceType Microsoft.Compute/virtualMachines -Prefix contoso, prod -Suffix 01 Generates a virtual machine name such as 'contoso-prod-vm-01'. .EXAMPLE Get-CafResourceName -ResourceType KeyVault -Prefix contoso -ResourceType matches as a substring, so this is equivalent to specifying the full 'Microsoft.KeyVault/vaults' ARM type. If a substring matches more than one resource type, narrow it down with a longer -ResourceType value and/or -Resource. .EXAMPLE Get-CafResourceName -Alias vmss -Prefix contoso If you already know the Cloud Adoption Framework abbreviation, -Alias (or its -Slug alias) is a shorter alternative to -ResourceType. .EXAMPLE Get-CafResourceName -Resource 'Key vault' -Prefix contoso -Resource alone works too, since every friendly name is unique - a third alternative to -ResourceType/-Alias for when you only remember the resource's plain-English name. .EXAMPLE Get-CafResourceName -TerraformResourceType azurerm_storage_account -Prefix contoso -RandomSuffixLength 6 Generates a storage account name identified by its Terraform resource type instead of its ARM type, alias or friendly name - a fourth alternative to -ResourceType/-Alias/-Resource. .EXAMPLE Get-CafResourceName -ResourceType Microsoft.Compute/virtualMachines -Prefix contoso, prod -Region eastus Generates 'contoso-prod-vm-eus' - -Region resolves 'eastus' to its CAF-recommended abbreviation the same way -ResourceType resolves to its slug, and inserts it after any -Suffix, so -Suffix always comes right after the resource type's slug. .EXAMPLE Get-CafResourceName -ResourceType Microsoft.Compute/virtualMachines -Prefix Contoso, Prod -Casing Upper Generates 'CONTOSO-PROD-VM' - -Casing re-cases every segment, including the resource type's own 'vm' slug, without needing to retype -Prefix/-Suffix in a particular case. .EXAMPLE Get-CafResourceName -ResourceType Microsoft.Compute/virtualMachines -Prefix contoso, prod -InstanceNumber 1 Generates 'contoso-prod-vm-001' - -InstanceNumber is zero-padded to 3 digits by default, matching the Cloud Adoption Framework's own example names such as 'vm-sql-test-001'. .EXAMPLE Get-CafResourceName -ResourceType Microsoft.Compute/virtualMachines -Prefix contoso, prod -Count 3 Generates 'contoso-prod-vm-001', 'contoso-prod-vm-002' and 'contoso-prod-vm-003' in one call. .EXAMPLE Get-CafResourceName -ResourceType Microsoft.Storage/storageAccounts -Prefix contoso -RandomSuffixLength 6 Generates a storage account name such as 'contosostabcdef', with 6 random characters appended to help ensure the globally-unique name doesn't collide with one that already exists. .EXAMPLE Get-CafResourceName -ResourceType Microsoft.Storage/storageAccounts -Prefix contoso -RandomSuffixLength 6 -RandomSuffixSeed 42 Generates the same storage account name every time it's run, since the random suffix is seeded. .EXAMPLE Get-CafResourceName -ResourceType Microsoft.Web/sites -Resource 'Function app' -Prefix contoso, prod Generates a function app name. -Resource is required here because 'Microsoft.Web/sites' is also used for web apps, which use a different abbreviation. .EXAMPLE Get-CafResourceName -ResourceType Microsoft.Web/sites -Alias func -Prefix contoso, prod Equivalent to the previous example - -Alias disambiguates 'Microsoft.Web/sites' just like -Resource does, if you already know the abbreviation rather than the friendly name. .EXAMPLE Get-CafResourceType -Slug kv | Get-CafResourceName -Prefix contoso -RandomSuffixLength 4 Pipes the resource type definition for the 'kv' (Key Vault) abbreviation straight into Get-CafResourceName. .EXAMPLE Get-CafResourceName -ResourceType Microsoft.Compute/virtualMachines -Prefix contoso -ConventionPath ./contoso.json Uses -Prefix explicitly, but falls back to whatever -Suffix/-Region/-Separator/etc. are saved in contoso.json (see New-CafNamingConvention) for anything not specified here. .EXAMPLE Import-Csv ./resources.csv | Get-CafResourceName Batch-generates a name for every row of resources.csv, which needs at least a ResourceType or Alias column, and may also have Resource/Prefix/Suffix/Separator/InstanceNumber columns. .LINK https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/resource-abbreviations #> [CmdletBinding()] param( [Parameter(Position = 0, ValueFromPipelineByPropertyName)] [ValidateNotNullOrEmpty()] [string] $ResourceType, [Parameter(ValueFromPipelineByPropertyName)] [Alias('Slug')] [ValidateNotNullOrEmpty()] [string] $Alias, [Parameter(ValueFromPipelineByPropertyName)] [ValidateNotNullOrEmpty()] [string] $Resource, [Parameter(ValueFromPipelineByPropertyName)] [Alias('Tf')] [ValidateNotNullOrEmpty()] [string] $TerraformResourceType, [Parameter(ValueFromPipelineByPropertyName)] [string[]] $Prefix, [Parameter(ValueFromPipelineByPropertyName)] [string[]] $Suffix, [Parameter(ValueFromPipelineByPropertyName)] [string] $Region, [Parameter(ValueFromPipelineByPropertyName)] [string] $Separator = '-', [Parameter(ValueFromPipelineByPropertyName)] [ValidateSet('None', 'Lower', 'Upper', 'Title')] [string] $Casing = 'None', [Parameter(ValueFromPipelineByPropertyName)] [Alias('In')] [ValidateRange(0, [int]::MaxValue)] [int] $InstanceNumber, [Parameter(ValueFromPipelineByPropertyName)] [Alias('Inp')] [ValidateRange(1, 10)] [int] $InstanceNumberPadding = 3, [Parameter(ValueFromPipelineByPropertyName)] [ValidateRange(1, 1000)] [int] $Count = 1, [Parameter(ValueFromPipelineByPropertyName)] [Alias('Rsl')] [ValidateRange(0, 24)] [int] $RandomSuffixLength = 0, [Parameter(ValueFromPipelineByPropertyName)] [Alias('Rss')] [int] $RandomSuffixSeed, [string] $ConventionPath, [Parameter(ValueFromPipelineByPropertyName)] [switch] $NoClean ) begin { # Every parameter above exists only to be bound and forwarded to New-CafResourceName via the # proxy-command plumbing below (for CmdletBinding/tab-completion/help purposes), never read # directly here - this satisfies PSScriptAnalyzer's PSReviewUnusedParameter rule. $null = $ResourceType, $Alias, $Resource, $TerraformResourceType, $Prefix, $Suffix, $Region, $Separator, $Casing, $InstanceNumber, $InstanceNumberPadding, $Count, $RandomSuffixLength, $RandomSuffixSeed, $ConventionPath, $NoClean # A hand-rolled `New-CafResourceName @PSBoundParameters` here would be unsafe: $PSBoundParameters # keeps stale values from a previous pipeline object once a later object lacks that property (a # known PowerShell quirk), which would leak e.g. one row's -Suffix into the next row's call. The # proxy-command pattern below instead feeds each pipeline object into New-CafResourceName's own # pipeline binding, which rebinds correctly per object. $WrappedCommand = $ExecutionContext.InvokeCommand.GetCommand('New-CafResourceName', [System.Management.Automation.CommandTypes]::Function) $ScriptCmd = { & $WrappedCommand @PSBoundParameters | ForEach-Object Name } $SteppablePipeline = $ScriptCmd.GetSteppablePipeline($MyInvocation.CommandOrigin) $SteppablePipeline.Begin($PSCmdlet) } process { $SteppablePipeline.Process($_) } end { $SteppablePipeline.End() } } function Get-CafResourceType { <# .SYNOPSIS Looks up the Cloud Adoption Framework naming rules for one or more Azure resource types. .DESCRIPTION Searches the module's bundled resourceDefinition.json and returns a resource type's recommended CAF abbreviation, naming scope, length limits and casing rules - the same rules Get-CafResourceName builds a name against. A local, offline lookup against static data - not a replacement for Get-AzResourceProvider, which reports live resource provider availability from Azure. .PARAMETER ResourceType The ARM resource type to search for, e.g. 'Microsoft.Compute/virtualMachines'. Matches as a substring; pass an explicit wildcard pattern (e.g. 'Microsoft.Compute/*') for tighter control. If omitted, all resource types are returned (optionally filtered by -Resource/-Alias). .PARAMETER Resource The friendly resource name to search for, e.g. 'Virtual machine'. Matches as a substring. Useful to disambiguate ARM resource types that cover more than one kind of resource. .PARAMETER Alias The CAF abbreviation to search for, e.g. 'vm'. Matches as a substring, and also accepts -Slug. .PARAMETER TerraformResourceType The Terraform azurerm resource type to search for, e.g. 'azurerm_storage_account'. Matches as a substring against any value on a resource type's TerraformResourceType property - which is usually a single string, but an array for the handful of resource types with more than one current real azurerm equivalent (e.g. 'azurerm_linux_virtual_machine' and 'azurerm_windows_virtual_machine' for a virtual machine); either one resolves it. $null for resource types Terraform doesn't model distinctly. .EXAMPLE Get-CafResourceType -ResourceType Microsoft.Compute/virtualMachines Returns the naming rule for an Azure virtual machine. .EXAMPLE Get-CafResourceType -ResourceType storageAccount Finds resource types whose ARM type contains 'storageAccount'. .EXAMPLE Get-CafResourceType -Alias vm Finds the resource type(s) that use the 'vm' abbreviation. .EXAMPLE Get-CafResourceType -TerraformResourceType azurerm_storage_account Finds the resource type that corresponds to the 'azurerm_storage_account' Terraform resource. .EXAMPLE Get-CafResourceType Lists every resource type known to the module. .LINK https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/resource-abbreviations #> [CmdletBinding()] param( [Parameter(Position = 0)] [string] $ResourceType, [string] $Resource, [Alias('Slug')] [string] $Alias, [Alias('Tf')] [string] $TerraformResourceType ) $definitions = @(Get-CafResourceDefinition) if ($ResourceType) { $definitions = Select-CafMatch -InputObject $definitions -Property ResourceType -Value $ResourceType } if ($Resource) { $definitions = Select-CafMatch -InputObject $definitions -Property Resource -Value $Resource } if ($Alias) { $definitions = Select-CafMatch -InputObject $definitions -Property Slug -Value $Alias } if ($TerraformResourceType) { $definitions = Select-CafMatch -InputObject $definitions -Property TerraformResourceType -Value $TerraformResourceType } $definitions | Select-Object ResourceType, Resource, Slug, TerraformResourceType, Scope, MinLength, MaxLength, Lowercase, Dashes } function New-CafNamingConvention { <# .SYNOPSIS Saves a reusable set of Get-CafResourceName defaults to a JSON file, so your organization's naming convention doesn't need to be retyped on every call. .DESCRIPTION Writes a small JSON file that Get-CafResourceName's -ConventionPath reads defaults from for -Prefix, -Suffix, -Region, -Separator, -Casing, -InstanceNumberPadding and -RandomSuffixLength. Anything also passed explicitly to Get-CafResourceName still takes precedence over the file. -RandomSuffixSeed deliberately isn't included: a shared seed would make the "random" suffix identical for everyone using the file, defeating the uniqueness -RandomSuffixLength exists for - it only makes sense passed directly, per call. .PARAMETER Path Where to save the convention file, e.g. './contoso.json'. .PARAMETER Prefix One or more strings to use as the default -Prefix, e.g. a company name or environment. .PARAMETER Suffix One or more strings to use as the default -Suffix. .PARAMETER Region An Azure region (ARM name, display name or slug) to use as the default -Region - resolved and stored as its ARM name, so an unrecognized value is caught here rather than on every later call. .PARAMETER Separator The default -Separator. Omit to leave this to Get-CafResourceName's own default ('-'). .PARAMETER Casing The default -Casing ('None', 'Lower', 'Upper' or 'Title'). Omit to leave this to Get-CafResourceName's own default ('None'). .PARAMETER InstanceNumberPadding The default -InstanceNumberPadding. Omit to leave this to Get-CafResourceName's own default (3). Also accepts -Inp as an alias. .PARAMETER RandomSuffixLength The default -RandomSuffixLength. Omit to leave this to Get-CafResourceName's own default (0, i.e. no random suffix unless a call asks for one explicitly). Also accepts -Rsl as an alias. .PARAMETER Force Overwrite -Path if it already exists. .EXAMPLE New-CafNamingConvention -Path ./contoso.json -Prefix contoso, prod -Region eastus -Separator '-' -InstanceNumberPadding 2 Saves a convention so that Get-CafResourceName -ConventionPath ./contoso.json applies that prefix, region, separator and padding by default. .EXAMPLE Get-CafResourceName -ResourceType Microsoft.Compute/virtualMachines -ConventionPath ./contoso.json -InstanceNumber 1 Uses the saved convention, overriding only -InstanceNumber for this particular call. .LINK https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/resource-naming#choose-naming-components #> [CmdletBinding(SupportsShouldProcess)] param( [Parameter(Mandatory, Position = 0)] [string] $Path, [string[]] $Prefix, [string[]] $Suffix, [string] $Region, [string] $Separator, [ValidateSet('None', 'Lower', 'Upper', 'Title')] [string] $Casing, [Alias('Inp')] [ValidateRange(1, 10)] [int] $InstanceNumberPadding, [Alias('Rsl')] [ValidateRange(0, 24)] [int] $RandomSuffixLength, [switch] $Force ) if ((Test-Path -Path $Path) -and -not $Force) { Write-Error "'$Path' already exists. Specify -Force to overwrite it." return } $Convention = [ordered]@{} if ($PSBoundParameters.ContainsKey('Prefix')) { $Convention.Prefix = $Prefix } if ($PSBoundParameters.ContainsKey('Suffix')) { $Convention.Suffix = $Suffix } if ($PSBoundParameters.ContainsKey('Region')) { $RegionDefinition = Resolve-CafRegion -Region $Region if (-not $RegionDefinition) { return } $Convention.Region = $RegionDefinition.Region } if ($PSBoundParameters.ContainsKey('Separator')) { $Convention.Separator = $Separator } if ($PSBoundParameters.ContainsKey('Casing')) { $Convention.Casing = $Casing } if ($PSBoundParameters.ContainsKey('InstanceNumberPadding')) { $Convention.InstanceNumberPadding = $InstanceNumberPadding } if ($PSBoundParameters.ContainsKey('RandomSuffixLength')) { $Convention.RandomSuffixLength = $RandomSuffixLength } if ($Convention.Count -eq 0) { Write-Error 'Specify at least one of -Prefix, -Suffix, -Region, -Separator, -Casing, -InstanceNumberPadding or -RandomSuffixLength.' return } if ($PSCmdlet.ShouldProcess($Path, 'Create naming convention file')) { $Convention | ConvertTo-Json | Set-Content -Path $Path Get-Item -Path $Path } } function New-CafResourceName { <# .SYNOPSIS Generates an Azure resource name that follows the Cloud Adoption Framework naming convention, returning the full result as an object. .DESCRIPTION Builds a resource name from an optional prefix, the CAF-recommended abbreviation for the given Azure resource type, and an optional suffix - trimmed, cleaned and cased to fit that resource type's length limit, allowed characters and casing rules. Returns an object with Name, ResourceType, Resource, Slug, TerraformResourceType, InstanceNumber and RandomSuffix properties - use Get-CafResourceName instead for just the name as a plain string. Accepts pipeline input by property name, so a list of resource specs (e.g. from a CSV) can be batch- generated in one call - see the pipeline example below. Use Get-CafResourceType to discover the accepted ResourceType/Resource values, and -Verbose to see the length-budget reasoning behind a result. .PARAMETER ResourceType The ARM resource type to generate a name for, e.g. 'Microsoft.Compute/virtualMachines'. Matches as a substring; use -Resource to disambiguate if needed. Tab-completable, and takes precedence over -Alias/-Resource if more than one is specified. .PARAMETER Alias The CAF abbreviation to generate a name for, e.g. 'vmss' - a shorter alternative to -ResourceType (also accepts -Slug). Can also disambiguate an ambiguous -ResourceType, the same way -Resource does. .PARAMETER Resource The resource's friendly name, e.g. 'Key vault' - a third alternative to -ResourceType/-Alias. Required alongside either when an ARM type covers more than one kind of resource, e.g. 'Microsoft.Web/sites' (Web app vs Function app). .PARAMETER TerraformResourceType The Terraform azurerm resource type to generate a name for, e.g. 'azurerm_storage_account' - a fourth alternative to -ResourceType/-Alias/-Resource. A resource type with more than one current real azurerm equivalent (e.g. a virtual machine's Linux/Windows variants) resolves from either one; $null for resource types Terraform doesn't model distinctly. Use Get-CafResourceType to check coverage. .PARAMETER Prefix One or more strings to prepend to the resource name, in order. Falls back to -ConventionPath's value if not specified. .PARAMETER Suffix One or more strings to append to the resource name, in order. Falls back to -ConventionPath's value if not specified. .PARAMETER Region An Azure region (ARM name, display name or CAF slug, e.g. 'eastus'/'East US'/'eus') to resolve and append after any -Suffix. Falls back to -ConventionPath's value if not specified. Use Get-CafRegion to look up supported regions. .PARAMETER Separator The character(s) used to join the prefix/slug/suffix segments. Ignored for resource types that don't permit one. Defaults to '-', or to -ConventionPath's value if it specifies one. .PARAMETER Casing Re-cases every segment of the generated name - -Prefix/-Suffix, the slug and -Region: 'Lower', 'Upper' or 'Title'. Defaults to 'None', or to -ConventionPath's value. Overridden by a resource type that requires an all-lowercase name. Doesn't affect the returned object's Slug property, which always reports the canonical CAF abbreviation. .PARAMETER InstanceNumber An instance number to append, for differentiating otherwise-identical resources (e.g. 'vm-sql-test-001'). Zero-padded to -InstanceNumberPadding digits. Also accepts -In. .PARAMETER InstanceNumberPadding Minimum digits to zero-pad -InstanceNumber to (default 3). Falls back to -ConventionPath's value if not specified. Also accepts -Inp. .PARAMETER Count Generates this many names in one call, with sequential instance numbers starting from -InstanceNumber (or 1). Each name gets its own random suffix if -RandomSuffixLength is used. .PARAMETER RandomSuffixLength Appends this many random lowercase alphanumeric characters, for resource types that need a globally-unique name. Falls back to -ConventionPath's value if not specified. Also accepts -Rsl. .PARAMETER RandomSuffixSeed Seeds -RandomSuffixLength's randomness, so the same seed reproduces the same name every time. Also accepts -Rss. .PARAMETER ConventionPath Path to a JSON file of organizational naming-convention defaults (created with New-CafNamingConvention) for -Prefix/-Suffix/-Region/-Separator/-Casing/-InstanceNumberPadding/ -RandomSuffixLength. Anything also specified explicitly takes precedence over the file. .PARAMETER NoClean Skip stripping characters that aren't valid for the resource type from -Prefix/-Suffix (the generated name will then fail validation if any remain). .EXAMPLE New-CafResourceName -ResourceType Microsoft.Compute/virtualMachines -Prefix contoso, prod -Suffix 01 Generates a virtual machine name such as 'contoso-prod-vm-01', returned as an object with Name, ResourceType, Resource, Slug, TerraformResourceType, InstanceNumber and RandomSuffix properties. .EXAMPLE New-CafResourceName -ResourceType KeyVault -Prefix contoso -ResourceType matches as a substring, so this is equivalent to specifying the full 'Microsoft.KeyVault/vaults' ARM type. If a substring matches more than one resource type, narrow it down with a longer -ResourceType value and/or -Resource. .EXAMPLE New-CafResourceName -Alias vmss -Prefix contoso If you already know the Cloud Adoption Framework abbreviation, -Alias (or its -Slug alias) is a shorter alternative to -ResourceType. .EXAMPLE New-CafResourceName -Resource 'Key vault' -Prefix contoso -Resource alone works too, since every friendly name is unique - a third alternative to -ResourceType/-Alias for when you only remember the resource's plain-English name. .EXAMPLE New-CafResourceName -TerraformResourceType azurerm_storage_account -Prefix contoso -RandomSuffixLength 6 Generates a storage account name identified by its Terraform resource type instead of its ARM type, alias or friendly name - a fourth alternative to -ResourceType/-Alias/-Resource. .EXAMPLE New-CafResourceName -ResourceType Microsoft.Compute/virtualMachines -Prefix contoso, prod -Region eastus Generates 'contoso-prod-vm-eus' - -Region resolves 'eastus' to its CAF-recommended abbreviation the same way -ResourceType resolves to its slug, and inserts it after any -Suffix, so -Suffix always comes right after the resource type's slug. .EXAMPLE New-CafResourceName -ResourceType Microsoft.Compute/virtualMachines -Prefix Contoso, Prod -Casing Upper Generates 'CONTOSO-PROD-VM' - -Casing re-cases every segment, including the resource type's own 'vm' slug, without needing to retype -Prefix/-Suffix in a particular case. The returned Slug property still reports the canonical 'vm', regardless of -Casing. .EXAMPLE New-CafResourceName -ResourceType Microsoft.Compute/virtualMachines -Prefix contoso, prod -InstanceNumber 1 Generates 'contoso-prod-vm-001' - -InstanceNumber is zero-padded to 3 digits by default, matching the Cloud Adoption Framework's own example names such as 'vm-sql-test-001'. .EXAMPLE New-CafResourceName -ResourceType Microsoft.Compute/virtualMachines -Prefix contoso, prod -Count 3 Generates 'contoso-prod-vm-001', 'contoso-prod-vm-002' and 'contoso-prod-vm-003' in one call. .EXAMPLE New-CafResourceName -ResourceType Microsoft.Storage/storageAccounts -Prefix contoso -RandomSuffixLength 6 Generates a storage account name such as 'contosostabcdef', with 6 random characters appended to help ensure the globally-unique name doesn't collide with one that already exists. .EXAMPLE New-CafResourceName -ResourceType Microsoft.Storage/storageAccounts -Prefix contoso -RandomSuffixLength 6 -RandomSuffixSeed 42 Generates the same storage account name every time it's run, since the random suffix is seeded. .EXAMPLE New-CafResourceName -ResourceType Microsoft.Web/sites -Resource 'Function app' -Prefix contoso, prod Generates a function app name. -Resource is required here because 'Microsoft.Web/sites' is also used for web apps, which use a different abbreviation. .EXAMPLE New-CafResourceName -ResourceType Microsoft.Web/sites -Alias func -Prefix contoso, prod Equivalent to the previous example - -Alias disambiguates 'Microsoft.Web/sites' just like -Resource does, if you already know the abbreviation rather than the friendly name. .EXAMPLE Get-CafResourceType -Slug kv | New-CafResourceName -Prefix contoso -RandomSuffixLength 4 Pipes the resource type definition for the 'kv' (Key Vault) abbreviation straight into New-CafResourceName. .EXAMPLE New-CafResourceName -ResourceType Microsoft.Compute/virtualMachines -Prefix contoso -ConventionPath ./contoso.json Uses -Prefix explicitly, but falls back to whatever -Suffix/-Region/-Separator/etc. are saved in contoso.json (see New-CafNamingConvention) for anything not specified here. .EXAMPLE Import-Csv ./resources.csv | New-CafResourceName | Export-Csv ./generated-names.csv Batch-generates a name for every row of resources.csv, which needs at least a ResourceType, Alias or TerraformResourceType column, and may also have Resource/Prefix/Suffix/Separator/ InstanceNumber columns. The ResourceType/Resource/Slug/TerraformResourceType/InstanceNumber/ RandomSuffix that produced each name is kept alongside it, rather than returning bare strings that lose track of which input row (or which -Count iteration) each one came from. .LINK https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/resource-abbreviations #> [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '', Justification = 'Pure in-memory name generator - the New verb reflects that it returns a new result object (as opposed to Get-CafResourceName''s plain string), not that it changes any external state.')] [CmdletBinding()] param( [Parameter(Position = 0, ValueFromPipelineByPropertyName)] [ValidateNotNullOrEmpty()] [string] $ResourceType, [Parameter(ValueFromPipelineByPropertyName)] [Alias('Slug')] [ValidateNotNullOrEmpty()] [string] $Alias, [Parameter(ValueFromPipelineByPropertyName)] [ValidateNotNullOrEmpty()] [string] $Resource, [Parameter(ValueFromPipelineByPropertyName)] [Alias('Tf')] [ValidateNotNullOrEmpty()] [string] $TerraformResourceType, [Parameter(ValueFromPipelineByPropertyName)] [string[]] $Prefix, [Parameter(ValueFromPipelineByPropertyName)] [string[]] $Suffix, [Parameter(ValueFromPipelineByPropertyName)] [string] $Region, [Parameter(ValueFromPipelineByPropertyName)] [string] $Separator = '-', [Parameter(ValueFromPipelineByPropertyName)] [ValidateSet('None', 'Lower', 'Upper', 'Title')] [string] $Casing = 'None', [Parameter(ValueFromPipelineByPropertyName)] [Alias('In')] [ValidateRange(0, [int]::MaxValue)] [int] $InstanceNumber, [Parameter(ValueFromPipelineByPropertyName)] [Alias('Inp')] [ValidateRange(1, 10)] [int] $InstanceNumberPadding = 3, [Parameter(ValueFromPipelineByPropertyName)] [ValidateRange(1, 1000)] [int] $Count = 1, [Parameter(ValueFromPipelineByPropertyName)] [Alias('Rsl')] [ValidateRange(0, 24)] [int] $RandomSuffixLength = 0, [Parameter(ValueFromPipelineByPropertyName)] [Alias('Rss')] [int] $RandomSuffixSeed, [string] $ConventionPath, [Parameter(ValueFromPipelineByPropertyName)] [switch] $NoClean ) begin { function Get-CleanString { param ( [string[]]$InputObject, [string]$Pattern ) foreach ($Str in $InputObject) { $Str -replace $Pattern, '' } } function Get-CasedString { param ( [string[]]$InputObject, [string]$Casing ) foreach ($Str in $InputObject) { switch ($Casing) { 'Lower' { $Str.ToLower() } 'Upper' { $Str.ToUpper() } # Lowercased first so an all-caps segment (e.g. 'NYC') isn't left alone as a # presumed acronym - .NET's ToTitleCase skips re-casing words that are already # all-uppercase. 'Title' { (Get-Culture).TextInfo.ToTitleCase($Str.ToLower()) } default { $Str } } } } $Convention = $null if ($ConventionPath) { if (-not (Test-Path -Path $ConventionPath -PathType Leaf)) { $PSCmdlet.ThrowTerminatingError( [System.Management.Automation.ErrorRecord]::new( [System.IO.FileNotFoundException]::new("Naming convention file not found: '$ConventionPath'."), 'ConventionFileNotFound', [System.Management.Automation.ErrorCategory]::ObjectNotFound, $ConventionPath ) ) } try { $Convention = Get-Content -Path $ConventionPath -Raw -ErrorAction Stop | ConvertFrom-Json -ErrorAction Stop Write-Verbose "Loaded naming convention from '$ConventionPath'." } catch { $PSCmdlet.ThrowTerminatingError($_) } } } process { if (-not $ResourceType -and -not $Alias -and -not $Resource -and -not $TerraformResourceType) { Write-Error 'Specify -ResourceType, -Alias, -Resource or -TerraformResourceType to identify the resource type.' return } $definition = Resolve-CafResourceDefinition -ResourceType $ResourceType -Alias $Alias -Resource $Resource -TerraformResourceType $TerraformResourceType if (-not $definition) { return } Write-Verbose "Resolved to $($definition.ResourceType) [$($definition.Resource)] (slug '$($definition.Slug)', max length $($definition.MaxLength), dashes $($definition.Dashes), lowercase $($definition.Lowercase))." $EffectivePrefix = if ($PSBoundParameters.ContainsKey('Prefix')) { $Prefix } else { $Convention.Prefix } $EffectiveSuffix = if ($PSBoundParameters.ContainsKey('Suffix')) { $Suffix } else { $Convention.Suffix } $EffectiveRegion = if ($PSBoundParameters.ContainsKey('Region')) { $Region } else { $Convention.Region } if ($EffectiveRegion) { $RegionDefinition = Resolve-CafRegion -Region $EffectiveRegion if (-not $RegionDefinition) { return } Write-Verbose "Resolved region '$EffectiveRegion' to '$($RegionDefinition.Region)' (slug '$($RegionDefinition.Slug)')." $EffectiveRegionSlug = $RegionDefinition.Slug } $EffectiveSeparator = if ($PSBoundParameters.ContainsKey('Separator')) { $Separator } elseif ($null -ne $Convention.Separator) { $Convention.Separator } else { $Separator } $EffectiveCasing = if ($PSBoundParameters.ContainsKey('Casing')) { $Casing } elseif ($Convention.Casing) { $Convention.Casing } else { $Casing } $EffectiveInstanceNumberPadding = if ($PSBoundParameters.ContainsKey('InstanceNumberPadding')) { $InstanceNumberPadding } elseif ($Convention.InstanceNumberPadding) { $Convention.InstanceNumberPadding } else { $InstanceNumberPadding } $EffectiveRandomSuffixLength = if ($PSBoundParameters.ContainsKey('RandomSuffixLength')) { $RandomSuffixLength } elseif ($null -ne $Convention.RandomSuffixLength) { $Convention.RandomSuffixLength } else { $RandomSuffixLength } if ($EffectiveInstanceNumberPadding -lt 1 -or $EffectiveInstanceNumberPadding -gt 10) { Write-Error "InstanceNumberPadding from the naming convention must be between 1 and 10, but was $EffectiveInstanceNumberPadding." return } if ($EffectiveRandomSuffixLength -lt 0 -or $EffectiveRandomSuffixLength -gt 24) { Write-Error "RandomSuffixLength from the naming convention must be between 0 and 24, but was $EffectiveRandomSuffixLength." return } if ($EffectiveCasing -notin 'None', 'Lower', 'Upper', 'Title') { Write-Error "Casing from the naming convention must be one of 'None', 'Lower', 'Upper' or 'Title', but was '$EffectiveCasing'." return } if ($NoClean) { $CleanPrefix = $EffectivePrefix $CleanSuffix = $EffectiveSuffix $CleanRegionSlug = $EffectiveRegionSlug } else { $CleanPrefix = Get-CleanString -InputObject $EffectivePrefix -Pattern $definition.InvalidCharsRegex $CleanSuffix = Get-CleanString -InputObject $EffectiveSuffix -Pattern $definition.InvalidCharsRegex $CleanRegionSlug = Get-CleanString -InputObject $EffectiveRegionSlug -Pattern $definition.InvalidCharsRegex } # $CasedSlug is kept separate from $definition.Slug (used as-is for the returned Slug property # and in error/verbose messages) so casing only affects the composed Name, not the canonical # CAF abbreviation callers can use to cross-reference Get-CafResourceType. $CasedSlug = $definition.Slug if ($EffectiveCasing -ne 'None') { $CleanPrefix = Get-CasedString -InputObject $CleanPrefix -Casing $EffectiveCasing $CleanSuffix = Get-CasedString -InputObject $CleanSuffix -Casing $EffectiveCasing $CleanRegionSlug = Get-CasedString -InputObject $CleanRegionSlug -Casing $EffectiveCasing $CasedSlug = Get-CasedString -InputObject $CasedSlug -Casing $EffectiveCasing } $ActualSeparator = if ($definition.Dashes) { $EffectiveSeparator } else { '' } $HasInstanceNumber = $PSBoundParameters.ContainsKey('InstanceNumber') -or $Count -gt 1 $StartInstanceNumber = if ($PSBoundParameters.ContainsKey('InstanceNumber')) { $InstanceNumber } else { 1 } $EndInstanceNumber = $StartInstanceNumber + $Count - 1 # Reserve space based on the longest instance number in the sequence, so the trimmed base name # (prefix/slug/region/suffix) is the same length for every generated name, not just the first one. $InstanceSegment = if ($HasInstanceNumber) { $EndInstanceNumber.ToString().PadLeft($EffectiveInstanceNumberPadding, '0') } else { $null } $reservedLength = 0 $reservedDescriptions = @() if ($InstanceSegment) { $reservedLength += $InstanceSegment.Length + $ActualSeparator.Length $reservedDescriptions += 'the instance number' } if ($EffectiveRandomSuffixLength -gt 0) { $reservedLength += $EffectiveRandomSuffixLength + $ActualSeparator.Length $reservedDescriptions += 'the random suffix' } $mainBudget = $definition.MaxLength - $reservedLength if ($reservedDescriptions.Count -gt 0) { Write-Verbose "Reserving $reservedLength character(s) for $($reservedDescriptions -join ' and '); $mainBudget of $($definition.MaxLength) remain for the prefix/slug/region/suffix." } else { Write-Verbose "No reserved segments; the full $mainBudget character limit is available for the prefix/slug/region/suffix." } if ($mainBudget -lt $definition.Slug.Length) { Write-Error "Not enough room within the $($definition.MaxLength) character limit for $($definition.ResourceType): '$($definition.Slug)' needs $($definition.Slug.Length) characters, but only $mainBudget are available after reserving space for $($reservedDescriptions -join ' and ')." return } $resourceArr = @($CleanPrefix) + @($CasedSlug) + @($CleanSuffix) + @($CleanRegionSlug) | Where-Object { $_ } $resourceName = $resourceArr -join $ActualSeparator Write-Verbose "Joined '$($resourceArr -join "', '")' with separator '$ActualSeparator' -> '$resourceName' ($($resourceName.Length) characters)." if ($resourceName.Length -gt $mainBudget) { $beforeTrimLength = $resourceName.Length $resourceName = $resourceName.Substring(0, $mainBudget) $reservedNote = if ($reservedDescriptions.Count -gt 0) { " (after reserving space for $($reservedDescriptions -join ' and '))" } else { '' } Write-Warning "Resource name has been trimmed to $mainBudget characters due to the $($definition.MaxLength) character max length restriction$reservedNote." Write-Verbose "Trimmed from $beforeTrimLength to $mainBudget characters -> '$resourceName'." } # A single shared Random, created once per pipeline item rather than per generated name, so a # -RandomSuffixSeed produces a reproducible sequence of distinct suffixes across the whole -Count batch. $Random = if ($EffectiveRandomSuffixLength -gt 0) { if ($PSBoundParameters.ContainsKey('RandomSuffixSeed')) { [System.Random]::new($RandomSuffixSeed) } else { [System.Random]::new() } } else { $null } $CharPool = 'abcdefghijklmnopqrstuvwxyz0123456789' for ($InstanceCounter = $StartInstanceNumber; $InstanceCounter -le $EndInstanceNumber; $InstanceCounter++) { $FinalName = $resourceName if ($HasInstanceNumber) { $CurrentInstanceSegment = $InstanceCounter.ToString().PadLeft($EffectiveInstanceNumberPadding, '0') $FinalName = $FinalName + $ActualSeparator + $CurrentInstanceSegment Write-Verbose "Appended instance segment '$CurrentInstanceSegment' -> '$FinalName'." } if ($EffectiveRandomSuffixLength -gt 0) { # Always lowercase alphanumeric, even for resource types that allow uppercase - the # random suffix exists for uniqueness, not communication, and 36^RandomSuffixLength is # already far more entropy than a uniqueness suffix needs. $RandomSuffix = -join (1..$EffectiveRandomSuffixLength | ForEach-Object { $CharPool[$Random.Next($CharPool.Length)] }) $FinalName = $FinalName + $ActualSeparator + $RandomSuffix Write-Verbose "Appended random suffix '$RandomSuffix' -> '$FinalName'." } if ($definition.Lowercase -and $FinalName -cmatch '[A-Z]') { $FinalName = $FinalName.ToLower() Write-Warning 'Resource name has been converted to lower case due to naming requirement.' Write-Verbose "Converted to lowercase -> '$FinalName'." } if ($FinalName -notmatch $definition.ValidationRegex) { Write-Error "The generated name '$FinalName' is not valid for $($definition.ResourceType) (pattern: $($definition.ValidationRegex))." } else { Write-Verbose "Final result: '$FinalName'." [pscustomobject]@{ Name = $FinalName ResourceType = $definition.ResourceType Resource = $definition.Resource Slug = $definition.Slug TerraformResourceType = $definition.TerraformResourceType InstanceNumber = if ($HasInstanceNumber) { $InstanceCounter } else { $null } RandomSuffix = if ($EffectiveRandomSuffixLength -gt 0) { $RandomSuffix } else { $null } } } } } } function Test-CafResourceName { <# .SYNOPSIS Tests whether a name complies with the Cloud Adoption Framework naming rules for an Azure resource type. .DESCRIPTION Checks a resource name against the same rules Get-CafResourceName enforces when building one: minimum/maximum length, required casing, whether a dash is allowed, and the overall set of valid characters. Returns an object with each rule's pass/fail, a plain-English Reason when invalid, and an overall IsValid - or just true/false with -Quiet. IsValid is the authoritative result; the per-rule fields are a diagnostic breakdown that can't always add up to it perfectly (e.g. a character disallowed only as the *first* character is flagged by -ValidCharacters wherever it appears, even if IsValid is still true). Treat IsValid as the source of truth. .PARAMETER Name The resource name to test, e.g. 'contoso-prod-vm-001'. .PARAMETER ResourceType The ARM resource type to test the name against, e.g. 'Microsoft.Compute/virtualMachines'. Matches as a substring; takes precedence over -Alias/-Resource if more than one is specified. .PARAMETER Alias The CAF abbreviation to test the name against, e.g. 'vmss' - a shorter alternative to -ResourceType (also accepts -Slug). Can also disambiguate an ambiguous -ResourceType, the same way -Resource does. .PARAMETER Resource The resource's friendly name, e.g. 'Key vault' - a third alternative to -ResourceType/-Alias. Required alongside either when an ARM type covers more than one kind of resource, e.g. 'Microsoft.Web/sites' (Web app vs Function app). .PARAMETER TerraformResourceType The Terraform azurerm resource type to test the name against, e.g. 'azurerm_storage_account' - a fourth alternative to -ResourceType/-Alias/-Resource. A resource type with more than one current real azurerm equivalent (e.g. a virtual machine's Linux/Windows variants) resolves from either one; $null for resource types Terraform doesn't model distinctly. Use Get-CafResourceType to check coverage. .PARAMETER Quiet Return only an overall $true/$false instead of the full breakdown object. .EXAMPLE Test-CafResourceName -Name 'contoso-prod-vm-001' -ResourceType Microsoft.Compute/virtualMachines Returns an object showing which naming rules the name passes or fails, and an overall IsValid. .EXAMPLE (Test-CafResourceName -Name 'CONTOSO' -ResourceType Microsoft.Storage/storageAccounts).Reason Returns 'Name must be all lowercase for this resource type.' - Reason explains an invalid result in plain English; it's $null when IsValid is $true. .EXAMPLE Test-CafResourceName -Name 'Contoso_VM!' -Alias vm -Quiet Returns $false - the name is uppercase, contains an underscore and an exclamation mark, none of which are valid for a virtual machine name. .EXAMPLE Test-CafResourceName -Name 'contoso-kv' -Resource 'Key vault' -Resource alone works too, since every friendly name is unique - a third alternative to -ResourceType/-Alias for when you only remember the resource's plain-English name. .EXAMPLE Test-CafResourceName -Name 'contoso-st' -TerraformResourceType azurerm_storage_account Tests a name identified by its Terraform resource type instead of its ARM type, alias or friendly name - a fourth alternative to -ResourceType/-Alias/-Resource. .EXAMPLE Get-CafResourceName -ResourceType Microsoft.Storage/storageAccounts -Prefix contoso -RandomSuffixLength 6 | Test-CafResourceName -ResourceType Microsoft.Storage/storageAccounts -Quiet Round-trips a name generated by Get-CafResourceName back through Test-CafResourceName. .LINK https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/resource-abbreviations #> [CmdletBinding()] param( [Parameter(Mandatory, Position = 0, ValueFromPipeline)] [ValidateNotNullOrEmpty()] [string] $Name, [Parameter(Position = 1, ValueFromPipelineByPropertyName)] [ValidateNotNullOrEmpty()] [string] $ResourceType, [Parameter(ValueFromPipelineByPropertyName)] [Alias('Slug')] [ValidateNotNullOrEmpty()] [string] $Alias, [Parameter(ValueFromPipelineByPropertyName)] [ValidateNotNullOrEmpty()] [string] $Resource, [Parameter(ValueFromPipelineByPropertyName)] [Alias('Tf')] [ValidateNotNullOrEmpty()] [string] $TerraformResourceType, [switch] $Quiet ) process { if (-not $ResourceType -and -not $Alias -and -not $Resource -and -not $TerraformResourceType) { Write-Error 'Specify -ResourceType, -Alias, -Resource or -TerraformResourceType to identify the resource type.' return } $definition = Resolve-CafResourceDefinition -ResourceType $ResourceType -Alias $Alias -Resource $Resource -TerraformResourceType $TerraformResourceType if (-not $definition) { return } $MinLength = $Name.Length -ge $definition.MinLength $MaxLength = $Name.Length -le $definition.MaxLength $Casing = -not ($definition.Lowercase -and $Name -cmatch '[A-Z]') $Dashes = $definition.Dashes -or $Name -cnotmatch '-' $ValidCharacters = $Name -cnotmatch $definition.InvalidCharsRegex $IsValid = $Name -cmatch $definition.ValidationRegex if ($Quiet) { return $IsValid } $Reasons = [System.Collections.Generic.List[string]]::new() if ($IsValid) { # Even if every breakdown field is individually true, IsValid is the authoritative check - # there's nothing to explain when it passed, regardless of what the breakdown says. } else { if (-not $MinLength) { $Reasons.Add("Name is $($Name.Length) character$(if ($Name.Length -ne 1) { 's' }), which is shorter than the $($definition.MinLength) character minimum.") } if (-not $MaxLength) { $Reasons.Add("Name is $($Name.Length) characters, which exceeds the $($definition.MaxLength) character maximum by $($Name.Length - $definition.MaxLength).") } if (-not $Casing) { $Reasons.Add('Name must be all lowercase for this resource type.') } if (-not $Dashes) { $Reasons.Add("Name contains a dash ('-'), which this resource type does not allow.") } if (-not $ValidCharacters) { $Reasons.Add('Name contains characters that are not allowed for this resource type.') } if ($Reasons.Count -eq 0) { # None of the simple per-rule checks explain it - some resource types have additional # positional rules (e.g. must start/end with a letter) that aren't broken out above. $Reasons.Add("Name does not match the required pattern for this resource type (pattern: $($definition.ValidationRegex)).") } } [pscustomobject]@{ Name = $Name ResourceType = $definition.ResourceType Resource = $definition.Resource TerraformResourceType = $definition.TerraformResourceType IsValid = $IsValid Reason = if ($Reasons.Count -gt 0) { $Reasons -join ' ' } else { $null } MinLength = $MinLength MaxLength = $MaxLength Casing = $Casing Dashes = $Dashes ValidCharacters = $ValidCharacters } } } # The JSON data files live alongside this one (Private/) so $PSScriptRoot finds them correctly in both # layouts this file runs in: dot-sourced here in dev mode ($PSScriptRoot = this Private folder), and # inlined into the combined/staged .psm1 (see Build/Tasks/CombineFunctionsAndStage.ps1), where the # build copies these same two files to the staged module's root - $PSScriptRoot there resolves to that # root too, since the combined file *is* the module's root script at that point. $Script:ResourceDefinitionPath = Join-Path $PSScriptRoot 'resourceDefinition.json' $Script:RegionDefinitionPath = Join-Path $PSScriptRoot 'regionDefinition.json' # Registered here (rather than via the [ArgumentCompleter(...)] attribute on each parameter) because an # attribute scriptblock isn't bound to this module's session state, so it can't see private functions # like Get-CafResourceDefinition - it would silently fail and PowerShell would fall back to file # completion. A scriptblock defined directly in a module file (dot-sourced here, inlined in the # combined/staged build) doesn't have that problem. $ResourceTypeCompleter = { param($CommandName, $ParameterName, $WordToComplete, $CommandAst, $FakeBoundParameters) $null = $CommandName, $ParameterName, $CommandAst, $FakeBoundParameters # Substring match, same as the cmdlets' own -ResourceType/-Alias partial matching, so what # tab-completes is consistent with what actually resolves. $Pattern = Get-CafWildcardPattern -Value $WordToComplete (Get-CafResourceDefinition).ResourceType | Select-Object -Unique | Where-Object { $_ -like $Pattern } | ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) } } $SlugCompleter = { param($CommandName, $ParameterName, $WordToComplete, $CommandAst, $FakeBoundParameters) $null = $CommandName, $ParameterName, $CommandAst, $FakeBoundParameters $Pattern = Get-CafWildcardPattern -Value $WordToComplete (Get-CafResourceDefinition).Slug | Select-Object -Unique | Where-Object { $_ -like $Pattern } | ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) } } $TerraformResourceTypeCompleter = { param($CommandName, $ParameterName, $WordToComplete, $CommandAst, $FakeBoundParameters) $null = $CommandName, $ParameterName, $CommandAst, $FakeBoundParameters # Substring match, same as the cmdlets' own -TerraformResourceType partial matching. Many entries # have no Terraform equivalent ($null), so those are filtered out before completing. Piping an # array-valued property (the handful of entries with more than one real azurerm equivalent, e.g. # a VM's Linux/Windows variants) flattens it automatically, so each name is still offered on its # own rather than as one combined completion. $Pattern = Get-CafWildcardPattern -Value $WordToComplete (Get-CafResourceDefinition).TerraformResourceType | Where-Object { $_ } | Select-Object -Unique | Where-Object { $_ -like $Pattern } | ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) } } $ResourceCompleter = { param($CommandName, $ParameterName, $WordToComplete, $CommandAst, $FakeBoundParameters) $null = $CommandName, $ParameterName, $CommandAst $Definitions = @(Get-CafResourceDefinition) # Narrow to whichever resource type the caller has already typed, if any, so -Resource only # offers the friendly names that actually apply to it (e.g. just 'Web app'/'Function app' once # -ResourceType Microsoft.Web/sites is on the line), rather than every friendly name there is. # $FakeBoundParameters is always keyed by the canonical parameter name, even if the caller typed # the -Slug alias instead of -Alias, so there's no separate case to handle for that. if ($FakeBoundParameters.ResourceType) { $Definitions = Select-CafMatch -InputObject $Definitions -Property ResourceType -Value $FakeBoundParameters.ResourceType } elseif ($FakeBoundParameters.Alias) { $Definitions = Select-CafMatch -InputObject $Definitions -Property Slug -Value $FakeBoundParameters.Alias } elseif ($FakeBoundParameters.TerraformResourceType) { $Definitions = Select-CafMatch -InputObject $Definitions -Property TerraformResourceType -Value $FakeBoundParameters.TerraformResourceType } $Pattern = Get-CafWildcardPattern -Value $WordToComplete $Definitions.Resource | Select-Object -Unique | Where-Object { $_ -like $Pattern } | Sort-Object | ForEach-Object { # Friendly names routinely contain spaces/parentheses (e.g. 'Managed disk (OS)'), so the # completion text needs quoting to stay a single valid token once it's inserted. $Quoted = "'" + $_.Replace("'", "''") + "'" [System.Management.Automation.CompletionResult]::new($Quoted, $_, 'ParameterValue', $_) } } $RegionCompleter = { param($CommandName, $ParameterName, $WordToComplete, $CommandAst, $FakeBoundParameters) $null = $CommandName, $ParameterName, $CommandAst, $FakeBoundParameters # Matches against the ARM region name, its display name or its slug, same fields Resolve-CafRegion # accepts, so typing 'east', 'East US' or 'eus' all offer a completion - but always completes to the # ARM name, since that's the unambiguous value every other Azure PowerShell -Location parameter # expects. $Pattern = Get-CafWildcardPattern -Value $WordToComplete (Get-CafRegionDefinition) | Where-Object { $_.Region -like $Pattern -or $_.DisplayName -like $Pattern -or $_.Slug -like $Pattern } | Sort-Object -Property Region -Unique | ForEach-Object { [System.Management.Automation.CompletionResult]::new($_.Region, "$($_.Region) ($($_.DisplayName))", 'ParameterValue', $_.DisplayName) } } Register-ArgumentCompleter -CommandName 'Get-CafResourceName', 'New-CafResourceName', 'Test-CafResourceName', 'Get-CafResourceType' -ParameterName 'ResourceType' -ScriptBlock $ResourceTypeCompleter Register-ArgumentCompleter -CommandName 'Get-CafResourceName', 'New-CafResourceName', 'Test-CafResourceName', 'Get-CafResourceType' -ParameterName 'Alias' -ScriptBlock $SlugCompleter Register-ArgumentCompleter -CommandName 'Get-CafResourceName', 'New-CafResourceName', 'Test-CafResourceName', 'Get-CafResourceType' -ParameterName 'Resource' -ScriptBlock $ResourceCompleter Register-ArgumentCompleter -CommandName 'Get-CafResourceName', 'New-CafResourceName', 'Test-CafResourceName', 'Get-CafResourceType' -ParameterName 'TerraformResourceType' -ScriptBlock $TerraformResourceTypeCompleter Register-ArgumentCompleter -CommandName 'Get-CafResourceName', 'New-CafResourceName', 'Get-CafRegion' -ParameterName 'Region' -ScriptBlock $RegionCompleter function Get-CafRegionDefinition { <# .SYNOPSIS Returns the cached set of Azure region abbreviation definitions. .DESCRIPTION Loads regionDefinition.json from the module root the first time it's needed and caches it for the lifetime of the module session, so repeated calls to Get-CafResourceName/Get-CafRegion don't re-read and re-parse the file from disk every time. .EXAMPLE Get-CafRegionDefinition #> [CmdletBinding()] param() if (-not $Script:CafRegionDefinitions) { $Script:CafRegionDefinitions = Get-Content -Path $Script:RegionDefinitionPath -Raw | ConvertFrom-Json } $Script:CafRegionDefinitions } function Get-CafResourceDefinition { <# .SYNOPSIS Returns the cached set of CAF resource naming definitions. .DESCRIPTION Loads resourceDefinition.json from the module root the first time it's needed and caches it for the lifetime of the module session, so repeated calls to Get-CafResourceName/Get-CafResourceType don't re-read and re-parse the file from disk every time. .EXAMPLE Get-CafResourceDefinition #> [CmdletBinding()] param() if (-not $Script:CafResourceDefinitions) { $Script:CafResourceDefinitions = Get-Content -Path $Script:ResourceDefinitionPath -Raw | ConvertFrom-Json } $Script:CafResourceDefinitions } function Get-CafWildcardPattern { <# .SYNOPSIS Turns a plain string into a partial ('contains') wildcard pattern. .DESCRIPTION Used by Get-CafResourceName/Get-CafResourceType so that -ResourceType and -Resource match as a substring by default (e.g. 'virtualMachines' matches 'Microsoft.Compute/virtualMachines'), while still respecting an explicit wildcard pattern (e.g. '*storageAccount*' or 'disk?') if the caller already supplied one, rather than wrapping it a second time. .EXAMPLE Get-CafWildcardPattern -Value 'virtualMachines' #> [CmdletBinding()] param( [Parameter(Mandatory)] [AllowEmptyString()] [string] $Value ) if ($Value -match '[*?\[\]]') { $Value } else { "*$Value*" } } function Resolve-CafRegion { <# .SYNOPSIS Resolves a -Region value to exactly one regionDefinition.json entry. .DESCRIPTION Shared resolution logic for Get-CafResourceName and Get-CafRegion, so both cmdlets identify a region the same way and report identical errors for an unknown/ambiguous value. Checks for an exact (case-insensitive) match against the ARM region name (e.g. 'eastus'), its display name (e.g. 'East US') or its CAF slug (e.g. 'eus') first - checking all three up front, rather than one at a time, matters for a short value like a slug: 'ae' (Australia East's slug) is also a substring of several other regions' ARM names (e.g. 'canadaeast', 'israelcentral'), so falling through to a substring search would make it ambiguous instead of resolving it. Only once no exact match exists does it fall back to a substring ('contains') search, same as -ResourceType/-Resource elsewhere in the module - against the ARM region name first, then the display name. The slug isn't included in that substring fallback: it's short enough that partial matching on it would mostly just produce ambiguous results, and a caller who doesn't already know the exact slug should be matching on the region name/display name instead. Writes a non-terminating error and returns nothing if the value doesn't resolve to exactly one entry - callers should check for a $null/empty result and return without continuing. .EXAMPLE Resolve-CafRegion -Region 'eastus' .EXAMPLE Resolve-CafRegion -Region 'East US' .EXAMPLE Resolve-CafRegion -Region 'eus' #> [CmdletBinding()] param( [Parameter(Mandatory)] [string] $Region ) $definitions = @(Get-CafRegionDefinition) $candidates = @($definitions | Where-Object { $_.Region -eq $Region -or $_.DisplayName -eq $Region -or $_.Slug -eq $Region }) if ($candidates.Count -eq 0) { $candidates = Select-CafMatch -InputObject $definitions -Property Region -Value $Region if ($candidates.Count -eq 0) { $candidates = Select-CafMatch -InputObject $definitions -Property DisplayName -Value $Region } } if ($candidates.Count -eq 0) { Write-Error "No Azure region matches '$Region'. Use Get-CafRegion to search for a supported region." return } if ($candidates.Count -gt 1) { $options = ($candidates | ForEach-Object { "$($_.Region) [$($_.DisplayName)]" }) -join "', '" Write-Error "'$Region' matches more than one Azure region. Narrow it down with the ARM region name: '$options'." return } $candidates[0] } function Resolve-CafResourceDefinition { <# .SYNOPSIS Resolves a -ResourceType, -Alias or -Resource value to exactly one resourceDefinition.json entry. .DESCRIPTION Shared resolution logic for Get-CafResourceName and Test-CafResourceName, so all three cmdlets identify a resource type the same way and report identical errors for an unknown/ambiguous value. Writes a non-terminating error and returns nothing if the value doesn't resolve to exactly one entry - callers should check for a $null/empty result and return without continuing. -ResourceType takes priority as the primary identifier if given, then -Alias, then -TerraformResourceType, with -Resource and (when -ResourceType/-Alias is primary) -TerraformResourceType all narrowing *within* whichever of those matched (for the handful of types used by more than one kind of resource). When none of -ResourceType/-Alias/ -TerraformResourceType is given, -Resource is used as the primary identifier instead - every "Resource" friendly name in resourceDefinition.json happens to be globally unique today, so this only fails if that ever stops being true upstream. Callers don't need to guard against more than one of -ResourceType/-Alias/-Resource being supplied - e.g. piping Get-CafResourceType's output through by property name binds ResourceType, Resource and (via its Slug alias) Alias all at once, since they're all present on that object and all describe the same entry: narrowing by -Alias/-Resource after an already-unambiguous -ResourceType match is a no-op in that case, since the pipelined values already agree with it. Precedence just needs to be deterministic for that case, not an error - it's not a conflict unless the caller explicitly typed contradictory values, in which case -Alias/-Resource narrowing a -ResourceType match down to zero candidates reports that clearly rather than silently ignoring it. .EXAMPLE Resolve-CafResourceDefinition -ResourceType 'Microsoft.Compute/virtualMachines' .EXAMPLE Resolve-CafResourceDefinition -Alias 'afd' -Resource 'classic' .EXAMPLE Resolve-CafResourceDefinition -ResourceType 'Microsoft.Web/sites' -Alias 'func' .EXAMPLE Resolve-CafResourceDefinition -Resource 'Key vault' .EXAMPLE Resolve-CafResourceDefinition -TerraformResourceType 'azurerm_storage_account' #> [CmdletBinding()] param( [string] $ResourceType, [string] $Alias, [string] $Resource, [string] $TerraformResourceType ) $ResourceIsPrimary = -not $ResourceType -and -not $Alias -and -not $TerraformResourceType if ($ResourceType) { $identifier = "'$ResourceType'" $candidates = Select-CafMatch -InputObject @(Get-CafResourceDefinition) -Property ResourceType -Value $ResourceType } elseif ($Alias) { $identifier = "alias '$Alias'" $candidates = Select-CafMatch -InputObject @(Get-CafResourceDefinition) -Property Slug -Value $Alias } elseif ($TerraformResourceType) { $identifier = "terraform resource type '$TerraformResourceType'" $candidates = Select-CafMatch -InputObject @(Get-CafResourceDefinition) -Property TerraformResourceType -Value $TerraformResourceType } else { $identifier = "resource '$Resource'" $candidates = Select-CafMatch -InputObject @(Get-CafResourceDefinition) -Property Resource -Value $Resource } if ($candidates.Count -eq 0) { Write-Error "No resource type matches $identifier. Use Get-CafResourceType to search for a supported resource type." return } if ($Alias -and $ResourceType) { $allCandidates = $candidates $candidates = Select-CafMatch -InputObject $candidates -Property Slug -Value $Alias if ($candidates.Count -eq 0) { $options = ($allCandidates | ForEach-Object { "$($_.ResourceType) [$($_.Resource)]" }) -join "', '" Write-Error "'$Alias' doesn't match any resource for $identifier. Available: '$options'." return } } if ($TerraformResourceType -and ($ResourceType -or $Alias)) { $allCandidates = $candidates $candidates = Select-CafMatch -InputObject $candidates -Property TerraformResourceType -Value $TerraformResourceType if ($candidates.Count -eq 0) { $options = ($allCandidates | ForEach-Object { "$($_.ResourceType) [$($_.Resource)]" }) -join "', '" Write-Error "'$TerraformResourceType' doesn't match any resource for $identifier. Available: '$options'." return } } if ($Resource -and -not $ResourceIsPrimary) { $allCandidates = $candidates $candidates = Select-CafMatch -InputObject $candidates -Property Resource -Value $Resource if ($candidates.Count -eq 0) { $options = ($allCandidates | ForEach-Object { "$($_.ResourceType) [$($_.Resource)]" }) -join "', '" Write-Error "'$Resource' doesn't match any resource for $identifier. Available: '$options'." return } } if ($candidates.Count -gt 1) { $options = ($candidates | ForEach-Object { "$($_.ResourceType) [$($_.Resource)]" }) -join "', '" $suggestion = if ($ResourceIsPrimary) { '-ResourceType' } else { '-Resource' } Write-Error "$identifier matches more than one resource type. Narrow it down with $suggestion`: '$options'." return } $candidates[0] } function Select-CafMatch { <# .SYNOPSIS Filters a collection to the items whose property exactly matches a value, falling back to a partial ('contains') match only when nothing matches exactly. .DESCRIPTION Used by Get-CafResourceName/Get-CafResourceType to make -ResourceType/-Resource match as a substring for convenience, without that breaking exact lookups: partial matching alone is ambiguous for values like 'Microsoft.Compute/virtualMachines', since (case-insensitively) it's also a substring of 'Microsoft.Compute/virtualMachineScaleSets'. Checking for an exact match first means a fully-qualified value always resolves to itself, and the substring fallback only kicks in when there was no exact match to begin with. .EXAMPLE Select-CafMatch -InputObject $definitions -Property ResourceType -Value 'Microsoft.Compute/virtualMachines' #> [CmdletBinding()] param( [Parameter(Mandatory)] [object[]] $InputObject, [Parameter(Mandatory)] [string] $Property, [Parameter(Mandatory)] [string] $Value ) $exact = @($InputObject | Where-Object { $_.$Property -eq $Value }) if ($exact.Count -gt 0) { return $exact } $pattern = Get-CafWildcardPattern -Value $Value @($InputObject | Where-Object { $_.$Property -like $pattern }) } |