RaaS Azure Architecture — Master Manual

Auto-generated by scripts/generate_docs.py. > Edit the generator, not this file.

---

1 Architecture Philosophy & Design Goals

This repository implements Rhapsody-as-a-Service (RaaS) on Microsoft Azure,

following a layered, composable Terraform pattern. Key design goals:

Goal	How we achieve it
Repeatability	Every environment is a Terraform root module; no manual clicks.
Isolation	Each customer + environment gets its own state file, VNet, and NSG rules.
Self-healing	VMs run inside single-instance VMSS so Azure auto-recreates failed nodes.
Least privilege	Storage firewalls default-deny; Key Vault access via managed identity only.
Composability	Base layers (account, connectivity, core) are deployed once; env modules consume them via terraform_remote_state.
Auditability	All changes flow through GitHub PRs; CI runs terraform plan before apply.

---

2 Module Relationship & Dependency Graph

graph TD
  subgraph L0["Foundation — Layer 0"]
    base_account["base-account<br/><small>Management</small>"]
    base_monitoring["base-monitoring<br/><small>IAM</small>"]
    env_raas_api["env-raas-api<br/><small>Compute</small>"]
    env_snapshots["env-snapshots<br/><small>Automation</small>"]
    env_upwind["env-upwind<br/><small>Management</small>"]
    test_ci_triage["test-ci-triage<br/><small>Utility</small>"]
  end
  subgraph L1["Platform — Layer 1"]
    base_connectivity["base-connectivity<br/><small>Connectivity</small>"]
    base_core["base-core<br/><small>Networking</small>"]
    base_counter["base-counter<br/><small>Utility</small>"]
    base_fwrules["base-fwrules<br/><small>Connectivity</small>"]
    env_directcifs["env-directcifs<br/><small>Foundation</small>"]
    env_raas_lb["env-raas-lb<br/><small>Compute</small>"]
  end
  subgraph L2["Services — Layer 2"]
    base_diagnostics["base-diagnostics<br/><small>Observability</small>"]
    base_expressroute["base-expressroute<br/><small>Connectivity</small>"]
    base_peering["base-peering<br/><small>Networking</small>"]
    base_routes["base-routes<br/><small>Networking</small>"]
    base_sftp["base-sftp<br/><small>Storage</small>"]
    base_vpn["base-vpn<br/><small>Connectivity</small>"]
    env_filetransfer["env-filetransfer<br/><small>Storage</small>"]
    env_raas["env-raas<br/><small>Compute</small>"]
  end
  avd_hub --> base_core
  base_account --> base_vpn
  base_connectivity --> base_expressroute
  base_connectivity --> base_vpn
  base_core --> base_diagnostics
  base_core --> base_expressroute
  base_core --> base_peering
  base_core --> base_routes
  base_core --> base_sftp
  base_core --> base_vpn
  base_core --> env_filetransfer
  base_core --> env_raas
  base_account --> base_connectivity
  base_account --> base_core
  base_account --> base_counter
  base_account --> base_diagnostics
  base_account --> env_raas
  base_core --> env_raas_lb
  base_sftp --> env_raas
  connectivity --> base_core
  connectivity --> base_diagnostics
  connectivity --> base_fwrules
  env_raas --> base_sftp
  env_raas --> env_filetransfer
  env_raas --> env_directcifs
  env_raas_nonprod --> base_fwrules
  env_raas_prod --> base_fwrules
  management --> base_core
  management --> env_raas

Layer Summary

Layer	Purpose	Modules
0	Foundation — identity, logging, shared config	base-account, base-monitoring, env-raas-api, env-snapshots, env-upwind, test-ci-triage
1	Platform — networking, firewalls, connectivity	base-connectivity, base-core, base-counter, base-fwrules, env-directcifs, env-raas-lb
2	Services — DNS, diagnostics, peering	base-diagnostics, base-expressroute, base-peering, base-routes, base-sftp, base-vpn, env-filetransfer, env-raas

---

3 Detailed Component Analysis

base-account

Property	Value
Layer	0
Role	Management
Depends on	none
Used by	base-vpn
Resource count	10 unique types

