Azure Deployment (AKS)

This guide provides step-by-step instructions for deploying Immuta 2026.1.x to Azure Kubernetes Service (AKS) with Azure Flexible Server for PostgreSQL and Azure Elastic for audit storage.

For the official Immuta self-managed deployment documentation, see Install Immuta.

Prerequisites

• Azure CLI (az) installed and authenticated with a subscription that has permissions to create resource groups, AKS clusters, ACR registries, PostgreSQL Flexible Servers, and Elastic monitors

• kubectl installed

• Helm 3.2.0+ installed

• skopeo installed (installation guide) -- used to copy container images between registries

• Immuta OCI registry credentials

• A valid TLS certificate and private key for your Immuta hostname

Required Variables

Set these environment variables before starting. All subsequent commands reference them.

# Deployment naming -- used as a prefix for all Azure resources
export RELEASE_NAME=<your-release-name>        # e.g., immuta-prod (lowercase, alphanumeric + hyphens)
export ACR_NAME=<your-acr-name>                # e.g., immutaprod (alphanumeric only, globally unique)
export LOCATION=eastus                         # Azure region

# Immuta version
export IMMUTA_VERSION=2026.1.0

# Immuta registry credentials
export IMMUTA_USER=<your-immuta-registry-username>
export IMMUTA_TOKEN=<your-immuta-registry-token>

# PostgreSQL credentials
export PG_ADMIN_PASSWORD=<your-postgres-admin-password>
export IMMUTA_DB_PASSWORD=<your-immuta-db-password>

# TLS / Ingress
export IMMUTA_URL=<your-hostname>              # e.g., immuta.example.com
export TLS_CERT=<path-to-tls-cert>             # e.g., ./immuta.crt
export TLS_KEY=<path-to-tls-key>               # e.g., ./immuta.key

# Namespace
export NAMESPACE=immuta

Avoid whitespace, $, &, :, \, /, and ' in passwords. These characters can cause authentication failures or Helm value parsing issues.

Step 1: Create Resource Group and Container Registry

Create an Azure resource group to hold all deployment resources, and an Azure Container Registry (ACR) to host the Immuta container images.

az group create --name ${RELEASE_NAME} --location ${LOCATION}

az acr create --resource-group ${RELEASE_NAME} \
              --name ${ACR_NAME} \
              --sku Basic

Verify:

az acr show --name ${ACR_NAME} --query "{name:name, loginServer:loginServer, status:provisioningState}" -o table

Step 2: Copy Immuta Images to ACR

Authenticate to ACR

Create a scoped ACR token and log in with skopeo:

az acr token create --name ${RELEASE_NAME}-token \
                    --registry ${ACR_NAME} \
                    --repository '*' content/write content/read

TOKEN_PASSWORD=$(az acr token credential generate \
                    -n ${RELEASE_NAME}-token \
                    -r ${ACR_NAME} \
                    --password1 \
                    --expiration-in-days 120 | jq -r '.passwords[0].value')

echo ${TOKEN_PASSWORD} | skopeo login --username ${RELEASE_NAME}-token --password-stdin ${ACR_NAME}.azurecr.io

Authenticate to Immuta Registry

echo ${IMMUTA_TOKEN} | skopeo login --username ${IMMUTA_USER} --password-stdin ocir.immuta.com

Copy images

for image in audit-service cache classify-service detect-temporal-worker immuta-db immuta-service temporal-admin-tools temporal-proxy temporal-server; do
  echo "Copying ${image}:${IMMUTA_VERSION}..."
  skopeo copy docker://ocir.immuta.com/stable/${image}:${IMMUTA_VERSION} \
              docker://${ACR_NAME}.azurecr.io/stable/${image}:${IMMUTA_VERSION}
done

Verify:

az acr repository list --name ${ACR_NAME} -o table

Step 3: Deploy AKS Cluster

Create an AKS cluster with the Azure CNI network plugin, OIDC issuer, workload identity, and the app routing ingress controller. The cluster is attached to the ACR for image pulls.

