Skip to main content

SSL/TLS encryption

BigHammer uses SSL/TLS (HTTPS) at the cluster edge to encrypt traffic between clients and the platform. TLS terminates on nginx Ingress — not on the Azure load balancer (L4 passthrough).

This page covers edge HTTPS certificates. PostgreSQL client SSL is separate — see postgresSSLMode in Platform Deployment and Key Vault Secrets.

Certificate lifecycle (Option A — Let's Encrypt)​

  1. cert-manager proves domain control via DNS-01 (TXT records in Azure DNS).
  2. Let's Encrypt issues a certificate; cert-manager stores it in Kubernetes secret <env>-az-bighammer-tls (name configurable).
  3. PushSecret (External Secrets Operator) copies tls.crt / tls.key to Key Vault.
  4. nginx Ingress mounts the Kubernetes TLS secret for HTTPS.
  5. Application pods (for example Keycloak) read PEM material from Key Vault via global.remoteSecrets.tls and ExternalSecrets.

Where certificates are stored​

StoreNameKeys / formatWritten byRead by
Kubernetes Secret<env>-az-bighammer-tls in bh-control-planetls.crt, tls.key (kubernetes.io/tls)cert-manager (Certificate) or kubectl create secret tlsnginx Ingress
Key Vault<env>-az-bighammer-tls-crtPEM certificatePushSecret (Option A) or az keyvault secret set (Option B)bighammer ExternalSecrets → Keycloak and other consumers
Key Vault<env>-az-bighammer-tls-keyPEM private keyPushSecret (Option A) or az keyvault secret set (Option B)Same

Default Key Vault secret names are configured in bighammer values:

global:
  remoteSecrets:
    tls:
      cert: <env>-az-bighammer-tls-crt
      key: <env>-az-bighammer-tls-key

See Key Vault Secrets.

How the bighammer chart references TLS​

ConsumerMechanismValues / template
nginx Ingressspec.tls.secretName on bh-ingressglobal.ingress.tlsSecretName
KeycloakExternalSecret pulls Key Vault PEM into pod secretglobal.remoteSecrets.tls.cert / .key
global:
  ingress:
    enabled: true
    tlsSecretName: <env>-az-bighammer-tls

All hostnames listed under global.ingress.*HostName use this TLS secret on the single bh-ingress resource.

Keycloak does not read the Ingress TLS secret directly. It syncs certificate and key from Key Vault:

# ExternalSecret data keys (from chart template)
KC_HTTPS_CERTIFICATE_FILE  → Key Vault: global.remoteSecrets.tls.cert
KC_HTTPS_CERTIFICATE_KEY_FILE → Key Vault: global.remoteSecrets.tls.key

Option A requires both the Kubernetes TLS secret (edge) and Key Vault copies (apps).

Option A — Let's Encrypt (cert-manager + DNS-01)​

Best for: Dev / non-prod with a public Azure DNS zone.

Sample manifests in the Helm chart​

The bighammer chart ships reference manifests under cert-manager/ (applied with kubectl, not via helm install):

FileKubernetes resource
cert-manager/cluster-issuer.yamlIssuer — Let's Encrypt + Azure DNS
cert-manager/wildcard-cert.yamlCertificate — wildcard request
cert-manager/push-secret.yamlPushSecret — sync to Key Vault
tar -xzf bighammer-<version>.tgz
ls bighammer/cert-manager/

Prerequisites​

#RequirementDoc
1cert-manager cert-manager-v1.19.2 in clusterPrerequisites — add-ons
2External Secrets OperatorExternal Secrets Operator
3Workload Identity — ESO + cert-manager DNS accessWorkload Identity
4Azure DNS public zone for your domainInfrastructure
5cert-manager controller identity with DNS Zone Contributor on the zoneDNS-01 challenge
6SecretStore/azure-secret-store in bh-control-planeCreated by bighammer chart or platform bootstrap
7PushSecret-capable ESO versionReference: ESO 0.18.x (PushSecret is v1alpha1)

Provision — apply order​

kubectl apply -f cluster-issuer.yaml
kubectl apply -f wildcard-cert.yaml
# Wait until Certificate is Ready and secret <env>-az-bighammer-tls exists
kubectl apply -f push-secret.yaml

Customize cluster-issuer.yaml for your Azure subscription, resource group, and DNS zone before apply.

Wire up bighammer values​

global:
  remoteSecrets:
    tls:
      cert: <env>-az-bighammer-tls-crt
      key: <env>-az-bighammer-tls-key
  ingress:
    enabled: true
    tlsSecretName: <env>-az-bighammer-tls

Renewal​

Automatic — cert-manager renews ~30 days before expiry and updates the Kubernetes TLS secret. PushSecret propagates new PEM to Key Vault on its refreshInterval. No Helm value changes needed if secret names stay the same.

Option B — Private SSL/TLS certificate​

Best for: Production, corporate CA, or environments without public DNS-01.

  1. Obtain wildcard or SAN certificate from your CA (PEM cert + key).
  2. Store in Key Vault (names must match global.remoteSecrets.tls):
az keyvault secret set --vault-name <VAULT> \
  --name <env>-az-bighammer-tls-crt --file wildcard.crt

az keyvault secret set --vault-name <VAULT> \
  --name <env>-az-bighammer-tls-key --file wildcard.key
  1. Create the Kubernetes TLS secret in bh-control-plane:
kubectl create secret tls <env>-az-bighammer-tls \
  --cert=wildcard.crt \
  --key=wildcard.key \
  -n bh-control-plane
  1. Set global.ingress.tlsSecretName: <env>-az-bighammer-tls and re-run helm upgrade.

Option B skips cert-manager manifests; you maintain renewal and Key Vault uploads manually.

Comparison​

Option A (Let's Encrypt)Option B (Private cert)
CostFreeCA-dependent
AutomationFull (cert-manager + PushSecret)Manual renewal
DNSPublic Azure DNS + DNS-01Any DNS
K8s secretcert-manager creates <env>-az-bighammer-tlsYou create with kubectl
Key VaultPushSecret populates crt/key secretsYou upload with az keyvault secret set
Manifests3 files in chart cert-manager/None
Prod fitDev / stagingRecommended for prod

Verify TLS​

kubectl get secret <env>-az-bighammer-tls -n bh-control-plane
kubectl get issuer,certificate,pushsecret -n bh-control-plane
kubectl get ingress -n bh-control-plane -o yaml | grep -A2 tls
curl -vI https://<your-hostname>

DNS records​

TLS certificates prove hostname identity; clients still need DNS A records pointing to your load balancer:

kubectl get svc -n ingress-nginx

Hostnames must match certificate SANs (dnsNames in wildcard-cert.yaml or your private cert).

ClusterSecretStore (multi-namespace TLS)​

If multiple namespaces (for example Airflow) need the same wildcard certificate, use a ClusterSecretStore to sync once from Key Vault. See the legacy page ClusterSecretStore for TLS for YAML examples.

TopicLink
NGINX installNGINX Ingress Deployment
Key Vault mappingKey Vault Secrets
Platform deployPlatform Deployment