High Availability Configuration
This topic assumes that you have set up your ThingWorx High Availability Clustering environment and want to configure the Azure IoT Hub Connector to connect to the HA cluster of ThingWorx Platform instances.
Before You Begin
The configuration instructions for the Azure IoT Hub Connector in an HA cluster assume the following tasks are complete:
• Your ThingWorx High Availability Cluster is installed, configured, and running. For links to ThingWorx HA help topics, refer to the section below,
More Information about ThingWorx High Availability Clustering.
• For security best practices, it is recommended to enable Simple Authentication Security Layer (SASL) for communications with the service discovery provider, ZooKeeper.
Before you begin, collect the following information for configuring the Azure IoT Hub Connector in your ThingWorx High Availability Clustering environment:
• From ThingWorx Composer, create an application key for this Azure IoT Hub Connector to use for authenticating with a ThingWorx Platform instance.
• In the ThingWorx High Availability Clustering environment the ThingWorx Platform instances register their IP addresses in ZooKeeper service discovery. The Azure IoT Hub Connector uses the IP address registered in ZooKeeper to connect to a ThingWorx Platform instance. Since host name validation is enabled by default, make sure that the TLS certificate of each ThingWorx Platform instance contains an IPAddress entry in the Subject Alternative Name extension that matches its IP address. Otherwise, the TLS connection will fail host name validation. Although not recommended, you can disable host name validation. Refer to
Optional Configuration Properties Shown in the Minimal and HA Sample Configuration
Files.
• To set the connectionString for service discovery, obtain a list of the host:port pairs for the ZooKeeper instances in the cluster. You need to enter these pairs as a comma-separated list while configuring service discovery for the Azure IoT Hub Connector.
• Decide whether to use SASL for communications with the ZooKeeper instances, and if so, obtain the paths to the configuration files for KRB5 (Kerberos) and JAAS (Java Authentication and Authorization Service) in the cluster.
 |
For information about configuring KRB5 and JAAS for SASL communications with ZooKeeper instances, refer to the topic,
Installing and Configuring ZooKeeper for ThingWorx HA, in the ThingWorx Help Center. For specific information about ZooKeeper and SASL, refer to the page,
ZooKeeper and SASL on the Apache web site. It provides links to information about configuring client-server mutual authentication and server-server mutual authentication with SASL and ZooKeeper. It also has an appendix that defines Kerberos, SASL, and JAAS, with links to download required software.
|
Configuring an Azure IoT Hub Connector for HA Operations - Required Settings
The azure-iot-ha-sample.conf file is organized such that the properties that you must set appear first, followed by required properties that you must not change, and finally optional properties. This section guides you through setting the required properties.
 |
Recall that the connection between the Connector and the Azure IoT Hub is protected by SSL. You provide connection strings for the Azure IoT Hub by setting properties for the AzureIotHubTemplate Thing in ThingWorx Composer. In an HA configuration file for the Connector, you can set up security for service discovery, which provides the connection to an instance of ThingWorx Platform in the cluster. Optionally you can
create a trust store for this connection.
|
To configure an Azure IoT Hub Connector to operate in a ThingWorx High Availability Clustering environment, follow these steps:
1. Navigate to the conf subdirectory of the Azure IoT Hub Connector installation, and make a copy of the azure-iot-ha-sample.conf file and rename it to azure-iot.conf.
2. Using a text editor, open your copy of the HA sample configuration file, azure-iot.conf. The file contains the required settings at the beginning of the file and the optional settings afterwards, all with comments to explain them. The following lines show the required settings that you need to change. For each property, change null to the value appropriate for your environment:
cx-server {
transport.websockets {
# ThingWorx Platform application key that the Connector uses
# to authenticate with the platform.
# For example: app-key = "88888888-4444-4444-aaaa-cccccccccccc"
app-key = null
}
discovery {
# A comma-separated list of host:port pairs for the ZooKeeper
# instances in the cluster. For example:
# connectionString = "zookeeper-1:2181, zookeeper-2:2181"
connectionString = null
}
protocol {
# The name of the Thing associated with the Azure IoT Hub
hub-thing-name = null
}
}
3. Using the information you collected, you must set these properties:
◦ transport.websockets.app-key — Replace null with the application key for the Azure IoT Hub Connector to use to authenticate with a ThingWorx Platform instance in the cluster. For example:
app-key = "77777777-2222-2222-aaaa-cccccccccccc"
◦ discovery.connectionString — Replace null with the comma-separated list of host:port pairs for the ZooKeeper instances in the cluster. For example:
connectionString = "zookeeper-1:2181,zookeeper-2:2181,zookeeper-3:2181"
◦ protocol.hub-thing-name — Replace null with the ThingName of the AzureIotHubTemplate Thing that represents the Azure IoT Hub that this Connector communicates with.
4. Leave the default settings for the following required properties. They must be set as is to enable successful connection to a ThingWorx High Availability Clustering environment:
cx-server {
. . .
# Configure the connection to the ThingWorx Platforms to work
# in a ThingWorx HA cluster.
platform.transport = "websockets_active_active"
# Enable the Connector to look up the ThingWorx Platform
# endpoints using ZooKeeper service discovery.
transport.websockets.service-discovery.enabled = true
. . .
}
|
|
In a ThingWorx HA Cluster, the ThingWorx Platform instances register their IP addreses in ZooKeeper service discovery. The Azure IoT Connector will connect to a ThingWorx Platform instance in a cluster using its IP address registered in ZooKeeper service discovery. The TLS connection will fail host name verification unless the ThingWorx Platform instance's TLS certificate contains an IPAddress entry in the Subject Alternative Name extension matching its IP address. If this scenario describes your use case, disable host name verification by changing the value of the transport.websockets.service-discovery.enabled property to false: Refer to
Optional Configuration Properties Shown in the Minimal and HA Sample Configuration
Files.
|
5. If you are using the Connector with ThingWorx Azure Industrial IoT (IIoT) OPC UA, you need to add the protocol.opcua.enabled property to the cx-server.protocol group in the configuration file and set it to true, as shown here:
cx-server {
protocol {
. . .
opcua {
enabled = true
}
}
}
You should have already configured the AzureIoTHubTemplate Thing in ThingWorx Composer. If you have not done so, do so after you finish this procedure. Refer to
Step 5. Create Azure IoT Entities in ThingWorx Composer for details; Step 6 of the procedure in that topic explains the configuration required for the AzureIoTHubTemplate Thing when using the ThingWorx Azure Industrial IoT OPC UA integration.
6. To validate the certificate presented by the ThingWorx Platform, the Azure IoT Hub Connector uses the trust store provided by the JRE (cacerts). If you are using a self-signed certificate (for development purposes only, NEVER in production), you need to import the self-signed certificate into the $JAVA_HOME/jre/lib/security/cacerts file.
7. Save the file. At this point you have completed the minimum required configuration for the Azure IoT Hub Connector to run in a ThingWorx HA Cluster.
Next Steps
At this point, you may want to configure optional properties and/or metrics reporting. If so, leave your configuration file open and follow the steps in the appropriate topic:
When you have completed the configuration, follow these steps:
1. As a best practice, encrypt the configuration for optimal security. Do this before setting the environment variable. For instructions, refer to
Step 7. Encrypt the Configuration File.
 |
If you are setting up an internal testing environment, it is strongly recommended but not required that you encrypt the configuration file. Make sure that you encrypt the Connector configuration file when setting up a production environment.
|
More Information about ThingWorx High Availability Clustering
For general information on ThingWorx High Availability Clustering installations, refer to the
Overview of ThingWorx High Availability.
For specifics on setting up the HA cluster, refer to the following topics: