New: Cybus Helm Charts 3.0.0.
Learn more.
Ctrlk
Contact Uscybus.io
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Upgrading Connectware Helm Charts to 3.0.0

How to upgrade your connectware and connectware-agent Helm charts from version 2.1.0 or later to version 3.0.0.

Chart 3.0.0 marks the first release of the Cybus Helm charts as a standalone update, separate from a Connectware release. The 3.0.0 Helm chart upgrade only affects the chart; your Connectware version is unchanged.

Chart versioning and Connectware versioning are now decoupled. This means that improvements to the Cybus Helm chart can be released independently of Connectware releases. The compatibility matrix shows which chart versions work with which Connectware versions. This makes it easy to plan upgrades for each type on its own schedule.

For a full list of new features and improvements in this release, see the changelog.

Switching to an OCI Registry

Starting with chart 3.0.0, charts are distributed via an OCI registry instead of a Helm chart repository.

Each chart version is now pulled directly by its exact version tag from an OCI registry, similar to how container images are handled. You do not have to manage a registered repo or run helm repo update before installing a new version anymore.

Especially for offline installations, this is a significant simplification: charts and container images can now be mirrored to the same registry, removing the need to host the chart separately. Use oci://repo.cybus.io as the registry. Make sure any proxies or network access rules allow traffic to that address.

Helm version 4 is required.

Before You Begin

Chart 3.0.0 restructures the values.yaml file for both the connectware chart and the connectware-agent chart. Many keys are renamed, several components have been moved from global.* into top-level blocks, and resource defaults have been reduced for most components.

This guide is split into two parts so that you can follow only the parts that apply to your installation:

  • Part A: changes to the connectware chart values.yaml file.

  • Part B: changes to the connectware-agent chart values.yaml file. Applies whether the agent chart runs standalone or as a subchart of the connectware chart.

Make sure to read the entire guide before you start. Some changes, such as security context overrides and protocol-mapper agent migration, require careful hand-merging to avoid stripping defaults or orphaning agents.

Prerequisites

  • A working installation of one or both of the following:

    • connectware Helm chart versions 2.1.0 to 2.4.0

    • connectware-agent Helm chart versions 2.1.0 to 2.4.0

  • Chart 2.1.0 is the minimum supported starting point. If you are on an older version, upgrade to 2.1.0 first.

  • Access to your current values.yaml file or files.

  • Backups of your Connectware database, Persistent Volumes, values.yaml file or files, and all service commissioning files.

  • Helm version 4 is installed on your system.

  • kubectl is installed on your system.

  • You know the name and namespace of your installations. See Obtaining the Name, Namespace, and Version of Your Installation.

  • Access to OCI registry oci://repo.cybus.io, or the Helm charts copied locally.

  • Kubernetes version >= 1.25: These new chart versions will not deploy on Kubernetes lower than 1.25.

A note on quoting strings

YAML interprets certain unquoted values as numbers, booleans, or dates. To avoid accidental type coercion, wrap string values in single or double quotes whenever they contain digits, punctuation, or look like a boolean. The examples in this guide follow this convention.

AI-Assisted Migration

You can migrate your values.yaml file using AI or manually. If you prefer the manual approach, skip this section and follow Part A and Part B instead. If you use the AI approach, it handles the key renames and structural moves in your values.yaml file. However, you still need to perform additional manual actions, as described below.

1. Migrating the values.yaml File

Download the skill below and run it with a tool supporting the Agent Skills format against your existing values.yaml file to automate the key renames and moves. The better the model's reasoning, the more reliable the output.

Always review the output before applying it.

39KB
cybus-helm-3-0-value-migration.zip
archive
Open

The skill covers values.yaml key changes; work through the items in the next step for everything else.

