Deploy on Azure AKS

Step 1: Pick the hostname

Choose the hostname on a domain you control, for example finance-agents.company.com. Whether it resolves publicly or only inside your network is your choice. TLS, the OIDC redirect URI, and the Gateway configuration all derive from it. You point DNS at the Gateway in Step 8.

Import or issue a TLS certificate for the hostname into Azure Key Vault, and note its identifier, https://<vault>.vault.azure.net/certificates/<name>.

Or use a hostname that Azure generates

You can use an Azure-generated hostname instead of one on your own domain. Azure Front Door (opens in a new tab) (Standard or Premium) gives each endpoint a hostname of the form <endpoint>-<hash>.z01.azurefd.net, and serves it over HTTPS with a certificate that Microsoft issues and rotates. You need no domain, no DNS record, and no certificate of your own, which suits a proof of concept. The reference Terraform takes this approach, and its README describes what it trades away.

Azure generates the hostname when you create the endpoint, so create the Front Door endpoint first and use its hostname wherever this guide asks for yours. By default, an endpoint that you delete and recreate with the same name in the same Entra ID tenant gets the same hostname back. Moving to a hostname of your own later is a hostname change like any other; see the warning in Part 1.

With a Front Door hostname, TLS terminates at Front Door instead of at the Gateway, and some later steps change:

• Step 1: skip the certificate.
• Step 3: give the Gateway an HTTP listener on port 80 with no certificate and no hostname, and make it the origin of the Front Door endpoint. Front Door reaches it over plain HTTP, because Front Door accepts an HTTPS origin only with a publicly trusted certificate for the origin's hostname. Use a network security group to admit only the AzureFrontDoor.Backend service tag to the Gateway's load balancer. The Gateway certificate identity is not needed.
• Step 6: set sectionName in the values file to the name of the HTTP listener.
• Step 8: skip it; the hostname already resolves to Front Door.

Front Door's own limits then apply to every request: it waits at most 240 seconds for a response from the origin, and it closes idle and long-lived WebSocket connections on its own schedule (opens in a new tab).

Step 2: Register the OIDC application

Register an OIDC application in your identity provider and capture the Discovery URL, Client ID, and Client Secret.

Configure it with:

• Callback URL: https://<hostname>/api/v1/auth/callback
• Logout URL: https://<hostname>
• Application login URI: https://<hostname>/login
• Allowed web origin: https://<hostname>
• Scopes: openid, profile, email

Follow the guide for your provider: Microsoft Entra ID · Auth0 · Okta.

Step 3: Provision Azure infrastructure

Provision the infrastructure using the bill of materials as the spec. The end state must include:

• An AKS cluster, version 1.36 or newer, with the OIDC issuer, workload identity, the managed Gateway API, and the application routing add-on's Gateway API implementation enabled, and kubectl access configured against it.
• The application node, a Standard_D32s_v5 with a 200 GiB OS disk, as the only node in a node pool of one.
• PostgreSQL Flexible Server, version 17 or 18, in private access mode in the cluster's virtual network, with PGCRYPTO and CITEXT in its azure.extensions parameter.
• A storage account and a blob container, reachable from the node subnet.
• A Key Vault with an RSA key that permits encrypt, decrypt, wrap key, and unwrap key, and the TLS certificate from Step 1.
• The application namespace, a Kubernetes service account in it, and a user-assigned managed identity that holds Storage Blob Data Contributor on the container and Key Vault Crypto User on the key, federated with that account. You name the account in the values file in Step 6.
• The Gateway, in a namespace of its own, serving your hostname over HTTPS with the certificate from Step 1. You name it in the values file in Step 6.

Node and storage checks

Node bootstrap needs nothing platform-specific: no custom data, no script, no packages, and no data volume. The node runs the stock AKS node image, and nested virtualization comes from the VM size. Bootstrap does not install the sandbox runtime; that is Step 4, and it prepares nodes that join later on its own.

There is no StorageClass to create: the chart creates the data root's class itself, as described in the bill of materials.

Confirm the node and the storage prerequisites:

• The node is Ready.
• /dev/kvm is present on the node.
• kubectl get csidriver disk.csi.azure.com returns the driver.

Application identity

The federation is the part to get exactly right. The service account carries the identity's client ID. The identity trusts the cluster's OIDC issuer for exactly that namespace and account:

kubectl create namespace <namespace>
kubectl -n <namespace> create serviceaccount <service-account>
kubectl -n <namespace> annotate serviceaccount <service-account> \
  azure.workload.identity/client-id=<identity-client-id>
 
