Heritage Docs

Appearance

0025 — Infrastructure Location, Naming, and Hosting ​

Status: Accepted (2026-06-21)

Date: 2026-06-21

ADO work item: AB#3675

Deciders: Kristopher Turner (platform owner)

Context ​

Heritage Community Hub must be hosted on Azure. Hybrid Cloud Solutions LLC (HCS) already operates an Azure tenant (kris@hybridsolutions.cloud) used for all HCS workloads. Two questions were left implicit across earlier ADRs and must be settled before any infrastructure code is written:

  1. Tenant placement — use the existing HCS tenant or provision a dedicated Heritage Virginia tenant? A separate tenant adds an administrative burden (new billing account, separate identity plane, separate Key Vault secrets rotation) with no technical benefit at the current scale of ~200 members and a single owner. Staying in the HCS tenant lets the platform reuse established service connections, GitHub App credentials, and Key Vault access policies.

  2. Resource naming — earlier design documents and Bicep stubs used both hch and heritageva as workload prefixes inconsistently. The Cloud Adoption Framework (CAF) and Well-Architected Framework (WAF) both require a consistent workload identifier throughout the resource hierarchy (resource group, resources, tags). heritageva is the canonical identifier: it is meaningful, unique within the tenant, and matches the primary domain (heritageva.app). The shorter hch prefix is retired.

Region selection is also settled here. East US (eastus) is the HCS tenant's default region and carries the lowest latency for the US East Coast congregation. Azure Static Web Apps has a more limited regional footprint than Container Apps; East US 2 (eastus2) is the nearest SWA-supported region and is used only for that resource.

This is a naming and placement decision. It introduces no application code.

Decision ​

Host Heritage Community Hub in the existing HCS Azure tenant (kris@hybridsolutions.cloud). Create a single resource group named rg-heritageva-prod-eus within that tenant. All Azure resources use heritageva as the CAF workload prefix. Primary region is East US (eastus); Azure Static Web Apps deploys to East US 2 (eastus2) due to SWA regional availability. Every resource carries a mandatory tag set.

Tenant and subscription ​

  • Tenant: existing HCS Azure tenant (kris@hybridsolutions.cloud).
  • Subscription: the active HCS subscription used for all HCS workloads.
  • No new tenant is provisioned for Heritage Virginia.

Resource group ​

AttributeValue
Namerg-heritageva-prod-eus
CAF patternrg-{workload}-{env}-{region-short}
RegionEast US (eastus)
SubscriptionHCS production subscription

Workload prefix ​

heritageva replaces hch everywhere. No resource name, Bicep parameter, or pipeline variable uses hch after this ADR.

Region assignments ​

Resource typeRegionReason
All resources except SWAEast US (eastus)HCS tenant default; lowest US East Coast latency
Static Web AppEast US 2 (eastus2)SWA region availability; nearest to primary region

CAF resource names ​

ResourceNameCAF abbreviation
Resource grouprg-heritageva-prod-eusrg
Container Apps Environmentcae-heritageva-prod-euscae
Container App (API)ca-heritageva-api-prod-eusca
Azure DB for PostgreSQL Flexible Serverpsql-heritageva-prod-euspsql
Key Vaultkv-heritageva-prod-euskv
Log Analytics Workspacelog-heritageva-prod-euslog
Application Insightsappi-heritageva-prod-eusappi
Static Web Appswa-heritageva-prod-eus2swa

Required tags ​

Every resource and the resource group itself must carry all four tags. Bicep modules enforce this via the tags parameter at the module level; a missing tag is a linting error in CI.

Tag keyValue
projectheritage-community-hub
environmentproduction
workloadheritageva
managedBybicep

Alternatives considered ​

OptionProsConsWhy not chosen
Existing HCS tenant, heritageva prefix (chosen)No new tenant overhead; reuses service connections, KV, GitHub App credentials; consistent naming across all resourcesComingles Heritage workloads with other HCS resources at the subscription level (mitigated by resource group isolation)— chosen
Dedicated Heritage Virginia Azure tenantClean separation from HCS workloads; independent billing and identity planeNew tenant provisioning cost and overhead; separate GitHub App registration; separate Key Vault; extra administrative burden for a solo owner at ~200 membersRejected — overhead not justified at current scale; resource group isolation is sufficient
Keep hch prefixNo rename workNot meaningful to external readers; conflicts with heritageva.app domain identity; inconsistent with existing design docs that already use heritagevaRejected — consistency across domain, design docs, and infra names is required before any resources are provisioned
Single region for all resources (including SWA)Simplest region modelSWA is not available in East US; forcing it there would require a different primary region or accepting an unsupported configurationRejected — East US 2 for SWA only is a minimal and well-understood exception

Consequences ​

Positive ​

  • All infrastructure code, CI/CD variables, Bicep parameters, and runbooks share one naming convention from day one. No post-hoc rename migrations after resources are provisioned.
  • Staying in the HCS tenant eliminates tenant provisioning, identity plane setup, and the GitHub App re-registration that a new tenant would require.
  • The heritageva prefix matches the primary domain (heritageva.app), making resource discovery intuitive in the Azure Portal and in cost reports.
  • The mandatory tag set enables cost filtering by workload=heritageva across all resources in a shared subscription, satisfying basic cost governance without a dedicated subscription.
  • East US is the HCS tenant's established default; no region-migration work is required for existing tenant-level resources (Key Vault, Log Analytics) that may be shared.

Negative / trade-offs ​

  • Shared subscription cost attribution. Resources share a subscription with other HCS workloads. Cost isolation is tag-based (workload=heritageva), not subscription-based. Tag compliance is enforced at the Bicep level but cannot prevent manually created resources from missing tags. Mitigation: Azure Policy require-tag assignments on the resource group.
  • SWA region split. East US 2 for Static Web Apps introduces a minor two-region footprint. In practice, SWA serves a CDN-backed static frontend; the region of the SWA resource itself has minimal latency impact on end users. The API and database remain co-located in East US.
  • No environment separation. Per the project decision (see deleted AB#3080), there is one environment: production. There is no dev or staging resource group. This simplifies naming but means any destructive infrastructure test must be performed against production resources or in a local/ephemeral environment.

Risks ​

  • Name collisions. Some Azure resource types (Key Vault, PostgreSQL server) require globally unique names. kv-heritageva-prod-eus and psql-heritageva-prod-eus must be verified as available before provisioning. Mitigation: Bicep what-if and portal availability check before the first deployment.
  • Tag drift. Manually provisioned resources (e.g., created via Portal for a quick test) may miss required tags. Mitigation: Azure Policy deny on missing tags scoped to rg-heritageva-prod-eus; document in the deployment runbook.

References ​

Heritage Community Hub — Internal. Access restricted via Cloudflare Access + Entra ID.

Heritage Virginia · Owner: Kristopher Turner