d-bis/the_order
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: implement naming convention, deployment automation, and infrastructure updates

Browse Source 
- 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
This commit is contained in:
defiQUG
2025-11-12 08:22:51 -08:00
parent 9e46f3f316
commit 8649ad4124
136 changed files with 17251 additions and 147 deletions
Download Patch File Download Diff File Expand all files Collapse all files

354
docs/governance/NAMING_CONVENTION.md Normal file
View File

@@ -0,0 +1,354 @@
# 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

172
docs/governance/NAMING_IMPLEMENTATION_SUMMARY.md Normal file
View File

@@ -0,0 +1,172 @@
# Naming Convention Implementation Summary
**Last Updated**: 2025-01-27
**Status**: ✅ Complete
---
## Overview
The standardized naming convention has been fully implemented across The Order project. All Azure resources now follow the pattern:
```
{provider}-{region}-{resource}-{env}-{purpose}
```
---
## Implementation Status
### ✅ Completed
1. **Naming Convention Document** (`docs/governance/NAMING_CONVENTION.md`)
- Comprehensive naming rules and patterns
- Region abbreviations
- Resource type abbreviations
- Environment abbreviations
- Purpose identifiers
- Examples for all resource types
2. **Terraform Implementation**
- ✅ Created `locals.tf` with centralized naming functions
- ✅ Updated `resource-groups.tf` to use new naming
- ✅ Updated `storage.tf` to use new naming (with special rules)
- ✅ Updated `outputs.tf` with naming convention outputs
- ✅ Updated `variables.tf` with region validation
- ✅ Updated `versions.tf` backend comments
3. **Deployment Scripts**
- ✅ Updated `scripts/deploy/config.sh` with naming functions
- ✅ Added region abbreviation mapping
- ✅ Added environment abbreviation mapping
- ✅ All resource names now use new convention
4. **Documentation**
- ✅ Updated deployment guide with naming convention reference
- ✅ Created naming validation document
- ✅ All examples updated
---
## Naming Examples
### Resource Groups
- **Old**: `the-order-dev-rg`
- **New**: `az-we-rg-dev-main`
### Storage Accounts
- **Old**: `theorderdevdata`
- **New**: `azwesadevdata` (alphanumeric only, max 24 chars)
### Key Vaults
- **Old**: `the-order-dev-kv`
- **New**: `az-we-kv-dev-main` (max 24 chars)
### AKS Clusters
- **Old**: `the-order-dev-aks`
- **New**: `az-we-aks-dev-main`
### Container Registries
- **Old**: `theorderacr`
- **New**: `azweacrdev` (alphanumeric only, max 50 chars)
---
## Key Features
### Centralized Naming
All naming logic is centralized in `infra/terraform/locals.tf`:
```hcl
locals {
provider = "az"
region_short = "we" # westeurope
env_short = "dev"
rg_name = "${local.provider}-${local.region_short}-rg-${local.env_short}-main"
sa_data_name = "${local.provider}${local.region_short}sa${local.env_short}data"
# ... etc
}
```
### Automatic Abbreviations
Region and environment abbreviations are automatically calculated:
- `westeurope` → `we`
- `northeurope` → `ne`
- `uksouth` → `uk`
- `dev` → `dev`
- `stage` → `stg`
- `prod` → `prd`
### Validation
Terraform variables include validation:
```hcl
validation {
condition = contains([
"westeurope", "northeurope", "uksouth", ...
], var.azure_region)
error_message = "Region must be one of the supported non-US regions."
}
```
---
## Usage
### In Terraform
```hcl
resource "azurerm_resource_group" "main" {
name = local.rg_name # az-we-rg-dev-main
location = var.azure_region
}
```
### In Deployment Scripts
```bash
# Automatically calculated from environment variables
readonly RESOURCE_GROUP_NAME="${NAME_PREFIX}-rg-${ENV_SHORT}-main"
# Result: az-we-rg-dev-main
```
---
## Benefits
1. **Consistency**: All resources follow the same pattern
2. **Clarity**: Names are self-documenting
3. **Compliance**: Meets Azure naming requirements
4. **Maintainability**: Centralized naming logic
5. **Scalability**: Easy to add new resources
6. **Automation**: Scripts automatically generate correct names
---
## Next Steps
When adding new resources:
1. Add naming function to `locals.tf`
2. Use the local value in resource definition
3. Update documentation if needed
4. Test with Terraform plan
---
## References
- [Naming Convention Document](./NAMING_CONVENTION.md)
- [Terraform Locals](../infra/terraform/locals.tf)
- [Deployment Config](../../scripts/deploy/config.sh)
- [Naming Validation](../infra/terraform/NAMING_VALIDATION.md)
---
**Status**: ✅ Implementation complete and ready for use