Skip to main content

Deploy Retool on Azure with Terraform

Deploy a production-ready self-hosted Retool instance on Azure using Retool's Terraform blueprints.

Self-hosted Retool must be deployed on a Kubernetes cluster with Helm. For new deployments, Retool provides an officially maintained Terraform blueprint that automatically provisions all the required infrastructure (virtual network, AKS cluster, Azure Database for PostgreSQL, Blob storage, Application Gateway, and managed TLS certificate) and deploys Retool using the official Helm chart.

Before you start​

1. Configure the template​

Use the following steps to configure the template.

1. Clone blueprints​

Clone the blueprints repository, confirm the example directory name, then copy it as your working directory:

git clone https://github.com/tryretool/terraform-retool-self-hosted-blueprints.git
ls terraform-retool-self-hosted-blueprints/examples/
cp -r terraform-retool-self-hosted-blueprints/examples/azure_all_inclusive my-retool-deployment
cd my-retool-deployment

The example directory name may change between releases. Use ls to confirm the name matches what you see in the repository before copying.

2. Copy provider template​

Copy the provider template:

cp provider.example.tf providers.tf

3. Update main.tf blocks​

Open main.tf and update the locals block with your values:

locals {
  subscription_id     = "00000000-0000-0000-0000-000000000000"  # your Azure subscription ID
  prefix              = "retool-prod"                           # prefix for all Azure resource names
  location            = "eastus2"                               # Azure region
  resource_group_name = "retool-prod"                           # resource group to create resources in
  domain_name         = "retool.example.com"                    # the domain Retool will be served from

  # HTTPS is enabled by default. cert-manager issues the certificate
  # automatically once DNS is delegated. Set to false to come up over HTTP first.
  enable_https = true
}

In the retool-services module block, set your license key:

module "retool-services" {
  # ...
  license_key          = "your-license-key"
  enable_agent_sandbox = true  # required for Retool AI agents
  enable_rr_blob       = true  # required for app storage, workflow artifacts, and sandbox snapshots
}

In the retool module block, set the Helm chart version and Retool image tag. Use the latest chart version from retool-helm releases and the current stable image tag from release notes:

module "retool" {
  # ...
  retool_helm_chart_version = "6.11.5"  # check retool-helm releases for the latest

  retool_helm_extra_values = [yamlencode({
    image = {
      tag = "X.Y.Z-stable"  # replace with current stable tag
    }
  })]
}

2. Initialize Terraform​

Run terraform init. Terraform downloads the provider plugins and module sources.

Configure a remote backend to store Terraform state before running terraform apply. The default local backend stores state in a file on disk. If that file is lost or corrupted, you lose the ability to manage your infrastructure with Terraform. Use an Azure Storage account backend for production deployments.

3. Apply the configuration​

Run terraform apply.

Review the plan and type yes to proceed. The apply provisions infrastructure in this order: virtual network → AKS → Azure Database for PostgreSQL → Retool services → ingress → Helm release.

The full apply takes 30–45 minutes. Most of that time is AKS cluster creation and database provisioning.

4. Configure DNS​

Once the apply completes, retrieve the Azure DNS zone nameservers:

terraform output -json modules | jq -r '.["user-ingress"].zone_name_servers[]'

The blueprints create an Azure DNS zone for your domain. Delegate your domain to it by updating the NS record at your registrar or parent DNS provider to point to these nameservers.

Confirm delegation has propagated:

dig +short NS retool.example.com

The output lists the nameservers from the previous step once the change propagates. The azure-user-ingress module manages the A record pointing at the Application Gateway's public IP. With enable_https = true (the default), the cert-manager Let's Encrypt issuer mints the TLS certificate automatically once DNS resolves, and https://retool.example.com comes up — no additional apply is needed.

5. Verify the deployment​

Retrieve the cluster details from the Terraform output, then update your kubeconfig:

CLUSTER_NAME=$(terraform output -json modules | jq -r '.["aks"].cluster.name')
az aks get-credentials --resource-group retool-prod --name "$CLUSTER_NAME"

Verify all pods are running:

kubectl get pods -n default

A healthy deployment includes pods for the core services, workflow services, and agent sandbox:

retool-api-xxx                              1/1     Running   0   5m
retool-jobs-runner-xxx                      1/1     Running   0   5m
retool-workflows-worker-xxx                 1/1     Running   0   5m
retool-workflows-backend-xxx                1/1     Running   0   5m
retool-code-executor-xxx                    1/1     Running   0   5m
retool-js-executor-xxx                      1/1     Running   0   5m
retool-agent-sandbox-controller-xxx         1/1     Running   0   5m
retool-agent-sandbox-proxy-xxx              1/1     Running   0   5m
retool-agent-sandbox-job-xxx (×5)           1/1     Running   0   5m

6. Complete setup in Retool​

Once the deployment is healthy, complete the following:

  1. Enable Temporal: click the Workflows nav item and follow the in-product setup steps. A valid license key is required. Temporal Cloud requires outbound egress on ports 443 and 7233; refer to Temporal egress.
  2. Configure your organization to use the new app builder.

Retool-managed AI keys are not compatible with self-hosted deployments. The managed key proxy has a 29-second timeout that agent operations regularly exceed, causing silent failures. Configure your own API keys (Bring Your Own Key) under Resources → AI.

Next steps​