Skip to main content

Retrieve secrets from GCP Secrets Manager

Learn how to use Google Cloud Platform (GCP) Secrets Manager to store your Retool resource secrets.

Secrets Manager Availability
Self-hosted Edge 3.36 or laterGenerally Available
Self-hosted Stable 3.33 or laterGenerally Available

Configuring Resources in Retool can require handling sensitive values, e.g., database passwords or API keys. Retool is SOC 2 Type 2 compliant, and most customers store these values with Retool. However, depending on your security posture, you may want to store secret values externally, rather than encrypted in Retool’s database. To support this, you can store and retrieve secrets from GCP Secrets Manager.

Requirements​

To use the GCP Secrets Manager with Retool, you must:

  • Run self-hosted Retool on versions 3.20 or later on the Enterprise plan.
  • Have admin permissions for your Retool organization.
  • Already have GCP Secrets Manager configured to store your secrets.

1. Set up Application Default Credentials​

In GCP, set up application default credentials to grant Retool access to your secrets.

Workload Identity on Google Kubernetes Engine (GKE)​

If you are using Google Kubernetes Engine to host Retool, you can use workload identity to set up application default credentials. Retool already creates a service account called retool in the GKE cluster. To complete the setup, add your IAM service account annotation to this pre-existing service account.

Alternatively, to automate this process, you can inject the annotations via values.yaml in the Retool Helm chart:

serviceAccount:
  create: true
  name:
  annotations:
    iam.gke.io/gcp-service-account: ${gke_service_account}

2. Configure Secrets Manager in Retool​

Secrets management must be configured for the primary organization, and for any spaces within an organization that need to use secrets.

For multiple deployment instances of Retool, make the same changes to your organization (and spaces within the organization) for each instance in which you want to use secrets.

For each Retool Space, navigate to Settings > Secrets Manager and enter the Project ID and Project Number associated with your GCP Secrets Manager instance, and an optional Namespace. Click Test connection to confirm Retool can connect to your GCP Secrets Manager, then click Save.

Namespace​

The Namespace field is a value that's prepended to any secret names Retool looks up. For example, if all your Retool-facing secrets in GCP Secrets Manager start with retool-, you might set the namespace to be retool- as well. If you have multiple Retool deployment instances, you can use this to resolve the same secret name in a resource configuration to different secrets in your GCP account. For this reason, setting the namespace is recommended if you use Protected Resources.

For example, if you have "development" and "production" deployment instances, you might use the following naming convention for secrets in your GCP account:

// Secrets for development
retool-dev-db_user
retool-dev-db_password

// Secrets for production


retool-prod-db_user
retool-prod-db_password

On your Retool development instance, you would then set the namespace to retool/dev, and on your production instance to retool/prod. You can then reference secrets for either deployment instance using {{ secrets.db_user }} and {{ secrets.db_password }}, and Retool will fetch the appropriate secret at runtime.

3. Use secrets in resources​

After you save your Secrets Manager configuration in Retool, if you granted Retool the Secret Manager Admin or Secret Manager Viewer IAM roles, available secrets appear on Settings > Secrets Manager.

For users to access secret values, the Secret Manager Admin or Secret Manager Secret Accessor IAM roles must be used. You can reference them in resource configurations using template syntax, e.g., {{ secrets.name }} or {{ secrets['name'] }}, either by copying values from the Reference column, or with autocomplete on the resource configuration page.

You can access JSON keys with {{ secrets.name.key }} or {{ secrets['name']['key'] }}. You can access arbitrary levels of nested keys in your secrets. Note that keys will not autocomplete.

If your secret values are not quoted, you may need to wrap the template string in quotes in resource configurations.

For example, given an unquoted secret (secret-value) for the key key_name, you'd use "{{ secrets.key_name.key }}". Given a quoted secret ("secret-value"), you'd use {{ secrets.key_name.key }}.

When you rotate secrets in GCP, Retool automatically reads updated values from your secrets manager. This means you don't need to restart your Retool instance or update any configuration when rotating secrets.

Time to live (TTL) setting​

Retool caches secrets it fetches with a configurable time to live. This reduces API calls to your secrets manager, which keeps queries fast and reduces costs. However, this means secrets may become temporarily stale when they are rotated. You can update Cache TTL (ms) in Settings > Secrets Manager to minimize failed queries in the event that a secret is rotated.

Security considerations​

Any user that can configure resources can use secrets in resources. This could lead to inappropriate uses of secrets. You can restrict the Secret Manager Admin, Secret Manager Secret Accessor, and Secret Manager Viewer IAM roles to authorized users only in GCP to mitigate the risk.