2. Before Running helm upgrade

  • Recreate the image pull secret if you used a different value for global.registryUser than license. Create a pull secret manually and reference it through global.image.pullSecrets, or pods will fail with ImagePullBackOff. See A1. License Values Changes.

  • Verify customized security contexts after migration. Overrides replace chart defaults and do not merge — the migrated output may be missing defaults. See A3. Security Contexts and B3. Security Contexts.

  • Decide whether to keep the previous resource defaults. If your values.yaml does not set resource requests and limits, the new lower defaults apply after the upgrade. See A8. Resources Moved to Per-Component and B7. Resource Defaults.

  • Set authServer.replicas: 1 if you want the old single-replica behavior. The default changed from 1 to 2. See A10. Auth-Server Default Replicas.

  • Detect cluster resource renames for connectware-agent installations with affected names. If your release is named connectware, or combined release-plus-agent names exceed 52 characters, run helm diff upgrade first. See B8. Cluster Resource Name Changes.

  • Re-add TCP ports for Cybus::IngressRoute resources. The ingress LoadBalancer Service no longer exposes ports 40000 to 40009 by default. If you have Cybus::IngressRoute resources of type tcp, add their connectwarePort to connectwareIngress.service.ports or they become unreachable. See A13. Ingress Service Ports for TCP IngressRoutes.

  • Review the Container Manager RBAC change if your cluster restricts RBAC manifests. The chart replaces the pod-manager Role with a connectware-${INSTALLATION_NAME}-pod-reader Role that only grants get, list, and watch on pods and pods/log, and binds a dedicated ServiceAccount instead of the namespace default ServiceAccount. If your cluster requires approval for changes to Roles, RoleBindings, or ServiceAccounts, share the diff with the team that approves RBAC manifests before running helm upgrade.

3. Running helm upgrade

Follow the Upgrade Procedure to run helm upgrade. Then continue to the next step for post-upgrade actions.

4. After Running helm upgrade

None of these items require changes to values.yaml.

  • Update external selectors that reference the app label. The label changed from app=<component> to app.kubernetes.io/name=<component>. See A12. Workload Label Rename.

  • Update references to the renamed ingress Deployment. The Deployment connectware is now connectware-ingress. See A7. Components Moved Out of global.

  • Re-register migrated protocol-mapper agents. Connectware treats agents migrated from the connectware chart as new entities. See Post-Upgrade Actions.

  • Review resource usage and set production limits. See Post-Upgrade Actions.

Upgrade Procedure

The procedure is divided into the following parts:

  • Part A — Connectware Chart Migration: Update the connectware chart values.yaml file to match the new chart schema.

  • Part B — Connectware-Agent Chart Migration: Update the connectware-agent chart values.yaml file. Applies to both standalone and subchart deployments.

  • Running the Upgrade: Apply the updated values using helm upgrade.

  • Post-Upgrade Actions: Re-register protocol-mapper agents and review resource requests.

As part of this upgrade, you will need to fully stop Connectware and any standalone connectware-agent releases, since some of the changes cannot be done in a rolling restart.

Overview of Mandatory Migration Steps

connectware chart steps:

  1. License Keys

  2. Image Version

  3. Security Contexts

  4. Storage to Persistence

  5. User Management to Authentication

  6. Other Global Value Changes

  7. Components Moved Out of global

  8. Resources Moved to Per-Component

  9. CybusMQ Broker Value Changes

  10. Auth-Server Default Replicas

  11. Reserved MFA Environment Variables

  12. Workload Label Rename

  13. Ingress Service Ports for TCP IngressRoutes

  14. NATS Metrics Path Change

connectware-agent chart steps:

  1. Protocol-Mapper Agents Structure

  2. Image Version

  3. Security Contexts

  4. Storage to Persistence

  5. TLS CA Configuration Renames

  6. Reserved Environment Variables

  7. Resource Defaults

  8. Cluster Resource Name Changes

Part A: Connectware Chart Migration

Apply the following changes to your connectware chart values.yaml file. If you only want to update the connectware-agent chart standalone, skip to Part B.

A1. License Values Changes

Why the Change?

Normalizing value names and capitalization to avoid future confusion.

What You Need to Do

Updating the License Values

  • Delete global.registryUser. If you authenticated against the image registry with a custom user, create a pull secret manually and reference it via global.image.pullSecrets. See Configuring Registries and Pull Secrets.

  • Rename global.licensekey to global.licenseKey (capital K).

  • If global.licenseFile is set to online, change it to "" (empty string) or remove it. Real license file bodies used for offline installations remain unchanged. If you do not have this key in your values.yaml, you do not need to add it.

Before

After

A2. Image Version

Why the Change?

The value controls the container image tag used, not necessarily a version. It is now aligned with the Kubernetes convention.

What You Need to Do

Renaming the Image Key

  • Rename global.image.version to global.image.tag.

Before

After

A3. Security Contexts

Why the Change?

Security context values now use Override suffixes to signal that they replace the chart defaults rather than merge with them.

We renamed securityContext to podSecurityContextOverride, to be consistent and explicit in the naming.

Override values replace defaults, they do not merge

A partial override strips any default it does not redeclare. If you customized a security context, your migrated output must include both the new 3.0.0 defaults and your customizations, merged by hand.

The same rename applies to per-agent security contexts in the connectware-agent chart. See B3. Security Contexts.