Adjust --node-vm-size and --node-count based on your workload. The minimum recommendation for Immuta is 3 nodes of Standard_D4s_v5 (4 vCPU, 16 GiB RAM each).

To see available Kubernetes versions in your region, run az aks get-versions --location ${LOCATION} -o table.

az aks create --location ${LOCATION} \
              --name ${RELEASE_NAME}-cluster \
              --resource-group ${RELEASE_NAME} \
              --kubernetes-version 1.33 \
              --network-plugin azure \
              --node-vm-size Standard_D4s_v5 \
              --node-count 3 \
              --enable-oidc-issuer \
              --enable-app-routing \
              --enable-workload-identity \
              --attach-acr ${ACR_NAME}

Connect kubectl to the cluster

az aks get-credentials --resource-group ${RELEASE_NAME} \
                       --name ${RELEASE_NAME}-cluster

Verify:

kubectl get nodes

You should see your nodes in Ready status.

Step 4: Deploy Azure Flexible Server for PostgreSQL

This section creates a PostgreSQL Flexible Server in its own VNet, peers it with the AKS VNet, and configures private DNS so the cluster can resolve the database endpoint.

Create a private DNS zone

This allows the AKS cluster to resolve the PostgreSQL hostname privately.

az network private-dns zone create --resource-group ${RELEASE_NAME} \
                                   --name ${RELEASE_NAME}.postgres.database.azure.com

Link the DNS zone to the AKS VNet

AKS_VNET_ID=$(az network vnet list \
    --resource-group MC_${RELEASE_NAME}_${RELEASE_NAME}-cluster_${LOCATION} \
    --query "[0].id" -o tsv)

az network private-dns link vnet create --resource-group ${RELEASE_NAME} \
                                        --name postgres-dns-link \
                                        --zone-name ${RELEASE_NAME}.postgres.database.azure.com \
                                        --virtual-network ${AKS_VNET_ID} \
                                        --registration-enabled false

Create the PostgreSQL Flexible Server

DNS_ZONE_ID=$(az network private-dns zone show \
    --resource-group ${RELEASE_NAME} \
    --name ${RELEASE_NAME}.postgres.database.azure.com \
    --query "id" -o tsv)

az postgres flexible-server create --version 16 \
    --resource-group ${RELEASE_NAME} \
    --name ${RELEASE_NAME}-postgres \
    --admin-user pgadmin \
    --admin-password ${PG_ADMIN_PASSWORD} \
    --private-dns-zone ${DNS_ZONE_ID} \
    --vnet ${RELEASE_NAME}-postgres-vnet \
    --subnet ${RELEASE_NAME}-postgres-subnet \
    --address-prefixes 10.0.0.0/16 \
    --subnet-prefixes 10.0.0.0/24 \
    --sku-name Standard_D2s_v3 \
    --tier GeneralPurpose \
    --storage-size 128 \
    --yes

Enable required PostgreSQL extensions

az postgres flexible-server parameter set --resource-group ${RELEASE_NAME} \
                                          --server-name ${RELEASE_NAME}-postgres \
                                          --name azure.extensions \
                                          --value "pgcrypto,btree_gin"

Peer the PostgreSQL and AKS VNets

Bidirectional VNet peering allows the AKS pods to reach the PostgreSQL server over the private network.

# PostgreSQL VNet → AKS VNet
az network vnet peering create --resource-group ${RELEASE_NAME} \
                               --name ${RELEASE_NAME}-postgres-to-cluster \
                               --vnet-name ${RELEASE_NAME}-postgres-vnet \
                               --remote-vnet ${AKS_VNET_ID} \
                               --allow-vnet-access

# AKS VNet → PostgreSQL VNet
POSTGRES_VNET_ID=$(az network vnet show \
    --name ${RELEASE_NAME}-postgres-vnet \
    --resource-group ${RELEASE_NAME} \
    --query "id" -o tsv)

