Upgrading Connectware to 2.0.0 (Kubernetes)
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. 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 (Kubernetes) 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.
In addition, the latest versions of PostgreSQL and auth-server require updated Kubernetes resource requests and limits to maintain stability and performance under heavier workloads.
What You Need to Do
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.crt
file directly on thecerts
volume.
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_dump
command on thepostgresql-0
pod.
kubectl exec -n [your-namespace] postgresql-0 -- \
bash -c "pg_dump -U cybus-admin --if-exists -c cybus_connectware" \
> connectware_database.sql
Upgrade 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 Helm Values
Why the Change?
Some changes to Connectware or the Helm chart prompt changes to Helm values, which you need to adapt your values.yaml
file to:
The optional control-plane-broker is removed from Connectware.
All parameters to tune the inter-service communication have been removed.
Obsolete Helm Values
New Helm Values
3. Preparing the Connectware Helm Upgrade
Why the Change?
Connectware 2.0.0 introduces architectural improvements that require you to remove or adjust certain resources before running the Helm 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 Helm upgrade.
5. Enabling Agents in the Connectware Helm Chart
When upgrading to Connectware 2.0.0, protocol-mapper agents must be explicitly enabled again. This requires updating Helm values and configuring TLS certificates — or, in less secure setups, choosing to trust all certificates.
The following steps are required:
Update Helm values to their new equivalents.
Configure TLS (recommended) or opt to trust all certificates (not recommended).
Re-run
helm upgrade
to apply the changes.
Agents connecting to Connectware must either:
Provide a valid CA certificate that matches the server certificate, OR
Skip certificate validation by setting
CYBUS_TRUST_ALL_CERTS
totrue
(not recommended).
Which Certificate to Use
The certificate that you provide depends on how the agent connects:
Via Connectware ingress: Use
cybus_ca.crt
.Via the internal network: Use
shared_yearly_ca.crt
.Simplified option that works for both cases: Use
cybus_combined_ca.crt
.
Use the table below to decide which option applies to your setup:
What You Need to Do
6. Updating Helm Values for the Connectware Agent Helm Chart
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 using the Helm value protocolMapperAgentDefaults.tls.ca.certChain
(renamed from protocolMapperAgentDefaults.mTLS.caChain.cert
).
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 Helm values have been deprecated, renamed, or newly introduced.
What You Need to Do
7. Upgrading Agents for the Connectware Agent Helm Chart
What You Need to Do
To upgrade your agents installed via the
connectware-agent
Helm chart, see Upgrading the connectware-agent Helm Chart.
8. 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,REAL6
Modbus:
services/myService/current/fc:3/address:7
HTTP:
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
Last updated
Was this helpful?