Variables and naming standard¶

Consistent naming across all HCS projects makes resources, secrets, and code predictable and searchable. This document is the authoritative reference — when in doubt, check here.

Azure resource naming¶

Pattern¶

<type>-<org>-<env>-<region>-<instance>

Component	Description	Example values
type	Resource type prefix (see table below)	`kv`, `rg`, `vm`
org	Short org identifier	`hcs`, `tp` (TierPoint), `ccb` (Country Cloud Boy)
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 instance - rg-hcs-platform-prd-eus-01 — Resource group with optional descriptive segment - st-hcs-artifacts-prd-eus-01 — Storage account (no hyphens in storage account names — use sthcsartifactsprdeus01)

Storage accounts, Key Vault names, and some other resources have character restrictions. Strip hyphens and shorten where required, but keep the naming intent intact.

Resource type prefixes¶

Prefix	Resource type
`kv`	Key Vault
`rg`	Resource Group
`vm`	Virtual Machine
`st`	Storage Account
`vnet`	Virtual Network
`nsg`	Network Security Group
`pip`	Public IP Address
`mi`	Managed Identity (user-assigned)
`app`	App Service
`func`	Function App
`acr`	Container Registry
`apim`	API Management
`sql`	Azure SQL Server
`cosmos`	Cosmos DB account
`aks`	AKS cluster
`la`	Log Analytics workspace
`ai`	Application Insights
`sb`	Service Bus
`evh`	Event Hub
`cdn`	CDN profile
`ag`	Application Gateway
`lb`	Load Balancer

Environment identifiers¶

Identifier	Use for
`dev`	Development and experimentation
`stg`	Staging, pre-production, UAT
`prd`	Production

Key Vault secret naming¶

Format: lowercase-kebab-case
Be descriptive — the name should tell you what the secret is without a lookup
Examples: hcs-github-org-pat, anthropic-api-key, spn-hcs-ado-pipelines-prd-secret
Avoid abbreviations unless they are universally understood (e.g., pat, api)

ADO variable group naming¶

Format: <project>-<env>-secrets
All lowercase-kebab-case
Examples: platform-prd-secrets, ranger-dev-secrets, scout-prd-secrets

GitHub repo naming¶

Format: lowercase-kebab-case
Prefix with project family for related repos: azurelocal-ranger, azurelocal-surveyor
No dots in repo names (they cause issues with some tools)
Examples: platform-engineering, azure-scout, hcs-bicep-modules

ADO project naming¶

Format: Title Case with spaces
Examples: Platform Engineering, Azure Local Cloud, TierPoint Automation

PowerShell naming¶

Element	Convention	Example
Parameters	`$PascalCase`	`$VaultName`, `$SubscriptionId`, `$DryRun`
Local variables	`$camelCase`	`$secretValue`, `$resourceGroup`, `$accountName`
Functions	`Verb-Noun` with approved verbs	`Get-HCSSecretName`, `Set-HCSEnvironment`
Script files	`Verb-Noun.ps1`	`Load-HCSEnvironment.ps1`, `New-HCSRepo.ps1`
Constants / config	`$PascalCase`	`$VaultName = 'kv-hcs-vault-01'`

Required Azure tags¶

Every Azure resource created by HCS must have these tags. Resources without required tags will be flagged in cost and governance reviews.

Tag	Description	Example
`Owner`	Email of the person or team responsible	`kris@hybridsolutions.cloud`
`Project`	Short project name	`platform-engineering`
`Environment`	One of: dev, stg, prd	`prd`
`CostCenter`	Billing identifier	`hcs-internal`, `tierpoint-consulting`
`ManagedBy`	How the resource was provisioned	`manual`, `bicep`, `terraform`, `ado-pipeline`

Apply tags at resource group level where possible; resources inherit from the group. Override at resource level only when it differs.

az tag update `
    --resource-id <resource-id> `
    --operation merge `
    --tags Owner=kris@hybridsolutions.cloud Project=platform-engineering Environment=prd CostCenter=hcs-internal ManagedBy=manual

Subscription and tenant IDs¶

Subscription ID and Tenant ID are not secrets — they are identifiers. However, they should not be hardcoded in scripts or committed to repos. Load them from environment variables or Key Vault:

AZURE_SUBSCRIPTION_ID — loaded by scripts/Load-HCSEnvironment.ps1
AZURE_TENANT_ID — add to Key Vault and Load-HCSEnvironment.ps1 if needed

Config YAML naming¶

Config files use snake_case for all keys, at every nesting level. Never use camelCase or PascalCase in YAML.

# Correct
identity:
  accounts:
    local_admin_username: hcs-local-admin
    local_admin_password: keyvault://kv-hcs-vault-01/account-local-admin-password
  active_directory:
    domain_name: corp.hybridsolutions.cloud
    ntp_servers:
      - 0.pool.ntp.org
      - 1.pool.ntp.org

compute:
  azure_local:
    cluster_name: hcs-cluster-01
    dns_servers:
      - 10.0.0.10
      - 10.0.0.11

# Wrong — never do this
identity:
  accounts:
    localAdminUsername: hcs-local-admin   # camelCase — prohibited
    LocalAdminPassword: ...               # PascalCase — prohibited

keyvault:// URI scheme¶

Config YAML files reference Key Vault secrets using the keyvault:// URI scheme. This keeps config files shareable (no actual secrets) while giving scripts a clear signal to resolve the value at runtime.

keyvault://<vault-name>/<secret-name>

Examples:

identity:
  accounts:
    local_admin_password:  keyvault://kv-hcs-vault-01/account-local-admin-password
    lcm_password:          keyvault://kv-hcs-vault-01/account-lcm-password
    domain_join_password:  keyvault://kv-hcs-vault-01/account-domain-join-password

Scripts resolve these at runtime using Resolve-KeyVaultRef. See scripting standard for the function implementation.

The <vault-name> in the URI should always be kv-hcs-vault-01 unless the project has its own isolated vault documented in docs/identity/overview.md.

Config file bootstrap policy¶

Every repo that uses a config/variables.yml file must also ship a config/variables.example.yml that is committed to the repo. The example file contains all keys with placeholder or safe default values — never real secrets or environment-specific values.

Scripts that require a config file must implement the bootstrap policy: if variables.yml is missing and variables.example.yml exists, copy the example file automatically and prompt the user to fill in their values before re-running.

# config/variables.example.yml
# Copy this file to variables.yml and fill in your environment values.
# variables.yml is gitignored — never commit it.

identity:
  accounts:
    local_admin_username: hcs-local-admin
    local_admin_password: keyvault://kv-hcs-vault-01/account-local-admin-password

compute:
  azure_local:
    cluster_name: REPLACE-WITH-YOUR-CLUSTER-NAME
    dns_servers:
      - REPLACE-WITH-DNS-SERVER-1
      - REPLACE-WITH-DNS-SERVER-2

The .gitignore for every infrastructure repo must include:

config/variables.yml
!config/variables.example.yml