AKS_VNET_NAME=$(az network vnet show --ids ${AKS_VNET_ID} --query "name" -o tsv)

az network vnet peering create \
    --resource-group MC_${RELEASE_NAME}_${RELEASE_NAME}-cluster_${LOCATION} \
    --name ${RELEASE_NAME}-cluster-to-postgres \
    --vnet-name ${AKS_VNET_NAME} \
    --remote-vnet ${POSTGRES_VNET_ID} \
    --allow-vnet-access

Verify peering status:

az network vnet peering list --resource-group ${RELEASE_NAME} \
                             --vnet-name ${RELEASE_NAME}-postgres-vnet \
                             --query "[].{Name:name, State:peeringState}" -o table

Both peerings should show Connected.

Step 5: Configure PostgreSQL Databases

Immuta requires three databases: immuta, temporal, and temporal_visibility. Since the PostgreSQL Flexible Server is only reachable from within its peered VNet, use an ephemeral pod in the AKS cluster to run the database setup.

Create the namespace

kubectl create namespace ${NAMESPACE}

Connect to PostgreSQL via an ephemeral pod

Launch a temporary PostgreSQL client pod inside the AKS cluster. The pod is automatically deleted when you exit.

PG_HOST=$(az postgres flexible-server show --resource-group ${RELEASE_NAME} \
    --name ${RELEASE_NAME}-postgres --query "fullyQualifiedDomainName" -o tsv)

kubectl run pg-setup --rm -it --image=postgres:16 -n ${NAMESPACE} \
    --env="PGSSLMODE=require" -- \
    psql -h ${PG_HOST} -U pgadmin -d postgres

The FQDN is queried from Azure because the actual hostname (<server-name>.postgres.database.azure.com) differs from the private DNS zone name. If the connection fails, verify VNet peering shows Connected (Step 4) and the private DNS zone is linked to the AKS VNet.

Create the Immuta role and databases

Run the following SQL statements:

-- Create the immuta role
CREATE ROLE immuta WITH LOGIN ENCRYPTED PASSWORD '<your-immuta-db-password>';
GRANT azure_pg_admin TO immuta;
GRANT immuta TO current_user;
ALTER ROLE immuta SET search_path TO bometadata, audit, public;

-- Create databases
CREATE DATABASE immuta OWNER immuta;
CREATE DATABASE temporal OWNER immuta;
CREATE DATABASE temporal_visibility OWNER immuta;

-- Grant permissions
GRANT ALL ON DATABASE immuta TO immuta;
GRANT ALL ON DATABASE temporal TO immuta;
GRANT ALL ON DATABASE temporal_visibility TO immuta;

Configure the immuta database

\c immuta
CREATE EXTENSION pgcrypto;

Configure the temporal database

\c temporal
GRANT CREATE ON SCHEMA public TO immuta;

Configure the temporal_visibility database

\c temporal_visibility
GRANT CREATE ON SCHEMA public TO immuta;
CREATE EXTENSION btree_gin;

Verify databases

\l

You should see immuta, temporal, and temporal_visibility with owner immuta.

Type \q to exit psql. The ephemeral pod is automatically deleted.

Step 6: Deploy Elasticsearch for Audit

Immuta requires Elasticsearch for the audit service. There are two options:

Option A: Azure Elastic Monitor (managed)

export EMAIL=<your-email>
az elastic monitor create --location ${LOCATION} \
                          --name ${RELEASE_NAME}-elastic \
                          --resource-group ${RELEASE_NAME} \
                          --user-info "{emailAddress:${EMAIL}}" \
                          --sku "{name:ess-consumption-2024_Monthly}"

After the Elastic deployment completes:

1. Navigate to the Azure Portal > your Elastic resource > Elasticsearch endpoint to find the endpoint URL

