Cloud Architecture on Azure

High-level cloud architecture for deploying the BigHammer platform on Azure Kubernetes Service (AKS) using the platform umbrella Helm chart.

This document describes components and data flows in a cloud-agnostic, environment-neutral way. Replace placeholders such as <your-keyvault>, <your-domain>, and <your-namespace> with values from your deployment.

---

Architecture overview

---

Deployment layers

Layer	Responsibility
Azure foundation	AKS, Key Vault, PostgreSQL, storage, ACR, DNS, optional private endpoints / VNet integration
Cluster add-ons	External Secrets Operator, NGINX Ingress Controller, Stakater Reloader, optional Redis
Messaging	RabbitMQ (separate Helm release; referenced by APIs and workers)
Platform chart	Umbrella chart — APIs, UI, workers, Keycloak, ingress rules, SecretStore
Orchestration (optional)	airflow-azure — workflow scheduling in a dedicated namespace

---

Platform umbrella chart

The platform umbrella chart packages the application stack as sub-charts, each toggled with global.<subchart>.enabled.

Sub-charts

Sub-chart	Type	Purpose
bhui	Deployment + Ingress	Main web UI
bhadminui	Deployment	Administration UI
bhcatalogapi	Deployment	Catalog / metadata API
bhauditapi	Deployment	Audit API
bhaiagent	Deployment	AI agent API
bhkeycloak	Deployment	Identity broker (SSO)
bhkeycloakapi	Deployment	Keycloak administration API
bhnginx	Deployment	Reverse proxy in front of Keycloak
bhtransformationutils	Deployment	Transformation utilities API
bhcatalogworker	Deployment	Celery worker for catalog jobs
bhauditworker	Deployment	Celery worker for audit jobs
bhaiagentworker	Deployment	Celery worker for AI agent jobs
bhcelerybeat	Deployment	Celery beat scheduler

Parent-chart resources

In addition to sub-charts, the umbrella chart creates:

Resource	Purpose
SecretStore	Namespace-scoped Azure Key Vault provider for External Secrets
external-secrets-operator ServiceAccount	Workload Identity–enabled SA used by ESO to read Key Vault
Storage ExternalSecret	Syncs blob account name/key for schema mounts
Shared blob PV/PVC	Optional ReadWriteMany volume for shared schema files (global.azureBlobSchemas)

RabbitMQ and Redis are not sub-charts of the platform umbrella chart. Deploy them as separate releases in the same or a peer namespace and point services at bhrabbitmq.<namespace>.svc.cluster.local and bhredis-master.<namespace>.svc.cluster.local in your values file.

---

Request and authentication flow

Airflow (when deployed) typically uses direct Entra OAuth rather than the Keycloak broker. See Airflow Azure Deployment.

---

Ingress routing

A single Ingress resource (defined in the bhui sub-chart) terminates TLS and routes by hostname. Hostnames are configured under global.ingress in your values file.

Ingress host key	Typical backend service	Port
uiHostName	bhui	80
adminuiHostName	bhadminui	80
catalogHostName	bhcatalogapi	80
auditHostName	bhauditapi	80
aiAgentHostName	bhaiagent	80
kcHostName	bhkeycloak	80
kcapiHostName	bhkeycloakapi	80
transformationUtilsHostName	bhtransformationutils	80
rabbitmqHostName	bhrabbitmq (management UI)	15672

TLS uses a Kubernetes secret name from global.ingress.tlsSecretName, populated by an ExternalSecret that reads the wildcard certificate from Key Vault.

---

Secrets architecture

• Each enabled sub-chart creates an ExternalSecret referencing the namespace SecretStore.
• The chart deploys a dedicated external-secrets-operator ServiceAccount in the platform namespace with azure.workload.identity annotations (global.secretStore.managedIdentityClientId).
• Sensitive values (database passwords, API keys, TLS material) are never stored in Git; only non-secret configuration lives in values files.
• Stakater Reloader (global.annotations.reloader.stakater.com/auto) restarts pods when synced secrets change.

For the full secret name list, see Key Vault Secrets.

---

Data stores

PostgreSQL

Azure Database for PostgreSQL Flexible Server hosts:

• A main application database (e.g. bighammer_db_<env>) with schemas: catalog_db, agent_db, audit_db, celery_db, keycloakapi_db, llm_observability_db
• Keycloak database (e.g. keycloak_db_<env>)
• Optional SonarQube database

Database bootstrap is automated by install scripts (see Scripts Reference).

Azure Blob Storage

Used for:

• Pipeline / catalog schemas (global.azureBlobSchemas)
• Application utilities and static assets (per-service azureBlob settings)
• Optional shared ReadWriteMany mount via Blob CSI

Redis (optional)

The AI agent stack uses Redis for caching/session state when a Redis release is deployed and referenced in global.bhaiagent.env.

RabbitMQ

Celery workers and APIs publish/consume tasks via RabbitMQ. Password is synced from Key Vault (bh-rabbitmq-password).

---

Async processing

See RabbitMQ & Celery Workers for worker configuration patterns.

---

Workload Identity

Pods authenticate to Azure without embedded credentials:

1. AKS — OIDC issuer and Workload Identity enabled
2. User-assigned managed identity — granted Key Vault Secrets User, AcrPull, and storage roles as needed
3. Federated credentials — link Kubernetes service accounts to the managed identity
4. Pod / SA annotations — azure.workload.identity/client-id and azure.workload.identity/use: "true"

Details: Workload Identity.

---

Optional: Airflow

Deploy airflow-azure in a separate namespace. It reuses:

• The same Key Vault (often via ClusterSecretStore)
• Wildcard TLS secrets
• PostgreSQL (airflow database) and/or Blob for DAG storage

See Airflow Azure Deployment and ClusterSecretStore for TLS.

---

Network and ports (reference)

Traffic	Protocol	Port	Notes
User → Ingress	HTTPS	443	Public or private ingress depending on deployment
Ingress → services	HTTP	80	TLS terminated at ingress
APIs → PostgreSQL	TCP	5432	Use sslmode=require
Workers → RabbitMQ	AMQP	5672	In-cluster service DNS
RabbitMQ management (ingress)	HTTPS	443	Proxied to 15672
Key Vault / Blob / ACR	HTTPS	443	Via private endpoint or Azure backbone

---

Related documentation

• Prerequisites
• Platform Deployment
• Key Vault Secrets
• External Secrets Operator
• Deployment Checklist