Key Changes

1. Pod and Container Security Context Renames

Both keys are available as a global default under global.* and as a per-component override. The per-component value takes precedence over the global one.

  • securityContext → podSecurityContextOverride

  • containerSecurityContext → containerSecurityContextOverride

This applies to global.* and every component.

2. Chart 3.0.0 Defaults to Merge Into Your Override

For your reference, these are the default security contexts our Helm charts apply. If you have customized a security context, merge your customization with these defaults and set them in the respective podSecurityContextOverride or containerSecurityContextOverride. You will find examples in the next steps. If you never customized a security context, delete any security context block from your values.yaml file and the defaults will apply.

Default pod security context

Default container security context

3. Merge Example (Pod Security Context)

This example adds runAsUser: 1000 on top of the defaults.

Before

After (defaults merged with your value)

4. Merge Example (Container Security Context)

This example sets the container to run as a specific user ID (runAsUser: 1000) on top of the defaults.

Before

After (defaults merged with your value)

5. Dropping Exact-Default Blocks

The former defaults and the 3.0.0 defaults listed above are identical. If your source security context block matches them exactly, drop the block entirely instead of emitting an override. The 3.0.0 defaults already cover it.

A4. Storage to Persistence

Why the Change?

The storage key was renamed to persistence across the chart, and several storage-related keys were adjusted to use uppercase initialisms. This aligns the naming with common Kubernetes conventions and keeps it consistent across the chart.

The same rename applies to per-agent storage in the connectware-agent chart. See B4. Storage to Persistence.

What You Need to Do

Renaming Storage Keys
Old
New

global.storage

global.persistence

<component>.storage (broker, nats, postgresql, systemControlServer, workbench)

<component>.persistence

postgresql.persistence.preprovisionedNfs

postgresql.persistence.preprovisionedNFS

Inner keys (size, storageClassName, data, log, accessMode) are unchanged.

Before

After

A5. User Management to Authentication

Why the Change?

The user management section is not different from the authentication section, so to simplify, they have been merged. The admin user password format was also simplified from base64 to plain text, which follows a common theme: literal Helm values take plain-text values. Base64 encoding is not a security measure to keep values secret. For more secure operations, use Helm values which take references to existing Kubernetes Secrets, in this case global.authentication.adminUser.existingSecret. The initial admin password has no effect during an upgrade, since it will never override an existing admin user.

The mTLS configuration block was removed a few versions back, since mTLS is now always enabled. If you still have it in your values.yaml, now is a good chance to remove it.

What You Need to Do

Migrating Authentication Values

  • Rename global.userManagement.adminUser to global.authentication.adminUser.

  • Change adminUser.enabled from the string "true" or "false" to the boolean true or false.

  • Change adminUser.initialPassword from base64 or the sentinel "automatic" to plain text. Decode any base64 value. Replace "automatic" with an empty string "" to auto-generate a password.

  • Rename global.userManagement.passwordPolicyRules to global.authentication.passwordPolicyRules.

  • Delete global.authentication.mTLS if present. mTLS has been auto-enabled for several Connectware versions and the value no longer has any effect.

Before

After

A6. Other Global Value Changes

Why the Change?

Some global values are no longer needed, the MetalLB address pool configuration moved to the ingress service annotations, and the ingress DNS names key was renamed to use the uppercase initialism.

What You Need to Do

Removing, Replacing, and Renaming Global Values

  • Delete global.setImmutableLabels. Labels on immutable objects are now always set.

  • If you use MetalLB, replace global.loadBalancer.metalLB.addressPoolName with an annotation on connectwareIngress.service.annotations as explained in the MetalLB documentation. You can then remove the global.loadBalancer section.

  • Rename global.ingressDnsNames to global.ingressDNSNames (uppercase DNS).

Before

After

A7. Components Moved Out of global

Why the Change?

Component configuration blocks were lifted out of global.* to their own top-level keys to follow Helm best practices and avoid confusion with subcharts being introduced into the connectware chart.

The "connectware" Deployment used the global.ingress section. The name of the Deployment and the name of the section were confusing, so they were both renamed. The Deployment is now named "connectware-ingress" and uses the matching Helm value section connectwareIngress. This conveys more clearly that this is an ingress proxy for Connectware, and has nothing to do with a Kubernetes Ingress. Instead it is exposed using a LoadBalancer Service by default.

What You Need to Do

Moving Component Blocks to the Top Level

Move every global.<component> block to the top-level <component> key. Use the mapping below.

Old
New

