Upgrading Connectware to 2.0.0 (Docker)
Disclaimer
Some Connectware upgrades require you to follow a few additional steps when upgrading Connectware to a newer version.
Before You Begin
Upgrading to Connectware 2.0.0 introduces significant improvements in performance, scalability, and reliability. However, these changes also come with updated requirements for versions, networking, hardware, and storage.
This guide outlines the prerequisites and known limitations you must consider to ensure a smooth and successful upgrade.
Before starting the upgrade, read the entire guide. Some steps require developer work or preparation before the upgrade process begins.
Upgrading to Connectware 2.0.0 requires reinstalling all services. The main benefit of upgrading instead of performing a fresh installation is that it preserves the user database, including Multi-Factor Authentication. If you do not rely heavily on these features, a fresh installation may be the better option.
Even with a fresh installation, you will still need to follow this upgrade guide to update configuration parameters and adapt to the behavioral changes introduced in Connectware 2.0.0. However, you can skip the multi-step upgrade process itself.
If you are considering a fresh installation, we strongly recommend consulting with the Cybus Customer Support beforehand to confirm whether this is the right approach for your setup.
Connectware Version Requirements
To be able to upgrade to Connectware 2.0.0, your Connectware version must be 1.7.0 or above.
If your Connectware installation is below 1.7.0, make sure that you have followed Upgrading Connectware to 1.7.0 (Docker) before upgrading to 2.0.0.
Network Requirements
Why the Change?
With Connectware 2.0.0, some internal components have been updated to improve communication and performance. As a result, the network configuration has changed:
Added: TCP/4222 and TCP/4223
Removed: TCP/1884 and TCP/8884
What You Need to Do
Hardware Requirements
Why the Change?
Connectware 2.0.0 makes increased use of its PostgreSQL database and adds some components. When planning this upgrade, ensure your infrastructure can accommodate the enhanced resource requirements. This upgrade requires additional computing power.
What You Need to Do
Storage Requirements
Why the Change?
We have added two new components to Connectware:
A streaming server called NATS
A service called resource-status-tracking
Alongside other improvements, these additions enable Connectware to scale effectively for much larger deployments.
Known Limitations
Adding Certificates Through Admin UI Not Supported
You cannot add certificates to Connectware's CA bundle via the Admin UI.
Instead, modify the
cybus_ca.crtfile directly on thecertsvolume.
Backup via Admin UI Not Supported
The backup functionality through Admin UI is not supported.
Instead, create backups of the database by running a
pg_dumpcommand on the postgresql container.When running the command, make sure that only a single Connectware instance is running. Otherwise, select the container manually.
docker exec \
$(docker container ls -q -f "label=io.cybus.connectware=core" -f "label=com.docker.compose.service=postgresql") \
bash -c "pg_dump -U cybus-admin --if-exists -c cybus_connectware" \
> connectware_database.sqlUpgrade Procedure
Follow this procedure to upgrade your Connectware installation to version 2.0.0. The steps are divided into two parts:
Mandatory Upgrade Steps: Required for all installations to ensure a smooth and stable upgrade.
Feature-Specific Upgrade Steps: Only needed if you use certain features, so they remain compatible with Connectware 2.0.0.
Expand the following sections for an overview of all upgrade steps.
Mandatory Upgrade Steps
These steps are required to upgrade your Connectware installation to Connectware 2.0.0.
1. TLS Changes
Why the Change?
To enhance security by default, Connectware agents now verify TLS certificate chains automatically. This ensures that all components communicate over a valid trust chain, while still giving you the option to keep the old behavior by explicitly disabling TLS verification.
Key Changes
2. Update .env Configuration
Why the Change?
Some changes to Connectware require updating your environment variable configuration. Adapt your .env file accordingly.
All parameters to tune the inter-service communication have been removed.
Obsolete Environment Variables Values
New Environment Variables
3. Preparing the Connectware Upgrade
Why the Change?
Connectware 2.0.0 introduces architectural improvements that require you to remove or adjust certain resources before running the upgrade. This ensures a clean and successful upgrade process.
What You Need to Do
4. Upgrading to Connectware 2.0.0
Make sure all prior steps are completed before proceeding with the upgrade.
5. Updating Agent Configuration
Why the Change?
With Connectware 2.0.0, the default handling of certificate chain verification has changed. Previously, protocol-mapper agents required explicit configuration to validate peer certificate chains. Now, certificate chain verification is enabled and enforced by default. While you can revert to the old behavior using a configuration switch, we strongly recommend using a proper TLS certificate chain.
You now must provide the CA certificate signing Connectware's public server certificate cybus_server.crt to agents.
Additionally, the control-plane-broker has been replaced with a new streaming-based control plane. Along with this change, the configuration values for both the control plane and the data plane have been redesigned. The new values are intended to be generic and resilient against future technology changes. As a result, several environment variables have been deprecated, renamed, or newly introduced.
What You Need to Do
Because Connectware agents are single containers, they can be orchestrated by many means, exceeding the possibilities of this upgrade guide. We will provide examples for Docker Compose orchestration. We trust that you know how to adapt these to an orchestrator of your choice. Contact Cybus Support for additional assistance.
6. Upgrading Agents
What You Need to Do
Ensure you followed the previous step to prepare the agents, by adjusting their configuration to the changes made with Connectware 2.0.0.
Enter the directory in which the
docker-compose.yamlfile for your agents is stored.Modify the agents
docker-compose.yamlfile and replace the image tag with2.0.0.
Example
services:
protocol-mapper-agent:
image: registry.cybus.io/cybus/protocol-mapper:2.0.0 # update the image tag
environment:
CYBUS_AGENT_MODE: distributed
CYBUS_AGENT_NAME: my-docker-compose-agent
CYBUS_HOSTNAME_INGRESS: connectware
volumes:
- protocol-mapper-agent:/data
- ./cybus_combined_ca.crt:/connectware/certs/ca/ca-chain.pem
restart: unless-stopped
network_mode: host
hostname: my-docker-compose-agent
volumes:
protocol-mapper-agent:Run
docker compose up.
7. Reinstalling Services
Why the Change?
With Connectware 2.0.0, your services and resources are no longer stored on the service-manager volume, but inside the PostgreSQL database.
What You Need to Do
Feature-Specific Upgrade Steps
Only follow these if you use the related features, so they continue working after the upgrade.
1. Permissions and Roles
Why the Change?
Permissions allow administrators to define who can access what resources and what actions they can perform. Each permission represents a specific access right to a resource.
Connectware 2.0.0 introduces new and permissions. Because of this, custom roles or specific permissions you have set up might not allow users to do everything they could before the 2.0.0 upgrade.
What You Need To Do
2. Custom Connectors
Why the Change?
Connectware has evolved its architecture, removing dependencies like VRPC and improving protocol handling. To ensure compatibility, you must update your custom connector implementations.
What You Need To Do
If you are using custom connectors, follow these steps to make your custom connector compatible with Connectware 2.0.0.
3. Systemstate Protocol
Why the Change?
To improve performance and reduce unnecessary messaging load, the Systemstate protocol no longer supports whole-service tracking or redundant status events. This simplifies agent responsibilities and avoids misleading lifecycle signals.
What You Need to Do
If you are using the Systemstate protocol, do the following:
4. Log Monitoring
Why the Change?
With version 2.0.0, several log messages have been corrected to fix spelling mistakes. These changes may affect existing log monitoring configurations.
What You Need to Do
5. Heidenhain Agents (Windows)
Why the Change?
For Connectware 2.0.0, the Heidenhain protocol has been updated.
What You Need to Do
6. Auto-Generated MQTT Topics of Resources
Why the Change?
With Connectware 2.0.0, auto-generated MQTT topics no longer include resource-specific properties. This makes the topic generation more unified and explicit. You must update any service commissioning file that hardcodes those old auto-generated topics.
Example of old behavior
Some auto-generated topics contained property-specific parts:
S7:
services/myService/pressure/address:DB1,REAL6Modbus:
services/myService/current/fc:3/address:7HTTP:
services/myService/myEndpoint/get[object Object]
These paths might have been referenced inside Cybus::Mapping resources. Using auto-generated topics inside Cybus::Mapping is not recommended. Instead, use references via !ref, “Reference Method”.
What You Need to Do
7. Auto-Generated MQTT Users
Why the Change?
Before 2.0.0, Connectware created a hidden MQTT user for every installed service. These auto-generated users were only used when the service commissioning file explicitly referenced the pseudo parameter Cybus::MqttUser.
With Connectware 2.0.0, hidden users and groups are created only when the service commissioning file uses the Cybus::MqttUser pseudo parameter. This reduces unused accounts and makes credential usage explicit.
What You Need to Do
Last updated
Was this helpful?