Azure Infrastructure

The BigHammer platform can be deployed on Microsoft Azure using various provisioning methods, including:

• Azure Portal
• Azure CLI (az)
• Terraform / Bicep
• Infrastructure-as-Code (IaC) tools approved by the customer

Regardless of the provisioning method used, the following reference architecture, resource requirements, and configuration values should be used as the baseline for setting up the infrastructure required for the BigHammer platform.

note

The exact implementation may vary based on customer-specific security, networking, compliance, and operational requirements. The reference values below are the minimum recommended configuration for deploying and operating the BigHammer platform on Azure.

Deploy readiness

After foundation is provisioned, use Prerequisites for the Helm deploy checklist (add-ons, networking, tools).

Azure services recommended configuration

Azure service	Description
AKS	Private or public AKS cluster with Workload Identity
PostgreSQL Flexible Server	Application DB, Keycloak DB, users, SSL — passwords in Key Vault
Key Vault	Bootstrap secrets; RBAC mode recommended
Azure DNS / private DNS	Application hostname resolution
Azure Blob / ADLS Gen2	Schemas, artifacts, optional Airflow DAG storage
Azure Container Registry (ACR)	Mirrored container images and Helm OCI charts
Managed identities	ESO + application pod access to Key Vault and storage
Azure Bastion (optional)	Operator access without public jumpbox SSH

Subscription & networking (reference)

Setting	Reference value
Subscription	Customer-specific
Region	Customer-specific (example: <your-azure-region>)
Resource group	Customer-specific naming convention
VNet CIDR	Customer-specific (example: 10.0.0.0/16)
AKS subnet	Dedicated subnet with sufficient IP space
Private endpoints subnet	Key Vault, storage, PostgreSQL PEs
DNS	Private DNS zones for PaaS endpoints and app hostnames

AKS

Setting	Reference value
Cluster name	Customer-specific
Kubernetes version	BigHammer tested: 1.34.x (other supported AKS versions typically work)
Workload Identity	Enabled
OIDC issuer	Enabled
Network plugin	Azure CNI or kubenet per customer policy
Node pool SKU	≥ Standard_D2ads_v5 (scale per workload; HPA enabled in chart)
Node count	≥ 3 for production-style dev; autoscale per policy

Node pool — platform / AI Agent (required)

Setting	Reference value
Pool name	Customer-specific
VM size	Standard_D8as_v5 or larger for multi-service dev
OS disk	≥ 128 GB managed disk
Max pods	Per subnet IP planning
Azure Policy / Defender	Per customer security baseline

PostgreSQL Flexible Server

Setting	Reference value
Server name	Customer-specific
PostgreSQL version	16 (tested)
SKU	≥ Standard_D2ads_v5 General Purpose
Storage	≥ 32 GB with auto-grow
Public access	Disabled (private access recommended)
Backup retention	Per customer policy (minimum 7 days for dev)
Entra auth	Optional; password auth + Entra supported

Databases

Provision on the PostgreSQL server. Names must match Helm values (POSTGRES_DB, KC_DB_URL).

Database	Purpose	Helm / chart
bighammer_db_<env>	Application data (APIs, workers, keycloakapi_db schema)	POSTGRES_DB on app services
keycloak_db_<env>	Keycloak server database (SSO runtime tables)	KC_DB_URL on bhkeycloak

Two databases — do not confuse

	Application	Keycloak server
Database	bighammer_db_<env>	keycloak_db_<env>
Provisioned by	Bootstrap script + automation	Automation / create-dbs-azure.sh
Chart service	APIs, workers, bhkeycloakapi	bhkeycloak only
Env vars	POSTGRES_DB, dual-role users	KC_DB_URL, KC_DB_USERNAME, KC_DB_PASSWORD
DB user	bh_dev_user / bh_app_user	keycloak_db_user
Key Vault password	azure-postgres-master-password, bh-app-user-password	bh-kcdbpwd