global.adminWebApp

adminWebApp

global.authServer

authServer

global.broker

broker

global.containerManager

containerManager

global.ingress

connectwareIngress

global.ingressController

ingressController

global.nats

nats

global.postgresql

postgresql

global.protocolMapper

protocolMapper

global.resourceStatusTracking

resourceStatusTracking

global.serviceManager

serviceManager

global.systemControlServer

systemControlServer

global.topicExplorer

topicExplorer

global.workbench

workbench

Before

After

A8. Resources Moved to Per-Component

Why the Change?

The global.podResources.* block has been removed. Resource limits and requests are now configured directly on each component. Default requests have also been reduced for most components.

If your current values.yaml file does not set global.podResources, your workloads will receive the new, lower default requests after the upgrade. Set the old values explicitly if your workload requires them.

What You Need to Do

1. Moving Resources to Each Component

Drop global.podResources.* and put resources: directly on each component. Watch the alias keys: connectware, controlServer, database, and distributedProtocolMapper do not match their target component names.

Old Path
New Path

global.podResources.<component>

<component>.resources

global.podResources.connectware

connectwareIngress.resources

global.podResources.controlServer

systemControlServer.resources

global.podResources.database

postgresql.resources

global.podResources.distributedProtocolMapper

connectwareAgent.protocolMapperAgentDefaults.resources. See also B1. Protocol-Mapper Agents Structure.

Before

After

2. Default Request Changes

The table below lists the default CPU and memory requests for each component in chart 2.4.0 and chart 3.0.0.

Most components have lower defaults in chart 3.0.0. However, lower defaults do not mean Connectware requires fewer resources. The chart reduces defaults to make it easier to get started on smaller clusters. Use actual resource consumption data to set values that match your workload before going to production.

Chart 3.0.0 also removes default limits. Running without limits is not recommended, since it allows workloads to starve others on the same cluster. See the Kubernetes documentation on resource requests and limits for guidance on setting appropriate values. If you are unsure where to start, see Right-Sizing Kubernetes Resources for Connectware.

Component
Old (cpu/mem)
New (cpu/mem)

adminWebApp

100m / 50Mi

50m / 50Mi

authServer

1500m / 1000Mi

1000m / 500Mi

broker

2000m / 3000Mi

600m / 1000Mi

connectwareIngress

1000m / 500Mi

400m / 250Mi

containerManager

250m / 200Mi

150m / 200Mi

ingressController

100m / 100Mi

150m / 100Mi

nats

2000m / 2000Mi

500m / 750Mi

postgresql

2000m / 2000Mi

500m / 750Mi

protocolMapper

2000m / 2000Mi

1000m / 1000Mi

resourceStatusTracking

1000m / 1000Mi

250m / 500Mi

serviceManager

1000m / 1000Mi

1000m / 500Mi

systemControlServer

200m / 200Mi

300m / 200Mi

topicExplorer

200m / 750Mi

200m / 500Mi

workbench

200m / 400Mi

150m / 200Mi

A9. CybusMQ Broker Value Changes

Why the Change?

Beyond the storage rename covered in A4 and the top-level move covered in A7, several CybusMQ broker keys were renamed or retyped.

What You Need to Do

Updating CybusMQ Broker Values

  • Rename replicaCount to replicas.

  • Rename messageQueueSize to onlineMessageQueueSize.

  • Convert allowRegisterDuringClusterFormation, allowPublishDuringClusterFormation, allowSubscribeDuringClusterFormation, and allowUnsubscribeDuringClusterFormation from the strings "on" or "off" to the booleans true or false.

  • Replace the clusterSecret placeholder <defineAnySecret> with a real value or an empty string "" to auto-generate. This upgrade requires completely stopping your cluster, which means it is possible to change the secret, as well as the approach to configuring it.

Before

After

A10. Auth-Server Default Replicas

Why the Change?

The default for authServer.replicas changed from 1 to 2 to improve availability.

What You Need to Do

Setting the Old Replica Count

If your values.yaml file does not set authServer.replicas, the new default applies after the upgrade. To keep the old behavior, set the replica count explicitly:

A11. Reserved MFA Environment Variables

Why the Change?

Chart 3.0.0 introduces dedicated Helm values for the MFA issuer and label: global.authentication.mfa.issuer and global.authentication.mfa.label. Because the chart now sets these on the auth-server itself, the matching environment variables CYBUS_MFA_ISSUER and CYBUS_MFA_LABEL are reserved and stripped from any authServer.env list. Setting them via env no longer has any effect.

