Private Cloud Connector

The Private Cloud Connector is an on-premises connector, which you can run as a Docker container or deploy to Kubernetes via Helm. The connector acts as a secure reverse tunnel between the data behind your company’s firewall, private network, or Virtual Private Cloud (VPC) and the Connect AI cloud-based services. It allows Connect AI to access your data without exposing your data directly to the internet.

You then register each connector in the Connect AI user interface, within the individual connection setup. You can have connectors in multiple locations. You must register a connector in Connect AI for each location. The Private Cloud Connector provides high availability by supporting multiple connector instances—either multiple Docker containers, or replicas in a Kubernetes deployment—pointing to the same location and account Id. If one instance goes down, requests are automatically routed to the remaining connector instances. The following diagram shows how Private Cloud Connector supports multiple locations and multiple data sources.

Private Cloud Connector Architecture Advanced

The following is a list of some of the connectors that Connect AI supports with the Private Cloud Connector:

Contact CData Support if you need a different connector with the Private Cloud Connector. Setting up the Private Cloud Connector involves three main steps:

Install and run the connector in each location where your on-premises data is located. You can either deploy the Private Cloud Connector with Docker or deploy the Private Cloud Connector on Kubernetes.

Finish the Private Cloud Connector setup in Connect AI to test the connector and complete the connection.

Register the Private Cloud Connector in Connect AI

To register the Private Cloud Connector in Connect AI:

Go to Sources and click Add Connection for a new connection, or edit an existing connection.

Click the Private Cloud Connector tab in the Add/Edit Connection page.

In Connectors, click Add. The Add Connector dialog appears.

Enter a descriptive location name to identify where the connector is installed, and click Confirm.Your location appears in the Connectors list, along with a key and a Pending status. Click the eye icon to view the key.

You must copy the following values for the connector (click the copy icons):

Account Id–this is the ACCOUNT_ID environment variable for the connector.
Location Id–this is the GATEWAY_LOCATION_ID environment variable for the connector.
Key–this is the GATEWAY_API_KEY environment variable for the connector.

Deploy the Private Cloud Connector with Docker

The Private Cloud Connector is a lightweight service that runs inside your network and acts as a secure reverse tunnel between Connect AI and your local data sources. The connector registers itself with Connect AI on startup. It then listens for incoming connections, via Azure Relay technology, without ever exposing them to the public internet. The connector is protocol-agnostic: it forwards raw bytes without any knowledge of the database protocol (such as MySQL, PostgreSQL, or SQL Server), making it compatible with any TCP-based data source.

Prerequisites

To run the Private Cloud Connector as a Docker container, you must have the following:

Docker installed on the host machine.
Network access to cloud.cdata.com.
The connector created in Connect AI.
Host IP forwarding (net.ipv4.ip_forward=1) enabled. Docker requires this for container outbound connectivity; note that OS patching and security-hardening baselines (CIS/STIG) may reset it to 0.
Egress TLS inspection must be bypassed for *.servicebus.windows.net, *.azurecr.io, and *.cdata.com. SSL inspection on these endpoints will prevent the connector relay tunnel from establishing.

Environment Variables

The following environment variables are required to run the connector:

Variable	Description
GATEWAY_LOCATION_ID	The unique identifier for this connector instance. Copy the value under the user-defined Location Name in the Connectors list in Connect AI.
GATEWAY_API_KEY	The secret API key used to authenticate this connector with Connect AI. Copy the value under Key in the Connectors list in Connect AI.
ACCOUNT_ID	Your CData Connect AI account identifier. This is specific to your organization. Copy Account Id in the Connectors list in Connect AI.

Run the Connector in Docker

Run the connector as follows:

docker run \
    --name my-onprem-gateway \
    -e GATEWAY_LOCATION_ID=<gateway_location_id> \
    -e GATEWAY_API_KEY=<gateway_api_key> \
    -e ACCOUNT_ID=<account_id> \
    connectaipublic.azurecr.io/connectgateway:latest

docker run will pull the Docker image from the registry if it is not already present on the host.

View Docker Logs

docker logs -f my-onprem-gateway

Stop the Connector

docker stop my-onprem-gateway
docker rm my-onprem-gateway

Docker Compose

Copy the following and save as docker-compose.yml:

version: "3.8"

services:
  onprem-gateway:
    image: connectaipublic.azurecr.io/connectgateway:latest
    container_name: my-onprem-gateway
    restart: unless-stopped
    environment:
      GATEWAY_LOCATION_ID: <gateway_location_id>
      GATEWAY_API_KEY: <gateway_api_key>
      ACCOUNT_ID: <account_id>

Start the Private Cloud Connector

docker compose up

docker compose up will pull the Docker image from the registry if it is not already present on the host.

View Logs

docker compose logs -f

Stop the Private Cloud Connector

docker compose down

Deploy the Private Cloud Connector on Kubernetes

