Quickstart

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:

Add a Resource: Define the database, API, or infrastructure you want to protect
Add a Native User: Create a user account for authentication
Configure a Connector: Create a Connector with listeners in the Control Plane
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

Navigate to Resources in the Formal console
Click Create Resource
Fill in the connection details:
- Technology: Select your technology (PostgreSQL, MySQL, MongoDB, Snowflake, HTTP, SSH, etc.)
- Resource Friendly Name: A friendly name for your resource
- Hostname: Your service hostname or IP
- Port: Service port (e.g., 5432 for PostgreSQL, 27017 for MongoDB)
- Space: (Optional) Logical grouping for access control
Set Termination Protection to Yes to prevent accidental deletion (recommended for production)
Click Create

The Formal Terraform Provider repository hosts the official provider source, resource examples, and deployment configs.

resource "formal_resource" "postgres" {
  name        = "production-database"
  hostname    = "db.internal.company.com"
  port        = 5432
  technology  = "postgres"
  termination_protection = true
}

Apply:

terraform apply

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

Navigate to Resources in the Formal console
Click on your resource to open its details
Open the Authentication tab
Under Native Users, click Add User
Select an authentication method (for example, Password), then fill in the fields:
- Username: resource username (e.g., app_user)
- Password: resource password
Click Create

After you create a resource that supports native users, the Formal console opens the Add Native User wizard automatically. You can complete it there or click Skip and add the user later from Authentication.

resource "formal_native_user" "app_user" {
  resource_id         = formal_resource.postgres.id
  native_user_id      = "app_user"
  native_user_secret  = var.native_user_secret
  use_as_default = true
}

variable "native_user_secret" {
  description = "Resource password for native user"
  type        = string
  sensitive   = true
}

Apply:

terraform apply

Step 3: Configure a Connector

Next, create a Connector in the Control Plane to define how clients will connect.

Web Console
Terraform

Navigate to Connectors in the Formal console
Click Create Connector
Enter a Name (and optional Space), then click Create
Open the Connector and go to the Listeners tab
Click New Listener, set a Name and Port (the port clients connect to, e.g. 5432), then click Create
Open the listener, click New Rule, and choose a rule type:
- Resource: Route to a specific resource
- Technology: Route to all resources of a type (e.g., all PostgreSQL databases)
Click Create, then copy the Connector API Token from the Connector details—you’ll need it for deployment

resource "formal_connector" "main" {
  name = "production-connector"
}

resource "formal_connector_listener" "main" {
  connector_id = formal_connector.main.id
  port = 5432
}

resource "formal_connector_listener_rule" "main" {
  connector_listener_id = formal_connector_listener.main.id
  type = "resource"
  resource_id = formal_resource.postgres.id
}

After applying, retrieve the API token:

terraform output connector_api_token

A single listener can use multiple rules. A Technology rule can route to matching resources via smart routing.

Step 4: Deploy the Connector

Now deploy the Connector container in your infrastructure.

Connector Container Image

Use either registry when you set the Connector image in ECS, Helm, or Docker:

AWS ECR: 654654333078.dkr.ecr.<region>.amazonaws.com/formalco-prod-connector:<tag>
GCP Artifact Registry: us-docker.pkg.dev/formal-public-assets/formalco-prod-connector/formalco-prod-connector:<tag>

AWS ECS Fargate (Terraform)
Kubernetes (Helm)
Docker (Local Testing)

The recommended deployment for AWS environments.

Quick Start

Clone the Formal Terraform examples:

git clone https://github.com/formalco/terraform-provider-formal.git
cd terraform-provider-formal/examples/deployments/aws/connector

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"

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.

Universal deployment for any Kubernetes cluster (AWS EKS, GCP GKE, Azure AKS, on-prem).

The Formal Helm Charts repository hosts the official Connector and helper charts with current values and release notes.

Prerequisites

If operating outside an AWS or GCP environment, install ECR credentials:

helm repo add formal https://formalco.github.io/helm-charts
helm show values formal/ecr-cred > ecr-values.yaml
# Edit ecr-values.yaml with your ECR credentials
helm install formal-ecr-cred formal/ecr-cred \
  --namespace formal \
  --create-namespace \
  -f ecr-values.yaml

Deploy the Connector

Get the default values:

helm show values formal/connector > values.yaml

Edit values.yaml and edit these three sections:

# API key for the Connector configured in Formal Control Plane
apiKey: ""

# Set to true only if pulling from AWS ECR outside an AWS or GCP environment to 
# use the ECR credentials job (ecr-cred Helm chart) to fetch ECR credentials
pullWithCredentials: false