Azure resource types provisioned

• azurerm_app_configuration — Centralized feature-flag and configuration store
• azurerm_key_vault — Secure secret, key, and certificate store with RBAC access control
• azurerm_log_analytics_workspace — Central log aggregation and query engine for monitoring
• azurerm_monitor_diagnostic_setting — Sends resource logs/metrics to Log Analytics or Storage
• azurerm_resource_group — Logical container for all Azure resources in this module
• azurerm_role_assignment — RBAC binding granting a principal access to a scope
• azurerm_storage_account — Azure Storage account for blobs, files, queues, or tables
• azurerm_storage_container — Blob container within a storage account
• null_resource
• time_sleep

base-connectivity

Property	Value
Layer	1
Role	Connectivity
Depends on	base_account
Used by	base-expressroute, base-vpn
Resource count	17 unique types

Azure resource types provisioned

• azuread_application_password
• azuread_application_registration
• azuread_service_principal
• azurerm_firewall — Azure Firewall for centralized network traffic inspection and filtering
• azurerm_firewall_policy — Reusable rule collection governing firewall behavior
• azurerm_firewall_policy_rule_collection_group — Grouped set of firewall rules applied as a unit
• azurerm_network_security_group — Stateful firewall rules controlling inbound/outbound traffic
• azurerm_network_security_rule — Individual allow/deny rule within an NSG
• azurerm_public_ip — Public IP address for internet-facing resources
• azurerm_resource_group — Logical container for all Azure resources in this module
• azurerm_role_assignment — RBAC binding granting a principal access to a scope
• azurerm_subnet — Network subdivision within a VNet for resource isolation
• azurerm_virtual_network — Virtual network providing isolated network address space
• coralogix_integration
• random_id
• random_integer
• time_sleep

base-core

Property	Value
Layer	1
Role	Networking
Depends on	avd_hub, base_account, connectivity, management
Used by	base-diagnostics, base-expressroute, base-peering, base-routes, base-sftp, base-vpn, env-filetransfer, env-raas
Resource count	13 unique types

Azure resource types provisioned

• azurerm_firewall_policy_rule_collection_group — Grouped set of firewall rules applied as a unit
• azurerm_network_security_group — Stateful firewall rules controlling inbound/outbound traffic
• azurerm_network_security_rule — Individual allow/deny rule within an NSG
• azurerm_network_watcher_flow_log
• azurerm_private_dns_zone — Private DNS zone for name resolution within VNets
• azurerm_private_dns_zone_virtual_network_link — Links a Private DNS zone to a VNet for resolution
• azurerm_resource_group — Logical container for all Azure resources in this module
• azurerm_route — Individual route entry forcing traffic through a specific next-hop
• azurerm_route_table — Custom routing table to override Azure default routes
• azurerm_storage_account — Azure Storage account for blobs, files, queues, or tables
• azurerm_subnet — Network subdivision within a VNet for resource isolation
• azurerm_virtual_network — Virtual network providing isolated network address space
• azurerm_virtual_network_peering — Bi-directional link between two VNets enabling private connectivity

base-counter

Property	Value
Layer	1
Role	Utility
Depends on	base_account
Used by	none
Resource count	1 unique types

Azure resource types provisioned

• null_resource

base-diagnostics

Property	Value
Layer	2
Role	Observability
Depends on	base-core, base_account, connectivity
Used by	none
Resource count	1 unique types

Azure resource types provisioned

• azurerm_monitor_diagnostic_setting — Sends resource logs/metrics to Log Analytics or Storage

base-expressroute

Property	Value
Layer	2
Role	Connectivity
Depends on	base-connectivity, base-core
Used by	none
Resource count	3 unique types

Azure resource types provisioned

• azurerm_express_route_circuit — Dedicated private connection to Azure via a connectivity provider
• azurerm_express_route_circuit_peering — BGP peering configuration for an ExpressRoute circuit
• azurerm_virtual_network_gateway — VPN or ExpressRoute gateway for hybrid connectivity

base-fwrules

