Hybrid Deployment with Kubernetes Setup Guide

Follow our setup guide to set up the Hybrid Deployment model with Kubernetes.

Prerequisites

To use Hybrid Deployment with Kubernetes, ensure your environment meets the requirements outlined in the following sections.

Software requirements

Kubernetes v1.29.x or above.
Helm CLI (v3.16.1 or above) to deploy the Hybrid Deployment Agent Helm chart.
Any on-premises Kubernetes service or one of the following cloud-based Kubernetes services:
We do not support AWS Fargate for Hybrid Deployment.

System requirements

The compute (CPU), memory (RAM), and storage requirements for your environment depend on the number of concurrent pipeline processes and the volume of data to sync. Before reviewing the table below, see our Sizing guidelines for detailed guidance on how to estimate resources based on connection type and deployment scale.

The following table provides the minimum CPU and RAM requirements, along with estimated storage requirements, based on the number of concurrent connections running on the same host:

Deployment Size	Number of Connections	vCPUs (x86-64)	RAM	Estimated Disk Space
Small	1-2	8	32 GB	More than 50 GB
Medium	2-6	8-16	32 GB	More than 300 GB
Large	6-12	16-24	64 GB	More than 500 GB

If you want to use more than 12 connections, we recommend distributing the load across multiple Medium or Large deployments.

The default memory allocation for the pipeline processing jobs is 4 GB, where the Java heap size uses 70% of the total allocated memory. However, you can increase the memory allocation based on your requirements. For connections with complex schemas and large datasets, we recommend allocating 8 GB. You can increase the memory allocation by modifying the values of the agent configuration parameters.
The disk space required depends on your data volume. In Kubernetes, the nodes share the available disk space.

Kubernetes requirements

A Persistent Volume Claim (PVC) with ReadWriteMany access mode. To create a PVC, you need a Storage Class and Persistent Volume with appropriate permissions. For more information, see your cloud service providers' documentation. For more information about checking the status of your PVC, see our FAQ documentation.
(Optional) A dedicated namespace for your deployment. If you do not have a dedicated namespace, we will use the default namespace. You can only run one agent per namespace.

Network requirements

Reliable connectivity between the cluster, source, and destination.
Outbound connectivity to the following external IP addresses and services:
- mTLS connection to the Fivetran Orchestration Service: 35.188.225.82 - ldp.orchestrator.fivetran.com
- HTTPS with secure token to Fivetran Public API: 35.236.237.87 - api.fivetran.com
- Google Artifact Registry - us-docker.pkg.dev (Google address range: 142.250.0.0 - 142.251.255.255)
- Logs used by the Fivetran Platform Connector - storage.googleapis.com/fivetran-metrics-log-sr

If your firewall supports it, we recommend using domain hostnames instead of IP ranges to restrict outbound connections.

Setup instructions

Create agent

Log in to your Fivetran account.
Go to the Destinations page and click Add destination.
Select your destination type.
Enter a Destination name of your choice.
Click Add.
In the destination setup form, choose Hybrid Deployment as your deployment model.
Click + Configure new agent.
In the Configure a new agent pane, read the Fivetran On-Prem Software License Addendum, and select the I have read and agree to the terms of the License Addendum and the Software Specific Requirements checkbox.
Click Next.
Choose Kubernetes as the environment for your deployment.
Click Next.
Enter an Agent name.
Click Generate agent token to generate the token and installation command for your agent.
Each Hybrid Deployment Agent has a unique token and installation command.
Make a note of the agent token. You will need it to install and start the agent.
Copy the installation command and paste it in a separate file where you can edit it, and then make the following changes to the command:
- (Optional) Replace the default deployment name (hd-agent) with a name of your choice.
- (Optional) Replace the default deployment namespace (default) with the namespace you want to use for your agent.
- Set the value of the data_volume_pvc parameter to your Persistent Volume Claim name. By default, this parameter contains a dummy value (VOL_CLAIM_HERE).
- Update the Helm chart version by replacing the default value of version (0.7.0) with a version that meets your requirements. For more information about the latest version, see the latest releases.
Make a note of the updated command. You will need it to install and start the agent.
Go back to the Fivetran dashboard and click Save.

You must install and start the agent before completing the destination setup.

Install and start agent

