Version-Specific Upgrades (Kubernetes)
Some Connectware upgrades require you to follow a few additional steps when upgrading Connectware to a newer version.
Upgrading Connectware to 1.11.0
Please consider that this release includes breaking changes and requires manual upgrade steps. If the current changes aren't immediately necessary for your implementation, we recommend waiting for the upcoming 1.12.0 release, which will also require manual upgrade steps. In case of questions, our Customer Success team is able to advise you.
Connectware 1.11.0 introduces NATS as its new Control Plane message bus and distributed state storage. As a result, you’ll need to follow a few additional steps when updating to Connectware 1.11.0 or later.
Here is an overview of the required steps to upgrade your Connectware installation to version 1.11.0. For complete step-by-step instructions, see Upgrading Procedure.
Network Port Requirements: Make ports TCP/4222 and TCP/4223 accessible both within Connectware and by agents.
Prepare Certificate Changes: Configure the new
cybus_nats_server.crt
certificate to include the hostname nats and any external DNS names for Connectware when using external agents.Configure DNS Names: Define the hostnames and IPs that will be included in the NATS Server certificate.
Resource Configuration: Specify Kubernetes resource limits for
nats
andresource-status-tracking
services.Update Connectware Helm Chart: Configure the Control Plane URI and certificates.
Update Agent Helm Chart: Configure the Control Plane URI and certificates.
Upgrade Connectware: Download and install Connectware 1.11.0.
Prerequisites
Connectware version: Your Connectware version is 1.7.3 or above. If your Connectware installation is below 1.7.3, make sure that you have followed Upgrading Connectware from 1.x to 1.5.0 and Upgrading Connectware to 1.7.0 before upgrading to 1.11.0.
Hardware resources: Connectware 1.11.0 introduces two new microservices (
resource-status-tracking
andnats
) to its architecture. When planning this upgrade, ensure your infrastructure can accommodate the enhanced resource requirements. This upgrade requires additional computing power. We recommend to add 8 CPU cores and 8 GB of memory to your current setup. However, these are general guidelines - check what your specific system needs and make adjustments accordingly.
Upgrading Procedure
Network Port Requirements
Connectware 1.11.0 introduces new network port requirements. Configure your network so that the following ports are accessible both within Connectware and by agents:
TCP/4222
TCP/4223
Minimal requirements: For installations requiring minimal firewall openings, you can configure the following:
Port TCP/4222 must be accessible within the Connectware network
For agents using mTLS authentication, port TCP/4222 must be accessible
For agents using username/password authentication, port TCP/4223 must be accessible
Verify both internal and external port accessibility to ensure proper communication between Connectware and its agents.
Preparing Certificate Breaking Changes
Connectware 1.11.0 introduces a new cybus_nats_server.crt
certificate which must contain the hostname nats
, as well as the external DNS name of Connectware if you are using any external agents. The configuration depends on whether you are using the built-in certificate infrastructure or a custom infrastructure.
2.1 When Using the Built-in Certificate Infrastructure
If you're using the built-in certificate infrastructure:
Do NOT proceed with the upgrade until you've completed Configuring DNS Names in Helm Values.
When updating DNS names, you must add the DNS name used by external agents to connect to Connectware.
Be aware that the upgrade will regenerate the certificate.
This may affect systems using certificate pinning.
Update any certificate pinning configurations after the upgrade.
2.2 When Using Custom Certificates
If you have modified the certificate infrastructure or use a custom cybus_server.crt
:
Prepare a new
cybus_nats_server.crt
certificate that meets these requirements:Must be signed by your existing Certificate Authority (CA).
Must include
nats
as a Subject Alternative Name (SAN).Must include your external Connectware DNS name as a SAN.
Installation steps:
Install the new certificate before starting the upgrade.
Update your Helm values to include the same external DNS name used in your certificate.
Certificate protection (optional): To prevent your custom certificate from being replaced during the upgrade, set the environment variable
CYBUS_DISABLE_NATS_CERTIFICATE_CHECKS
totrue
on the system-control-server by configuring the following Helm values:
Configuring DNS Names in Helm Values
To enable external agents to connect to the Connectware Control Plane, you must configure the global.ingressDnsNames
through Helm values. This setting defines the hostnames that will be included in the NATS server certificate's Subject Alternative Names (SAN) section.
Set the
global.ingressDnsNames
list in your Helm values to include all hostnames used for Connectware access.
Example
If the hostname on which Connectware is running is named company.io
, set the Helm value to:
Hostname Formats
You can include multiple hostnames in the list. The certificate will include all specified names in its SAN section.
The configuration accepts various hostname formats:
Wildcards (e.g.,
*.company.io
)Subdomains (e.g.,
connectware.company.io
)Custom hostnames (e.g.,
localhost
)
Example
Configuring nats and resource-status-tracking Resources
The nats
and resource-status-tracking
microservices come with preset Kubernetes resource requests and limits. Adjust the default values to your specific requirements. You can also start with the default values, monitor the metrics, and adjust your resources according to your insights.
To adjust the default values, update their values in the
global.podResources
Helm value context.
Example
Update Kubernetes Agent Configuration (Connectware Helm Chart)
5.1 Control Plane URI Configuration (Default Behavior)
The Connectware Helm chart automatically configures CYBUS_CONTROLPLANE_URI
using:
Hostname:
nats
Protocol scheme and port: Derived from the agent's mTLS configuration
5.2 Control Plane URI Configuration (Custom Configuration)
If you need to override the default configuration:
Set the Helm value
global.protocolMapperAgents[*].controlPlane.host
to the hostname of the Connectware Control Plane for your agent:
If you want to adjust the scheme or port for the
CYBUS_CONTROLPLANE_URI
, you can specify a full URI inglobal.protocolMapperAgents[*].controlPlane.host
:
5.3 Certificate Configuration
When using agents with username and password, you can configure the authentication of the agents to the Connectware server during Control Plane connections. You have two options:
Set the
TRUST_ALL_CERTS
environment variable on the agent to bypass certificate verification entirelyAuthenticate using certificates. For certificate authentication, ensure that the agent trusts the CA certificate that signed Connectware's cybus_nats_server.crt. This is only done automatically if you are using a globally trusted certificate for Connectware - otherwise, you need to provide the agent with the appropriate CA certificate.
The following table shows the result of configuring TRUST_ALL_CERTS
and providing the CA certificate.
TRUST_ALL_CERTS
affects all certificate validations, not just Connectware connections. Always test any changes to this setting in a staging environment before deploying to production.
CA certificate
Value of TRUST_ALL_CERTS
Behavior
Log shown during connection
Not Configured
true
Default: The connection to Control Plane (NATS) will not validate certificates and will trust all certificates.
CA certificate not found, trusting all certificates for NATS connection.
Not Configured
false
The connection to Control Plane (NATS) will try to use the system trust store to do certificate validation. This will only work when the CAs being used in Connectware are signed by a well known CA authority or when self-signed CAs were added to the system trust store.
CA certificate not found, using system trusted CAs for NATS connection.
Configured
true
The connection to Control Plane (NATS) will not validate server certificates and will trust any cert.
CA certificate found, but trusting all certificates for NATS connection.
Configured
false
The connection to Control Plane (NATS) will validate server certificates and will not trust any cert.
CA certificate found, using it for NATS connection with CA verification.
5.4 Changed Helm Values
This update includes changes to the Helm value structure for the mTLS key pair and the TLS CA certificate. The following Helm values have been updated:
global.protocolMapperAgents[*].mTLS.caChain.cert
global.protocolMapperAgents[*].tls.ca.certChain
global.protocolMapperAgents[*].mTLS.caChain.existingConfigMap
global.protocolMapperAgents[*].tls.ca.existingConfigMap
If you were following the scheme <chart-name>-<release-name>-<agent-name>-mtls-ca-cert
for the name of your existingConfigMap
you were not required to enter the name into the global.protocolMapperAgents[*].mTLS.caChain.existingConfigMap
Helm value in the past. This is now required, so make sure you enter any existing ConfigMap for the CA certificate chain into global.protocolMapperAgents[*].tls.ca.existingConfigMap
.
Migration Notes
Ensure the name of an existing ConfigMap for your CA is set through a Helm value, and does not rely on the name scheme
<chart-name>-<release-name>-<agent-name>-mtls-ca-cert
.You can simply move your existing configurations to the new paths
Old paths are temporarily supported for backward compatibility
Future updates will remove support for old paths
It's recommended to migrate to the new structure as soon as possible
Update Kubernetes Agent Configuration (Agent Helm Chart)
6.1 Control Plane URI Configuration (Default Behavior)
The Agent Helm chart automatically manages CYBUS_CONTROLPLANE_URI
using the existing Helm value protocolMapperAgentDefaults.connectwareHost
. This default configuration should work for most installations.
6.2 Control Plane URI Configuration (Custom Configuration)
If you need to override the default configuration:
Set the Helm value
protocolMapperAgentDefaults.controlPlane.host
to the hostname of the Connectware Control Plane, if it differs fromprotocolMapperAgentDefaults.connectwareHost
.
If you want to adjust the scheme or port for the
CYBUS_CONTROLPLANE_URI
, you can specify a full URI inprotocolMapperAgentDefaults.controlPlane.host
instead ofprotocolMapperAgentDefaults.connectwareHost
.
Example
6.3 Certificate Configuration
When using agents with username and password, you can configure the authentication of the agents to the Connectware server during Control Plane connections. You have two options:
Set the
TRUST_ALL_CERTS
environment variable on the agent to bypass certificate verification entirelyAuthenticate using certificates. For certificate authentication, ensure that the agent trusts the CA certificate that signed Connectware's cybus_nats_server.crt. This is only done automatically if you are using a globally trusted certificate for Connectware - otherwise, you need to provide the agent with the appropriate CA certificate.
The following table shows the result of configuring TRUST_ALL_CERTS
and providing the CA certificate.
TRUST_ALL_CERTS
affects all certificate validations, not just Connectware connections. Always test any changes to this setting in a staging environment before deploying to production.
CA certificate
Value of TRUST_ALL_CERTS
Behavior
Log shown during connection
Not Configured
true
Default: The connection to Control Plane (NATS) will not validate certificates and will trust all certificates.
CA certificate not found, trusting all certificates for NATS connection.
Not Configured
false
The connection to Control Plane (NATS) will try to use the system trust store to do certificate validation. This will only work when the CAs being used in Connectware are signed by a well known CA authority or when self-signed CAs were added to the system trust store.
CA certificate not found, using system trusted CAs for NATS connection.
Configured
true
The connection to Control Plane (NATS) will not validate server certificates and will trust any cert.
CA certificate found, but trusting all certificates for NATS connection.
Configured
false
The connection to Control Plane (NATS) will validate server certificates and will not trust any cert.
CA certificate found, using it for NATS connection with CA verification.
6.4 Changed Helm Values
This update includes changes to the Helm value structure for the mTLS key pair and the TLS CA certificate. The following Helm values have been updated:
Default Agent Configuration
protocolMapperAgentDefaults.mTLS.caChain.cert
protocolMapperAgentDefaults.tls.ca.certChain
protocolMapperAgentDefaults.mTLS.caChain.existingConfigMap
protocolMapperAgentDefaults.tls.ca.existingConfigMap
Individual Agent Configuration
protocolMapperAgents[*].mTLS.caChain.cert
protocolMapperAgents[*].tls.ca.certChain
protocolMapperAgents[*].mTLS.caChain.existingConfigMap
protocolMapperAgents[*].tls.ca.existingConfigMap
If you were following the scheme <chart-name>-<release-name>-<agent-name>-mtls-ca-cert
for the name of your existingConfigMap
you were not required to enter the name into the protocolMapperAgents[*].mTLS.caChain.existingConfigMap
Helm value in the past. This is now required, so make sure you enter any existing ConfigMap for the CA certificate chain into protocolMapperAgents[*].tls.ca.existingConfigMap
or protocolMapperAgentDefaults.tls.ca.existingConfigMap
.
Migration Notes
Ensure the name of an existing ConfigMap for your CA is set through a Helm value, and does not rely on the name scheme
<chart-name>-<release-name>-<agent-name>-mtls-ca-cert
.You can simply move your existing configurations to the new paths
Old paths are temporarily supported for backward compatibility
Future updates will remove support for old paths
It's recommended to migrate to the new structure as soon as possible
Upgrading Connectware to 1.11.0
To upgrade Connectware to 1.11.0, see Upgrading Connectware (Kubernetes).
Upgrading Connectware to 1.7.0
Connectware 1.7.0 affects the backward compatibility of the Connectware broker. Older broker data volumes are not compatible with brokers of Connectware 1.7.0 and newer. Upgrading to Connectware 1.7.0 requires additional upgrade procedures.
Additionally, multi-factor authentication (MFA) is now controlled via a dedicated configuration switch.
Important Notes
This upgrade will delete all persisted data of the Connectware broker. This includes client sessions, subscriptions, and retained data. If your configuration relies on any type of data persisted by the broker, make sure to properly initialize your applications after the upgrade.
If you rely on persisted data, create a backup or snapshot of the broker data volumes. This allows you to roll back in case of complications.
Upgrading Procedure
Important: If your Connectware installation is below 1.5.0, make sure that you have followed Upgrading from 1.x to 1.5 before upgrading to 1.7.0.
Scale down the broker cluster in Kubernetes. Set the number of broker nodes and control-plane-broker nodes to zero and wait until all broker pods have been successfully removed.
Delete the broker and control-plane-broker data volumes. Log volumes do not have to be deleted.
If you are using multi-factor authentication (MFA), set the Helm value
global.authentication.mfa.enabled
totrue
.Apply the updated Helm Chart of Connectware version 1.7.0 For more information, see Installing Connectware on Kubernetes.
Once all pods are up and running again and no new deviations appear in Connectware, the upgrade has been successful.
Upgrading Connectware from 1.x to 1.5.0
This Cybus Kubernetes guide provides a detailed procedure to help admins adjust the persistent volume content permissions to ensure a smooth upgrade to Connectware 1.5.0 in Kubernetes environments.
Prerequisites
Connectware version 1.3.0 or higher is installed on Kubernetes
Administrative rights to run privileged workloads in your Kubernetes cluster
kubectl
configured with access to the target installationHelm version 3 installed on your system
Cybus Helm repository added for access to:
Connectware Helm chart
connectware
in version1.5.0
.Connectware Agent Helm chart
connectware-agent
in version1.1.0
.
Access to the values.yaml file specific to your installation
Knowledge of the name and namespace of your Connectware installation
Overview of the Upgrade
Before you begin the upgrade process, ensure that you have made the necessary preparations and that all relevant stakeholders are involved.
The following steps give you an overview of what you need to do. See below for detailed step-by-step instructions.
Create the YAML snippets: Create YAML snippets for each PersistentVolumeClaim used by Connectware. This step is essential for identifying the volumes that need permission adjustments.
Filter volumes: Carefully review the created snippets to ensure that only related volumes are included. This is critical to avoid unnecessary modifications and potential disruptions.
Update the Kubernetes job file: Integrate the snippets into the kubernetes-job.yml file as described.
Shutdown Connectware: Securely shut down all Connectware and agent pods to prevent any access conflicts during the permissions update. This step is crucial to ensure that the permissions changes are applied without interference.
Run the Kubernetes job: Run the job to adjust permissions on all relevant volumes. This action addresses the core challenge posed by the upgrade and ensures that the new, non-root containers can access the files they need.
Delete Kubernetes services: Remove all services used by Connectware in preparation for the new version. This step is necessary to accommodate updates that are incompatible with the existing service configurations.
Apply Helm upgrade: Proceed with the Helm upgrade to Connectware version 1.5.0. This step completes the upgrade process and implements the new security measures and permissions model.
Important Notes
Permissions on NFS-based storage: NFS-based storage, such as EKS, may not allow permission changes directly through Kubernetes. For such storages, adjust permissions directly on the storage device if needed. This ensures that the required volumes are accessible to the new container users. The permissions are as follows:
For all volumes besides postgresql set ownership to
1000:0
and permissions to770
.For postgresql set ownership to
70:0
and permissions to770
.
Downtime for Connectware services: This process involves downtime for Connectware services. Schedule the upgrade accordingly to minimize the impact on your operations.
Deleting Kubernetes services: Deleting Kubernetes services before the upgrade is critical. This is necessary in order to update our existing headless services to ClusterIP services. Transitioning to ClusterIP services enables port translation, allowing you to continue to connect to the pre-upgrade service ports (80,443) while also being able to connect to the new service ports (8080, 8443). This ensures uninterrupted service access and compatibility after the upgrade.
Upgrading Procedure
Creating YAML Snippets for relevant PersistentVolumeClaim names
Create a script named
create-pvc-yaml.sh
containing the following:
Select the target environment:
Make the script executable and run it:
Review the output to confirm only relevant volumes are listed.
Example output:
Updating and Applying the Kubernetes Job
Create a script named
kubernetes-job.yml
containing the following:
Open
kubernetes-job.yml
and integrate the output of thecreate-pvc-yaml.sh
script.Shut down all Connectware and agent pods:
Apply the job to change permissions:
Verifying and Cleaning Up
Check the job logs for confirmation:
Example output
Delete the Kubernetes job afterward:
Delete outdated Kubernetes services:
Upgrading Connectware
Run the Helm command to upgrade Connectware to 1.5.0.
If you have any connectware-agent Helm chart installations, update them to Helm chart version 1.1.0.
Result: You have successfully upgraded Connectware to 1.5.0.
Functionality of Provided Files
create-pvc-yaml.sh
This script is designed to automatically generate Kubernetes resource lists, specifically volumeMounts
and volumes
, for Connectware deployments on Kubernetes. It simplifies the preparation process for upgrading Connectware by:
Identifying PersistentVolumeClaims (PVCs) used by Connectware and optionally by external agents.
Creating the YAML snippets required for mounting these volumes into the Kubernetes job designed to fix permissions.
Allowing customization through parameters such as
--kubeconfig
,--context
,--namespace
, to specify the Kubernetes cluster and namespace.Providing options to exclude volumes related to Connectware or external agents, if necessary.
The script outputs sections that can be directly copied and pasted into the kubernetes-job.yml
file, ensuring that the correct volumes are mounted with the appropriate permissions for the upgrade process.
`kubernetes-job.yml``
This YAML file defines a Kubernetes job responsible for adjusting the permissions of the volumes identified by the create-pvc-yaml.sh
script. The job is tailored to run with root privileges, enabling it to modify ownership and permissions of files and directories within PVCs that are otherwise inaccessible due to the permission changes introduced in Connectware 1.5.0.
The job’s purpose is to ensure that all persistent volumes used by Connectware are accessible by the new, non-root container user, addressing the core upgrade challenge without compromising on security by avoiding the use of root containers in the Connectware deployment itself.
Last updated
Was this helpful?