Property	Value
Layer	1
Role	Connectivity
Depends on	connectivity, env_raas_nonprod, env_raas_prod
Used by	none
Resource count	1 unique types

Azure resource types provisioned

• azurerm_firewall_policy_rule_collection_group — Grouped set of firewall rules applied as a unit

base-monitoring

Property	Value
Layer	0
Role	IAM
Depends on	none
Used by	none
Resource count	5 unique types

Azure resource types provisioned

• azuread_application_password
• azuread_application_registration
• azuread_service_principal
• azurerm_role_assignment — RBAC binding granting a principal access to a scope
• coralogix_integration

base-peering

Property	Value
Layer	2
Role	Networking
Depends on	base-core
Used by	none
Resource count	1 unique types

Azure resource types provisioned

• azurerm_virtual_network_peering — Bi-directional link between two VNets enabling private connectivity

base-routes

Property	Value
Layer	2
Role	Networking
Depends on	base-core
Used by	none
Resource count	1 unique types

Azure resource types provisioned

• azurerm_route — Individual route entry forcing traffic through a specific next-hop

base-sftp

Property	Value
Layer	2
Role	Storage
Depends on	base-core, env-raas
Used by	none
Resource count	8 unique types

Azure resource types provisioned

• azurerm_private_endpoint — Private IP endpoint for accessing PaaS services over the backbone
• azurerm_resource_group — Logical container for all Azure resources in this module
• azurerm_role_assignment — RBAC binding granting a principal access to a scope
• azurerm_storage_account — Azure Storage account for blobs, files, queues, or tables
• azurerm_storage_account_local_user
• azurerm_storage_container — Blob container within a storage account
• azurerm_user_assigned_identity — Managed identity for passwordless Azure service authentication
• blob

base-vpn

Property	Value
Layer	2
Role	Connectivity
Depends on	base-account, base-connectivity, base-core
Used by	none
Resource count	10 unique types

Azure resource types provisioned

• azapi_update_resource
• azurerm_key_vault_secret — Individual secret (password, connection string, PSK) stored in Key Vault
• azurerm_local_network_gateway — Representation of an on-premises VPN device in Azure
• azurerm_monitor_diagnostic_setting — Sends resource logs/metrics to Log Analytics or Storage
• azurerm_public_ip — Public IP address for internet-facing resources
• azurerm_virtual_network_gateway — VPN or ExpressRoute gateway for hybrid connectivity
• azurerm_virtual_network_gateway_connection — IPsec/IKE tunnel to an on-premises site
• random_password
• time_sleep
• time_static

env-directcifs

Property	Value
Layer	1
Role	Foundation
Depends on	env_raas
Used by	none
Resource count	6 unique types

Azure resource types provisioned

• azapi_resource
• azurerm_cosmosdb_account
• azurerm_cosmosdb_sql_container
• azurerm_cosmosdb_sql_database
• azurerm_cosmosdb_sql_role_assignment
• azurerm_resource_group — Logical container for all Azure resources in this module

env-filetransfer

Property	Value
Layer	2
Role	Storage
Depends on	base-core, env-raas
Used by	none
Resource count	13 unique types

Azure resource types provisioned

• azurerm_private_dns_zone — Private DNS zone for name resolution within VNets
• azurerm_private_dns_zone_virtual_network_link — Links a Private DNS zone to a VNet for resolution
• azurerm_private_endpoint — Private IP endpoint for accessing PaaS services over the backbone
• azurerm_resource_group — Logical container for all Azure resources in this module
• azurerm_role_assignment — RBAC binding granting a principal access to a scope
• azurerm_storage_account — Azure Storage account for blobs, files, queues, or tables
• azurerm_storage_account_local_user
• azurerm_storage_account_queue_properties
• azurerm_storage_container — Blob container within a storage account
• azurerm_storage_share — Azure Files SMB/NFS share for shared file access
• azurerm_user_assigned_identity — Managed identity for passwordless Azure service authentication
• blob
• file

env-raas

Property	Value
Layer	2
Role	Compute
Depends on	base-core, base_account, base_sftp, management
Used by	base-sftp, env-filetransfer
Resource count	33 unique types

