Deployment

The Connector is available as a statically linked binary in a multi-architecture distroless Docker image.

Container Image Registries

You can pull Connector images from either of these registries:

AWS ECR: 654654333078.dkr.ecr.<region>.amazonaws.com/formalco-prod-connector:<tag> Available regions: us-east-1, us-west-1, us-west-2, ap-southeast-1, and eu-west-1.
GCP Artifact Registry: us-docker.pkg.dev/formal-public-assets/formalco-prod-connector/formalco-prod-connector:<tag>

On AKS, use the GAR image with azure-gar-cred. Set pullWithCredentials: true in the Connector Helm values.

Amazon ECR Pull-Through Cache

You can cache Formal images in your own Amazon ECR registry with an ECR pull-through cache rule. Your clusters then pull from your registry, so they need no Formal image pull secret. Formal must first allowlist your AWS account ID or organization ID for ECR pulls. Contact Formal support to request access.

Create an IAM role for the cache Amazon ECR assumes this role to pull from Formal’s registry. Save this trust policy as ptc-trust.json:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "Service": "pullthroughcache.ecr.amazonaws.com" },
      "Action": "sts:AssumeRole"
    }
  ]
}

Save this permissions policy as ptc-permissions.json:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecr:GetAuthorizationToken",
        "ecr:BatchGetImage",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchImportUpstreamImage",
        "ecr:GetImageCopyStatus",
        "ecr:InitiateLayerUpload",
        "ecr:UploadLayerPart",
        "ecr:CompleteLayerUpload",
        "ecr:PutImage"
      ],
      "Resource": "*"
    }
  ]
}

Create the role:

aws iam create-role \
  --role-name formal-ecr-pull-through-cache \
  --assume-role-policy-document file://ptc-trust.json
aws iam put-role-policy \
  --role-name formal-ecr-pull-through-cache \
  --policy-name formal-ecr-pull-through-cache \
  --policy-document file://ptc-permissions.json

Create the pull-through cache rule Run this in the AWS account and region of your registry. Set --upstream-registry-url to a Formal ECR region listed above.

aws ecr create-pull-through-cache-rule \
  --ecr-repository-prefix formal \
  --upstream-registry ecr \
  --upstream-registry-url 654654333078.dkr.ecr.us-east-1.amazonaws.com \
  --custom-role-arn arn:aws:iam::<YOUR_ACCOUNT_ID>:role/formal-ecr-pull-through-cache

Pull through your registry Prefix Formal repository names with formal/ and use your registry host:
<YOUR_ACCOUNT_ID>.dkr.ecr.<YOUR_REGION>.amazonaws.com/formal/formalco-prod-connector:<tag>
In the Connector Helm chart, set image.repository to this value and keep pullWithCredentials: false.

Verify:

aws ecr get-login-password --region <YOUR_REGION> | docker login \
  --username AWS --password-stdin <YOUR_ACCOUNT_ID>.dkr.ecr.<YOUR_REGION>.amazonaws.com
docker pull <YOUR_ACCOUNT_ID>.dkr.ecr.<YOUR_REGION>.amazonaws.com/formal/formalco-prod-connector:latest
aws ecr describe-images --region <YOUR_REGION> --repository-name formal/formalco-prod-connector
# Expected: the cached image appears in your registry

Amazon ECR checks Formal’s registry for tag updates at most once every 24 hours. Pin versioned tags instead of latest. Keep cached repositories tag-mutable, or cached tags stop updating.

Infrastructure Requirements

Operating System: Linux environment
Architecture: AMD64 or ARM64
Container Runtime: Docker or compatible container runtime

Network Requirements

The Connector requires:

Network access to api.joinformal.com (Formal Control Plane)
Outbound access to your protected resources
Inbound access from clients on configured listener ports

AWS VPC Private Link Connectivity

For customers deploying on AWS, the Connector can connect to the Formal Control Plane using AWS VPC Private Link instead of traversing the public internet. This provides enhanced security and network isolation. Service Details:

Service Name: com.amazonaws.vpce.eu-west-1.vpce-svc-01bfea09d5ec08d36
Region: eu-west-1
Endpoint Type: Interface (services that use NLBs or GWLBs)

Setup Steps:

Create VPC Endpoint Using AWS Console:
- Navigate to VPC → Endpoints → Create Endpoint
- Select Other endpoint services
- Enter service name: com.amazonaws.vpce.eu-west-1.vpce-svc-01bfea09d5ec08d36
- Click Verify service
- Select your VPC and subnets where the Connector is deployed
- Configure security groups to allow outbound HTTPS traffic (port 443) from the Connector
- Important: Check Enable Private DNS Name
- If your VPC is in a region other than eu-west-1, enable Cross-region endpoint and specify eu-west-1 as the target region
- Review and create the endpoint
Configuration Requirements
- Private DNS: Must be enabled for proper DNS resolution of Control Plane endpoints
- Cross-region Support: Required if your VPC is in any region other than eu-west-1
- Security Groups: Must allow outbound HTTPS (port 443) from Connector to VPC endpoint
- Network ACLs: Ensure subnet ACLs permit traffic to/from the VPC endpoint

Verify Connectivity Once the endpoint is in Available state, test from your Connector instance:

# Verify DNS resolves to private IP
nslookup api.joinformal.com

# Test HTTPS connectivity
curl -v https://api.joinformal.com

The VPC endpoint uses Private DNS to automatically redirect api.joinformal.com traffic through the private connection. No configuration changes are needed on the Connector side.

For cross-region deployments (regions other than eu-west-1), you must enable the cross-region endpoint feature and specify eu-west-1 as the target region, or the connection will fail.

Resource Requirements

The Connector requires adequate resources to apply policies with minimal latency and maintain all necessary context in RAM (Control Plane data, queries metadata, responses data, log buffer, etc.).

Spec	Minimum	Recommended
CPU	1 core	2 cores per node (2 nodes)
RAM	2 GB	4 GB per node (2 nodes)
Disk	0 GB	10 GB

CPU Throttling Warning: If you don’t allocate entire CPU cores to the Connector and rely on CPU throttling (e.g., CFS quotas on Linux, CPU limits in Kubernetes), you will most likely experience increased latency and timeouts during peak loads.

Production Recommendations

For production deployments, we recommend:

High Availability: Run at least 2 nodes behind a load balancer
Resource Allocation: 2 CPU cores and 4 GB RAM per node
Load Distribution: Distribute traffic across multiple Connector instances
Persistent Storage: Mount a persistent volume to /formal/logs for the log spool

CPU, RAM and disk requirements vary based on usage patterns, query types, traffic volume, and enforced policies. Monitor your Connector with a telemetry collector and scale resources as needed. The Connector buffers up to 400 MB of logs in memory before spooling to disk. A typical log entry is around 1 KB – at 100 requests per second, 10 GB of disk provides more than a day of outage buffer. The Connector works without disk (spooling is disabled), but logs may be lost during disruptions.

When deploying multiple instances, Connectors attempt automatically to form a cluster with shared state. It enables Connectors to coordinate rate limiting across all instances. See the Clustering page for details.

Recommended Deployment Options

AWS ECS Fargate

Deploy as a Fargate service behind a Network Load Balancer with multi-AZ availability

Kubernetes

Deploy using Formal Helm charts on any Kubernetes cluster (EKS, GKE, AKS, on-premises).

Docker

Run as a standalone container (development/testing only)

See the Quickstart guide for step-by-step deployment instructions.

Environment Variables

The Connector is configured primarily through the Control Plane, but requires the following environment variable:

Variable	Type	Description
`FORMAL_CONTROL_PLANE_API_KEY`	String	API token to authenticate with the Control Plane (obtained when creating the Connector)

Getting Started

Example Use Cases

AI Governance

Configuring Formal

Integrations

Configuration

Container Image Registries

Amazon ECR Pull-Through Cache

Infrastructure Requirements

Network Requirements

AWS VPC Private Link Connectivity

Resource Requirements

Production Recommendations

Recommended Deployment Options

AWS ECS Fargate

Kubernetes

Docker

Environment Variables

​Container Image Registries

​Amazon ECR Pull-Through Cache

​Infrastructure Requirements

​Network Requirements

​AWS VPC Private Link Connectivity

​Resource Requirements

​Production Recommendations

​Recommended Deployment Options

AWS ECS Fargate

Kubernetes

Docker

​Environment Variables

Container Image Registries

Amazon ECR Pull-Through Cache

Infrastructure Requirements

Network Requirements

AWS VPC Private Link Connectivity

Resource Requirements

Production Recommendations

Recommended Deployment Options

Environment Variables