Some data never leaves the building. A hospital's patient tables, a bank's core ledger, a European retailer's customer records under a strict data residency policy — the analytics team still needs them in the warehouse, but security will not approve a SaaS pipeline that reads production and moves rows through a vendor's cloud.
That is the problem Fivetran Hybrid Deployment exists to solve. You keep the managed control plane — the UI, scheduling, schema drift handling, connector maintenance — but the part that actually touches your data runs inside your own network, on infrastructure you own. This tutorial walks through what that architecture actually looks like, how to stand up the Local Data Processing Agent, and the operational details that are easy to miss until you are three weeks into a compliance review.
The architecture in one paragraph
In a standard Fivetran deployment, Fivetran's cloud connects directly to your source, pulls rows, and writes them to your destination. In Hybrid Deployment, you install a Local Data Processing Agent inside your network. The agent holds an outbound-only connection to the Fivetran control plane, receives sync instructions, and does all extraction, processing and loading itself. Source credentials, source rows and destination credentials stay inside your perimeter. What crosses the boundary is metadata: sync status, row counts, schema names, error messages, table and column names.
That last sentence is the one to bring to your security review. Column names leave; column values do not.
When it is worth it
Be honest about whether you need this. Hybrid Deployment adds infrastructure you must run, patch and monitor. It is worth it when:
- A regulator or contract requires that data never transit a third-party cloud.
- Sources sit in a private network and you have been refused a peering, VPN or reverse-tunnel exception for a vendor.
- Data residency rules mean processing must physically occur in a specific region.
- Your security team's objection is architectural rather than about a specific control.
It is not worth it if your only concern is encryption in transit, or if you simply want faster syncs. SaaS Fivetran with private networking (PrivateLink, VPC peering, SSH tunnels) solves most connectivity problems with far less to operate. Reach for Hybrid Deployment when the requirement is genuinely "the data plane must be ours."
What you need before you start
- A Kubernetes cluster (or a Docker host for smaller footprints) inside the network that can reach your sources and your destination.
- Outbound HTTPS (443) from the agent to Fivetran's control plane. No inbound ports. If anyone asks you to open a firewall hole into your VPC for this, something has been misunderstood.
- A container runtime and somewhere to pull images from — either public registries or an internal mirror if egress is locked down.
- Node sizing: start around 4 vCPU / 16 GB per agent node and scale from there. Memory is what you run out of first on wide tables and large batch loads.
- Persistent local storage for staging. Fivetran writes intermediate files during processing; give it real disk, not an overlay filesystem that vanishes on restart.
1. Create the agent in the Fivetran UI
In the Fivetran dashboard, go to Hybrid Deployment → Local Data Processing Agents → Create agent. Name it for the environment and region it serves, not for the team that asked for it — eu-prod-agent ages better than finance-agent.
Fivetran generates a one-time token and an installation script. The token authenticates this specific agent; treat it as a secret and put it into your normal secret manager immediately rather than leaving it in a terminal scrollback.
2. Install the agent
The generated script bootstraps the agent, but in any environment with change control you will want the manifest in your repository rather than a curl-to-bash. The shape of a Kubernetes install:
kubectl create namespace fivetran
kubectl create secret generic fivetran-agent-token \
--namespace fivetran \
--from-literal=token="$FIVETRAN_AGENT_TOKEN"
helm repo add fivetran https://fivetran.github.io/helm-charts
helm repo update
helm install ldp fivetran/hybrid-deployment-agent \
--namespace fivetran \
--set agent.tokenSecretName=fivetran-agent-token \
--set resources.requests.cpu=2 \
--set resources.requests.memory=8Gi \
--set resources.limits.memory=24Gi \
--set persistence.enabled=true \
--set persistence.size=200Gi
Check the current chart name and values against Fivetran's Hybrid Deployment documentation before you run this — the deployment surface has changed more than once since launch, and the docs are authoritative.
For a Docker host the equivalent is a single long-running container with the token in the environment and a bind-mounted staging volume. Same principles: no inbound ports, real disk, restart policy set to always.
Within a minute or two the agent should show as connected in the UI. If it does not, the cause is almost always egress filtering — an explicit proxy or an allowlist that does not yet include Fivetran's endpoints.
3. Point a destination at the agent
A destination in Hybrid Deployment is configured the same way as a SaaS destination, except that you select the agent that will serve it. Do this before creating connections; a connection inherits its processing location from the destination's group.
Destination → Snowflake
Host: acme-prod.eu-central-1.snowflakecomputing.com
Database: ANALYTICS
Auth: key pair
Processing location: Hybrid — eu-prod-agent
The credentials you enter here are stored and used locally by the agent. Verify that in your own review rather than taking it on faith: run the setup test, then watch the connection open from the agent's node, not from an external address, in your warehouse's login history.
-- Snowflake: confirm where the connection originated
select user_name, client_ip, first_authentication_factor, event_timestamp
from snowflake.account_usage.login_history
where user_name = 'FIVETRAN_USER'
order by event_timestamp desc
limit 20;
If client_ip is your NAT gateway rather than a vendor range, the data plane is where you think it is. That query is worth screenshotting for the compliance file.
4. Create connections as usual
From here the experience is ordinary Fivetran. Add a Postgres connection with logical replication, a Salesforce connection, an S3 connection — the connector catalogue for Hybrid Deployment is large but not identical to SaaS. Check that the specific connectors you need are supported in this deployment model before promising a timeline; discovering a gap after the infrastructure is approved is a bad week.
Setup mechanics are otherwise unchanged. Our Postgres CDC to Snowflake walkthrough applies verbatim — replication slots, publications and WAL retention behave the same whether the reader is Fivetran's cloud or your agent.
5. Terraform it
Do not leave a compliance-critical deployment as click-ops. The Fivetran Terraform provider covers hybrid destinations and connections; the agent itself belongs in whatever manages your cluster.
resource "fivetran_hybrid_deployment_agent" "eu_prod" {
display_name = "eu-prod-agent"
group_id = fivetran_group.eu_analytics.id
auth_type = "AUTO"
env_type = "KUBERNETES"
}
Then reference the agent from the destination so the processing location is explicit in code. Our Terraform provider tutorial covers importing an existing account without triggering accidental re-syncs — which matters doubly here, because a re-sync now consumes your compute as well as MAR.
6. Monitoring: you own more of the stack now
In SaaS Fivetran, if a sync is slow, it is Fivetran's problem. In Hybrid Deployment, slow syncs are often your node's problem. Watch three layers:
The agent. Standard Kubernetes signals — pod restarts, OOMKills, disk pressure on the staging volume. An agent that is quietly OOMKilling on one wide table looks, from the Fivetran UI, like a connection that keeps failing for no clear reason.
kubectl -n fivetran get pods -w
kubectl -n fivetran logs -l app=ldp-agent --tail=200
kubectl -n fivetran describe pod <pod> | grep -A5 "Last State"
The pipelines. Enable the Fivetran Platform Connector and query sync history in the warehouse rather than reading the UI every morning:
select
c.connector_name,
date_trunc('day', l.time_stamp) as day,
count(*) filter (where l.event = 'sync_end') as syncs,
count(*) filter (where l.event = 'sync_start') as starts,
max(l.time_stamp) as last_event
from fivetran_log.log l
join fivetran_log.connector c on c.connector_id = l.connector_id
where l.time_stamp > current_date - 7
group by 1, 2
order by 2 desc, 1;
The boundary. Alert on agent disconnection specifically. A disconnected agent does not fail loudly — syncs simply stop being scheduled, and stale dashboards are noticed by a stakeholder days later. Wire the connection_failure webhook and an agent-health check into the same channel your on-call actually reads.
The operational gotchas
Capacity is now a planning exercise. Concurrent syncs compete for the same node. Schedule your three largest historical loads to run at the same hour and you will find the ceiling immediately. Stagger heavy connections, and size for the peak rather than the average.
Upgrades are yours to run. The agent gets released regularly, with security patches among them. Decide now whether you auto-update or pin, put it in your patch cadence, and write it down. "We forgot to upgrade the agent for eleven months" is a finding.
Egress allowlists drift. A network change that tightens outbound rules can silently sever the agent. Include the Fivetran endpoints in whatever documentation your network team consults before changes.
Disk fills. Staging files for large loads are bigger than people expect. Alert at 70% on the staging volume, not 90% — by 90% a sync has already failed.
Cost is split. You still pay Fivetran MAR, and you now pay for the compute and storage running the agent. That is usually a fine trade for the compliance outcome, but the finance conversation goes better if you say it up front. Our connection-level MAR guide covers the Fivetran side of the bill.
A realistic rollout plan
- Week 1 — Stand up an agent in a non-production namespace. Connect one small, boring source. Prove the flow end to end.
- Week 2 — Run the security review with evidence: the login-history query, the firewall rules showing egress only, the list of metadata fields that leave the network.
- Week 3 — Move one real regulated source. Watch node metrics through the initial sync; this is where you learn your true sizing.
- Week 4 — Codify in Terraform, wire alerting, document the upgrade cadence and ownership.
- Then — Migrate remaining in-scope sources one at a time. Leave everything that is not in scope on SaaS Fivetran. A mixed estate is entirely normal and much cheaper to run.
The goal is not to move everything behind the perimeter. It is to move exactly what has to be there, prove it, and leave the rest managed.
If you are scoping a Hybrid Deployment for a regulated workload — sizing, the security review pack, or migrating existing connections without a full re-sync — our Fivetran platform setup and management and maintenance and support teams do this work regularly. Get in touch with the shape of your estate and constraints.