Log into the environment where kubectl and Helm is configured to connect to your Kubernetes cluster.
You can test the connectivity to your cluster using kubectl cluster-info and helm list --all-namespaces.
Run the agent installation command to install the Helm chart and start the agent.
You must run the command with the changes you made and not the default command that you copied from the Fivetran dashboard.
Example:
```
$ helm upgrade --install hd-agent \
 oci://us-docker.pkg.dev/prod-eng-fivetran-ldp/public-docker-us/helm/hybrid-deployment-agent \
 --create-namespace \
 --namespace default \
 --set config.data_volume_pvc=VOL_CLAIM_HERE \
 --set config.token="YOUR_TOKEN_HERE" \
 --set config.namespace=default \
 --version 0.11.0
```
The installation command does the following:
- Creates a ConfigMap with the agent configurations
- Creates the necessary service account, role, and role bindings
- Deploys the Hybrid Deployment Agent Pod, which pulls the latest agent container image
For more information about the Helm chart, see our GitHub repository.
Verify whether the agent is up and running.
- Run the following commands to verify the agent status:
```
kubectl get deployments -n <namespace>
kubectl get pods -n <namespace>
```
- Run either of the following commands to verify the agent log:
```
kubectl logs -l app.kubernetes.io/name=<deployment_name> -n <namespace>
```
  or
```
kubectl logs pod/<pod_name> --follow -n <namespace>
```
Once the agent is deployed, you can go to the Fivetran dashboard and view the agent details and status in Account Settings > General > Hybrid Deployment Agents.
You can use helm list -a to view the list of all Helm charts installed in your environment and helm uninstall <deployment_name> --namespace <namespace> to uninstall a Helm chart.

Agent configuration parameters

The following are the mandatory agent configuration parameters:

Deployment name
Namespace
Persistent Volume Claim name
Agent token
Helm chart version

You can set the configuration parameters as command line options using the --set command. For example:

  $ helm upgrade --install hd-agent \
  oci://us-docker.pkg.dev/prod-eng-fivetran-ldp/public-docker-us/helm/hybrid-deployment-agent \
  --create-namespace \
  --namespace default \
  --set config.data_volume_pvc=VOL_CLAIM_HERE \
  --set config.token="YOUR_TOKEN_HERE" \
  --set config.namespace=default \
  --version 0.11.0

Advanced users can also use a values.yaml file to set these parameters. We recommend using the values.yaml file for complex configurations, such as when using Node Selector or Node Affinity rules.

For example:

config:
  namespace: fivetran
  data_volume_pvc: VOL_CLAIM_HERE
  token: YOUR_TOKEN_HERE

agent:
  image: "us-docker.pkg.dev/prod-eng-fivetran-ldp/public-docker-us/ldp-agent:production"
  image_pull_policy: "Always"

Deploy the agent using the following command:

  $ helm upgrade --install hd-agent \
  oci://us-docker.pkg.dev/prod-eng-fivetran-ldp/public-docker-us/helm/hybrid-deployment-agent \
  --create-namespace \
  --namespace fivetran \
  -f values.yaml \
  --version 0.11.0

The above example of a values.yaml file contains the default agent container resources also.
If required, you can specify additional labels or node selection options in the values.yaml file.
You must specify the agent configuration parameters and their values only in the config section of the values.yaml file.

The configuration options supported by the agent in Kubernetes along with their default values are listed in the table below. You must specify these parameters only in the config section of the values.yaml file. The ConfigMap created by the Helm chart during the agent installation will by default contain all the configuration parameters you specify in the values.yaml file.

