Skip to main content

Deploy Retool on GCP with Terraform

Deploy a production-ready self-hosted Retool instance on Google Cloud 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 (VPC, GKE cluster, Cloud SQL database, GCS bucket, load balancer, and managed TLS certificate) and deploys Retool using the official Helm chart.

Before you start​

On a new GCP project, enable the required APIs before deploying to avoid API-propagation races during the apply:

gcloud services enable \
  compute.googleapis.com \
  servicenetworking.googleapis.com \
  sqladmin.googleapis.com \
  container.googleapis.com \
  secretmanager.googleapis.com \
  dns.googleapis.com \
  certificatemanager.googleapis.com \
  --project your-project-id

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/gcp_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 {
  prefix      = "retool-prod"          # prefix for all GCP resource names
  project_id  = "your-project-id"      # your GCP project ID
  region      = "us-central1"          # GCP region
  domain_name = "retool.example.com"   # the domain Retool will be served from
}

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_gcs        = 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 a GCS bucket 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: VPC → GKE → Cloud SQL → Retool services → ingress → Helm release.

The full apply takes 30–45 minutes. Most of that time is GKE cluster creation and Cloud SQL instance provisioning.

Cloud SQL provisioning can outlast Terraform's client timeout. If the apply errors with a timeout but the instance shows as RUNNABLE in the Cloud SQL console, import it and re-apply rather than recreating it.

4. Configure DNS​

Once the apply completes, retrieve the Cloud DNS managed zone nameservers:

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

The blueprints create a Cloud DNS managed 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 gcp-user-ingress module manages the A record (via external-dns) pointing at the reserved static IP, and the Certificate Manager DNS authorization validates automatically once delegation completes. After validation, 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 '.["gke"].cluster.name')
CLUSTER_REGION=$(terraform output -json modules | jq -r '.["gke"].cluster.location')
PROJECT_ID=$(terraform output -json modules | jq -r '.["gke"].cluster.project')
gcloud container clusters get-credentials "$CLUSTER_NAME" --region "$CLUSTER_REGION" --project your-project-id

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​