How to Set Up Hybrid Deployment Using the REST API

Use this tutorial to create a Hybrid Deployment Agent record via the API, retrieve the agent token to install the agent container, verify the agent is online, and then create a connection that routes through the agent.

You must have an Enterprise or Business Critical plan to use Hybrid Deployment.

Prerequisites

You have a scoped API key and secret.
You know the group_id of the destination group where you want to route connections through the agent.
You know which runtime environment you are deploying: DOCKER, PODMAN, or KUBERNETES.
You know the connector service you want to create.
You have jq installed.

Endpoints used in this workflow

POST /v1/hybrid-deployment-agents
GET /v1/hybrid-deployment-agents/{agentId}
POST /v1/connections

Instructions

Follow the steps below to set up a Hybrid Deployment Agent and then create connections using the agent.

Set your environment variables

Set up environment variables for REST API authentication, agent creation, and connection creation.

export FIVETRAN_API_KEY="<your_api_key>"
export FIVETRAN_API_SECRET="<your_api_secret>"
export FIVETRAN_BASE_URL="https://api.fivetran.com/v1"
export FIVETRAN_AUTH_HEADER=$(printf "%s" "$FIVETRAN_API_KEY:$FIVETRAN_API_SECRET" | base64 | tr -d '\n')

# Required for agent creation.
export GROUP_ID="<your_group_id>"
export AGENT_DISPLAY_NAME="<your_agent_display_name>"
export AGENT_ENV_TYPE="DOCKER"   # Possible values: DOCKER, PODMAN, KUBERNETES

# Required for connection creation.
export CONNECTION_SERVICE="<your_connection_service>"
# Example of connection service: postgres_rds

Create Hybrid Deployment Agent

Use the Create a Hybrid Deployment Agent endpoint to create the agent:

CREATE_AGENT_RESPONSE=$(curl --silent --show-error \
  --request POST \
  --url "$FIVETRAN_BASE_URL/hybrid-deployment-agents" \
  --header "Accept: application/json" \
  --header "Authorization: Basic $FIVETRAN_AUTH_HEADER" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{
  "group_id": "$GROUP_ID",
  "display_name": "$AGENT_DISPLAY_NAME",
  "env_type": "$AGENT_ENV_TYPE",
  "accept_terms": true
}
JSON
)

echo "$CREATE_AGENT_RESPONSE"
export AGENT_ID=$(echo "$CREATE_AGENT_RESPONSE" | jq -r '.data.id')
export AGENT_TOKEN=$(echo "$CREATE_AGENT_RESPONSE" | jq -r '.data.token')
echo "AGENT_ID=$AGENT_ID"
echo "AGENT_TOKEN=$AGENT_TOKEN"

The response includes:

data.id — The agent ID, used in subsequent API calls and stored as AGENT_ID.
data.token — A Base64-encoded token used to register the agent container, stored as AGENT_TOKEN. This token is only returned once. Store it securely before proceeding. If you lose it before completing the container installation, use the Re-Authenticate Hybrid Deployment Agent endpoint to obtain a new token.
data.files — Base64-encoded config.json, auth.json, and docker-compose.yaml files for Docker-based installations.

The script in this tutorial prints the agent token to stdout. For production deployments, redirect the API response to a file with restricted permissions or store the token in a secrets manager. To rotate the token, use the Re-Authenticate Hybrid Deployment Agent endpoint.

Install agent container

Use the AGENT_TOKEN from the previous step to install and start the agent on your host.

Use the token value from the response to install the agent container. Follow the setup guide for your runtime:

Hybrid Deployment with Docker — Start from the Install agent step.
Hybrid Deployment with Kubernetes — Start from the Install and start agent step.
Hybrid Deployment with Podman — Start from the Install agent step.

Verify agent is online

Use the Retrieve Hybrid Deployment Agent Details endpoint. - Poll until online is true before creating connections. Creating a connection before the agent is online may result in setup test failures because the agent cannot yet proxy traffic.

for i in {1..30}; do
  AGENT_STATUS_RESPONSE=$(curl --silent --show-error \
    --request GET \
    --url "$FIVETRAN_BASE_URL/hybrid-deployment-agents/$AGENT_ID" \
    --header "Accept: application/json" \
    --header "Authorization: Basic $FIVETRAN_AUTH_HEADER")

  AGENT_ONLINE=$(echo "$AGENT_STATUS_RESPONSE" | jq -r '.data.online')
  AGENT_ENABLED=$(echo "$AGENT_STATUS_RESPONSE" | jq -r '.data.enabled')

  echo "Attempt $i: online=$AGENT_ONLINE enabled=$AGENT_ENABLED"

  if [ "$AGENT_ONLINE" = "true" ]; then
    break
  fi

  sleep 10
done

Response fields

data.online — true when the agent process has established a connection to Fivetran cloud. Proceed only when this is true.
data.enabled — true when the agent is enabled for routing traffic.

Create connection using agent

Use the Create a Connection endpoint. Pass hybrid_deployment_agent_id to create and route the connection through the agent. If you do not specify hybrid_deployment_agent_id for the connection, Fivetran falls back to the agent configured on the destination. To override this, always supply hybrid_deployment_agent_id explicitly.

CREATE_CONNECTION_RESPONSE=$(curl --silent --show-error \
  --request POST \
  --url "$FIVETRAN_BASE_URL/connections" \
  --header "Accept: application/json" \
  --header "Authorization: Basic $FIVETRAN_AUTH_HEADER" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{
  "service": "$CONNECTION_SERVICE",
  "group_id": "$GROUP_ID",
  "paused": true,
  "hybrid_deployment_agent_id": "$AGENT_ID",
  "config": {
    "host": "<connector_host>",
    "port": "<connector_port>",
    "database": "<connector_database>",
    "user": "<connector_user>",
    "password": "<connector_password>"
  }
}
JSON
)

echo "$CREATE_CONNECTION_RESPONSE"
export CONNECTION_ID=$(echo "$CREATE_CONNECTION_RESPONSE" | jq -r '.data.id')
echo "CONNECTION_ID=$CONNECTION_ID"

The config object in the Create a connection using the agent step is connector-specific. Use the schema in Create a Connection for your selected connector service.