cloudelements-petit

Cloud Elements Ground2Cloud

This is the Cloud Elements Ground2Cloud Remote Connector (a.k.a. 'Petit', after Phillipe Petit, a.k.a. 'Tightrope', a.k.a. 'Elements Connect'), which is used to allow a private backend service to expose itself to the Cloud Elements product.

Documentation on the Ground2Cloud configuration file, by default ~/.petit/config.toml can be found here. You can use the petit-client init or petit-server init (see below) to create this file.

Background

Most CE elements connect to "backend services" to operate. These customer-run services are either publically available via the internet, or co-located on the same private cloud deployment. However, some customers rightly wish to allow CE to access their services, while they want or need more stringent restrictions on everyone else. This is especially true when the services in question are located on end-user personal or business computers, and are generally not hosted environments.

In the past, the options for these customers were limited to:

• keeping an up-to-date IP-based access whitelist
• installing a full CE private cloud deployment
• maintaining some sort of expensive and/or intrusive VPN setup

The Cloud Elements On-Prem Connector was created to solve this problem; it allows individual service providers to quickly and easily expose their service (and only their service) to elements that are located on the public cloud.

How It Works

The Cloud Elements On-Prem Connector comes in two parts: a server that runs on the CE public cloud, and a client that runs on the backend service machine or subnet. The client application registers itself with the server, and then opens a reverse proxy tunnel from the server machine to its host environment. As long as the client is running, public elements on the server environment will be able to access the target service on the client machine as if they were co-located.

Communication along the tunnel is protected by a TLS layer, so all chatter between the endpoints is secured. The connector implements a robust protocol for registration and selection, so all clients connect to all elements--and only those elements--which are destined for that customer.

Installation and Maintenance

The Cloud Elements On-Prem Connector is executed and distributed using the Node.js runtime environment. To expose a customer service, you will need to download and install Node on the client machine.

Note: The node version should be greater or equal to 10 node>=10

Once Node is installed, you can use the "Node Package Manager" (npm) to install the On-Prep Connector package. Run the following command with root or administrator privilege:

# npm install -g cloudelements-petit

You can keep the client up-to-date at any time using npm as well:

# npm update -g cloudelements-petit

Installation with Docker

You can use docker to create a node-based container, without having node installed on the host.

$ docker-compose build && docker-compose up

Currently, when using Ctrl-C to exit docker-compose, it does not shutdown cleanly, leaving a lock file in the container. If this happens, you need to run $ docker-compose up --force-recreate to start up the server again.

To avoid this issue entirely, don't use Ctrl-C to exit docker-compose; instead, issue a STOP command to the server:

$ echo -ne "STOP\x03" | nc <host> 3016

On linux, host is the actual host machine (i.e. localhost). When running on a MacOS, the host is the VirtualBox machine on which the Docker service runs. It's usually something like 192.168.99.100. Run docker-machine ls to find the actual IP.

Running the Client

Once installed, you can run petit-client commands to control the client process. For example, you can initialize the client like this (you don't need administrator privilege to run petit-client commands):

$ petit-client init

This command creates a default ~/.petit/config.toml configuration file in your home directory. You can edit the config file at this point to suit your needs: read more about the config file here.

Once the configuration is to your liking, you can register with the server:

$ petit-client register

And then start:

$ petit-client start

start will open the connection between your service and the public elements that use it. If you need to restart the machine where the Connector is running, be sure to start the Connector again.

Some other commands that you may find useful:

$ petit-client stop         # shutdown the connector
$ petit-client status       # output the connector status
$ petit-client unregister   # unregister from the server
$ petit-client config       # show the current configuration
$ petit-client sping        # to test server communication