Platform Azure Deployment

Deploy the BigHammer umbrella chart (bighammer) on AKS. This page covers values preparation and Helm install — the final step after infrastructure, database bootstrap, secrets, and cluster add-ons are ready.

For architecture diagrams and component relationships, see Cloud Architecture.

Before you start

Complete these steps before running helm upgrade:

Step	Action	Doc
0	AKS, PostgreSQL, platform Key Vault passwords, DNS	Infrastructure
1	Application DB schemas and grants	Scripts Reference — Database creation
2	Verify Key Vault + create one-time secrets	Key Vault Secrets · Scripts Reference
3	ESO, edge, RabbitMQ, TLS	Cluster preparation

Also confirm Prerequisites and mirror entitled artifacts per Release Manifest & Distribution.

End-to-end journey

Step	Action	Doc
0	AKS, PostgreSQL, provision platform Key Vault passwords, DNS	Infrastructure
1	Application DB schemas and grants	Scripts Reference
2	Verify Key Vault + create one-time secrets	Key Vault Secrets · Scripts Reference
3	ESO, edge, RabbitMQ, TLS	Cluster preparation
4	Mirror chart, prepare values, Helm install (this page)	—

If pods fail with permission denied for schema, see Database bootstrap troubleshooting.

Mirror chart and prepare values

Pull the chart from your mirrored ACR after Release Manifest & Distribution:

az acr login --name <registry>

helm pull oci://<registry>.azurecr.io/bh-helm-release/bighammer \
  --version <CHART_VERSION>

tar -xzf bighammer-<CHART_VERSION>.tgz
cp bighammer/values.yaml values.yaml
cp bighammer/values-release.yaml values-<env>.yaml   # edit all placeholders

Do not deploy values-release.yaml as-is

values-release.yaml uses fictional placeholders (sample hostnames, resource IDs). Copy it to values-<env>.yaml in your deploy repo and replace every sample value.

What the chart deploys

The platform umbrella chart installs:

Category	Components
Web	`bhui`, `bhadminui`
APIs	`bhcatalogapi`, `bhauditapi`, `bhaiagent`, `bhkeycloakapi`, `bhtransformationutils`
Identity	`bhkeycloak`, `bhnginx`
Workers	`bhcatalogworker`, `bhauditworker`, `bhaiagentworker`, `bhcelerybeat`
Platform resources	SecretStore, ESO service account, storage ExternalSecret, optional shared blob PV/PVC, Ingress

Deploy separately (not bundled in the umbrella chart):

Release	Purpose
external-secrets	Sync Key Vault → Kubernetes
ingress-nginx	Ingress class `nginx`
reloader	Restart pods on secret/config changes
rabbitmq	Celery message broker
redis (optional)	AI agent cache
airflow (optional)	Workflow orchestration

Prerequisites

Complete Azure Prerequisites before deploying:

AKS with Workload Identity and OIDC issuer
Azure Key Vault with required secrets (Key Vault Secrets)
PostgreSQL Flexible Server with databases and roles created
ACR with platform images
Cluster add-ons installed (ESO, ingress-nginx, reloader, RabbitMQ)

Values files

File	Use
`values.yaml`	Chart defaults, `global.remoteSecrets`, service toggles
`values-release.yaml`	Sample customer overlay in the chart (placeholder hostnames — reference and CI only)
`values-<env>.yaml`	Your per-environment overlay (copy from `values-release.yaml`)

Copy a values file and replace all environment-specific settings. Never commit secrets to Git.

Database and Key Vault mapping

global:
  remoteSecrets:
    postgres:
      password: azure-postgres-master-password   # POSTGRES_PASSWORD → bh_dev_user
    app:
      userPassword: bh-app-user-password         # BH_APP_USER_PASSWORD → bh_app_user

  bhcatalogapi:
    env:
      POSTGRES_USER: bh_dev_user
      BH_APP_USER: bh_app_user
      POSTGRES_DB: bighammer_db_<env>

Key `global` settings

Path	Description
`global.namespace`	Kubernetes namespace (default pattern: `bh-control-plane`)
`global.image.repository`	ACR prefix, e.g. `<your-acr>.azurecr.io/`
`global.secretStore.vaultUrl`	`https://<your-keyvault>.vault.azure.net/`
`global.secretStore.tenantId`	Microsoft Entra tenant ID
`global.secretStore.managedIdentityClientId`	User-assigned MI for ESO Key Vault access
`global.secretStore.name`	SecretStore resource name
`global.ingress.*HostName`	Per-service DNS hostnames
`global.ingress.tlsSecretName`	Kubernetes TLS secret name for ingress
`global.azureBlobSchemas`	Blob account, container, mount path for schemas
`global.azureStorageAccount`	Storage account for CSI / ESO storage secret
`global.<subchart>.enabled`	Toggle each sub-chart
`global.dev.enabled`	When `true`, enables additional dev-only ExternalSecret keys

Per-service configuration

Each sub-chart is configured under global.<name> with:

image.name / image.tag — container image in ACR
env — non-secret environment variables (DB host, schema names, internal URLs)
serviceAccount.annotations — Workload Identity client ID per service
resources, livenessProbe, readinessProbe

