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
note

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 and remove the original to avoid a duplicate provider error on the next step:

cp provider.example.tf providers.tf && rm provider.example.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              = "your-retool-org"                       # prefix for all Azure resource names, must be globally unique
  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
}

prefix also names the storage account used for app storage, workflow artifacts, and agent sandbox snapshots (<prefix>rr, with hyphens stripped). Azure Storage account names are unique across every Azure subscription, so a generic value like retool-prod can collide with a storage account another customer already created. Choose a prefix specific to your organization to avoid this.

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. Getting the chart version right matters since the chart and image tag need to be compatible with each other. Check the current version on Artifact Hub or the retool-helm releases page, and pin to it explicitly rather than leaving it unset:

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

  retool_helm_extra_values = [yamlencode({
    image = {
      tag = "4.0.9-stable"  # current recommended stable release; never the "latest" tag
    }
  })]
}
Warning

All services must run the same tag. Tag mismatches can cause the deployment to run incorrectly.

2. Initialize Terraform​

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

Caution

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')
RESOURCE_GROUP=$(awk -F'"' '/resource_group_name[[:space:]]*=/{print $2; exit}' main.tf)
az aks get-credentials --resource-group "$RESOURCE_GROUP" --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:

note

After you sign up, the deployment performs some one-time setup steps in the background. If a feature doesn't seem to work right away, wait a few minutes before troubleshooting further.

  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.

Next steps​