Skip to main content

Azure Installation Guide

This guide walks through deploying a Catalyst Enterprise Self-Hosted region into a private Azure Virtual Network, with all traffic routed through a centralized Azure Firewall. It also shows how to configure the deployment with the optional PostgreSQL backing store required for Workflow visualization.

Demonstration only

This guide is intended as a reference walkthrough for demonstration and proof-of-concept deployments. It is not a production-ready deployment recipe — use the Production Installation guidance and adapt this script to your organization's networking, security, and operational requirements before going to production.

Prerequisites​

Required tools​

  • Azure CLI (v2.45.0+) — for managing Azure resources and authentication
  • Diagrid CLI (v0.12.0+) — for managing Catalyst regions and projects
  • Helm (v3.12.0+) — for deploying Catalyst to Kubernetes
  • kubectl (v1.28+) — for interacting with the Kubernetes cluster
  • jq (v1.6+) — for JSON parsing in shell scripts

Azure requirements​

  • A valid Azure subscription with owner permissions for resource creation
  • Sufficient vCPU and memory quotas for AKS and VM resources
  • An SSH key pair for VM access (generate with ssh-keygen -t rsa -b 4096 if needed)

Scripts​

The provisioning scripts referenced in this guide live in the guides/azure directory of the diagridio/charts repository. Clone the repository and run the scripts from inside that directory:

git clone https://github.com/diagridio/charts.git
cd charts/guides/azure

Architecture overview​

The provisioning script creates a secure baseline environment for Catalyst Enterprise Self-Hosted on Azure, modelled on the AKS Baseline Architecture. All compute resources (AKS and the management VM) live in a private network, with all ingress and egress traffic controlled and inspected by Azure Firewall. Only required ports and FQDNs are allowed, and SSH access is tightly controlled via DNAT rules.

The script provisions:

  • Resource Group — logical container for all Catalyst-related resources

  • Virtual Network (VNet) — isolated network space (default 10.42.0.0/16)

  • Subnets

    • Primary subnet for AKS and the management VM (default 10.42.1.0/24)
    • Firewall subnet, dedicated to Azure Firewall (default 10.42.2.0/24, must be named AzureFirewallSubnet)

  • Azure Firewall with a public IP, with all outbound traffic from the AKS cluster and VM routed through it for inspection. Network rules allow:

    • NTP (UDP 123) for time synchronization
    • DNS (UDP 53) to Azure DNS
    • Service tags for Azure Container Registry, Microsoft Container Registry, Azure Active Directory, and Azure Monitor
    • TCP 9000 and UDP 1194 for Azure API and VPN access

    Application rules allow HTTP/HTTPS access to the FQDNs required for:

    • Diagrid services (*.diagrid.io)
    • Kubernetes image and package downloads
    • GitHub and container registries (Azure, AWS, GCP, Docker)
    • Ubuntu and Linux package repositories
    • Azure management and monitoring endpoints
    • Helm and Bitnami chart repositories
    • AKS-specific FQDN tags for Kubernetes operations
    • The management VM accessing the private AKS API server via the firewall

    A DNAT rule allows SSH (port 22) from your client IP to the VM's private IP via the firewall's public IP for secure, auditable management access.

  • Route Table — sends all traffic from the primary subnet to the firewall via a 0.0.0.0/0 route with the firewall's private IP as the next hop

  • AKS cluster — private cluster (API server not internet-exposed), 3 nodes by default, deployed in the primary subnet, with User Defined Routing forcing all outbound traffic through the firewall and Managed Identity enabled

  • Management VM — Ubuntu jumpbox in the primary subnet with no public IP (accessed via the firewall DNAT rule), with Managed Identity and the Contributor role assigned

Workflow support​

At its core, Catalyst Enterprise Self-Hosted hosts the Dapr Workflow API, providing a foundation for building long-running, stateful workflows with built-in fault tolerance, scalability, and visualization.

Workflow visualization in the Catalyst console requires PostgreSQL to store the workflow data. You can either use a single PostgreSQL instance for both workflow visualization and workflow state, or bring your own workflow state store. This guide installs an in-cluster PostgreSQL instance via the Bitnami Helm chart and uses it for both purposes.

If you choose to enable Workflow support, the script configures Catalyst as follows:

  • Creates a dedicated catalyst database via the PostgreSQL Helm chart
  • Sets default credentials (postgres/postgres) for initial setup
  • Configures internal Kubernetes service discovery via postgres-postgresql.postgres.svc.cluster.local
  • Sets agent.config.project.default_managed_state_store_type: postgresql-shared-external and the matching connection string parameters

If you forgo the Workflow setup, you can still use Catalyst Enterprise Self-Hosted with the other supported Dapr APIs (service invocation, pub/sub, state management, and so on).

note

To visualize workflows through the Catalyst console, ensure your network rules allow access to the Catalyst UI from your environment.

Installation steps​

1. Create a Catalyst region​

Use the Diagrid CLI to create a new region and capture a join token:

diagrid login

export PRIVATE_REGION="azure-region"
export AZURE_API_KEY="azure-key"

# Create a new region and capture the join token
export JOIN_TOKEN=$(diagrid region create $PRIVATE_REGION \
  --ingress "http://*.10.42.1.180.nip.io:8080" | jq -r .joinToken)

