In any organisation it is important to get a standard naming convention in place for most things, but especially with cloud-based resources.
As many types of cloud resources require globally unique names (due to platform DNS resolution), it’s important to have a strategy that will give you a good chance of achieving global uniqueness, but also as helpful as possible to human beings, as well as codifiable in DevOps CD pipelines.
The easiest thing would be to have some horrendous code or GUID that is either unreadable and/or requires copious looking up of codes in code tables to decipher what and where the resource is.
After years of using Azure, I thought I would share my preferred naming convention. I believe it to be intuitive, human readable and provides a good level of information and … a reasonable chance of first attempt anyway, of global uniqueness.
The Convention
$OrganisationCode-$ProjectCode-$ResourceTypeCode-$AppCode-$EnvironmentCode-$RegionCode-[$InstanceNo]
or without hyphens
$OrganisationCode$ProjectCode$ResourceTypeCode$AppCode$EnvironmentCode$RegionCode[$InstanceNo]
The examples above would be the first instance (001) of the Storage Account (sa) for my organisation’s (nerr) project (test) diagnostics and logging data (diag) in the development environment (dev) that will be hosted in the UK South region (uks).
The order and number of elements is not accidental. It will become clear when you have multiple environments in multiple regions!
The ‘codes’ should be kept as small as possible. Somewhere between 3 and 8 characters ideally.
See the examples below.
The Elements
| Name Part | Description |
|---|---|
| Organisation code | This is your identifiable organisation name short-code. Don’t make it too generic a word, but this will be key to maximising you names global uniqueness. It is also useful if you support multiple divisions or organisations to easily differentiate between them. For Example: McDonalds might use ‘mcd’ or ‘mcdon’ Microsoft might use ‘ms’ Oracle might use ‘orcl’ Mine is ‘nerr’ |
| Project short code | This is the project, product, or platform identifier. This needs to be unique in your organisation. Here I have used ‘test’, meaning this is my test project hint: removing all vowels from a name can be a way to create a good code |
| Resource type code | This is a code that represents the Azure (or other cloud providers) resource type. See the list below. |
| App code | This is the name of the workload, purpose, or app that the resource supports. e.g. ‘Customer Function API’ would shorten to ‘cust’ and related resources, such as storage etc., would have the same code and only vary by resource type. |
| Environment code | This refers to the deployment environments. Such as Development, Test or Production. Recommended codes are: – dev – qa – sit – pre – prod |
| Region code | This refers to the regional data centre that the resource is deployed to. see the list below for Azure |
| Instance no | [Optional] This is only required when you will be instantiating multiples of the same resource. E.g. multiple VM’s in a cluster I would use one leading zero, as this allows good sorting for up to 99 instances of something. e.g. ’01’, ’02’. In large really large environments even 3 leading zero’s’001′ |
Key Principles
- All names should be lowercase or Pascal Case (Camel Case with the first character uppercase) if allowed
- Use and update the tables below for short-codes
- Use hyphens when possible
- If no environment is specified in the name, then Production is assumed
- try and keep the name length concise
- Do not use any non URL safe charters anywhere
- Do NOT use any special characters at the start or end of the name
- If you name turns out to not be unique then alter the ‘Product Code’ to be more unusual.
Examples
For a one of my test apps called Customer I may have an Function API, A SQL Azure database and a Storage account all in a Resource Group. Development in North Europe and Production in West Europe. The naming would be as follows:
- nerr-test-rg-dev-ne
- nerr-test-func-cust-dev-ne
- nerr-test-sql-cust-dev-ne
- nerr-test-st-diag-dev-ne
- ner-test-rg-prod-we
- nerr-test-func-cust-prod-we
- nerr-test-sql-cust-prod-we
- nerr-test-st-diag-prod-we
Some Resource Type Codes (Azure)
This is not a comprehensive list but should give you the idea. If you want to contribute here, please send me your codes 😉
| Resource | Code | Hyphens Allowed |
|---|---|---|
| Resource Group | rg | yes |
| Application Service Plan | aps | yes |
| Container Registry | cr | no |
| Storage Account | st | no |
| Data Factory | df | yes |
| Databricks Workspace | dbw | yes |
| Function App | func | yes |
| Azure SQL Server | sql | yes |
| Virtual Machine | vm | yes |
| Virtual Network | vnet | yes |
| Search Service | srch | yes |
| Web App Service | wa | yes |
| API App Service | api | yes |
| Data Lake Store | dsl | no |
| Network Security Group | nsg | yes |
| Public IP Address | pip | yes |
| Load Balancer | lb | yes |
| Availability Set | la | yes |
| Recovery Services Vault | vlt | yes |
| Key Vault | kv | yes |
| DevTest Lab | lab | yes |
| Application Service Plan | asp | yes |
| Kubernetes Service | aks | yes |
| Local Network Gateway | lng | yes |
| Virtual Network Gateway | vng | yes |
| Service Bus Namespace | sbn | yes |
| Synapse Analytics Workspaces | synw | yes |
| Synapse Analytics SQL Dedicated Pool | syndp | yes |
| Synapse Analytics Spark Pool | synsp | yes |
For Microsoft’s recommended abbreviations see Abbreviation examples for Azure resources – Cloud Adoption Framework | Microsoft Learn
Environment Codes
| Environment | Code |
|---|---|
| Development | dev |
| QA / Test | qa |
| System Integration Testing | sit |
| User Acceptance Test | uat |
| Staging | stag |
| Pre-production | pre |
| Production | prod |
Region Codes (Azure)
Exceptions, Variations and Restrictions
Storage Accounts
Storage accounts must be between 3 and 24 characters in length and not contain ‘-‘ dashes.
When we account for the other elements
nerrtestsa{AppName}devne
In my case we can see that the maximum length of the {AppName} is 7, 8 or 9 characters depending on location and environments.
Any creation pipeline must concatenate the {PlatformShortCode}{AppName}.
Key Vault Secrets
One Key Vault exists for each security boundary. The security boundary may incorporate several applications and databases. So, it important the keys are explicit, descriptive, and unique across the estate to ensure everyone can identify them and that they can be used, unambiguously in release pipelines.
There will be a Key Vault for each environment and is essential that the key is identical between environments, so does not include the environment short-code at all.
Service Bus and Message Queue Names
Messages often carry information that pass the baton of handling certain steps in a workflow or a processing chain to a different role inside a system. Those messages, like a purchase order or a monetary account transfer record, may express significant inherent monetary value. That value may be lost and/or very difficult to recover if such a message were somehow lost in transfer.
Events are also messages, but they don’t convey a publisher intent, other than to inform. An event captures a fact and conveys that fact. A consumer of the event can process the fact as it pleases and doesn’t fulfill any specific expectations held by the publisher.
{service | workload | subject}-{event | purpose | Intent}-{message type or contract}-sbqExample:
messaging-send-emailprofile-sbqTopic Names
{service | workload | subject}-{event | purpose | intent}-{message type or contract}-sbtExample:
customer-added-identity-sbthere the message or contract is an identity object. This kind of object may be the same used in many queues, topics or events.
SQL Servers and database names
In the world of micro-services the name of the database should reflect the microservice it is associated with.
Database
Including the Platform ShortCode allows databases to be aggregated onto shared database servers if required.
{ProjectShortCode}{AppName}
Database Name Examples:
- testcustomer
- testoffer
References
Since producing this scheme, Microsoft have published their own advice which you can find at
and detailed information on Naming rules and restrictions for Azure resources can be found at
https://docs.microsoft.com/en-gb/azure/azure-resource-manager/management/resource-name-rules