What You Need to Do

Migrating MFA Environment Variables to Helm Values

If you previously set CYBUS_MFA_ISSUER or CYBUS_MFA_LABEL through authServer.env, remove them from the env list and set the equivalent Helm values instead.

Environment Variable
Helm Value

CYBUS_MFA_ISSUER

global.authentication.mfa.issuer

CYBUS_MFA_LABEL

global.authentication.mfa.label

Before

After

A12. Workload Label Rename

Why the Change?

Workloads created by the connectware chart no longer carry the short app=<component> label. The chart now uses the standard Kubernetes recommended label app.kubernetes.io/name=<component> instead. This aligns the chart with Kubernetes recommended labels and matches what the connectware-agent chart already uses.

What You Need to Do

Updating External Workload Selectors

No changes to your values.yaml file are required. The upgrade works without action.

If you have external tooling that selects Connectware workloads through the old label, update the selector. Common examples:

  • kubectl commands using -l app=<component>.

  • Scripts, CI pipelines, or operators that filter pods, services, or other resources by app=<component>.

  • NetworkPolicy, PodMonitor, ServiceMonitor, or other resources whose selector or podSelector matches app=<component>.

  • Monitoring or logging configurations that group workloads by the app label.

Replace the selector with app.kubernetes.io/name=<component>. For example:

Before

After

A13. Ingress Service Ports for TCP IngressRoutes

Why the Change?

The connectware LoadBalancer Service is now fully configurable through connectwareIngress.service.ports. The new default port list only contains the core Connectware ports. The ports 40000 to 40009, which were previously exposed for Cybus::IngressRoute TCP resources, are no longer exposed unless you add them.

What You Need to Do

Adding TCP Ports for IngressRoutes

If you do not use Cybus::IngressRoute resources of type tcp, no action is required.

If you do, add an entry to connectwareIngress.service.ports for every connectwarePort your TCP IngressRoutes use. Ports between 40000 and 40100 are valid.

The list under connectwareIngress.service.ports fully replaces the default Service ports. When adding entries, keep the default Connectware ports from the chart's values.yaml and append your TCP ports, otherwise the Admin UI, MQTT, and other core entry points become unreachable.

A14. NATS Metrics Path Change

Why the Change?

The intermediate prometheus block under NATS metrics is gone. The exporter sidecar configuration (enabled, resources) and the ServiceMonitor configuration now live directly under nats.metrics.

What You Need to Do

Moving NATS Metrics Keys

If you configured NATS metrics, move every key from global.nats.metrics.prometheus.* up one level to nats.metrics.*. The global.nats → nats move from A7. Components Moved Out of global applies here as well.

Old
New

global.nats.metrics.prometheus.enabled

nats.metrics.enabled

global.nats.metrics.prometheus.resources

nats.metrics.resources

global.nats.metrics.prometheus.serviceMonitor.*

nats.metrics.serviceMonitor.*

Before

After

Part B: Connectware-Agent Chart Migration

Chart 3.0.0 removes built-in agent orchestration from the connectware chart and replaces it with the connectware-agent chart, embedded as a subchart. The following steps cover both migrating agents from the old connectware chart and updating existing subchart installations.

After the upgrade, you must re-register any agents that were scheduled with the connectware chart. See Post-Upgrade Actions.

Apply the following changes to your connectware-agent or connectware chart values. Not all sections apply to both deployment modes. Check the table below before working through them. Sections with mode-specific examples use Standalone and Subchart tabs:

Section
Standalone
Subchart

B1. Protocol-Mapper Agents Structure

No changes

Required

B2. Image Version

Required

No changes

B3. Security Contexts

Required

Required

B4. Storage to Persistence

No changes

Required

B5. TLS CA Configuration Renames

Required

Required

B6. Reserved Environment Variables

Required

Required

B7. Resource Defaults

Required

Required

B8. Cluster Resource Name Changes

Required

Required

B1. Protocol-Mapper Agents Structure

Why the Change?

Chart 3.0.0 replaces the built-in agent templates under global.protocolMapperAgents with the connectware-agent subchart. Subchart users now configure agents through connectwareAgent.* instead of global.*, and gain access to the protocolMapperAgentDefaults mechanism that standalone connectware-agent Helm chart already uses.

Standalone connectware-agent users are not affected by this restructuring. The per-key renames in B2 through B6 still apply, but the overall protocolMapperAgents / protocolMapperAgentDefaults layout is unchanged.

What You Need to Do

