Installing a Tulip On-Premise Connector Host

What are the network requirements for hosting an on-premise Connector Host?

The on-premise Connector Host has the following networking requirements:

• An IP address

• DNS resolution to <your-account>.tulip.co

• Outbound access on port 443 from the Connector Host to Tulip. IP addresses to whitelist are available in this article: Networking Requirements for a Tulip Deployment

• Outbound access to the Docker repository at bckca2dh98.execute-api.us-east-1.amazonaws.com

• Outbound access to all systems to be used in Connectors over the relevant ports for the external service (default ports listed above).

Note that no inbound access (from the internet to the Connector Host) is required. The Connector Host initiates all connections to the Tulip Cloud.

How is the on-premise Connector Host distributed?

The on-premise Connector Host is distributed as a Docker container that can be deployed in any of the following locations:

• A customer-provided host (computer, virtual machine, or cloud container service like AWS's ECS or Azure's Container Instances Service) with the ability to host a Docker container. This host should enable log rotations by default following the recommendations in this article from Docker.

• A Tulip-provided VM (.ova format exported from Virtualbox) hosting a Docker container

In both deployment scenarios, it is the responsibility of the customer to monitor and update the container and its host machine using the provided documentation.

The recommended system requirements for this container are:

• 8GB disk space

• 4GB RAM

• 2 vCPU or equivalent

You should monitor the resource usage of your Connector Host. You may need to allocate more resources if you're using the machine monitoring features to consume hundreds of data points per second via OPC UA, or executing hundreds of requests per second using the HTTP or SQL connectors. This is not needed for most customers.

Alerts for virtual machine vitals should be set up. Our suggestions are to monitor the CPU usage, RAM usage, Disk utilization, and Network usage as percentages of the total resource available.

We do not distribute the Connector Host without a meeting between yourself as the customer, your Tulip representative, and the Tulip support team. If you are interested in an on-premise Connector Host, please contact your Tulip representative.

Administration of the Connector Host

Administrators should be familiar with basic Docker concepts and the Docker Command Line Interface. A container can be created with the following command:

$ docker run -d \
    --name tulip-connector-host \
    -e TULIP_FACTORY='https://<FACTORY>.tulip.co' \
    -e TULIP_UUID='<UUID>' \
    -e TULIP_MACHINE_SECRET='<SECRET>' \
    -e TULIP_DEVICE_TYPE='onprem' \
    -e HTTP_PROXY='' \
    -e HTTPS_PROXY='' \
    -e EXIT_ON_DISCONNECT=true \
    --restart=unless-stopped \
    --net=host \
    --mount type=volume,source=tuliplog,target=/log \
    bckca2dh98.execute-api.us-east-1.amazonaws.com/public/connector-host:prod

where the values in < >'s will be provided by your Tulip Account Manager.

If you have an HTTP or HTTPS Web Proxy you would like to route all web traffic through, specify that with the HTTP_PROXY and HTTPS_PROXY environment variables, respectively.

Note that if using Docker on Windows, the single quotes in the above command must be removed.

Any name can be provided to the --name option to make it easy to refer to this container later. A proxy to be used for the Connector Host to Tulip Cloud connection can be passed in the command as well.

Log rotation

To enable log rotations for docker running on Linux, run the following set of commands before creating a new docker container. This needs to be done once per machine and will apply to all containers launched after log rotations are enabled.

$ sudo su
$ touch /etc/docker/daemon.json

$ cat > /etc/docker/daemon.json <<EOF
> {
>   "live-restore": true,
>   "log-driver": "json-file",
>   "log-opts": {
>     "max-size": "10m",
>     "max-file": "3"
>   }
> }
> EOF

Restart docker service for these changes to take effect

$ sudo systemctl start docker

View Logs

To view logs for the connector, run:

$ docker logs tulip-connector-host

Update Connector Host

To update your Tulip Connector Host, run the following commands to pull the new image and then restart the docker container:

$ docker pull bckca2dh98.execute-api.us-east-1.amazonaws.com/public/connector-host:prod
$ docker restart tulip-connector-host