The Private Cloud Connector Kubernetes Helm chart is available in a GitHub repository.

Prerequisites

To deploy the Private Cloud Connector on Kubernetes, you must have the following:

Kubernetes 1.25 or later
Helm 3.10 or later
Metrics Server installed on your cluster (required for memory-based autoscaling)
Network egress from the cluster to cloud.cdata.com
Egress TLS inspection must be bypassed for *.servicebus.windows.net, *.azurecr.io, and *.cdata.com. SSL inspection on these endpoints will prevent the connector relay tunnel from establishing.
Your Account Id, Location Id, and Key from Connect AI. See Register the Private Cloud Connector in Connect AI for the location of these values.

Quick Start

Add the Helm repository:

helm repo add cdata https://cdatasoftware.github.io/connect-gateway-helm
helm repo update

Install the chart:

helm install connect-gateway cdata/connect-gateway \
  --set gateway.locationId=<location-id> \
  --set gateway.accountId=<account-id> \
  --set gateway.apiKey=<api-key> \
  -n connect-gateway --create-namespace

You can also install directly from a GitHub release. This is useful for air-gapped environments or when you do not want to add a Helm repo. Replace the version in the URL below with the latest release.

helm install connect-gateway \
  https://github.com/CDataSoftware/connect-gateway-helm/releases/download/v1.0.0/connect-gateway-1.0.0.tgz \
  --set gateway.locationId=<location-id> \
  --set gateway.accountId=<account-id> \
  --set gateway.apiKey=<api-key> \
  -n connect-gateway --create-namespace

For production, create a Kubernetes Secret containing your gateway credentials and pass --set existingSecret=<secret-name> instead of --set gateway.apiKey=…. Passing the API key with --set writes it to shell history and to the Helm release’s stored values. See the Helm chart Readme file for secret-management patterns.

Verify the Private Cloud Connector is Running

Check that the connector pods are ready and view their logs:

kubectl get pods -n connect-gateway
kubectl logs -n connect-gateway -l app.kubernetes.io/name=connect-gateway -f

Upgrade the Private Cloud Connector

helm repo update
helm upgrade connect-gateway cdata/connect-gateway -n connect-gateway

Uninstall the Private Cloud Connector

helm uninstall connect-gateway -n connect-gateway

Refer to the Helm chart Readme file for the full list of installation options, configuration values, and secret-management patterns.

Finish Private Cloud Connector Setup

Return to Connect AI and finish the Private Cloud Connector setup.

After you complete the steps to deploy the Private Cloud Connector with Docker or deploy the Private Cloud Connector on Kubernetes, you can test the connectors you added to Connectors. Click the Private Cloud Connector tab of the Add/Edit Connection page. Click Test Connectors. The Status turns to Success if all connector setup is complete.

You still must click Save & Test to test the entire connection.

Return to the Basic Settings tab of your connection. Under Connection Type, select Private Cloud Connector.

Select the Private Cloud Connector location to use from the drop-down list.

Enter the Authentication instructions for the connector according to the connector’s Documentation pane.

Click Save & Test to authenticate your connector.

Getting Started

Data Sources

Explore and Model

MCP/Data Integrations

LLM Integrations

AI

Security and Governance

Virtual Databases

Operations

Private Cloud Connector

Register the Private Cloud Connector in Connect AI

Deploy the Private Cloud Connector with Docker

Prerequisites

Environment Variables

Run the Connector in Docker

View Docker Logs

Stop the Connector

Docker Compose

Start the Private Cloud Connector

View Logs

Stop the Private Cloud Connector

Deploy the Private Cloud Connector on Kubernetes

Prerequisites

Quick Start

Verify the Private Cloud Connector is Running

Upgrade the Private Cloud Connector

Uninstall the Private Cloud Connector

Finish Private Cloud Connector Setup

​Register the Private Cloud Connector in Connect AI

​Deploy the Private Cloud Connector with Docker

​Prerequisites

​Environment Variables

​Run the Connector in Docker

​View Docker Logs

​Stop the Connector

​Docker Compose

​Start the Private Cloud Connector

​View Logs

​Stop the Private Cloud Connector

​Deploy the Private Cloud Connector on Kubernetes

​Prerequisites

​Quick Start

​Verify the Private Cloud Connector is Running

​Upgrade the Private Cloud Connector

​Uninstall the Private Cloud Connector

​Finish Private Cloud Connector Setup

Register the Private Cloud Connector in Connect AI

Deploy the Private Cloud Connector with Docker

Prerequisites

Environment Variables

Run the Connector in Docker

View Docker Logs

Stop the Connector

Docker Compose

Start the Private Cloud Connector

View Logs

Stop the Private Cloud Connector

Deploy the Private Cloud Connector on Kubernetes

Prerequisites

Quick Start

Verify the Private Cloud Connector is Running

Upgrade the Private Cloud Connector

Uninstall the Private Cloud Connector

Finish Private Cloud Connector Setup