the_order/docs/governance/NAMING_CONVENTION.md

# 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:

```hcl
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:

```bash
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

- [Azure Naming Conventions](https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/naming-and-tagging)
- [Azure Resource Naming Rules](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/resource-name-rules)
- [Terraform Azure Provider Documentation](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs)

---

**Status**: ✅ Standard naming convention defined and ready for implementation