Azure resource types provisioned

• azurerm_application_insights
• azurerm_lb — Azure Load Balancer distributing traffic across backend instances
• azurerm_lb_backend_address_pool — Pool of backend IPs that the load balancer distributes to
• azurerm_lb_nat_rule — Inbound NAT rule for direct port-forwarding to a specific instance
• azurerm_lb_probe — Health probe determining if backend instances can receive traffic
• azurerm_lb_rule — Load-balancing rule mapping frontend port to backend pool
• azurerm_linux_function_app
• azurerm_linux_virtual_machine_scale_set
• azurerm_managed_disk — Persistent block storage attached to VMs
• azurerm_monitor_action_group
• azurerm_monitor_autoscale_setting — Auto-scaling rules for VMSS based on metrics or schedules
• azurerm_monitor_metric_alert
• azurerm_netapp_account
• azurerm_netapp_pool
• azurerm_netapp_volume
• azurerm_network_interface — Virtual NIC attached to a VM or VMSS instance
• azurerm_network_interface_backend_address_pool_association
• azurerm_network_security_rule — Individual allow/deny rule within an NSG
• azurerm_orchestrated_virtual_machine_scale_set — Flexible VMSS for self-healing single-instance VMs
• azurerm_private_dns_a_record — DNS A record within a private zone
• azurerm_private_dns_zone — Private DNS zone for name resolution within VNets
• azurerm_private_dns_zone_virtual_network_link — Links a Private DNS zone to a VNet for resolution
• azurerm_private_endpoint — Private IP endpoint for accessing PaaS services over the backbone
• azurerm_resource_group — Logical container for all Azure resources in this module
• azurerm_role_assignment — RBAC binding granting a principal access to a scope
• azurerm_service_plan
• azurerm_storage_account — Azure Storage account for blobs, files, queues, or tables
• azurerm_storage_blob
• azurerm_storage_container — Blob container within a storage account
• azurerm_storage_share — Azure Files SMB/NFS share for shared file access
• azurerm_user_assigned_identity — Managed identity for passwordless Azure service authentication
• null_resource
• time_sleep

env-raas-api

Property	Value
Layer	0
Role	Compute
Depends on	none
Used by	none
Resource count	14 unique types

Azure resource types provisioned

• azurerm_api_management
• azurerm_api_management_api
• azurerm_api_management_api_operation
• azurerm_api_management_backend
• azurerm_application_gateway
• azurerm_lb — Azure Load Balancer distributing traffic across backend instances
• azurerm_lb_backend_address_pool — Pool of backend IPs that the load balancer distributes to
• azurerm_lb_probe — Health probe determining if backend instances can receive traffic
• azurerm_lb_rule — Load-balancing rule mapping frontend port to backend pool
• azurerm_monitor_autoscale_setting — Auto-scaling rules for VMSS based on metrics or schedules
• azurerm_orchestrated_virtual_machine_scale_set — Flexible VMSS for self-healing single-instance VMs
• azurerm_public_ip — Public IP address for internet-facing resources
• azurerm_resource_group — Logical container for all Azure resources in this module
• azurerm_user_assigned_identity — Managed identity for passwordless Azure service authentication

env-raas-lb

Property	Value
Layer	1
Role	Compute
Depends on	base_core
Used by	none
Resource count	13 unique types

Azure resource types provisioned

• azurerm_lb — Azure Load Balancer distributing traffic across backend instances
• azurerm_lb_backend_address_pool — Pool of backend IPs that the load balancer distributes to
• azurerm_lb_probe — Health probe determining if backend instances can receive traffic
• azurerm_lb_rule — Load-balancing rule mapping frontend port to backend pool
• azurerm_managed_disk — Persistent block storage attached to VMs
• azurerm_monitor_autoscale_setting — Auto-scaling rules for VMSS based on metrics or schedules
• azurerm_network_interface — Virtual NIC attached to a VM or VMSS instance
• azurerm_network_security_rule — Individual allow/deny rule within an NSG
• azurerm_orchestrated_virtual_machine_scale_set — Flexible VMSS for self-healing single-instance VMs
• azurerm_private_dns_a_record — DNS A record within a private zone
• azurerm_role_assignment — RBAC binding granting a principal access to a scope
• azurerm_user_assigned_identity — Managed identity for passwordless Azure service authentication
• null_resource