az identity federated-credential create \
  --resource-group <resource-group> \
  --identity-name <identity-name> \
  --name <namespace>-<service-account> \
  --issuer "$(az aks show --resource-group <resource-group> --name <cluster> \
      --query oidcIssuerProfile.issuerUrl --output tsv)" \
  --subject system:serviceaccount:<namespace>:<service-account> \
  --audiences api://AzureADTokenExchange

Ingress and the Gateway

Turn on the ingress (Azure CLI 2.86.0 or newer). The first command installs the application routing add-on with its NGINX controller off and the Key Vault secrets provider on; on a cluster that already has the add-on, run az aks approuting update with the same flags. The second installs the managed Gateway API definitions and the add-on's implementation of them. The third lets the secrets provider pick up a renewed certificate:

az aks approuting enable --resource-group <resource-group> --name <cluster> \
  --nginx None --enable-kv
az aks update --resource-group <resource-group> --name <cluster> \
  --enable-gateway-api --enable-app-routing-istio
az aks addon update --resource-group <resource-group> --name <cluster> \
  --addon azure-keyvault-secrets-provider --enable-secret-rotation

kubectl get gatewayclass approuting-istio should show the class as accepted.

The add-on reads the TLS certificate from Key Vault as an identity you give it, federated with a service account in the Gateway's namespace. Create the namespace and the account, grant the Gateway certificate identity from Part 1 Key Vault Secrets User on the vault, and federate it with the account:

kubectl create namespace <gateway-namespace>
kubectl -n <gateway-namespace> create serviceaccount <gateway-service-account>
kubectl -n <gateway-namespace> annotate serviceaccount <gateway-service-account> \
  azure.workload.identity/client-id=<gateway-identity-client-id>
kubectl -n <gateway-namespace> label serviceaccount <gateway-service-account> \
  azure.workload.identity/use=true
 
az role assignment create \
  --assignee-object-id <gateway-identity-principal-id> \
  --assignee-principal-type ServicePrincipal \
  --role "Key Vault Secrets User" \
  --scope <key-vault-resource-id>
 
az identity federated-credential create \
  --resource-group <resource-group> \
  --identity-name <gateway-identity-name> \
  --name <gateway-namespace>-<gateway-service-account> \
  --issuer "$(az aks show --resource-group <resource-group> --name <cluster> \
      --query oidcIssuerProfile.issuerUrl --output tsv)" \
  --subject system:serviceaccount:<gateway-namespace>:<gateway-service-account> \
  --audiences api://AzureADTokenExchange

Then create the Gateway with kubectl apply -f. It has one HTTPS listener for your hostname, named https, and admits routes from the application namespace only:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: <gateway>
  namespace: <gateway-namespace>
spec:
  gatewayClassName: approuting-istio
  listeners:
    - name: https
      hostname: <hostname>
      port: 443
      protocol: HTTPS
      tls:
        mode: Terminate
        options:
          # The certificate from Step 1. Leave the version off so a renewed
          # certificate is picked up.
          kubernetes.azure.com/tls-cert-keyvault-uri: https://<vault>.vault.azure.net/certificates/<name>
          kubernetes.azure.com/tls-cert-service-account: <gateway-service-account>
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              kubernetes.io/metadata.name: <namespace>

The Gateway's own namespace keeps its load balancer, and so the address your DNS record points at, in place when you reinstall the application. The load balancer is public by default. To keep it private, add the internal load balancer annotation to the Gateway's spec:

spec:
  infrastructure:
    annotations:
      service.beta.kubernetes.io/azure-load-balancer-internal: "true"

Wait for the add-on to provision the Gateway, then confirm it synced the certificate into a Secret named kv-gw-cert-<gateway>-https:

kubectl -n <gateway-namespace> wait --for=condition=programmed gateway/<gateway> --timeout=300s
kubectl -n <gateway-namespace> get secret

For more on this setup, including publishing the DNS record from Azure DNS automatically, see Configure Azure DNS and TLS with the application routing Gateway API implementation (opens in a new tab).

Step 4: Install the sandbox runtime

Install Kata Containers into the cluster, once, following Install the sandbox runtime. Verify it before continuing:

kubectl get runtimeclass kata-clh
kubectl get nodes -l katacontainers.io/kata-runtime=true

Step 5: Create the database and its roles