Internal service URLs use Kubernetes DNS, e.g. http://bhcatalogapi, bhrabbitmq.<namespace>.svc.cluster.local.

Deployment options

Option 1: Automated install (recommended)

Install scripts in the deployment repository (scripts/) orchestrate:

Validate dependencies (PostgreSQL, Key Vault, ACR, ESO, RabbitMQ)
Create databases and roles (create-dbs-azure.sh)
Push or verify Key Vault secrets
Confirm External Secrets Operator is healthy
helm upgrade --install for the platform chart

cd scripts
cp install-config-azure.example.env install-config-azure.env
# Edit install-config-azure.env — see Scripts Reference

./install-prerequisites-azure.sh   # once per cluster
./install-platform-azure.sh        # databases, secrets, helm deploy (script name may vary)

Or use the one-shot wrapper in your deployment repository.

See Scripts Reference for configuration variables and skip flags.

Option 2: Manual Helm deployment

cd <platform-chart-directory>
helm dependency update

helm upgrade --install <release-name> . \
  --namespace <your-namespace> \
  --create-namespace \
  -f values-<env>.yaml \
  --wait \
  --timeout 15m

Use a release name such as bighammer and namespace such as bh-control-plane.

Install configuration (`install-config-azure.env`)

Copy install-config-azure.example.env to install-config-azure.env. Required variables:

Variable	Description
`DB_USER`	PostgreSQL admin user
`DB_HOST`	`<server>.postgres.database.azure.com`
`DB_PORT`	`5432` (default)
`DB_PASSWORD`	PostgreSQL admin password
`KEY_VAULT_NAME`	Azure Key Vault name
`KEY_VAULT_RESOURCE_GROUP`	Resource group containing the vault
`HELM_NAMESPACE`	Target namespace (e.g. `bh-control-plane`)
`HELM_RELEASE`	Helm release name (e.g. `bighammer`)
`VALUES_FILE`	Optional path to custom values overlay
`ACR_REGISTRY`	ACR login server for image validation

Skip flags (set to true to skip a step):

Flag	Skips
`SKIP_DATABASES`	Database creation
`SKIP_KEYVAULT`	Key Vault secret sync
`SKIP_ESO_CHECK`	External Secrets Operator verification
`SKIP_HELM`	Helm deployment (print command only)
`SKIP_PREREQUISITES`	ESO / reloader / RabbitMQ install

Post-deploy verification

# Pods in platform namespace
kubectl get pods -n <your-namespace>

# ExternalSecrets synced from Key Vault
kubectl get externalsecret -n <your-namespace>

# SecretStore ready
kubectl describe secretstore <secret-store-name> -n <your-namespace>

# Ingress and hosts
kubectl get ingress -n <your-namespace>

Confirm:

All platform pods are Running
ExternalSecrets show SecretSynced / Ready
HTTPS endpoints resolve for each configured ingress host
Celery workers connect to RabbitMQ (check worker logs)

Ingress hosts

Configure hostnames under global.ingress in your values file:

Service	Values key	Example pattern
Main UI	`uiHostName`	`ui.<env>.<domain>`
Admin UI	`adminuiHostName`	`adminui.<env>.<domain>`
Catalog API	`catalogHostName`	`catalog.<env>.<domain>`
Audit API	`auditHostName`	`audit.<env>.<domain>`
AI Agent	`aiAgentHostName`	`aiagent.<env>.<domain>`
Keycloak	`kcHostName`	`kc.<env>.<domain>`
Keycloak API	`kcapiHostName`	`kcapi.<env>.<domain>`
Transformation utils	`transformationUtilsHostName`	`transformation-utils.<env>.<domain>`
RabbitMQ management	`rabbitmqHostName`	`rabbitmq.<env>.<domain>`

Ensure DNS (public or private) points to your ingress load balancer IP.

Enabling or disabling components

Toggle sub-charts in values:

global:
  bhaiagent:
    enabled: true
  bhaiagentworker:
    enabled: true
  bhcelerybeat:
    enabled: true
  # Disable a component entirely:
  bhtransformationutils:
    enabled: false

Disabled sub-charts do not create Deployments or ExternalSecrets.

Upgrades and rollbacks

helm history <release-name> -n <your-namespace>
helm upgrade <release-name> . -f values-<env>.yaml -n <your-namespace>
helm rollback <release-name> <revision> -n <your-namespace>

After image tag changes, verify ACR contains the new tags before upgrading.

Topic	Link
Key Vault names and scripts	Key Vault Secrets · Scripts Reference
Pre-install checklist	Deployment Checklist
Schema / grant errors	Database Bootstrap Troubleshooting
Architecture	Cloud Architecture

Before you start​

End-to-end journey​

Mirror chart and prepare values​

What the chart deploys​

Prerequisites​

Values files​

Database and Key Vault mapping​

Key global settings​

Per-service configuration​

Deployment options​

Option 1: Automated install (recommended)​

Option 2: Manual Helm deployment​

Install configuration (install-config-azure.env)​

Post-deploy verification​

Ingress hosts​

Enabling or disabling components​

Upgrades and rollbacks​

Related​