d-bis/the_order
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
the_order/docs/governance/NAMING_CONVENTION.md
defiQUG 8649ad4124 feat: implement naming convention, deployment automation, and infrastructure updates 
- Add comprehensive naming convention (provider-region-resource-env-purpose)
- Implement Terraform locals for centralized naming
- Update all Terraform resources to use new naming convention
- Create deployment automation framework (18 phase scripts)
- Add Azure setup scripts (provider registration, quota checks)
- Update deployment scripts config with naming functions
- Create complete deployment documentation (guide, steps, quick reference)
- Add frontend portal implementations (public and internal)
- Add UI component library (18 components)
- Enhance Entra VerifiedID integration with file utilities
- Add API client package for all services
- Create comprehensive documentation (naming, deployment, next steps)

Infrastructure:
- Resource groups, storage accounts with new naming
- Terraform configuration updates
- Outputs with naming convention examples

Deployment:
- Automated deployment scripts for all 15 phases
- State management and logging
- Error handling and validation

Documentation:
- Naming convention guide and implementation summary
- Complete deployment guide (296 steps)
- Next steps and quick start guides
- Azure prerequisites and setup completion docs

Note: ESLint warnings present - will be addressed in follow-up commit
2025-11-12 08:22:51 -08:00

9.9 KiB
Raw Permalink Blame History

Naming Convention - The Order

Last Updated: 2025-01-27
Status: Standard naming convention for all Azure resources

Overview

This document defines the standardized naming convention for all Azure resources in The Order project. The convention ensures consistency, clarity, and compliance with Azure naming requirements.

Naming Pattern

Format Structure

{provider}-{region}-{resource}-{env}-{purpose}

Segment Definitions

Segment Description Format Examples
provider Cloud provider identifier 2-3 chars, lowercase az (Azure)
region Azure region abbreviation 2-3 chars, lowercase we (westeurope), ne (northeurope)
resource Resource type abbreviation 2-5 chars, lowercase rg (resource group), sa (storage account)
env Environment identifier 3-5 chars, lowercase dev, stg, prd
purpose Resource purpose/name 3-15 chars, lowercase, alphanumeric main, data, kv (key vault)

Region Abbreviations

Full Name Abbreviation Code
westeurope we we
northeurope ne ne
uksouth uk uk
switzerlandnorth ch ch
norwayeast no no
francecentral fr fr
germanywestcentral de de

Rule: Use first 2 letters of country code or region identifier.

Resource Type Abbreviations

Resource Type Abbreviation Azure Limit Example
Resource Group rg 90 chars az-we-rg-dev-main
Storage Account sa 24 chars, alphanumeric azwesadevdata
Key Vault kv 24 chars, alphanumeric az-we-kv-dev-main
AKS Cluster aks 63 chars az-we-aks-dev-main
Container Registry acr 50 chars, alphanumeric azweacrdev
PostgreSQL Server psql 63 chars az-we-psql-dev-main
Database db 63 chars az-we-db-dev-main
Virtual Network vnet 64 chars az-we-vnet-dev-main
Subnet snet 80 chars az-we-snet-dev-main
Network Security Group nsg 80 chars az-we-nsg-dev-main
Public IP pip 80 chars az-we-pip-dev-main
Load Balancer lb 80 chars az-we-lb-dev-main
Application Gateway agw 80 chars az-we-agw-dev-main
Log Analytics Workspace law 63 chars az-we-law-dev-main
Application Insights appi 255 chars az-we-appi-dev-main
Managed Identity mi 128 chars az-we-mi-dev-main
Service Principal sp N/A az-we-sp-dev-main

Environment Abbreviations

Environment Abbreviation Usage
Development dev Development environment
Staging stg Pre-production testing
Production prd Production environment
Management mgmt Management/infrastructure

Purpose Identifiers

Purpose Identifier Usage
Main application main Primary application resources
Data storage data Application data storage
State/Backend state Terraform state, backend storage
Secrets sec Key Vault, secrets management
Monitoring mon Monitoring and logging
Network net Networking resources
Compute cmp Compute resources (VMs, AKS)
Database db Database resources
Container cnt Container registry

Naming Examples

Resource Groups

az-we-rg-dev-main          # Main development resource group
az-we-rg-stg-main          # Main staging resource group
az-we-rg-prd-main          # Main production resource group
az-we-rg-mgmt-state        # Management resource group for Terraform state

Storage Accounts

azwesadevdata              # Development data storage (24 chars max)
azwesastgdata              # Staging data storage
azwesaprddata              # Production data storage
azwesamgmtstate            # Terraform state storage

Key Vaults

az-we-kv-dev-main         # Development Key Vault
az-we-kv-stg-main         # Staging Key Vault
az-we-kv-prd-main         # Production Key Vault
az-we-kv-mgmt-sec         # Management Key Vault