Parameter	Default Value	Description
affinity_rules	null (no value)	Defines the node affinity criteria for each rule. These settings control which nodes the corresponding connections can run on. For more information, see our FAQ documentation.
cleanup_jobs_interval_seconds	60	Job cleanup interval in seconds.
connector_pvc_integrations_your-integration-id	null(no value)	Specifies a custom Persistent Volume Claim (PVC) for a specific connector. Replace `your-integration-id` with your actual connector ID. When specified, jobs for that connector will use this PVC instead of the default `data_volume_pvc`. For more information, see our FAQ documentation.
donkey_container_cpu_limit	unlimited	CPU limit for pipeline processing job.
donkey_container_cpu_limit_integrations_your-integration-id	unlimited	CPU limit for pipeline processing job per integration.
donkey_container_cpu_request	2	CPU request for pipeline processing job.
donkey_container_max_cpu_limit (Discontinued)	unlimited	Maximum CPU limit for pipeline processing job.
donkey_container_max_memory_limit (Discontinued)	4Gi	Maximum memory limit for pipeline processing job.
donkey_container_memory_limit	4Gi	Memory limit for pipeline processing job.
donkey_container_memory_limit_integrations_your-integration-id	4Gi	Memory limit for pipeline processing job per integration.
donkey_container_memory_request	4Gi	Memory request for pipeline processing job.
donkey_container_min_cpu_request (Discontinued)	2	Minimum CPU request for pipeline processing job.
donkey_container_min_memory_request (Discontinued)	4Gi	Minimum memory request for pipeline processing job.
http_proxy	null (no value)	Enables proxy server connection with the proxy server host address for HTTP connections. For example: `http://proxy.local:3128`
https_proxy	null (no value)	Enables proxy server connection with the proxy server host address for HTTPS connections. For example: `http://proxy.local:3128`
no_proxy	null (no value)	Disables proxy server connection for specified hosts. For example: `localhost,gateway`
hva_container_cpu_limit	unlimited	CPU limit for HVA sidecar.
hva_container_cpu_request	2	CPU request for HVA sidecar.
hva_container_max_cpu_limit (Discontinued)	unlimited	Maximum CPU limit for HVA sidecar.
hva_container_max_memory_limit (Discontinued)	4Gi	Maximum memory limit for HVA sidecar.
hva_container_memory_limit	4Gi	Memory limit for HVA sidecar.
hva_container_memory_request	4Gi	Memory request for HVA sidecar.
hva_container_min_cpu_request (Discontinued)	2	Minimum CPU request for HVA sidecar.
hva_container_min_memory_request (Discontinued)	4Gi	Minimum memory request for HVA sidecar.
kubernetes_affinity	null (no value)	Defines a list of `affinity_rules` that associate connection IDs with scheduling rules. For more information, see our FAQ documentation.
kubernetes_agent_deployment_name	hd-agent	Deployment name of the Hybrid Deployment Agent. The deployment name overrides the Helm chart release name, allowing you to assign a specific name to the agent deployment.
kubernetes_node_selector_custom_selector	null (no value)	Allows you to schedule a pod on a specific node sharing the same set of labels by using a list of `key:value` values. For more information, see our FAQ documentation.
kubernetes_node_selector_enable	false	Enables Kubernetes Node Selector for Hybrid Deployment pipeline processing jobs. You cannot use it with `kubernetes_affinity`. For more information, see our FAQ documentation.
kubernetes_node_selector_include_role	false	Optionally includes the additional node selector `fivetran.role=job` on pipeline processing job pods. For more information, see our FAQ documentation.
pending_pod_status_check_max_interval_seconds	300	Poll interval used for checking pod in the pending state.
standard_config_container_cpu_limit	unlimited	CPU limit for getting schema (standard configuration) job.
standard_config_container_cpu_request	2	CPU request for getting schema (standard configuration) job
standard_config_container_max_cpu_limit (Discontinued)	unlimited	Maximum CPU limit for getting schema (standard configuration) job.
standard_config_container_max_memory_limit (Discontinued)	4Gi	Maximum memory limit for getting schema (standard configuration) job.
standard_config_container_memory_limit	4Gi	Memory limit for getting schema (standard configuration) job.
standard_config_container_memory_request	4Gi	Memory request for getting schema (standard configuration) job.
standard_config_container_min_cpu_request (Discontinued)	2	Minimum CPU request for getting schema (standard configuration) job
standard_config_container_min_memory_request (Discontinued)	4Gi	Minimum memory request for getting schema (standard configuration) job.
test_runner_container_cpu_limit	unlimited	CPU limit for connectivity test job.
test_runner_container_cpu_request	2	CPU request for connectivity test job.
test_runner_container_max_cpu_limit (Discontinued)	unlimited	Maximum CPU limit for connectivity test job.
test_runner_container_max_memory_limit (Discontinued)	4Gi	Maximum memory limit for connectivity test job.
test_runner_container_memory_limit	4Gi	Memory limit for connectivity test job.
test_runner_container_memory_request	4Gi	Memory request for connectivity test job.
test_runner_container_min_cpu_request (Discontinued)	2	Minimum CPU request for connectivity test job.
test_runner_container_min_memory_request (Discontinued)	4Gi	Minimum memory request for connectivity test job.
token	your-agent-token	The agent token that appears on the Fivetran dashboard.
token_secret_name	null (no value)	Name of the existing secret you want to use for the agent token. Use this parameter if you want the agent token to use a secret that already exists in your Kubernetes cluster. You cannot use both the `token` and `token_secret_name` parameters at the same time.
token_secret_key	token	The secret key you want to assign to the agent token. Use this parameter if you want the agent token to use a secret that already exists in your Kubernetes cluster. You cannot use both the `token` and `token_secret_key` parameters at the same time.

Hybrid Deployment Overview

Hybrid Deployment FAQ

Documentation Home