Retool-managed deployment architecture
Learn about the system architecture for Retool-managed, self-hosted deployments.
Retool-managed, self-hosted deployments are available for invoiced customers. Contact your Retool account manager to learn more.
A self-hosted and Retool-managed deployment is a customer-owned VPC that's hosted on Amazon Web Services (AWS) and contains a self-hosted instance. You retain full ownership of, and control over, your data, encryption keys, access, and network infrastructure.
Infrastructure layers
A Retool-managed, self-hosted deployment consists of two infrastructure layers that operate on a dedicated AWS account.
- The support layer: The foundation of a Retool-managed, self-hosted deployment.
- The services layer: The resources needed by the self-hosted instance.
You have full ownership and control over every aspect of the deployment. Retool only has access to what's required for managing the self-hosted instance.
Support layer
The support layer represents the dedicated VPC, resources, and configuration necessary for the deployment. It includes:
| Resource | Description |
|---|---|
| VPC | The environment that contains the Runner VM and Retool-managed self-hosted instance. |
| AWS Secrets Manager | The resource in which secrets and environment variables are stored. |
| Runner VM | The service that allows Retool to manage the self-hosted instance without having access to your larger infrastructure or data. |
| IAM roles and policies | The resources that govern the scope of access granted to the Runner VM for Retool. |
| DNS and private network configuration | Resources related to routing user traffic to the VPC. |
Retool cannot directly access nor manage any resources within the support layer, and works with you to create them. To ensure that the resources are configured exactly as intended, Retool uses an Infrastructure as Code approach; a CloudFormation template is provided to your AWS admin that automatically provisions and configures the VPC, Runner VM, and IAM resources.
Secrets and environment variables
AWS Secrets Manager is used to securely store secrets and environment variables needed for the deployment. Resources needing to use these values retrieves them directly from Secrets Manager, to which Retool has no access.
For instance, your AWS admin adds the following secrets to Secrets Manager which are required by the CloudFormation template:
- Retool Encryption Key
- Retool JWT Secret
Unless you are migrating from an Retool Cloud to a BYOC instance, the Retool encryption key and JWT secret values can be randomly generated. Retool recommends using openssl rand -base64 32. Customers who are migrating from Retool Cloud are provided values to use instead.
Using Secrets Manager for environment variables also allows customers to make changes to update their instance configuration without directly modifying it.
Runner VM
The Runner VM is a dedicated virtual server that operates within the VPC and functions as an agent for Retool's management services. It allows Retool to manage the instance without the need for broader access to your cloud environment. The Runner VM receives instructions from Retool—such as performing an update—and then executes them on the Retool-managed, self-hosted instance.
Any temporary disruption to the Runner VM does not impact the instance itself. If the Runner VM is unavailable, Retool loses access, and cannot remotely monitor or manage the instance.
IAM roles and policies
The Runner VM requires access that's managed using IAM roles and policies. These are used to securely manage Retool's access, prevents any escalation of privileges, and any configuration changes that might compromise the scope of access.
The Runner VM depends on three IAM roles to function correctly and have sufficient access to Retool-managed, self-hosted resources.
| Role | Description |
|---|---|
| Provision | Used at initial setup time, primarily to create new resources. The customer disables this role after initial setup is complete for maximum data security. |
| Maintenance | Used after setup for the lifetime of the Retool-managed, self-hosted instance. This role is typically used to perform GET or describe-action to monitor the health of the instance. The Runner VM may also need to create or delete resources as part of ongoing maintenance. This role is subject to tighter restrictions that prevent access to customer data. This role is subject to additional restrictions that prevent access to customer data and credentials. |
| Deprovision | Used to delete all cloud resources if the customer has decommissioned their instance. This role can remain disabled and only enabled if needed. |
DNS and private network configuration
Once your instance is ready, you configure DNS records for your users to have access. This is an action you perform with your DNS provider after both the CloudFormation stack and instance are set up.
Retool supports additional private network options, such as VPC PrivateLink and VPN user access. While supported, Retool can only provide guidance—customers are responsible for the configuration and maintenance of any custom network configuration.
Services layer
The services layer contains required and optional resources for the self-hosted instance, most of which are managed by Retool. This is created and managed by Retool for you, via the Runner VM. Retool cannot directly access any resources within the services layer. The Runner VM is also used by Retool to interact with the resources of the service layer.
| Resource | Description |
|---|---|
| EKS cluster | Kubernetes pods and services. |
| RDS PostgreSQL database (main) | PostgreSQL database for the storage of metadata. |
| Application Load Balancer (ALB) | Network traffic management and distribution. |
| Route53 DNS zones and records | DNS configuration for the instance (e.g., Retool Spaces). |
EKS cluster
The Retool-managed, self-hosted instance uses an Amazon Elastic Kubernetes Service (Amazon EKS) cluster that operates within the dedicated VPC.
PostgreSQL database
The main database in which Retool stores metadata uses Amazon RDS for PostgreSQL.
Route53 DNS zones
Retool uses an Amazon Route53 publicly hosted zone to manage DNS records within the deployment. This includes:
- TLS certificate validation records.
- Application Load Balanceer (ALB) alias records.
- Wildcard records for Retool Spaces.
This hosted zone is scoped to the custom domain used for the instance.
Configuration options
Retool only supports the available configuration options listed below and cannot substitute them with alternatives.
Retool uses a standard deployment configuration by default that's suitable for most use-cases. You can also customize certain configuration options to best suit your needs.
- Standard: A configuration option that's used by default if you do not request an available custom configuration option.
- Available: A configuration option that's not used by default but can be enabled upon request.
- Custom: An alternative configuration option that's available for use upon request.
Although custom configuration options are available, Retool cannot support, access, or manage any external infrastructure they use. For instance, you can request that your deployment only be accessible by VPN but Retool cannot implement nor manage the VPN for you.
Some custom options can only be configured to deployment while others are available for use at any time. Unless otherwise stated, you must configure and manage any custom configuration options you request.
DNS
Configuration options for managing DNS records of the deployment.
| Option | Description |
|---|---|
| NS record delegation Standard | DNS for the deployment domain is delegated using NS records. Supports automatic certificate renewal and subdomain support for Spaces. |
| Direct Application Load Balancer and certificate validation records Custom | Individual DNS records are configured to provide more granular control, such as support for Web Application Firewall (WAF) policies. DNS records for certificate renewal are also configured. Retool can provide guidance but you must configure and manage this configuration. |
Ingress
Configuration options for managing user access to the deployment.
| Option | Description |
|---|---|
| Retool-managed Application Load Balancer Standard | Publicly accessible ALB that handles internal and external traffic. |
| Customer-managed Application Load Balancer Custom | ALB with custom configuration, such as Web Application Firewall (WAF) policies. Retool-managed, self-hosted deployments include a byolb ALB target group by default for which Retool can provide guidance but you must configure and manage this configuration. |
| Customer-managed VPN Custom | Accessible only through a VPN connection. Retool can provide guidance but you must configure and manage all aspects of the VPN connection between the user and the deployment. |
Egress
Configuration options for managing how the deployment accesses external resources (e.g., cloud-hosted data sources).
| Option | Description |
|---|---|
| Public internet egress Standard | Unrestricted internet access for connecting to any publicly reachable resource. |
| Static IP address pool for allowlists Standard | Retool connects to resources using a pool of static IP addresses that can be added to allowlists. |
| SSH tunnelling Standard | Connect to private resources using SSH tunnels. |
| VPN access Custom | Connect to private resources using a VPN. Retool can provide guidance but you must configure and manage all aspects of the VPN connection between the deployment and private resources. |
| VPC PrivateLink Custom | Private connection between the deployment's VPC and another VPC using AWS PrivateLink. Retool can provide guidance but you must configure and manage all aspects of the PrivateLink connection. |
Storage database and fault tolerance
Configuration options that apply to the main PostgreSQL database of the Retool-managed, self-hosted instance. Any customization must be requested prior to setup.
| Option | Description |
|---|---|
| Single-availability zone Standard | A single, non-replicated RDS database used for metadata. |
| Multi-availability zone Available Configured pre-deployment | A fault-tolerant RDS database that's replicated across multiple regions. |
Optional Retool features
Configuration options for features not enabled by default. Retool can enable, configure, and manage these features for you at any time. These features require additional resources which may incur additional AWS costs.
| Option | Description |
|---|---|
| Retool Database Available | Requires an additional RDS database that you provision using Retool-provided information. |
| Retool Storage Available | Requires an Amazon S3 bucket. You can use an existing bucket or provision a new one using Retool-provided information. |
| Retool RPC Available | Requires an Amazon ElastiCache for Redis resource that you provision using retool-provided information. |
| Collaborative editing (Multiplayer) Custom | No additional resources required and can be enabled upon request. |
Retool always assumes that these services contain sensitive data. To maintain the security boundary that separates Retool from your wider infrastructure and data, Retool is prevented from accessing them.