[Chore]: Standardize naming conventions and implement Azure naming patterns in main.bicep

[PlagueHO]

Area

Infrastructure (Bicep/infra)

Chore Type

Code quality

Description

The infra/main.bicep file has inconsistent naming conventions that don't align with Azure naming best practices and make the code harder to maintain. Issues include:

• Mix of camelCase, PascalCase, and snake_case in variable and parameter names
• Non-descriptive generic names like temp, config, settings
• Inconsistent prefix/suffix patterns across similar resources
• Variable names that don't clearly indicate their purpose or scope
• Resource name generation logic that doesn't follow Azure naming conventions

Justification

Consistent naming conventions improve code readability, reduce cognitive load for developers, prevent naming conflicts, align with Azure Well-Architected Framework operational excellence pillar, and make the codebase more maintainable for future contributors.

Acceptance Criteria

• Standardize all parameter names to use camelCase convention
• Standardize all variable names to use camelCase convention
• Replace generic variable names with descriptive, purpose-driven names
• Implement consistent resource naming patterns using Azure abbreviations
• Add prefix/suffix conventions for different resource types
• Ensure generated resource names comply with Azure naming requirements
• Update all references to renamed parameters and variables
• Add naming convention documentation to parameter descriptions
• Verify no breaking changes to external parameter file references
• Update infrastructure-deployment-bicep-avm.md specification with naming conventions

Resolution Documentation

Step 1: Standardize Parameter Names

// Current inconsistent naming
param environment_name string     // snake_case
param ResourceGroupName string    // PascalCase
param storageaccountname string   // lowercase
param aiFoundryIP_AllowList array // mixed case

// Standardized camelCase naming
param environmentName string
param resourceGroupName string  
param storageAccountName string
param aiFoundryIpAllowList array

Step 2: Implement Azure Resource Naming Pattern

// Import Azure abbreviations from abbreviations.json
var azureResourceAbbreviations = loadJsonContent('./abbreviations.json')

// Standardized naming pattern: {workload}-{environment}-{resourceType}-{instance}
var namingPrefix = '${workloadName}-${environmentName}'

var resourceNames = {
  // Storage resources
  storageAccount: '${namingPrefix}-${azureResourceAbbreviations.storageAccount}-001'
  blobContainer: '${namingPrefix}-${azureResourceAbbreviations.blobContainer}'
  fileShare: '${namingPrefix}-${azureResourceAbbreviations.fileShare}'
  
  // AI/ML resources  
  aiFoundryHub: '${namingPrefix}-${azureResourceAbbreviations.machineLearningWorkspace}-001'
  aiFoundryProject: '${namingPrefix}-${azureResourceAbbreviations.machineLearningWorkspace}-proj-001'
  cognitiveService: '${namingPrefix}-${azureResourceAbbreviations.cognitiveService}-001'
  
  // Networking resources
  virtualNetwork: '${namingPrefix}-${azureResourceAbbreviations.virtualNetwork}-001'
  networkSecurityGroup: '${namingPrefix}-${azureResourceAbbreviations.networkSecurityGroup}-001'
  privateEndpoint: '${namingPrefix}-${azureResourceAbbreviations.privateEndpoint}'
  
  // Security resources
  keyVault: '${namingPrefix}-${azureResourceAbbreviations.keyVault}-001'
  logAnalyticsWorkspace: '${namingPrefix}-${azureResourceAbbreviations.logAnalyticsWorkspace}-001'
}

Step 3: Replace Generic Variable Names

// Before: Generic, unclear names
var temp = loadJsonContent('./sample-ai-foundry-projects.json')
var config = {
  setting1: value1
  setting2: value2
}
var settings = merge(defaultSettings, userSettings)

// After: Descriptive, purpose-driven names  
var aiFoundryProjectsConfiguration = loadJsonContent('./sample-ai-foundry-projects.json')
var networkSecurityConfiguration = {
  allowedIpRanges: aiFoundryIpAllowList
  privateEndpointEnabled: deployPrivateNetworking
}
var mergedDeploymentSettings = merge(defaultDeploymentSettings, userProvidedSettings)