AKS Clusters

az-we-aks-dev-main        # Development AKS cluster
az-we-aks-stg-main        # Staging AKS cluster
az-we-aks-prd-main        # Production AKS cluster

Container Registries

azweacrdev                 # Development ACR (alphanumeric only)
azweacrstg                 # Staging ACR
azweacrprd                 # Production ACR

PostgreSQL Servers

az-we-psql-dev-main       # Development PostgreSQL server
az-we-psql-stg-main       # Staging PostgreSQL server
az-we-psql-prd-main       # Production PostgreSQL server

Databases

az-we-db-dev-main         # Development database
az-we-db-stg-main         # Staging database
az-we-db-prd-main         # Production database

Virtual Networks

az-we-vnet-dev-main       # Development virtual network
az-we-vnet-stg-main       # Staging virtual network
az-we-vnet-prd-main       # Production virtual network

Application Insights

az-we-appi-dev-main       # Development Application Insights
az-we-appi-stg-main       # Staging Application Insights
az-we-appi-prd-main       # Production Application Insights

Log Analytics Workspaces

az-we-law-dev-main        # Development Log Analytics workspace
az-we-law-stg-main        # Staging Log Analytics workspace
az-we-law-prd-main        # Production Log Analytics workspace

Special Cases

Storage Account Naming

Storage accounts have strict requirements:

  • Max length: 24 characters
  • Allowed characters: Lowercase letters and numbers only
  • No hyphens: Must be alphanumeric only

Pattern: {provider}{region}{resource}{env}{purpose}

Example: azwesadevdata (az + we + sa + dev + data)

Container Registry Naming

ACR names have requirements:

  • Max length: 50 characters
  • Allowed characters: Alphanumeric only
  • No hyphens: Must be alphanumeric only

Pattern: {provider}{region}{resource}{env}

Example: azweacrdev (az + we + acr + dev)

Key Vault Naming

Key Vault names:

  • Max length: 24 characters
  • Allowed characters: Alphanumeric and hyphens
  • Must be globally unique

Pattern: {provider}-{region}-{resource}-{env}-{purpose}

Example: az-we-kv-dev-main

Kubernetes Resources

Namespaces

the-order-dev              # Development namespace
the-order-stg              # Staging namespace
the-order-prd              # Production namespace

Service Names

identity                   # Identity service
intake                     # Intake service
finance                    # Finance service
dataroom                   # Dataroom service
portal-public              # Public portal
portal-internal            # Internal portal

Deployment Names

identity                   # Identity deployment
intake                     # Intake deployment
finance                    # Finance deployment
dataroom                   # Dataroom deployment
portal-public              # Public portal deployment
portal-internal            # Internal portal deployment

Tags

All resources must include the following tags:

Tag Key Value Example
Environment Environment name dev, stg, prd
Project Project identifier the-order
Region Azure region westeurope
ManagedBy Management tool Terraform, Manual
CostCenter Cost allocation engineering
Owner Resource owner platform-team

Naming Validation

Terraform Validation

All resource names should be validated in Terraform:

variable "resource_name" {
  type = string
  validation {
    condition = can(regex("^az-[a-z]{2}-[a-z]{2,5}-[a-z]{3,5}-[a-z]{3,15}$", var.resource_name))
    error_message = "Resource name must follow pattern: az-{region}-{resource}-{env}-{purpose}"
  }
}

Script Validation

Deployment scripts should validate names:

validate_name() {
  local name=$1
  local pattern="^az-[a-z]{2}-[a-z]{2,5}-[a-z]{3,5}-[a-z]{3,15}$"
  if [[ ! $name =~ $pattern ]]; then
    echo "Invalid name format: $name"
    return 1
  fi
}

Migration Guide

Current Naming → New Naming

Current New Notes
the-order-dev-rg az-we-rg-dev-main Add provider and region
theorderdevdata azwesadevdata Storage account (no hyphens)
the-order-dev-kv az-we-kv-dev-main Add provider and region
the-order-dev-aks az-we-aks-dev-main Add provider and region

Implementation Checklist

  • Update Terraform variables to use new naming
  • Update deployment scripts (config.sh)
  • Update all Terraform resource definitions
  • Update documentation
  • Migrate existing resources (if applicable)
  • Validate all names meet Azure requirements
  • Update CI/CD pipelines
  • Update monitoring and alerting

Best Practices

  1. Consistency: Always use the same pattern across all resources
  2. Clarity: Names should be self-documenting
  3. Length: Keep names as short as possible while maintaining clarity
  4. Uniqueness: Ensure names are unique within Azure subscription
  5. Validation: Always validate names before resource creation
  6. Documentation: Document any deviations from the standard
  7. Tags: Use tags for additional metadata, not names

References

Status: ✅ Standard naming convention defined and ready for implementation

Reference in New Issue View Git Blame Copy Permalink