This section applies to subchart users only. Move global.protocolMapperAgents to connectwareAgent.protocolMapperAgents. The connectwareAgent.protocolMapperAgentDefaults block is now available for values shared across agents.

Connectware treats migrated agents as new entities after the upgrade. After the Helm upgrade completes, you must de-register the old agents and register the new ones. See Post-Upgrade Actions.

Promoting Shared Values to protocolMapperAgentDefaults

Optional but recommended when you have multiple agents. Override precedence is: schema defaults, then protocolMapperAgentDefaults, then per-agent entry. Each agent entry then only needs its name plus its overrides. For full semantics, see Configuration Principles for the connectware-agent Helm Chart.

A subset of keys also inherits from the parent connectware chart's global.* values when not set on the agent or its defaults. This applies to security contexts, image values other than image.name, podPriorityClassName, nodeSelector, and tolerations. The effective precedence in that case is: schema defaults, then inherited global.* values from the connectware chart, then protocolMapperAgentDefaults, then per-agent entry.

To promote shared values:

  1. Identify values that are identical across every agent, such as env, connectwareHost, tls.ca, mTLS.enabled, persistence.storageClassName, and resources.

  2. Move those values into protocolMapperAgentDefaults.

  3. Leave only the per-agent overrides plus name in each protocolMapperAgents entry.

Some keys are always agent-specific and have no default counterpart: name, mTLS.keyPair, and existingAgentPasswordSecret. Keep them on the agent entry.

Simple Example (Two Agents, Shared env)

Before

After (shared env promoted)

Advanced Example (Shared CA, Security Context, and Storage Class)

Agents share env, tls.ca.cert, storageClassName, and containerSecurityContext, but differ in storageSize.

Before

After

In this example, containerSecurityContext matches the 3.0.0 default, so the block was dropped entirely. If your block had only partially overridden the default, you would merge it by hand as described in B3. Security Contexts.

B2. Image Version

Why the Change?

The value controls the container image tag used, not necessarily a version. It is now aligned with the Kubernetes convention, matching the rename in A2. Image Version.

What You Need to Do

This section applies to standalone connectware-agent users only. Subchart users were previously unable to control image settings for agents. They can now use the values provided by the connectware-agent subchart, or let the chart fall back on the global connectware chart image tag in global.image.tag , which is already covered by A2. Image Version.

Renaming the Image Key

  • Rename image.version to image.tag.

Before

After

B3. Security Contexts

Why the Change?

Per-agent security context keys were renamed to use Override suffixes, matching the convention introduced in A3. Security Contexts.

Override values replace defaults, they do not merge

A partial override strips any default it does not redeclare. If you customized a per-agent security context, your migrated output must include both the new 3.0.0 defaults (listed in A3) and your customizations, merged by hand.

What You Need to Do

Per agent, in each entry under protocolMapperAgents:

  • securityContext → podSecurityContextOverride

  • containerSecurityContext → containerSecurityContextOverride

You can also use the protocolMapperAgentDefaults.podSecurityContextOverride and protocolMapperAgentDefaults.containerSecurityContextOverride block to set security context for all agents.

If your source security context block exactly matches the 3.0.0 defaults from A3, drop the block instead of emitting an override.

Before

After

B4. Storage to Persistence

Why the Change?

Per-agent storage keys of the connectware chart were folded into a persistence block by migrating to the connectware-agent chart as a subchart, matching the rename in A4. Storage to Persistence. You can also use the connectwareAgent.protocolMapperAgentDefaults.persistence block to set persistence for all agents.

What You Need to Do

Per agent, in each entry under protocolMapperAgents:

Old
New

storageSize

persistence.size

storageClassName

persistence.storageClassName

No changes are required when upgrading a standalone connectware-agent installation.

B5. TLS CA Configuration Renames

Why the Change?

The key holding the CA certificate body was renamed to reflect that it accepts a full certificate chain. The legacy mTLS.caChain.* path is also gone — previously it was kept for backwards compatibility and is now removed. Move all CA configuration under tls.ca.*.

What You Need to Do

Per agent, in each entry under protocolMapperAgents, and in protocolMapperAgentDefaults if you use it:

Old
New

tls.ca.cert

tls.ca.certChain

mTLS.caChain.cert

tls.ca.certChain

mTLS.caChain.existingConfigMap

tls.ca.existingConfigMap

Before

After

B6. Reserved Environment Variables

Why the Change?

Chart 3.0.0 strips a fixed set of environment variables from any user-supplied env list before they reach the agent pod. These names are reserved for the chart to set internally, so that agent identity, connectivity, and security cannot be silently misconfigured. Previously, user overrides could be applied or ignored; now they are always filtered. Use the Helm values we provide if you previously set one of these environment variables.

What You Need to Do

Remove the following names from every env list, including each entry under protocolMapperAgents and protocolMapperAgentDefaults if you use it:

  • CYBUS_AGENT_MODE

  • CYBUS_AGENT_NAME

  • CYBUS_HOSTNAME_INGRESS

  • CYBUS_PROTOCOL_MAPPER_PASSWORD

  • CYBUS_USE_MUTUAL_TLS

  • Any name starting with CYBUS_DATAPLANE_

  • Any name starting with CYBUS_STREAMSERVER_

Custom variables you set through env are unaffected. Only the names above and the two prefixes are filtered.

Helm Values to Use Instead

The following table shows how to control these environment variables with the connectware-agent Helm chart.

Environment Variable
Helm Value

CYBUS_AGENT_MODE

Always set to "distributed", do not set manually

CYBUS_AGENT_NAME

protocolMapperAgents[*].name

CYBUS_HOSTNAME_INGRESS

protocolMapperAgents[*].connectwareHost or protocolMapperAgentDefaults.connectwareHost

CYBUS_PROTOCOL_MAPPER_PASSWORD

Read from key agentPassword in the existing Kubernetes Secret configured in protocolMapperAgents[*].existingAgentPasswordSecret or protocolMapperAgentDefaults.existingAgentPasswordSecret

CYBUS_USE_MUTUAL_TLS

protocolMapperAgents[*].mTLS.enabled

CYBUS_DATAPLANE_HOST

protocolMapperAgents[*].dataPlane.host, protocolMapperAgentDefaults.dataPlane.host, protocolMapperAgents[*].connectwareHost or protocolMapperAgentDefaults.connectwareHost

CYBUS_DATAPLANE_PORT

Computed or overridden with protocolMapperAgents[*].dataPlane.port or protocolMapperAgentDefaults.dataPlane.port

CYBUS_DATAPLANE_SCHEME

Computed, do not set manually

CYBUS_DATAPLANE_USE_TLS

Computed or overridden with protocolMapperAgents[*].dataPlane.tls or protocolMapperAgentDefaults.dataPlane.tls

CYBUS_STREAMSERVER_HOST

protocolMapperAgents[*].streamServer.host, protocolMapperAgentDefaults.streamServer.host, protocolMapperAgents[*].connectwareHost or protocolMapperAgentDefaults.connectwareHost

CYBUS_STREAMSERVER_PORT

Computed or overridden with protocolMapperAgents[*].streamServer.port or protocolMapperAgentDefaults.streamServer.port

CYBUS_STREAMSERVER_SCHEME

Computed, do not set manually

Before

Reserved name CYBUS_AGENT_MODE listed alongside a custom variable:

After

Reserved name removed, custom variable kept:

B7. Resource Defaults

Why the Change?

Chart 3.0.0 halves the default CPU and memory requests and removes the default limits for protocol-mapper agents, matching the change made for connectware chart components in A8. Resources Moved to Per-Component. Additionally, for agents orchestrated using the connectware chart, the compute resource requests and limits need to be moved to the Helm values provided by the connectware-agent chart.

Resource Field
Old (chart 2.x)
New (chart 3.0.0)

requests.cpu

2000m

1000m

requests.memory

2000Mi

1000Mi

limits.cpu

2000m

not set

limits.memory

2000Mi

not set

The same reasoning applies as in A8. Resources Moved to Per-Component: lower defaults do not reflect lower resource requirements, and running without limits in production is not recommended.

This affects both standalone and subchart deployments. If your values.yaml file does not set agent resources, your agents will receive the new, lower default requests and no default limits after the upgrade. Set the old values explicitly if your workloads require them.

What You Need to Do

If you set per-agent or protocolMapperAgentDefaults resources directly in standalone mode, your values carry over unchanged.

Subchart users only: if you previously set global.podResources.distributedProtocolMapper in the connectware chart, migrate it to connectwareAgent.protocolMapperAgentDefaults.resources as described in A8. Resources Moved to Per-Component.

If you relied on the chart-level defaults, decide whether to keep the previous values or adopt the new defaults. To keep the previous behavior, set the old chart 2.x defaults explicitly on each agent or on protocolMapperAgentDefaults.

Before

values.yaml contained a default of 2000m / 2000Mi for both requests and limits.

After

Set the previous values explicitly if you relied on these compute resource defaults:

B8. Cluster Resource Name Changes