The application does not create its own database, and it connects with three least-privilege roles rather than the server administrator. The server has no public endpoint, so connect from inside the virtual network. A throwaway Pod in the cluster works, and prompts for the administrator password:

kubectl run psql --rm -it --restart=Never --image=postgres:18-alpine -- \
  psql -h <server>.postgres.database.azure.com -U <admin-user> -d postgres

Run the following, with your own names and strong passwords:

CREATE ROLE <migrator_role> LOGIN PASSWORD '<migrator_password>'
  NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS;
CREATE ROLE <definer_role> NOLOGIN
  NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION BYPASSRLS;
CREATE ROLE <app_role> LOGIN PASSWORD '<app_password>'
  NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS;
GRANT <definer_role> TO <migrator_role>;
CREATE DATABASE <database>;
GRANT <migrator_role> TO CURRENT_USER;
ALTER DATABASE <database> OWNER TO <migrator_role>;
GRANT CONNECT ON DATABASE <database> TO <app_role>, <definer_role>;
REVOKE <migrator_role> FROM CURRENT_USER;

The migrator role applies the schema on install and upgrade, the app role is what the application connects as at runtime, and the definer role owns privileged functions and cannot log in; see The database roles for the full rationale. The migrator enables the pgcrypto and citext extensions itself, which is why both must be on the server's allow-list. The Flexible Server administrator is not a PostgreSQL superuser, but on PostgreSQL 16 and newer it can create the definer role with BYPASSRLS.

Capture the database name, the three role names, and the two passwords: they go into the values file.

Step 6: Prepare your values file

Start from the template below and replace every REPLACE_ME. Only what the chart cannot know about your environment is in it; everything else is a chart default, tuned for the supported node. Keep the file: you reuse it for every upgrade. The template is for application version 3.1.4 or later; do not pass an older version to helm install in Step 7.

# Helm values for a self-hosted deployment on Azure AKS.
# Requires application version 3.1.4 or later.
#
# Complete every REPLACE_ME before you install; a value you cannot fill in is
# a prerequisite that is not ready yet. Keep this file: you reuse it for
# upgrades. Everything not set here is a chart default, tuned for the
# supported 32 vCPU / 128 GiB node.
 
# Your hostname from Step 1 as https://<hostname>: scheme, host, and an
# optional port, with no path. The chart derives every URL the platform
# needs about itself from it: the sign-in callback, the allowed browser
# origin, and the webhook callback URLs. The URLs you registered in your
# identity provider in Step 2 are built from the same hostname, and
# httpRoute.hostnames below repeats it. Each derived URL has an explicit
# override; see Advanced configuration.
applicationUrl: https://REPLACE_ME
 
# The Kubernetes service account that gives the application access to Azure
# resources. Create it in the application namespace, annotate it with the
# client ID of the user-assigned managed identity
# (azure.workload.identity/client-id), and federate the identity with it.
serviceAccount:
  create: false
  name: REPLACE_ME
 
# The application database and its three roles, created before the install
# (see "Create the database and its roles" in the AKS guide).
postgres:
  host: REPLACE_ME
  database: REPLACE_ME
  appRole: REPLACE_ME
  appPassword: REPLACE_ME
  definerRole: REPLACE_ME
  migratorRole: REPLACE_ME
  migratorPassword: REPLACE_ME
 
# The Azure resources from the bill of materials, in one block. From these the
# chart derives everything Azure-shaped:
#   - object storage at abfss://<container>@<account>.dfs.core.windows.net,
#     plus the optional prefix, reached as the managed identity federated with
#     the service account above (no account keys);
#   - a Premium SSD StorageClass on the Azure Disk CSI driver, encrypted at
#     rest with platform-managed keys, and the data root claimed from it as a
#     raw block volume on the node (100 GiB by default; raise
#     vfs.dataRoot.size later and upgrade, the filesystem grows without a
#     restart);
#   - the sandbox wiring for AKS: the Kata runtime you installed before the
#     platform, reached through the node's containerd, with the release
#     installing no Kata of its own;
#   - no Ingress: the application is served through the HTTPRoute below.
# Anything set explicitly elsewhere in this file wins over a derived value.
infrastructure:
  platform: azure
  azure:
    # The storage account name only: 3 to 24 lowercase letters and digits.
    storageAccountName: REPLACE_ME
    # The container name only. The optional key prefix keeps several
    # deployments apart in one container.
    blobContainerName: REPLACE_ME
    # blobKeyPrefix: ""
    # Identifier of the RSA key in Key Vault reserved for envelope encryption
    # of secrets at rest, as https://<vault>.vault.azure.net/keys/<name>. The
    # chart requires it. Leave the version off to follow the key's rotation.
    # The key must permit encrypt, decrypt, wrap key, and unwrap key, and the
    # managed identity needs Key Vault Crypto User on it.
    keyVaultKeyUrl: REPLACE_ME
 