env-snapshots

Property	Value
Layer	0
Role	Automation
Depends on	none
Used by	none
Resource count	7 unique types

Azure resource types provisioned

• azurerm_automation_account — Azure Automation account for runbooks and scheduled tasks
• azurerm_automation_job_schedule — Binding between a runbook and a schedule
• azurerm_automation_runbook — PowerShell/Python script executed by Azure Automation
• azurerm_automation_schedule — Time-based trigger for automation runbooks
• azurerm_resource_group — Logical container for all Azure resources in this module
• azurerm_role_assignment — RBAC binding granting a principal access to a scope
• azurerm_user_assigned_identity — Managed identity for passwordless Azure service authentication

env-upwind

Property	Value
Layer	0
Role	Management
Depends on	none
Used by	none
Resource count	13 unique types

Azure resource types provisioned

• azuread_application
• azuread_application_api_access
• azuread_application_password
• azuread_service_principal
• azurerm_key_vault — Secure secret, key, and certificate store with RBAC access control
• azurerm_key_vault_secret — Individual secret (password, connection string, PSK) stored in Key Vault
• azurerm_resource_group — Logical container for all Azure resources in this module
• azurerm_role_assignment — RBAC binding granting a principal access to a scope
• azurerm_role_definition
• azurerm_user_assigned_identity — Managed identity for passwordless Azure service authentication
• null_resource
• random_id
• time_sleep

test-ci-triage

Property	Value
Layer	0
Role	Utility
Depends on	none
Used by	none
Resource count	0 unique types

No azurerm_ resources (delegates to sub-modules or uses null resources).

---

4 Operational Workflows & Administration

Deploying a new customer environment

1. Onboard — run onboarding/gen-config.py to generate a customer config

JSON under configs///.

1. Base layers — apply in order:

base-account -> base-connectivity -> base-core -> base-vpn (if VPN needed)

1. Environment — apply env-raas with the customer's .tfvars file.
2. Snapshots — optionally apply env-snapshots for automated disk snapshots.

Day-2 operations

Task	Module	Command
Rotate secrets	base-account	Re-apply; Key Vault secrets are refreshed.
Add peering	base-peering	Supply spoke VNet IDs in tfvars.
Scale VMSS	env-raas	Adjust instance_count in tfvars, re-apply.
Update firewall rules	base-connectivity / base-core	Edit rule collection groups, re-apply.
Snapshot disks	env-snapshots	Automation runbook runs on schedule.

State file layout

Each module stores its state in a dedicated Azure Storage container

(base-account provisions the backend). The key convention is:

    <tenant>/<client>/<module>/<env>.tfstate

This keeps blast radius small — one module's bad apply cannot corrupt another.

---

5 Network Traffic Flow

    flowchart LR
        Internet((Internet))
        FW[Azure Firewall<br/>base-connectivity]
        VPN[VPN Gateway<br/>base-vpn]
        HUB[Hub VNet<br/>base-connectivity]
        SPOKE[Spoke VNet<br/>base-core]
        VMSS[Rhapsody VMSS<br/>env-raas]
        PE[Private Endpoints<br/>env-raas]
        ST[(Storage Accounts)]

        Internet --> FW
        Internet --> VPN
        FW --> HUB
        VPN --> HUB
        HUB -->|VNet Peering| SPOKE
        SPOKE --> VMSS
        VMSS --> PE
        PE --> ST

Key network security controls:

• Azure Firewall in base-connectivity inspects all ingress/egress traffic.
• NSG rules in base-core enforce allow-lists per environment (deny-high-risk-ports rule blocks known dangerous ports).
• Route tables in base-core force spoke traffic through the firewall.
• Private Endpoints in env-raas ensure storage access stays on the Azure backbone; no public internet traversal.
• Private DNS Zones in base-core are linked to the management VNet so name resolution works across peered networks.

