Skip to content

Commit c9ad181

Browse files
petrsxpetrsx
committed
feat: add Azure resource naming conventions based on Microsoft CAF
1 parent 6397070 commit c9ad181

1 file changed

Lines changed: 256 additions & 0 deletions

File tree

‎instructions/azure-naming.instructions.md‎

Lines changed: 256 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,256 @@
1+
---
2+
applyTo: "**/*.bicep,**/*.tf,**/*.tfvars,**/*.bicepparam,**/infra/**,**/infrastructure/**"
3+
description: "Azure resource naming conventions based on Microsoft CAF (Cloud Adoption Framework). Use when creating, reviewing, or suggesting names for Azure resources."
4+
---
5+
6+
# Azure Resource Naming Conventions (CAF)
7+
8+
Source: [Define your naming convention](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/resource-naming) | [Abbreviations](https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/resource-abbreviations) | [Name rules](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-name-rules)
9+
10+
Always follow these rules when creating, suggesting, or reviewing Azure resource names.
11+
12+
---
13+
14+
## General Pattern
15+
16+
```
17+
<resource-type-abbr>-<workload>-<environment>-<region>-<instance>
18+
```
19+
20+
**Component rules:**
21+
- **Resource type** — use the official abbreviation from the table below, placed first
22+
- **Workload / app / project** — short descriptive name (e.g., `navigator`, `payments`)
23+
- **Environment** — `prod`, `dev`, `qa`, `stage`, `test`
24+
- **Region** — use Azure region short names: `westus`, `eastus2`, `westeurope`, `northeurope`, `uksouth`, `southeastasia`, `australiaeast`, etc.
25+
- **Instance** — zero-padded number: `001`, `002`
26+
27+
**General character rules:**
28+
- Prefer lowercase letters and hyphens (`-`). No spaces, no underscores unless the resource type requires it.
29+
- Some resources **do not allow hyphens** — use concatenated lowercase alphanumerics instead (see table).
30+
- Do not use: `#`, `<`, `>`, `%`, `&`, `\`, `?`, `/` or control characters.
31+
- Do not encode sensitive data (subscription ID, tenant ID) in names.
32+
- Most names are **case-insensitive** in Azure — always compare case-insensitively.
33+
- Resources with public endpoints cannot include reserved words or trademarks.
34+
35+
---
36+
37+
## Naming Scope
38+
39+
| Scope | Meaning |
40+
|-------|---------|
41+
| **Global** | Unique across all of Azure (PaaS with public endpoints) |
42+
| **Resource group** | Unique within the resource group |
43+
| **Resource** | Unique within the parent resource |
44+
45+
---
46+
47+
## Official Abbreviations and Naming Rules
48+
49+
### Management and Governance
50+
51+
| Resource | Abbr | Scope | Length | Valid Characters | Example |
52+
|----------|------|-------|--------|-----------------|---------|
53+
| Management group | `mg` | tenant | 1-90 | Alphanumerics, hyphens, underscores, periods, parentheses | `mg-platform-prod` |
54+
| Resource group | `rg` | subscription | 1-90 | Underscores, hyphens, periods, parentheses, letters, digits | `rg-navigator-prod` |
55+
| Log Analytics workspace | `log` | resource group | 4-63 | Alphanumerics and hyphens | `log-navigator-prod-001` |
56+
| Application Insights | `appi` | resource group | 1-260 | Can't use: `%&\?/` | `appi-navigator-prod-001` |
57+
| Automation account | `aa` | resource group + region | 6-50 | Alphanumerics and hyphens, start with letter | `aa-navigator-prod-001` |
58+
59+
### Networking
60+
61+
| Resource | Abbr | Scope | Length | Valid Characters | Example |
62+
|----------|------|-------|--------|-----------------|---------|
63+
| Virtual network | `vnet` | resource group | 2-64 | Alphanumerics, underscores, periods, hyphens | `vnet-shared-eastus2-001` |
64+
| Subnet | `snet` | virtual network | 1-80 | Alphanumerics, underscores, periods, hyphens | `snet-shared-eastus2-001` |
65+
| Network security group | `nsg` | resource group | 1-80 | Alphanumerics, underscores, periods, hyphens | `nsg-weballow-001` |
66+
| Application security group | `asg` | resource group | 1-80 | Alphanumerics, underscores, periods, hyphens | `asg-navigator-prod-001` |
67+
| Network interface | `nic` | resource group | 1-80 | Alphanumerics, underscores, periods, hyphens | `nic-01-vmnavigator-prod-001` |
68+
| Public IP address | `pip` | resource group | 1-80 | Alphanumerics, underscores, periods, hyphens | `pip-navigator-prod-westus-001` |
69+
| Load balancer (internal) | `lbi` | resource group | 1-80 | Alphanumerics, underscores, periods, hyphens | `lbi-navigator-prod-001` |
70+
| Load balancer (external) | `lbe` | resource group | 1-80 | Alphanumerics, underscores, periods, hyphens | `lbe-navigator-prod-001` |
71+
| Application gateway | `agw` | resource group | 1-80 | Alphanumerics, underscores, periods, hyphens | `agw-navigator-prod-001` |
72+
| Firewall | `afw` | resource group | 1-80 | Alphanumerics, underscores, periods, hyphens | `afw-navigator-prod-001` |
73+
| Firewall policy | `afwp` | resource group | 1-80 | Alphanumerics, underscores, periods, hyphens | `afwp-navigator-prod-001` |
74+
| Route table | `rt` | resource group | 1-80 | Alphanumerics, underscores, periods, hyphens | `rt-navigator-prod-001` |
75+
| Virtual network gateway | `vgw` | resource group | 1-80 | Alphanumerics, underscores, periods, hyphens | `vgw-shared-eastus2-001` |
76+
| VPN Gateway | `vpng` | resource group | 1-80 | Alphanumerics, underscores, periods, hyphens | `vpng-navigator-prod-001` |
77+
| Azure Bastion | `bas` | resource group | 1-80 | Alphanumerics, underscores, periods, hyphens | `bas-navigator-prod-001` |
78+
| Private endpoint | `pep` | resource group | 2-64 | Alphanumerics, underscores, periods, hyphens | `pep-navigator-prod-001` |
79+
| Traffic Manager profile | `traf` | global | 1-63 | Alphanumerics and hyphens (no periods) | `traf-navigator-prod` |
80+
| ExpressRoute circuit | `erc` | resource group | 1-80 | Alphanumerics, underscores, periods, hyphens | `erc-navigator-prod-001` |
81+
| CDN profile | `cdnp` | resource group | 1-260 | Alphanumerics and hyphens | `cdnp-navigator-prod-001` |
82+
| Front Door profile | `afd` | resource group | 5-64 | Alphanumerics and hyphens | `afd-navigator-prod` |
83+
84+
### Compute and Web
85+
86+
| Resource | Abbr | Scope | Length | Valid Characters | Example |
87+
|----------|------|-------|--------|-----------------|---------|
88+
| Virtual machine | `vm` | resource group | 1-15 (Windows) / 1-64 (Linux) | No spaces or: `~ ! @ # $ % ^ & * ( ) = + _ [ ] { } \| ; : . ' " , < > / ?` | `vm-sql-test-001` |
89+
| VM scale set | `vmss` | resource group | 1-15 (Windows) / 1-64 (Linux) | Same as VM | `vmss-navigator-prod-001` |
90+
| Availability set | `avail` | resource group | 1-80 | Alphanumerics, underscores, periods, hyphens | `avail-navigator-prod-001` |
91+
| App Service plan | `asp` | resource group | 1-60 | Alphanumeric, hyphens, Unicode | `asp-navigator-prod-001` |
92+
| Web app | `app` | global | 2-60 | Alphanumeric, hyphens, Unicode. Can't start/end with hyphen. | `app-navigator-prod-001` |
93+
| Function app | `func` | global | 2-60 | Alphanumeric, hyphens, Unicode. Can't start/end with hyphen. | `func-navigator-prod-001` |
94+
| Static web app | `stapp` | resource group | — | — | `stapp-navigator-prod-001` |
95+
| App Service environment | `ase` | resource group | — | — | `ase-navigator-prod-001` |
96+
97+
### Containers
98+
99+
| Resource | Abbr | Scope | Length | Valid Characters | Example |
100+
|----------|------|-------|--------|-----------------|---------|
101+
| AKS cluster | `aks` | resource group | 1-63 | Alphanumerics, underscores, hyphens | `aks-navigator-prod-001` |
102+
| AKS system node pool | `npsystem` | managed cluster | 1-12 (Linux) / 1-6 (Windows) | Lowercase letters and numbers, can't start with number | `npsystem` |
103+
| AKS user node pool | `np` | managed cluster | 1-12 (Linux) / 1-6 (Windows) | Lowercase letters and numbers, can't start with number | `npusers` |
104+
| Container apps | `ca` | resource group | 2-32 | Lowercase letters, numbers, hyphens. Start with letter, end with alphanumeric. | `ca-navigator-prod-001` |
105+
| Container apps environment | `cae` | resource group | — | — | `cae-navigator-prod-001` |
106+
| Container instance | `ci` | resource group | 1-63 | Lowercase letters, numbers, hyphens. Can't start/end with hyphen. | `ci-navigator-prod-001` |
107+
| Container registry | `cr` | global | 5-50 | **Alphanumerics only — no hyphens** | `crnavigatorprod001` |
108+
109+
### Databases
110+
111+
| Resource | Abbr | Scope | Length | Valid Characters | Example |
112+
|----------|------|-------|--------|-----------------|---------|
113+
| Azure SQL server | `sql` | global | 1-63 | Lowercase letters, numbers, hyphens. Can't start/end with hyphen. | `sql-navigator-prod-001` |
114+
| Azure SQL database | `sqldb` | SQL server | 1-128 | Can't use: `<>*%&:\/?` | `sqldb-navigator-prod` |
115+
| SQL Managed Instance | `sqlmi` | global | 1-63 | Lowercase letters, numbers, hyphens. Can't start/end with hyphen. | `sqlmi-navigator-prod-001` |
116+
| Azure Cosmos DB | `cosmos` | global | 3-44 | Lowercase letters, numbers, hyphens. Start with lowercase letter or number. | `cosmos-navigator-prod` |
117+
| Azure Managed Redis | `amr` | global | 1-63 | Alphanumerics and hyphens. Start/end with alphanumeric. | `amr-navigator-prod-001` |
118+
| MySQL server | `mysql` | global | 3-63 | Lowercase letters, hyphens, numbers. Can't start/end with hyphen. | `mysql-navigator-prod-001` |
119+
| PostgreSQL server | `psql` | global | 3-63 | Lowercase letters, hyphens, numbers. Can't start/end with hyphen. | `psql-navigator-prod-001` |
120+
121+
### Storage
122+
123+
| Resource | Abbr | Scope | Length | Valid Characters | Example |
124+
|----------|------|-------|--------|-----------------|---------|
125+
| Storage account | `st` | global | 3-24 | **Lowercase letters and numbers only — no hyphens** | `stnavigatordata001` |
126+
| Backup vault | `bvault` | resource group | 2-50 | Alphanumerics and hyphens. Start with a letter. | `bvault-navigator-prod-001` |
127+
128+
### Security
129+
130+
| Resource | Abbr | Scope | Length | Valid Characters | Example |
131+
|----------|------|-------|--------|-----------------|---------|
132+
| Key vault | `kv` | global | 3-24 | Alphanumerics and hyphens. Start with letter, end with letter or number. No consecutive hyphens. | `kv-navigator-prod-001` |
133+
| Managed identity | `id` | resource group | 3-128 | Alphanumerics, hyphens, underscores. Start with letter or number. | `id-navigator-prod-001` |
134+
135+
### Integration
136+
137+
| Resource | Abbr | Scope | Length | Valid Characters | Example |
138+
|----------|------|-------|--------|-----------------|---------|
139+
| API Management | `apim` | global | 1-50 | Alphanumerics and hyphens. Start with letter, end with alphanumeric. | `apim-navigator-prod` |
140+
| Service Bus namespace | `sbns` | global | 6-50 | Alphanumerics and hyphens. Start with letter, end with letter or number. | `sbns-navigator-prod` |
141+
| Service Bus queue | `sbq` | Service Bus | 1-260 | Alphanumerics, periods, hyphens, underscores, slashes | `sbq-navigator` |
142+
| Service Bus topic | `sbt` | Service Bus | 1-260 | Alphanumerics, periods, hyphens, underscores, slashes | `sbt-navigator` |
143+
| Event Hubs namespace | `evhns` | global | 6-50 | Alphanumerics and hyphens. Start with letter, end with letter or number. | `evhns-navigator-prod` |
144+
| Event hub | `evh` | Event Hubs namespace | 1-256 | Alphanumerics, periods, hyphens, underscores | `evh-navigator` |
145+
| Logic app | `logic` | resource group | 1-43 | Alphanumerics, hyphens, underscores, periods | `logic-navigator-prod-001` |
146+
147+
### AI and Machine Learning
148+
149+
| Resource | Abbr | Scope | Length | Valid Characters | Example |
150+
|----------|------|-------|--------|-----------------|---------|
151+
| Azure OpenAI Service | `oai` | resource group | 2-64 | Alphanumerics and hyphens | `oai-navigator-prod` |
152+
| AI Search | `srch` | global | — | — | `srch-navigator-prod` |
153+
| Azure ML workspace | `mlw` | resource group | 3-33 | Alphanumerics, hyphens, underscores | `mlw-navigator-prod` |
154+
| Foundry hub | `hub` | resource group | 3-33 | Alphanumerics, hyphens, underscores | `hub-navigator-prod` |
155+
| Foundry hub project | `proj` | Foundry hub | 3-33 | Alphanumerics, hyphens, underscores | `proj-navigator-prod` |
156+
| Foundry account | `aif` | resource group | 2-64 | Alphanumerics and hyphens | `aif-navigator-prod` |
157+
| Foundry account project | `proj` | Foundry account | — | — | `proj-navigator-prod` |
158+
| Foundry Tools (multi-service) | `ais` | resource group | 2-64 | Alphanumerics and hyphens | `ais-navigator-prod` |
159+
160+
### Analytics and IoT
161+
162+
| Resource | Abbr | Scope | Length | Valid Characters | Example |
163+
|----------|------|-------|--------|-----------------|---------|
164+
| Azure Data Factory | `adf` | global | 3-63 | Alphanumerics and hyphens. Start/end with alphanumeric. | `adf-navigator-prod` |
165+
| Azure Databricks workspace | `dbw` | resource group | 3-64 | Alphanumerics, underscores, hyphens | `dbw-navigator-prod-001` |
166+
| Azure Data Explorer cluster | `dec` | global | 4-22 | Lowercase letters and numbers. Start with a letter. | `decnavigatorprod` |
167+
| Azure Synapse workspace | `synw` | global | 1-50 | Lowercase letters, hyphens, numbers. Start/end with letter or number. | `synw-navigator-prod` |
168+
| IoT hub | `iot` | global | 3-50 | Alphanumerics and hyphens. Can't end with hyphen. | `iot-navigator-prod` |
169+
| Event Grid topic | `evgt` | region | 3-50 | Alphanumerics and hyphens | `evgt-navigator-prod` |
170+
171+
### Developer Tools
172+
173+
| Resource | Abbr | Scope | Length | Valid Characters | Example |
174+
|----------|------|-------|--------|-----------------|---------|
175+
| App Configuration store | `appcs` | global | 5-50 | Alphanumerics and hyphens. No more than two consecutive hyphens. | `appcs-navigator-prod` |
176+
| SignalR | `sigr` | global | 3-63 | Alphanumerics and hyphens. Start with letter, end with letter or number. | `sigr-navigator-prod` |
177+
178+
---
179+
180+
## Resources That Do NOT Allow Hyphens
181+
182+
These resources require concatenated lowercase alphanumerics (no separators):
183+
184+
| Resource | Abbr | Pattern |
185+
|----------|------|---------|
186+
| Storage account | `st` | `st{workload}{env}{instance}` → `stnavigatorprod001` |
187+
| Container registry | `cr` | `cr{workload}{env}{instance}` → `crnavigatorprod001` |
188+
| Azure Data Explorer cluster | `dec` | `dec{workload}{env}` → `decnavigatorprod` |
189+
190+
---
191+
192+
## Examples (CAF)
193+
194+
```
195+
# Management
196+
rg-navigator-prod
197+
rg-webapp-database-dev
198+
199+
# Networking
200+
vnet-shared-eastus2-001
201+
snet-shared-eastus2-001
202+
nsg-weballow-001
203+
pip-dc1-shared-eastus2-001
204+
lbe-navigator-prod-001
205+
206+
# Compute
207+
vm-sql-test-001
208+
vm-sharepoint-dev-001
209+
vmss-navigator-prod-001
210+
asp-navigator-prod-001
211+
app-navigator-prod-001
212+
func-navigator-prod-001
213+
214+
# Containers
215+
aks-navigator-prod-001
216+
ca-navigator-prod-001
217+
cae-navigator-prod-001
218+
crnavigatorprod001 # no hyphens!
219+
220+
# Databases
221+
sql-navigator-prod-001
222+
sqldb-navigator-prod
223+
cosmos-navigator-prod
224+
psql-navigator-prod-001
225+
226+
# Storage / Security
227+
stnavigatordata001 # no hyphens!
228+
kv-navigator-prod-001
229+
id-navigator-prod-001
230+
231+
# Integration
232+
apim-navigator-prod
233+
sbns-navigator-prod
234+
evhns-navigator-prod
235+
236+
# Monitoring
237+
log-navigator-prod-001
238+
appi-navigator-prod-001
239+
240+
# AI
241+
oai-navigator-prod
242+
srch-navigator-prod
243+
```
244+
245+
---
246+
247+
## Do NOT Do
248+
249+
- Do not use underscores unless the resource type requires it — use hyphens.
250+
- Do not spell out the full resource type word (e.g., `storageaccount-myapp` → use `stmyapp001`).
251+
- Do not use uppercase letters (resources are case-insensitive; lowercase is the convention).
252+
- Do not include sensitive data (subscription ID, tenant ID, passwords) in names.
253+
- Do not skip the environment segment — even for production.
254+
- Do not use `#` — it breaks URL parsing in Azure Resource Manager.
255+
- Do not use reserved words or trademarks in names for resources with public endpoints.
256+
- Do not use more than two consecutive hyphens (e.g., `app--prod` is invalid).

0 commit comments

Comments
 (0)