2. Create a user for the audit service in Kibana:

   • Open Kibana from the Elastic resource overview

   • Navigate to Stack Management > Security > Users

   • Create a user (e.g., immuta-audit-service) with the superuser role (or a custom role with index create/write/read permissions)

3. Note the endpoint URL and credentials for the Helm values in Step 8

The Elasticsearch endpoint URL typically looks like https://<deployment-name>.es.<region>.azure.elastic-cloud.com/. You can find it in the Azure Portal under your Elastic Monitor resource.

Option B: In-cluster Elasticsearch using ECK

For deployments that prefer in-cluster Elasticsearch, follow the In-cluster Elasticsearch using ECK guide. Use the resulting in-cluster service endpoint (e.g., http://immuta-elasticsearch-es-http.immuta.svc.cluster.local:9200) in your Helm values.

Step 7: Create Kubernetes Secrets

TLS secret for ingress

The namespace was already created in Step 5. Create the TLS secret for the ingress controller:

kubectl -n ${NAMESPACE} create secret tls ${IMMUTA_URL}-tls \
    --key=${TLS_KEY} \
    --cert=${TLS_CERT}

Verify:

kubectl -n ${NAMESPACE} get secrets

Azure PostgreSQL Flexible Server uses DigiCert Global Root G2 certificates, which are included in standard system trust stores. Unlike AWS RDS (which requires an explicit CA bundle), no additional CA certificate secret is needed for Temporal's TLS connection to Azure PostgreSQL.

If Temporal pods fail to connect with TLS certificate errors, you can add an explicit CA certificate as a fallback. See the Troubleshooting section for details.

Step 8: Install Immuta via Helm

Authenticate Helm to the Immuta registry

echo ${IMMUTA_TOKEN} | helm registry login --password-stdin --username ${IMMUTA_USER} ocir.immuta.com

Deploy Immuta

helm upgrade --install -n ${NAMESPACE} immuta \
    oci://ocir.immuta.com/stable/immuta-enterprise \
    --version ${IMMUTA_VERSION} \
    -f immuta-values.yaml \
    --timeout 10m \
    --wait

Replace all <placeholder> values in the example below with your actual configuration. The comments show which ${VARIABLE} from the Required Variables section each value corresponds to.

Example Helm Values (immuta-values.yaml)

global:
  imageRegistry: <your-acr-name>.azurecr.io       # ${ACR_NAME}.azurecr.io
  imageTag: "2026.1.0"                            # ${IMMUTA_VERSION}
  postgresql:
    host: <release-name>-postgres.postgres.database.azure.com  # ${PG_HOST} from Step 5
    port: 5432
    username: immuta
    password: <your-immuta-db-password>             # ${IMMUTA_DB_PASSWORD}
    ssl: true

audit:
  enabled: true
  postgresql:
    database: immuta
  config:
    elasticsearchEndpoint: <your-elasticsearch-endpoint>       # from Step 6 (Azure Elastic endpoint)
    elasticsearchUsername: <your-elasticsearch-username>
    elasticsearchPassword: <your-elasticsearch-password>

secure:
  extraConfig:
    publicImmutaUrl: https://<your-hostname>                   # https://${IMMUTA_URL}
  postgresql:
    database: immuta
  ingress:
    ingressClassName: webapprouting.kubernetes.azure.com
    hostname: <your-hostname>                                  # ${IMMUTA_URL}
    tls: true
    secretName: <your-hostname>-tls                            # ${IMMUTA_URL}-tls

temporal:
  enabled: true
  schema:
    createDatabase:
      enabled: false
  server:
    config:
      persistence:
        default:
          sql:
            database: temporal
            tls:
              enabled: true
        visibility:
          sql:
            database: temporal_visibility
            tls:
              enabled: true

Temporal pods may show initial restarts while waiting for database connectivity. This is expected behavior and the pods should stabilize within a few minutes.

Step 9: Verify Deployment and Configure DNS

Wait for pods to become ready

for deploy in $(kubectl get deploy -n ${NAMESPACE} -o jsonpath='{.items[*].metadata.name}' | tr ' ' '\n' | grep '^immuta-'); do
  echo "Waiting for ${deploy}..."
  kubectl rollout status deployment/${deploy} -n ${NAMESPACE} --timeout=300s || true
done

Check pod status

kubectl get pods -n ${NAMESPACE}

All pods should show Running status (Temporal pods may take a few minutes to stabilize).

Check ingress

kubectl get ingress -n ${NAMESPACE}

Configure DNS

Retrieve the ingress IP assigned by the app routing controller:

kubectl -n ${NAMESPACE} get ingress -o jsonpath='{.items[0].status.loadBalancer.ingress[0].ip}'

Create a DNS A record pointing ${IMMUTA_URL} to this IP address. If using Azure DNS zones, you can create a CNAME instead.

If you manage your DNS zone in Azure, you can use ExternalDNS to automate DNS record creation:

helm repo add external-dns https://kubernetes-sigs.github.io/external-dns
helm upgrade --install --namespace=external-dns --create-namespace \
    external-dns external-dns/external-dns \
    --set provider=azure

Access the Immuta UI

Navigate to https://${IMMUTA_URL} in your browser. You should see the Immuta login page.

Troubleshooting

Common Issues

Symptom	Likely Cause	Resolution
ImagePullBackOff	ACR authentication or image not found	Verify az acr repository list shows all images; check ACR is attached to AKS
Temporal pods in CrashLoopBackOff	Database unreachable or TLS cert issue	Check pod logs; if TLS errors, add explicit CA cert (see below)
Database connection errors	VNet peering not connected or wrong hostname	Check az network vnet peering list shows Connected; verify PostgreSQL hostname
Ingress has no IP	App routing addon not enabled or DNS not configured	Verify az aks show includes ingressProfile.webAppRouting.enabled: true
Audit service errors	Elasticsearch endpoint unreachable or wrong credentials	Test endpoint connectivity from a pod: kubectl exec -n ${NAMESPACE} <pod> -- curl -u user:pass <es-endpoint>

Temporal TLS fallback: adding an explicit CA certificate

If Temporal pods fail with TLS certificate verification errors, the container image may not include the DigiCert Global Root G2 certificate in its trust store. Add it explicitly:

curl -o DigiCertGlobalRootG2.crt.pem https://cacerts.digicert.com/DigiCertGlobalRootG2.crt.pem

kubectl -n ${NAMESPACE} create secret generic secret-with-certs \
    --from-file=global-bundle.pem=DigiCertGlobalRootG2.crt.pem

Then add the following to the temporal.server section in your Helm values and re-run helm upgrade:

temporal:
  server:
    extraVolumes:
      - name: secret-with-certs
        secret:
          secretName: secret-with-certs
    extraVolumeMounts:
      - name: secret-with-certs
        mountPath: /certs/
    config:
      persistence:
        default:
          sql:
            tls:
              enabled: true
              caFile: /certs/global-bundle.pem
        visibility:
          sql:
            tls:
              enabled: true
              caFile: /certs/global-bundle.pem

Useful commands

# View pod logs
kubectl logs -n ${NAMESPACE} <pod-name>

# Describe a failing pod
kubectl describe pod -n ${NAMESPACE} <pod-name>

# Check all services
kubectl get svc -n ${NAMESPACE}

# Test PostgreSQL connectivity from a pod
kubectl run pg-test --rm -it --image=postgres:16 -n ${NAMESPACE} \
    --env="PGSSLMODE=require" -- \
    psql -h <pg-host> -U immuta -d immuta -c "\l"

Cleanup

To remove all Azure resources created by this guide, delete the resource group. This removes the AKS cluster, ACR, PostgreSQL Flexible Server, Elastic Monitor, VNets, and all associated resources.

This is irreversible. All data in the PostgreSQL databases and Elasticsearch indices will be permanently deleted.

az group delete --name ${RELEASE_NAME} --yes --no-wait