bhkeycloakapi uses the application database (schema keycloakapi_db), not the Keycloak server database.

Database users

User	Purpose	Key Vault secret
Admin login	Bootstrap / automation	Not used by Helm at runtime
bh_dev_user	Migrations / Alembic — DDL	azure-postgres-master-password
bh_app_user	Runtime — DML (BH_APP_USER)	bh-app-user-password
keycloak_db_user	Keycloak JDBC	bh-kcdbpwd

After provisioning:

1. Application DB — run schema/grant SQL via create-dbs-azure.sh (see Scripts Reference).
2. Keycloak DB — database and user created by automation; password in Key Vault as bh-kcdbpwd.
3. One-time secrets — push remaining Key Vault secrets before Helm install — Key Vault Secrets.

DNS

Setting	Reference value
Zone	Customer-specific private or public zone
Domain	Customer-specific (example: dataplatform.example.com)
Records	A/CNAME for each global.ingress.*HostName → ingress load balancer IP

Record examples: ui.<env>.<domain>, catalog.<env>.<domain>, kc.<env>.<domain>.

Key Vault

Setting	Reference value
Vault name	Customer-specific
Authorization	RBAC (recommended)
Network	Private endpoint recommended
Soft delete	Enabled per customer policy

Secret names and chart mapping: Key Vault Secrets.

Storage (Blob / ADLS Gen2)

Resource	Purpose
Storage account	Schema artifacts, utilities, optional Loki/Airflow blobs
Containers	Per-service paths (schemas, DAGs, logs)
Access	Private endpoint + managed identity or account key in Key Vault

Azure Container Registry (reference)

Setting	Reference value
Registry	Customer ACR after mirror
Login server	<registry>.azurecr.io
Image path prefix	<registry>.azurecr.io/<repository>/
Helm OCI	oci://<registry>.azurecr.io/bh-helm-release/bighammer

Customer mirror workflow: Release Manifest & Distribution.

Workload Identity (managed identities)

Managed identity	Kubernetes service account(s)	Azure RBAC
ESO identity	external-secrets-operator in platform namespace	Key Vault Secrets User
Platform identity	App KSAs / kubelet identity	Key Vault Secrets User, AcrPull, Storage Blob Data Contributor

Full bindings and chart config: Workload Identity.

Optional platform services

Service	Purpose
Azure Databricks	Analytics / lakehouse (VNet-injected)
Airflow on AKS	Workflow orchestration — Airflow Deployment
Azure AI Foundry	LLM / embeddings for bhaiagent

Helm chart inputs (after provisioning)

Map provisioned resources into your environment values file (for example values-<env>.yaml):

Helm path	Source
global.secretStore.vaultUrl	Key Vault URI
global.secretStore.tenantId	Microsoft Entra tenant ID
global.secretStore.managedIdentityClientId	ESO managed identity client ID
global.image.repository	ACR login server + repository prefix
POSTGRES_HOST	PostgreSQL FQDN or private endpoint
POSTGRES_USER / POSTGRES_DB	bh_dev_user / application database name
BH_APP_USER	bh_app_user
global.bhkeycloak.env.KC_DB_USERNAME	keycloak_db_user
global.bhkeycloak.env.KC_DB_URL	JDBC URL with Keycloak database name
Key Vault secret keys	See Key Vault Secrets

Renaming databases or users

If provisioning uses different database or user names than the reference defaults, update every consumer in your values-<env>.yaml overlay — chart templates read runtime values from Helm values, not hardcoded names.

Object	Chart env var	Typical services
Application DB	POSTGRES_DB	APIs, workers, bhkeycloakapi
Keycloak DB	KC_DB_URL	bhkeycloak only
Keycloak user	KC_DB_USERNAME	bhkeycloak

Also update bootstrap scripts and Key Vault secret values to match.

Customer artifact mirror workflow: Release Manifest & Distribution.