Naming standard
Standard scope
Applies to: All HCS-governed repositories and Azure resources Domain: naming Status: Active
This standard defines how Azure resources, files, branches, and identifiers are named. It was split out of variables.md — that file now covers config YAML, keyvault:// URIs, and variable naming, while this file owns naming patterns specifically.
Three genuinely different naming patterns exist across the estates this repo governs. Rather than force one estate to adopt another's convention — which would break live automation and existing infrastructure — this standard documents the default pattern and then documents the two deviations explicitly, as scope overlays. The divergence is intentional and recorded here, not accidental.
Base pattern (default — applies unless a repo's scope says otherwise)
<type>-<workload/org>-<env>-<region>-<instance>This is a CAF-aligned pattern: resource type prefix, workload or org identifier, environment, Azure region short code, and a zero-padded instance number.
| Component | Description | Example values |
|---|---|---|
| type | Resource type prefix | kv, rg, vm, st |
| workload/org | Short workload or org identifier | hcs, tp, ccb, platform |
| env | Environment | dev, stg, prd |
| region | Azure region short name | eus (East US), wus (West US), neu (North Europe) |
| instance | Two-digit zero-padded number | 01, 02 |
Examples:
kv-hcs-prd-eus-01— Key Vault, HCS org, production, East US, first instancerg-hcs-platform-prd-eus-01— Resource group with an optional descriptive segmentsthcsartifactsprdeus01— Storage account (no hyphens allowed — strip them, keep the naming intent)
Region and instance are always present in the base pattern. Some resource types have character restrictions (Key Vault, Storage Account); strip hyphens and shorten as required while preserving the naming intent. See variables.md for the full resource type prefix table and required tags.
This base pattern applies to every repo unless the repo's standards_scope in master-registry.db is azurelocal or tierpoint-prodtech, in which case the overlay below applies instead.
Overlay: azurelocal scope — purpose-based short form
AzureLocal-scoped repos (community demos, the fictional "Infinite Improbability Corp" examples used throughout AzureLocal documentation) use a shorter, purpose-based pattern with no region segment:
<type>-iic-<purpose>-<##>| Resource | Pattern | Example |
|---|---|---|
| Resource Group | rg-iic-<purpose>-<##> | rg-iic-platform-01 |
| Virtual Network | vnet-iic-<purpose>-<##> | vnet-iic-compute-01 |
| Subnet | snet-iic-<purpose> | snet-iic-management |
| Network Security Group | nsg-iic-<purpose> | nsg-iic-management |
| Key Vault | kv-iic-<purpose> | kv-iic-platform |
| Storage Account | stiic<purpose><##> | stiicdata01 |
| Log Analytics | law-iic-<purpose>-<##> | law-iic-monitor-01 |
| Managed Identity | id-iic-<purpose> | id-iic-deploy |
Why no region: these examples exist to teach a pattern in documentation and community demos, not to model a specific multi-region deployment. Purpose (what the resource is for) is more useful than region in that context. iic always refers to the fictional company — see examples.md for the full IIC policy.
This overlay also covers Active Directory objects (OU=<Purpose>,OU=Servers,DC=iic,DC=local, svc.iic.<purpose> service accounts, grp-iic-<purpose> groups) used in AzureLocal walkthroughs.
Overlay: tierpoint-prodtech scope — full CAF pattern + multi-platform matrix
tierpoint-prodtech-scoped repos use the fuller CAF pattern for Azure resources:
rg-<workload>-<environment>-<region>-<instance>This is functionally close to the HCS base pattern but is documented separately in that scope because it feeds a much larger naming matrix covering platforms the HCS base pattern does not address at all: VMware vSphere (clusters, ESXi hosts, VMs, datastores), Hyper-V (hosts, VMs, virtual switches), Azure Virtual Desktop (host pools, workspaces, session hosts), networking (VLANs, subnets, switches), and firewalls (rules, policies) — each with its own pattern, character-limit table, and NetBIOS constraints (many Windows-joined resources are capped at 15 characters).
This matrix is genuinely large — dozens of patterns across five infrastructure platforms — and it is tierpoint-prodtech-specific. Rather than reproduce it here, the authoritative source stays in that scope:
- Full matrix:
D:/git/tierpoint/prodtech/docs/docs/docs/standards/documentation/naming-conventions.mdx - Azure resource naming specifically: maintained as a separate single source of truth within that same portal (
/product-azure-local-anywhere/planning/01-naming-standards) to prevent drift between documents — it is not duplicated even within the prodtech portal itself, and it is not duplicated here either - Access via the MCP or the scope overlay mechanism described in
_scopes/README.md, which resolvestierpoint-prodtech-scoped standards from the prodtech source at build time
The prodtech naming matrix stays off the public HCS site — see docs-platforms.md for why.
Do not force convergence
These are different estates with different needs. The HCS base pattern serves Azure-only, region-aware production infrastructure. The azurelocal overlay serves teaching examples where region is noise. The tierpoint-prodtech overlay serves a genuinely multi-platform estate (VMware, Hyper-V, AVD, on-prem networking) where Azure is only one of several target platforms. Attempting to unify these into one pattern would either strip useful information from two of the three scopes or add irrelevant complexity to the third. The purpose of this document is to make each scope's pattern explicit and discoverable, not to eliminate the differences.
File, branch, and variable naming
These naming rules are shared across all scopes (no overlay):
| Type | Convention | Pattern | Example |
|---|---|---|---|
| Directories | lowercase-with-hyphens | ^[a-z][a-z0-9-]*$ | getting-started/ |
| Markdown files (docs/) | lowercase-with-hyphens | *.md | deployment-guide.md |
| Root files | UPPERCASE | — | README.md, CHANGELOG.md |
| PowerShell scripts | Verb-Noun.ps1 (PascalCase) | ^[A-Z][a-zA-Z0-9-]*\.ps1$ | Deploy-Solution.ps1 |
| Config files | lowercase-with-hyphens | — | variables.example.yml |
Git branches:
| Pattern | Usage | Example |
|---|---|---|
main | Default branch | — |
feature/<description> | New features | feature/add-validation |
fix/<description> | Bug fixes | fix/config-parsing |
docs/<description> | Documentation | docs/deployment-guide |
chore/<description> | Maintenance, config, tooling | chore/bump-mkdocs |
Variable naming (YAML config keys, snake_case) is covered in variables.md.
Related
- Variables standard — config YAML,
keyvault://URIs, required tags - Examples standard — the IIC fictional-company policy referenced by the
azurelocaloverlay - Key Vault standard — secret naming inside Key Vault (a distinct pattern from resource naming)
_scopes/README.md— how scope overlays are resolved