Step 4: Implement Consistent Resource Variable Naming

// Before: Inconsistent naming patterns
var storageacc = 'storage${uniqueString(resourceGroup().id)}'
var aiFoundry_name = 'aifoundry${environmentName}'
var KeyVaultName = 'kv-${environmentName}-${workloadName}'

// After: Consistent camelCase with descriptive names
var storageAccountUniqueName = 'st${workloadName}${environmentName}${take(uniqueString(resourceGroup().id), 6)}'
var aiFoundryHubName = 'mlw-${workloadName}-${environmentName}-hub-001'
var keyVaultName = 'kv-${workloadName}-${environmentName}-001'

Step 5: Standardize Configuration Object Names

// Before: Inconsistent structure names
var networkConfig = {
  addressSpace: '10.0.0.0/16'
  subnets: subnets_list
}

var security_settings = {
  enablePrivateAccess: true
  IP_whitelist: allowedIPs
}

// After: Consistent camelCase structure
var networkConfiguration = {
  addressSpace: '10.0.0.0/16'  
  subnetConfigurations: subnetConfigurationList
}

var securityConfiguration = {
  enablePrivateAccess: true
  ipAllowList: aiFoundryIpAllowList
}

Step 6: Update Parameter Descriptions with Naming Context

@description('Environment name for resource naming. Used as: {workload}-{environment}-{resourceType}-{instance}. Must be lowercase, 1-10 characters.')
@minLength(1)
@maxLength(10)
@pattern('^[a-z0-9]+$')
param environmentName string

@description('Workload name for resource naming. Used as: {workload}-{environment}-{resourceType}-{instance}. Must be lowercase, 1-15 characters.')
@minLength(1)
@maxLength(15) 
@pattern('^[a-z0-9]+$')
param workloadName string

Step 7: Add Naming Validation Functions

// Function to validate resource names meet Azure requirements
func validateResourceName(name string, minLength int, maxLength int, allowedChars string) bool =>
  length(name) >= minLength && length(name) <= maxLength && name =~ allowedChars

// Validate generated names
var resourceNameValidation = {
  storageAccount: validateResourceName(resourceNames.storageAccount, 3, 24, '^[a-z0-9]+$')
  keyVault: validateResourceName(resourceNames.keyVault, 3, 24, '^[a-zA-Z0-9-]+$')
  cognitiveService: validateResourceName(resourceNames.cognitiveService, 2, 64, '^[a-zA-Z0-9-_]+$')
}

Step 8: Create Naming Convention Documentation

/*
NAMING CONVENTIONS:
- Parameters: camelCase (e.g., environmentName, workloadName)
- Variables: camelCase (e.g., resourceNames, networkConfiguration)  
- Resources: Azure naming pattern {workload}-{environment}-{resourceType}-{instance}
- Configuration objects: descriptive camelCase with 'Configuration' suffix
- Validation functions: camelCase starting with verb (e.g., validateResourceName)

AZURE RESOURCE NAMING PATTERN:
{workload}-{environment}-{resourceType}-{instance}
Examples:
- aifoundry-dev-st-001 (Storage Account)
- aifoundry-prod-mlw-001 (ML Workspace)
- aifoundry-test-kv-001 (Key Vault)
*/

Side Effects

• Breaking Change: External parameter files (main.bicepparam) will need parameter name updates
• Documentation: All references to old parameter names in documentation must be updated
• Scripts: Any deployment scripts or GitHub Actions workflows referencing old parameter names need updates
• Dependencies: Module calls using old parameter names will break and need updating
• Testing: Existing test configurations may need parameter name adjustments

Priority

Medium - Affects code maintainability

Additional Context

This addresses technical debt identified in the infrastructure audit. Consistent naming conventions are crucial for team collaboration and long-term maintainability. The current inconsistencies make the code harder to understand and more error-prone. Implementing these changes will align with Azure Well-Architected Framework operational excellence principles and industry best practices for Infrastructure as Code.