api:
  config:
    # Encryption keys, yours to generate and to keep. Generate a long random
    # string for each, for example with `openssl rand -hex 32`.
    # secretsKeys encrypts the credentials the platform stores in its
    # database: model platform keys, integration and OAuth tokens. The
    # database outlives the cluster, and without the exact key its encrypted
    # contents cannot be decrypted; the database may become unusable.
    # projectPortabilityKeys protects exported project archives the same
    # way. Keep this file backed up somewhere safe outside the cluster.
    secretsKeys: '{"v1":"REPLACE_ME"}'
    projectPortabilityKeys: '{"active":"REPLACE_ME"}'
 
    # The OIDC application you registered against your hostname in Step 2.
    auth:
      oidc:
        server: REPLACE_ME # your provider's discovery URL; the bare issuer URL also works
        clientId: REPLACE_ME
        clientSecret: REPLACE_ME
 
# Routing through the Gateway you created in Step 3, on the AKS application
# routing add-on's Gateway API implementation. The chart renders an HTTPRoute
# for the application's paths and attaches it to the Gateway's HTTPS
# listener, where TLS terminates with your certificate from Key Vault.
httpRoute:
  enabled: true
  parentRefs:
    - name: REPLACE_ME # the Gateway's name
      namespace: REPLACE_ME # the Gateway's namespace
      sectionName: https # the listener's name
  hostnames:
    # Your hostname from Step 1, as on the Gateway's listener.
    - REPLACE_ME

Three things are worth a moment. The data root size is not in the file because 100 GiB is the chart default; you can raise it later (vfs.dataRoot.size) without a restart, and on Azure a larger disk is also a faster one (see Data root performance). Every value the infrastructure block or applicationUrl derives has an explicit override that wins over the convention (a StorageClass of your own, vfs.blobs.uri set directly, or one of the derived URLs set on its own key), but the file above is the supported shape; see Advanced configuration. The data root mounts at /var/lib/blockparty/<release>, named after the Helm release you install under; nothing in the file needs to say so. And no internal service tokens are in the file: the chart generates them at first install, reuses them across upgrades, and they die with the deployment. The two encryption keys are in the file, deliberately: they protect what the platform stores in your database, so their custody stays with you and this file, not with the cluster.

Step 7: Install the application

Install into the namespace that holds the service account from Step 3, not into a new one.

Expect the VFS and sandbox Pods to sit in ContainerCreating for a few minutes on a first install: they bind the data root, and they start once the data-root workload has claimed, formatted, and mounted it.

Step 8: Point DNS at the Gateway

Read the load balancer address from the Gateway:

kubectl -n <gateway-namespace> get gateway <gateway> \
  -o jsonpath='{.status.addresses[0].value}{"\n"}'

Create the DNS record resolving your hostname to that address. Sign-in does not complete until the hostname resolves and TLS is serving.

Step 9: Validate

• Check the data root: the claim is Bound and the data-root log ends with data root ready. See Verify the data root.
• Check the workload identity: kubectl -n <namespace> describe pod -l app.kubernetes.io/component=vfs | grep AZURE_ lists AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_FEDERATED_TOKEN_FILE. If they are missing, the service account annotation or the federated credential is not in place, and blob storage fails on first use rather than at startup.
• Check the route: kubectl -n <namespace> get httproute -o jsonpath='{range .items[*].status.parents[*].conditions[*]}{.type}={.status} {end}{"\n"}' shows Accepted=True and ResolvedRefs=True. If Accepted is False, the Gateway does not admit routes from the application namespace, or the hostname does not match its listener.
• Browse to https://<hostname>. Sign-in should redirect to your identity provider.
• Sign in with a permitted user and confirm you land in the workspace.

Step 10: Back up the encryption keys

The two encryption keys you generated into the values file encrypt the secrets the platform stores in its database (model platform credentials, integration and OAuth tokens), and the database outlives the cluster.

Store the two key values in your secrets manager, alongside your other infrastructure credentials, so they survive the loss of the machine that holds the values file. Treat them as root credentials.