# Create an API key for CLI use from the management VM
# Note: this API key expires after 24 hours. Remove --duration for a long-lived key.
export API_KEY=$(diagrid apikey create \
  --name $AZURE_API_KEY \
  --role cra.diagrid:editor \
  --duration 86400 | jq -r .token)

2. Log in to Azure​

az login

3. Deploy Azure resources​

Run the provided install.sh script to provision the Azure architecture described above. The script creates the resource group, VNet, subnets, firewall, AKS cluster, and management VM, and applies the routing and security rules — no manual configuration of these resources is required.

chmod +x ./install.sh
./install.sh

4. Connect to the Azure VM​

The provisioning step also generates a connect.sh helper that establishes an SSH session to the management VM through the firewall:

chmod +x ./connect.sh
./connect.sh
note

From this point on, commands should be executed on the Azure VM unless stated otherwise.

5. Prepare the Azure VM​

Install the CLI tooling and dependencies on the VM, source the generated environment, and authenticate the Diagrid CLI:

chmod +x "$HOME/setup.sh"
"$HOME/setup.sh"
rm "$HOME/setup.sh"

# Source the environment generated by install.sh
source .env

# Authenticate the Diagrid CLI
diagrid login --api-key="$API_KEY"

6. Install PostgreSQL for Dapr Workflow​

To use Dapr Workflow with Catalyst Enterprise Self-Hosted, deploy a PostgreSQL instance into the AKS cluster. This step is optional.

helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update
helm install postgres bitnami/postgresql \
  --set auth.postgresPassword=postgres \
  --set auth.database=catalyst \
  --create-namespace \
  --namespace postgres

7. Configure and install Catalyst​

Create a Helm values file. Use the with PostgreSQL variant if you installed PostgreSQL above; otherwise use the without PostgreSQL variant.

With PostgreSQL:

agent:
  config:
    project:
      default_managed_state_store_type: postgresql-shared-external
      external_postgresql:
        enabled: true
        auth_type: connectionString
        namespace: postgres
        connection_string_host: postgres-postgresql.postgres.svc.cluster.local
        connection_string_port: 5432
        connection_string_username: postgres
        connection_string_password: postgres
        connection_string_database: catalyst
gateway:
  envoy:
    service:
      type: LoadBalancer
    podAnnotations:
      service.beta.kubernetes.io/azure-load-balancer-internal: "true"
      service.beta.kubernetes.io/azure-load-balancer-ipv4: 10.42.1.180

Without PostgreSQL:

agent:
  config:
    project:
      default_managed_state_store_type: postgresql-shared-disabled
gateway:
  envoy:
    service:
      type: LoadBalancer
    podAnnotations:
      service.beta.kubernetes.io/azure-load-balancer-internal: "true"
      service.beta.kubernetes.io/azure-load-balancer-ipv4: 10.42.1.180

Install Catalyst:

helm install catalyst oci://public.ecr.aws/diagrid/catalyst \
   -n cra-agent \
   --create-namespace \
   -f catalyst-values.yaml \
   --set join_token="${JOIN_TOKEN}" \
   --version 1.42.0-rc.2

Wait for all pods to be ready:

kubectl -n cra-agent wait --for=condition=ready pod --all --timeout=5m

8. Get started​

Create a Catalyst project in the newly deployed region:

export PROJECT_NAME="azure-project"

diagrid project create $PROJECT_NAME --region $PRIVATE_REGION
diagrid project use $PROJECT_NAME

Create App IDs in the new project to test resource creation and connectivity:

diagrid appid create app1
diagrid appid create app2

# Wait until the App IDs are ready
diagrid appid list

# See the Dapr runtime instances running in Kubernetes
kubectl get po -A | grep prj

Open a new SSH session to the Azure VM and start a listener for app1:

./connect.sh

# Wait until you see:
# ✅ Connected App ID "app1" to http://localhost:<port> ⚡️
diagrid listen -a app1

From the original SSH session, send a service-invocation request between App IDs:

diagrid call invoke get app1.hello -a app2

You should see the request received on the app1 listener:

{
  "method": "GET",
  "url": "/hello"
}

This proves that you can use Dapr's service invocation API by calling an App ID over the private gateway IP. In this scenario the Diagrid CLI is acting as both the sending and receiving applications — see Test Catalyst APIs using the Diagrid CLI.

To continue, see the local development guide for guidance on building and deploying your own apps.

Configuration options​

Network configuration​

  • VNet address space — ADDRESS_PREFIX (default 10.42.0.0/16)
  • Subnet ranges — SUBNET_PREFIX (default 10.42.1.0/24)
  • Load balancer IP — LOADBALANCER_IPV4 (default 10.42.1.180)

Compute resources​

  • AKS node count — default 3 nodes, configurable in install.sh
  • VM size — default Standard_B2s (2 vCPU, 4 GiB), set via VM_SIZE
  • AKS node pool — VM sizes and autoscaling are configurable in the script

Security customization​

  • Firewall rules — extend the FQDN allowlist for additional services
  • Network rules — add ports or protocols as needed
  • Access control — adjust SSH access rules and IP restrictions

Workflow configuration​

  • PostgreSQL — optional, enables Workflow visualization and state storage
  • External state stores — Catalyst supports custom external PostgreSQL instances
  • Database credentials — configurable via Helm values

Limitations​

  • Secrets backends — Catalyst Enterprise Self-Hosted supports AWS Secrets Manager and Kubernetes Secrets. Azure Key Vault support is on the roadmap.
Last updated on