---

6 Resource Naming Convention

Resources follow a consistent naming pattern derived from variables:

    <prefix>-<client>-<environment>-<region>-<resource_type>

Examples:

Resource	Naming pattern
Resource group	rg---
VNet	vnet---
NSG	nsg---
Storage account	st (no hyphens, 24 char limit)
Key Vault	kv---
VMSS	vmss---

Naming inputs are controlled per-customer via .tfvars files under each module's

config/ directory.

---

7 External Module Pins

Modules sourced from other repositories and pinned by commit:

Repository	Directory	Branch	Commit
raas-azure-terraform-base-account	base-account	main	v3.6.0
raas-azure-terraform-base-account	base-account	main	416ed5c47dd3
raas-azure-terraform-base-routes	base-routes	main	v1.1.0
raas-azure-terraform-connectivity	base-connectivity	main	v3.3.0
raas-azure-terraform-connectivity	base-connectivity	main	v3.2.0
raas-azure-terraform-core	base-core	main	v3.11.0
raas-azure-terraform-core	base-core	main	v3.13.0
raas-azure-terraform-core	base-core	main	v3.12.0
raas-azure-terraform-core	base-core	main	v3.7.1
raas-azure-terraform-core	base-core	mubadala	4c09c0a13c61
raas-azure-terraform-core	base-core	mubadala	ffffe235187b
raas-azure-terraform-counter	base-counter	main	v3.2.0
raas-azure-terraform-counter	base-counter	main	v3.1.0
raas-azure-terraform-counter	base-counter	mubadala	644dc43d53ca
raas-azure-terraform-counter	base-counter	main	845a38bd8e6f
raas-azure-terraform-env-directcifs	env-directcifs	main	v3.5.0
raas-azure-terraform-env-directcifs	env-directcifs	mubadala-legacy	42dd2a4bf5cf
raas-azure-terraform-env-raas	env-raas	main	v3.25.1
raas-azure-terraform-env-raas	env-raas	main	v3.27.2
raas-azure-terraform-env-raas	env-raas	main	v3.27.1
raas-azure-terraform-env-raas	env-raas	main	v3.25.0
raas-azure-terraform-env-raas	env-raas	main	v3.6.1
raas-azure-terraform-env-raas	env-raas	main	v3.17.2
raas-azure-terraform-env-raas	env-raas	mubadala	35b5ca9a3d74
raas-azure-terraform-env-raas	env-raas	mubadala	547d458a1878
raas-azure-terraform-env-raas	env-raas	mubadala	058da8607c52
raas-azure-terraform-env-raas-lb	env-raas-lb	main	v3.12.6
raas-azure-terraform-env-raas-lb	env-raas-lb	main	v3.5.1
raas-azure-terraform-env-snapshots	env-snapshots	main	v3.1.3
raas-azure-terraform-env-snapshots	env-snapshots	main	v3.2.0
raas-azure-terraform-env-snapshots	env-snapshots	main	v3.1.1
raas-azure-terraform-env-snapshots	env-snapshots	main	68d4f2be1e68
raas-azure-terraform-filetransfer	env-filetransfer	main	v3.3.0
raas-azure-terraform-firewall-rules	base-fwrules	main	v1.0.3
raas-azure-terraform-monitoring	base-monitoring	main	v3.5.0
raas-azure-terraform-monitoring	base-monitoring	main	v3.4.1
raas-azure-terraform-sftp	base-sftp	main	v3.8.0
raas-azure-terraform-upwind	env-upwind	main	v3.1.0
raas-azure-terraform-upwind	env-upwind	main	v3.0.4
raas-azure-terraform-vnet-peering	base-peering	main	v3.2.1
raas-azure-terraform-vpn	base-vpn	main	v4.2.0
raas-azure-terraform-vpn	base-vpn	main	v4.0.0

---

_📋Auto-Generated Documentation | Team: Azure Infrastructure | Generated by: AI Documentation Engine | Date: 2026-08-14 22:09 UTC _