# Define the ports of the connector depending on the listeners you've
# configured in Formal Control Plane
ports:
  # - name: postgres-listener
  #   port: 5432

You can download a pre-filled values.yaml file directly on the Formal console when viewing your Connector details and clicking Deploy Connector.

After adding a listener, update ports in your Helm values and run helm upgrade. The Kubernetes Service and its load balancer do not update from Control Plane listener changes.

Install:

helm install formal-connector formal/connector \
  --namespace formal \
  --create-namespace \
  -f values.yaml

Verify deployment:

kubectl get pods -n formal
kubectl logs -n formal -l app.kubernetes.io/name=formal-connector

For local testing and development only.

export FORMAL_CONNECTOR_IMAGE="654654333078.dkr.ecr.us-east-1.amazonaws.com/formalco-prod-connector:latest"
# Or use GCP Artifact Registry:
# export FORMAL_CONNECTOR_IMAGE="us-docker.pkg.dev/formal-public-assets/formalco-prod-connector/formalco-prod-connector:latest"

docker run -d \
  --name formal-connector \
  -p 5432:5432 \
  -v formal-logs:/formal/logs \
  -e FORMAL_CONTROL_PLANE_API_KEY=your-connector-api-token \
  "$FORMAL_CONNECTOR_IMAGE"

This is not recommended for production use. Always deploy with proper orchestration (ECS, Kubernetes) and high availability.

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

Navigate to Connectors in the Formal console
Select your Connector and go to Hostnames
Click Add Hostname
Enter your custom domain (e.g., db.yourcompany.com)
Choose TLS management:
- Formal-Managed: Automatic TLS certificates and DNS records (recommended)
- Customer-Managed: Upload your own TLS certificate and private key in PEM format

Option 1: Formal-managed TLS (Recommended and default option)

resource "formal_connector_hostname" "main" {
  connector_id = formal_connector.main.id
  hostname     = "db.yourcompany.com"
}

Option 2: Custom TLS certificates

resource "formal_connector_hostname" "main" {
  connector_id = formal_connector.main.id
  hostname     = "db.yourcompany.com"
  certificate  = var.tls_certificate
  private_key  = var.tls_private_key
}

variable "tls_certificate" {
  description = "TLS certificate in PEM format"
  type        = string
  sensitive   = true
}

variable "tls_private_key" {
  description = "TLS private key in PEM format"
  type        = string
  sensitive   = true
}

Apply:

terraform apply

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

mongosh "mongodb://your-connector-hostname.com:27017/your-database"

mysql -h your-connector-hostname.com -P 3306 -u your-username -p

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

Connector won't start

Verify your API token is valid
Check connectivity to api.joinformal.com
Review logs in CloudWatch (ECS) or kubectl logs (Kubernetes)
Ensure no port conflicts (port 8080 is reserved for health checks)

Can't connect to resources

Verify the resource is reachable from the Connector’s network
Check security group rules allow outbound connections
Confirm the resource host and port are correct in Formal console
Test direct connectivity from the Connector container

Clients can't reach the Connector

Verify DNS is resolving correctly
Check security group/firewall rules allow inbound traffic
Confirm the listener port matches your client connection string
Test the Connector health endpoint: http://connector:8080/health

Need help? Contact support at support@joinformal.com or check the full deployment guides.

Getting Started

Configuring Formal

Leveraging Formal

Integrations

Configuration

Client Apps

Example Use Cases

Overview

Step 1: Add a Resource

Step 2: Add a Native User to your Resource

Step 3: Configure a Connector

Step 4: Deploy the Connector

Connector Container Image

Quick Start

Prerequisites

Deploy the Connector

Network Requirements

Step 5: Configure DNS and TLS (Optional)

Step 6: Connect Through Formal

Next Steps

Write Access Policies

View Audit Logs

Troubleshooting

​Overview

​Step 1: Add a Resource

​Step 2: Add a Native User to your Resource

​Step 3: Configure a Connector

​Step 4: Deploy the Connector

​Connector Container Image

​Quick Start

​Prerequisites

​Deploy the Connector

​Network Requirements

​Step 5: Configure DNS and TLS (Optional)

​Step 6: Connect Through Formal

​Next Steps

Write Access Policies

View Audit Logs

​Troubleshooting

Overview

Step 1: Add a Resource

Step 2: Add a Native User to your Resource

Step 3: Configure a Connector

Step 4: Deploy the Connector

Connector Container Image

Quick Start

Prerequisites

Deploy the Connector

Network Requirements

Step 5: Configure DNS and TLS (Optional)

Step 6: Connect Through Formal

Next Steps

Troubleshooting