Variables and naming standard

Standard scope

Applies to: All HCS-governed repos — variable, parameter, and config naming conventions Domain: variables Status: Active

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

Azure resource naming conventions now live in naming.md.

---

Environment identifiers

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

---

Key Vault secret naming

For the naming standard that governs secrets, keys, and certificates stored inside Key Vault, see the dedicated Key Vault standard.

The KV resource itself (kv-hcs-vault-01) follows the Azure resource naming pattern defined in naming.md: kv-<org>-<env>-<region>-<instance>.

---

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, no org prefix for solution/product projects — see ado-project-strategy.md for the full naming rules (solution vs independent-repo em-dash naming).
• Examples: Platform Engineering, CloudSmith, Repo Wrangler, Azure Local — Ranger

---

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 is always read from config (security.keyvault.kv_name, or the URI itself) — it is never assumed. Resolve-KeyVaultRef must not hardcode a vault name. This repo's own default happens to be kv-hcs-vault-01, but other scopes resolve against their own vaults (for example kv-tp-tplabs-01 for TierPoint work). The Key Vault standard is the authoritative reference for the multi-vault model, cross-vault access via the platform managed identity, and per-org vault assignment.

---

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