Skip to main content
Get production-ready access controls running in minutes. This guide walks you through deploying your first Connector and connecting to a protected resource.

​
Overview

Deploying Formal consists of four main steps:
  1. Add a Resource: Define the database, API, or infrastructure you want to protect
  2. Add a Native User: Create a user account for authentication
  3. Configure a Connector: Create a Connector with listeners in the Control Plane
  4. Deploy the Connector: Run the Connector container in your infrastructure

​
Step 1: Add a Resource

The first step is to register the resource you want to protect in Formal.
  • Web Console
  • Terraform
  1. Navigate to Resources in the Formal console
  2. Click New Resource
  3. Fill in the connection details:
    • Name: A friendly name for your resource
    • Type: Select your technology (PostgreSQL, MySQL, MongoDB, Snowflake, HTTP, SSH, etc.)
    • Host: Your service hostname or IP
    • Port: Service port (e.g., 5432 for PostgreSQL, 27017 for MongoDB)
    • Space: (Optional) Logical grouping for access control
  4. Enable Termination Protection to prevent accidental deletion (recommended for production)
  5. Click Create Resource
Your resource doesn’t need to be publicly accessible. The Connector will reach it from within your VPC.

​
Step 2: Add a Native User to your Resource

Add a native user account that will be used to authenticate connections to your resource.
  • Web Console
  • Terraform
  1. Navigate to Resources in the Formal console
  2. Click on your resource to open its details
  3. Go to the Native Users tab
  4. Click Add Native User
  5. Fill in the user details:
    • Username: resource username (e.g., app_user)
    • Password: resource password
    • Description: Optional description for the user
  6. Click Create Native User

​
Step 3: Configure a Connector

Next, create a Connector in the Control Plane to define how clients will connect.
  • Web Console
  • Terraform
  1. Navigate to Connectors in the Formal console
  2. Click New Connector
  3. Enter a Name for your Connector
  4. Add a Listener:
    • Port: The port clients will connect to (e.g., 5432 for PostgreSQL)
    • Rule Type: Choose how to route connections:
      • Resource: Route to a specific resource
      • Technology: Route to all resources of a type (e.g., all PostgreSQL databases)
      • Any: Auto-detect protocol and route intelligently
  5. Click Create Connector
  6. Save the API Token that appears—you’ll need it for deployment
The Connector supports smart routing: a single listener on one port can handle multiple protocols and automatically route to the correct resource.

​
Step 4: Deploy the Connector

Now deploy the Connector container in your infrastructure.
  • AWS ECS Fargate (Terraform)
  • Kubernetes (Helm)
  • Docker (Local Testing)
The recommended deployment for AWS environments.

​
Quick Start

  1. Clone the Formal Terraform examples:
git clone https://github.com/formalco/terraform-provider-formal.git
cd terraform-provider-formal/examples/deployments/aws/connector
  1. Create a terraform.tfvars file:
region             = "us-west-2"
availability_zones = ["us-west-2a", "us-west-2b"]
formal_api_key     = "your-formal-api-key"
formal_org_name    = "your-org-name"
  1. Deploy:
terraform init
terraform apply
This creates:
  • ECS Fargate service across multiple availability zones
  • Network Load Balancer for high availability
  • CloudWatch logging for monitoring
  • IAM roles and Secrets Manager for secure key storage
For production, integrate the Connector into your existing VPC and networking setup instead of using the demo VPC.

​
Network Requirements

Ensure your Connector can reach:
  • Outbound to Formal Control Plane: api.joinformal.com (gRPC)
  • Inbound from clients: Port(s) configured in your listeners
  • Outbound to resources: Your database/API endpoints

​
Step 5: Configure DNS and TLS (Optional)

For production deployments, add a custom domain and TLS:
  • Web Console
  • Terraform
  1. Navigate to Connectors in the Formal console
  2. Select your Connector and go to Hostnames
  3. Click Add Hostname
  4. Enter your custom domain (e.g., db.yourcompany.com)
  5. Choose TLS management:
    • Formal-managed: Automatic TLS certificates and DNS records (recommended)
    • Custom certificates: Upload your own TLS certificate and private key in PEM format

​
Step 6: Connect Through Formal

You’re ready to connect! Route your database connections through the Connector: 
psql -h your-connector-hostname.com -p 5432 -U your-username -d your-database
The Connector will:
  • ✅ Authenticate your identity
  • ✅ Evaluate policies in real-time
  • ✅ Log all queries and responses
  • ✅ Apply data masking and redaction rules
  • ✅ Route to the correct resource

​
Next Steps

Now that your first Connector is running, explore these features:

Write Access Policies

Control who can access what with policy-as-code

View Audit Logs

Monitor all queries and sessions in real-time

​
Troubleshooting

  1. Verify your API token is valid
  2. Check connectivity to api.joinformal.com
  3. Review logs in CloudWatch (ECS) or kubectl logs (Kubernetes)
  4. Ensure no port conflicts (port 8080 is reserved for health checks)
  1. Verify the resource is reachable from the Connector’s network 2. Check security group rules allow outbound connections 3. Confirm the resource host and port are correct in Formal console 4. Test direct connectivity from the Connector container
  1. Verify DNS is resolving correctly
  2. Check security group/firewall rules allow inbound traffic
  3. Confirm the listener port matches your client connection string
  4. Test the Connector health endpoint: http://connector:8080/health
Need help? Contact support at support@joinformal.com or check the full deployment guides.