Why the Change?

Chart 3.0.0 replaces the helper that builds Kubernetes resource names for protocol-mapper agents. Most installations are unaffected, but a few naming patterns produce a different result on upgrade.

The patterns that produce a different name in chart 3.0.0:

  • The release name connectware. The duplicated prefix connectware-connectware-agent-<agent> collapses to connectware-agent-<agent>. Affects every agent under that release. If you have used the name connectware for a connectware-agent chart installation, set the fullNameOverride Helm value to connectware-connectware-agent.

  • Long combined release-plus-agent names. The new helper truncates the combined name at 52 characters with a fixed split between chart and agent name, instead of the old 63-character single truncation. Names that previously hit the old limit truncate differently.

StatefulSet selectors are immutable in Kubernetes

If any of the patterns above apply to your installation, helm upgrade fails on the rename and the existing PersistentVolumeClaims are orphaned. Detect this before upgrading.

If none of these patterns apply to your release name or agent names, you do not need to take any action for this section. Continue to Running the Upgrade.

Detecting Renames Before You Upgrade

Use the helm-diff plugin to compare the rendered output of the new chart version against the cluster state before applying the upgrade.

Substitute the following placeholders:

  • ${NAMESPACE}: the namespace of the installation.

  • ${INSTALLATION_NAME}: the name of the Helm release.

  • <values.yaml>: the path to the migrated values.yaml file.

If the diff shows a StatefulSet, Service, or PersistentVolumeClaim renaming for any agent, stop and contact support before continuing. Resolving the rename requires deleting the old resources by hand, recreating them under the new name, and migrating data from the orphaned PVCs.

Complete Before-and-After Examples

Use these as a reference for the overall output shape.

Connectware Chart

Before (chart 2.1.0 values)
After (chart 3.0.0 values)

Connectware-Agent Chart

Before (chart 2.1.0 values)

After (chart 3.0.0 values)

Running the Upgrade

After migrating your values.yaml file or files, run the Helm upgrade.

Verifying Your Backups

Make sure you have backups of the following before running the upgrade:

  • All Kubernetes PersistentVolumes that Connectware uses

  • Your Connectware database. See Backing Up the Connectware Database.

  • Your values.yaml file or files

  • All service commissioning files

Running the Helm Upgrade

Follow the steps for the chart you are upgrading.

Some changes in this release cannot be applied through a rolling restart, so you must fully stop Connectware before running the upgrade.

1. Shutting Down Connectware

Delete all workload controllers:

2. Running the Helm Upgrade

Substitute the following placeholders:

  • ${NAMESPACE}: the namespace of the installation.

  • ${INSTALLATION_NAME}: the name of the Helm release.

  • <values.yaml>: the path to the migrated values.yaml file.

Monitoring the Upgrade

Monitor pod status while the upgrade runs.

Each pod passes through the following stages: Terminating, Pending, PodInitializing, ContainerCreating, Init:x/x, and finally Running. The upgrade is complete when all pods report Running and show the same number on both sides of the slash in the READY column.

See Verifying the Connectware Upgrade for additional details on how to monitor the upgrade.

Post-Upgrade Actions

Two tasks remain before your deployment is fully operational: re-registering migrated agents and reviewing resource usage.

Re-Registering Protocol-Mapper Agents

This applies if you moved agents from global.protocolMapperAgents to connectwareAgent.protocolMapperAgents in B1.

After the Helm upgrade, Connectware still holds the old agent identities — one user entry in Users View and one entry in the Agents View per agent. The new agent pods start up with fresh credentials and attempt to register, but the old entries block them. You must clean up the old entries first, then authorize the new registrations.

Repeat the following steps for each migrated agent:

  1. In the Admin UI, delete the user whose name matches the agent. This clears the old credentials so the new agent can register under the same name.

  2. In the Agents View, select the old agent and click Delete to remove it from the list.

  3. The agent pod registers automatically after the old entries are removed. In the Admin UI, open the Client Registry and authorize the pending registration for each agent. Check the agent name and pairing ID to confirm you are authorizing the correct agent.

  4. Confirm each agent comes back online in System > System Status > Agents.

Reviewing Resource Requests

If you did not set explicit resource values in A8 or B7, your workloads now run with the chart 3.0.0 defaults: reduced CPU and memory requests with no limits set. Monitor resource usage and set explicit values on affected components if you observe throttling or eviction.

PreviousUpgrading Connectware (Kubernetes)NextUpgrading Connectware to 2.4.0 (Kubernetes)

Last updated

Was this helpful?