When Should I Use Custom Root Certificates for Hybrid Deployment, and How Do I Configure Them?

Question

When should I use custom root certificates for Hybrid Deployment, and how do I configure them?

Environment

Container platform: Docker, Podman, and Kubernetes

Answer

Use custom root certificates when your environment intercepts or inspects outbound SSL/TLS traffic using internal or non-standard certificate authorities (CAs). This ensures secure communication between the agent and Fivetran services in compliance with your organization’s security policies.

Common use cases

• SSL inspection by corporate firewalls: If your network performs SSL inspection or interception, provide the root CA certificate used by your firewall or proxy so the agent can trust the intercepted SSL/TLS connections.
• Private PKI or internal trust chains: If your organization uses internal certificate authorities, configure the agent to trust these CAs by supplying their root certificates.
• Zero-trust architectures: In environments where all network communication is explicitly validated, use custom root certificates to ensure secure and policy-compliant communication with Fivetran services.

When to configure custom root certificates

If the agent encounters SSL handshake errors (for example: javax.net.ssl.SSLHandshakeException: unable to find valid certification path to requested target), you likely need to configure custom trusted root certificates.

Fivetran Hybrid Deployment supports these certificates for environments that inspect or block SSL/TLS traffic unless it is signed by an internal CA.

Where custom root certificates apply

The agent uses custom root certificates in two key communication paths:

• Orchestrator connections: Secure communication between the agent and orchestrator, including job execution.
• Fivetran API communication: Authentication and interaction between the agent and Fivetran API.

Certificates must be in PEM format (Base64 encoded), and you can specify multiple certificates to support full trust chains.

Configuration examples

Docker and Podman**

Add the trusted_root_ca_certs field to your config.json file:

{
  "trusted_root_ca_certs": [
    "-----BEGIN CERTIFICATE-----\nMIIEyzCCA7OgAwIBAgIJAP6a00mzN8gtMA0GCSqGSIb3DQEBCwUAMCIxIDAeBgNV...\n-----END CERTIFICATE-----",
    "-----BEGIN CERTIFICATE-----\nMIID...another_custom_root_cert...\n-----END CERTIFICATE-----"
  ]
}

Kubernetes

Add the trusted_root_ca_certs field to your values.yaml file:

trusted_root_ca_certs: |
  '[
    "-----BEGIN CERTIFICATE-----\nMIIEyzCCA7OgAwIBAgIJAP6a00mzN8gtMA0GCSqGSIb3DQEBCwUAMCIxIDAeBgNV...\n-----END CERTIFICATE-----",
    "-----BEGIN CERTIFICATE-----\nMIID...another_custom_root_cert......\n-----END CERTIFICATE-----"
  ]'