Cloud Profiles

Starting with version 1.4.0, thin-edge.io supports multiple Cumulocity connections using cloud profiles. This can be useful for migrating from one Cumulocity tenant to another, where Cloud profiles allow you to configure and run multiple tedge-mapper c8y instances from a single tedge.toml configuration file.

tip

User Context

You can customize the documentation and commands shown on this page by providing relevant settings which will be reflected in the instructions. It makes it even easier to explore and use thin-edge.io.

Loading user context...

The user context will be persisted in your web browser's local storage.

Configuration

There are a few values that need to be configured before we are able to connect to a second Cumulocity tenant.

URL

To connect to a second tenant, start by configuring the URL of the new tenant:

sudo tedge config set c8y.url undefined --profile undefined

The profile name can be any combination of letters and numbers, and is used only to identify the cloud profile within thin-edge. The names are case insensitive, so --profile second and --profile SECOND are equivalent.

You can now see the configuration has been applied to tedge.toml:

tedge config list url

Output

c8y.url=undefined
c8y.profiles.undefined.url=undefined

In addition to the URL there are a couple of other configurations that need to be set for the second mapper:

• the MQTT bridge topic prefix
• the Cumulocity proxy bind port

MQTT bridge topic prefix

sudo tedge config set c8y.bridge.topic_prefix c8y-undefined --profile undefined

Setting c8y.bridge.topic_prefix will change the MQTT topics that the Cumulocity bridge publishes to/listens to in mosquitto. The default value is c8y, so the mappper publishes measurements to c8y/s/us, and this is forwarded to Cumulocity on the s/us topic. In the example above, we set the topic prefix to c8y-second, so the equivalent local topic would c8y-second/s/us. It is recommended, but not required, to include c8y in the topic prefix, to make it clear that the relevant topics are bridge topics that will forward to and from Cumulocity.

Cumulocity proxy bind port

sudo tedge config set c8y.proxy.bind.port 8002 --profile undefined

Since the Cumulocity mapper hosts a proxy server for Cumulocity and there will be a second mapper instance running, this configuration also needs to be unique per profile.

Optional per-profile configurations

All the Cumulocity-specific configurations (those listed by tedge config list --doc c8y) can be specified per-profile to match tenant-specific constraints.

Connecting

Once the second cloud profile has been configured, you can finally connect the second mapper using:

sudo tedge connect --profile undefined

Output

Connecting to Cumulocity with config:
        device id: undefined
        cloud profile: undefined
        cloud host: undefined:8883
        certificate file: /etc/tedge/device-certs/tedge-certificate.pem
        bridge: mosquitto
        service manager: systemd
        mosquitto version: 2.0.11
Creating device in Cumulocity cloud... ✓
Restarting mosquitto... ✓
Waiting for mosquitto to be listening for connections... ✓
Verifying device is connected to cloud... ✓
Enabling tedge-mapper-c8y@undefined... ✓
Checking Cumulocity is connected to intended tenant... ✓
Enabling tedge-agent... ✓

Once the mapper is running, you can restart it by running:

sudo systemctl restart tedge-mapper-c8y@undefined

This uses a systemd service template to create the tedge-mapper-c8y@second service. If you are not using systemd, you will need to create a service definition for tedge-mapper-c8y@second before attempting to connect your device to a second Cumulocity instance.

Environment variables

For easy configuration of profiles in shell scripts, you can set the profile name using the environment variable TEDGE_CLOUD_PROFILE.

With arguments

sudo tedge config set c8y.url undefined
sudo tedge connect c8y

sudo tedge config set c8y.url undefined --profile undefined
sudo tedge config set c8y.bridge.topic_prefix c8y-undefined --profile undefined
sudo tedge config set c8y.proxy.bind.port 8002 --profile undefined
sudo tedge connect c8y --profile undefined

With environment variable

# You can set the profile name to an empty string to use the default profile
export TEDGE_CLOUD_PROFILE=
sudo tedge config set c8y.url undefined
sudo tedge connect c8y

export TEDGE_CLOUD_PROFILE=undefined
sudo tedge config set c8y.url undefined
sudo tedge config set c8y.bridge.topic_prefix c8y-undefined
sudo tedge config set c8y.proxy.bind.port 8002
sudo tedge connect c8y

export TEDGE_CLOUD_PROFILE=
sudo tedge config get c8y.url #=> undefined

export TEDGE_CLOUD_PROFILE=undefined
sudo tedge config get c8y.url #=> undefined

If you need to temporarily override a profiled configuration, you can use environment variables of the form TEDGE_C8Y_PROFILES_<NAME>_<CONFIGURATION>. For example:

$ TEDGE_C8Y_PROFILES_undefined_URL=different.example.com tedge config get c8y.url --profile undefined
different.example.com
$ TEDGE_C8Y_PROFILES_undefined_PROXY_BIND_PORT=1234 tedge config get c8y.proxy.bind.port --profile undefined
1234

If you are configuring thin-edge.io entirely with environment variables, e.g. in a containerised deployment, you probably don't need to make use of cloud profiles as you can set the relevant configurations directly on each mapper instance.