Version-Specific Upgrades (Kubernetes)

Some Connectware upgrades require you to follow a few additional steps when upgrading Connectware to a newer version.

When upgrading your Connectware instance, follow the required upgrade path based on your current version:

• If you are running Connectware version 1.0.0 to below 1.5.0:

  1. First upgrade to version 1.5.0

  2. Then upgrade to version 1.7.0

  3. Finally upgrade to version 1.11.0 or later

• If you are running Connectware version 1.5.0 to below 1.7.0:

  1. First upgrade to version 1.7.0

  2. Then upgrade to version 1.11.0 or later

• If you are running Connectware version 1.7.0 to below 1.11.0:

  • You can directly upgrade to version 1.11.0 or later

For detailed instructions on each upgrade step, refer to:

• Upgrading Connectware to 1.11.0

• Upgrading Connectware to 1.7.0

• Upgrading from Connectware 1.x to 1.5.0

Upgrading Connectware to 1.11.0

We have identified a critical bug in this release. Please do not upgrade to 1.11.0. We are working on a fix that will be released soon.

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.

1. Network Port Requirements: Make ports TCP/4222 and TCP/4223 accessible both within Connectware and by agents.

2. 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.

3. Configure DNS Names: Define the hostnames and IPs that will be included in the NATS Server certificate.

4. Resource Configuration: Specify Kubernetes resource limits for nats and resource-status-tracking services.

5. Update Connectware Helm Chart: Configure the Control Plane URI and certificates.

6. Update Agent Helm Chart: Configure the Control Plane URI and certificates.

7. 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 and nats) 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

1

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.

2

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:

1. Do NOT proceed with the upgrade until you've completed Configuring DNS Names in Helm Values.
2. When updating DNS names, you must add the DNS name used by external agents to connect to Connectware.

3. 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:

1. 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.

2. 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.

3. Certificate protection (optional): To prevent your custom certificate from being replaced during the upgrade, set the environment variable CYBUS_DISABLE_NATS_CERTIFICATE_CHECKS to true on the system-control-server by configuring the following Helm values:

global:
    systemControlServer:
        env:
            - name: CYBUS_DISABLE_NATS_CERTIFICATE_CHECKS
              value: 'true'

3

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.

This certificate configuration only affects the cybus_nats_server.crt file. Any hostnames that you specify in the global.ingressDnsNames list will not be included in the cybus_server.crt certificate that is used by other services such as the Admin UI.

• 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:

global:
    ingressDnsNames:
        - company.io

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

global:
    ingressDnsNames:
        - company.io
        - localhost
        - *.company.io
        - connectware.company.io
        - 192.168.100.42

4

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

global:
    podResources:
        nats:
            limits:
                cpu: 2000m
                memory: 2000Mi
            requests:
                cpu: 2000m
                memory: 2000Mi
        resourceStatusTracking:
            limits:
                cpu: 1000m
                memory: 1000Mi
            requests:
                cpu: 1000m
                memory: 1000Mi

5

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:

1. Set the Helm value global.protocolMapperAgents[*].controlPlane.host to the hostname of the Connectware Control Plane for your agent:

global:
    protocolMapperAgents:
        - myAgent:
              controlPlane:
                  host: connectware.mycompany.tld

1. If you want to adjust the scheme or port for the CYBUS_CONTROLPLANE_URI, you can specify a full URI in global.protocolMapperAgents[*].controlPlane.host:

global:
    protocolMapperAgents:
        - myAgent:
              controlPlane:
                  host: nats://connectware.mycompany.tld:10422

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 entirely

• Authenticate 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:

Old path	New path
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

6

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 from protocolMapperAgentDefaults.connectwareHost.

protocolMapperAgentDefaults:
    controlPlane:
        host: connectware.mycompany.tld

• If you want to adjust the scheme or port for the CYBUS_CONTROLPLANE_URI, you can specify a full URI in protocolMapperAgentDefaults.controlPlane.host instead of protocolMapperAgentDefaults.connectwareHost.

Example

protocolMapperAgentDefaults:
    controlPlane:
        host: nats://connectware.mycompany.tld:10422

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 entirely

• Authenticate 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

Old path	New path
protocolMapperAgentDefaults.mTLS.caChain.cert	protocolMapperAgentDefaults.tls.ca.certChain
protocolMapperAgentDefaults.mTLS.caChain.existingConfigMap	protocolMapperAgentDefaults.tls.ca.existingConfigMap

• Individual Agent Configuration

Old path	New path
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

7

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

1. 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.
2. 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.

3. Delete the broker and control-plane-broker data volumes. Log volumes do not have to be deleted.

4. If you are using multi-factor authentication (MFA), set the Helm value global.authentication.mfa.enabled to true.

5. 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.

Connectware 1.5.0 introduces a significant change regarding container privileges. Now, containers are started without root privileges. This change causes an issue where files that persisted on volumes that were created by a user other than the one accessing them, cannot easily have their permissions changed. As a result, this upgrade requires the admin to manually update the permissions.

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 installation

• Helm version 3 installed on your system

• Cybus Helm repository added for access to:

  • Connectware Helm chart connectware in version 1.5.0.

  • Connectware Agent Helm chart connectware-agent in version 1.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.

1. 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.

2. 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.

3. Update the Kubernetes job file: Integrate the snippets into the kubernetes-job.yml file as described.

4. 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.

5. 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.

6. 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.

7. 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 to 770.

  • For postgresql set ownership to 70:0 and permissions to 770.

• 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

1

Creating YAML Snippets for relevant PersistentVolumeClaim names

1. Create a script named create-pvc-yaml.sh containing the following:

#!/usr/bin/env bash
#
# Creates a Kubernetes resource list of volumeMounts and volumes for Connectware (agent) deployments
#
function usage {
    printf "Usage:n"
    printf "$0 [--kubeconfig|-kc <kubeconfig_file>] [--context|-ctx <target_context>] [--namespace|-n <target_namespace>] [--no-external-agents] [--no-connectware]n"
    exit 1
}

function argparse {

  while [ $# -gt 0 ]; do
    case "$1" in
      --kubeconfig|-kc)
        # a kube_config file for the Kubernetes cluster access
        export KUBE_CONFIG="${2}"
        shift
        ;;
      --context|-ctx)
        # a KUBE_CONTEXT for the Kubernetes cluster access
        export KUBE_CONTEXT="${2}"
        shift
        ;;
      --namespace|-n)
        # the Kubernetes cluster namespace to operate on
        export NAMESPACE="${2}"
        shift
        ;;
      --no-external-agents)
        export NO_EXTERNAL_AGENTS=true
        shift
        ;;
      --no-connectware)
        export NO_CONNECTWARE=true
        shift
        ;;
      *)
        printf "ERROR: Parameters invalid"
        usage
    esac
    shift
  done
}

#
# init
export NO_EXTERNAL_AGENTS=false
export NO_CONNECTWARE=false
export KUBECTL_BIN=$(command -v kubectl)

argparse $*

shopt -s expand_aliases
# Check for kubectl paramaters and construct the ${KUBECTL_CMD} command to use
if [ ! -z $KUBE_CONFIG ]; then
  KUBECONFIG_FILE_PARAM=" --kubeconfig=${KUBE_CONFIG}"
fi
if [ ! -z $KUBE_CONTEXT ]; then
  KUBECONFIG_CTX_PARAM=" --context=${KUBE_CONTEXT}"
fi
if [ ! -z $NAMESPACE ]; then
  NAMESPACE_PARAM=" -n${NAMESPACE}"
fi

KUBECTL_CMD=${KUBECTL_BIN}${KUBECONFIG_FILE_PARAM}${KUBECONFIG_CTX_PARAM}${NAMESPACE_PARAM}

volumes=$(${KUBECTL_CMD} get pvc -o name | sed -e 's/persistentvolumeclaim///g' )
valid_pvcs=""
volume_yaml=""
volumemounts_yaml=""

if [[ "${NO_CONNECTWARE}" == "false" ]]; then
  valid_pvcs=$(cat << EOF
system-control-server-data
certs
brokerdata-*
brokerlog-*
workbench
postgresql-postgresql-*
service-manager
protocol-mapper-*
EOF
)
fi

if [[ "${NO_EXTERNAL_AGENTS}" == "false" ]]; then
  # Add volumes from agent Helm chart
  pvc_volumes=$(${KUBECTL_CMD} get pvc -o name -l connectware.cybus.io/service-group=agent | sed -e 's/persistentvolumeclaim///g' )
  valid_pvcs="${valid_pvcs}
  ${pvc_volumes}"
fi

# Collect volumeMounts
for pvc in $volumes; do
  for valid_pvc in $valid_pvcs; do
      if [[ "$pvc" =~ $valid_pvc ]]; then
        volumemounts_yaml="${volumemounts_yaml}
          - name: $pvc
            mountPath: /mnt/connectware_$pvc"
        break
      fi
  done
done

# Collect volumes
for pvc in $volumes; do
  for valid_pvc in $valid_pvcs; do
      if [[ "$pvc" =~ $valid_pvc ]]; then
        volume_yaml="${volume_yaml}
        - name: $pvc
          persistentVolumeClaim:
            claimName: $pvc"
          break
      fi
  done
done


# print volumeMounts
echo
echo "Copy this as the "volumeMounts:" section:"
echo "######################################"
echo -n "        volumeMounts:"
echo "$volumemounts_yaml"

# print volumes
echo
echo "Copy this as the "volumes:" section:"
echo "######################################"
echo -n "      volumes:"
echo "$volume_yaml"

1. Select the target environment:

kubectl config use-context <my-cluster>
kubectl config set-context --current --namespace <my-connectware-namespace>

1. Make the script executable and run it:

chmod u+x create-pvc-yaml.sh
./create-pvc-yaml.sh

1. Review the output to confirm only relevant volumes are listed.

Example output:

Copy this as the "volumeMounts:" section:
    ######################################
    volumeMounts:
        - name: brokerdata-broker-0
          mountPath: /mnt/connectware_brokerdata-broker-0
        - name: brokerdata-control-plane-broker-0
          mountPath: /mnt/connectware_brokerdata-control-plane-broker-0
        - name: brokerlog-broker-0
          mountPath: /mnt/connectware_brokerlog-broker-0
        - name: brokerlog-control-plane-broker-0
          mountPath: /mnt/connectware_brokerlog-control-plane-broker-0
        - name: certs
          mountPath: /mnt/connectware_certs
        - name: postgresql-postgresql-0
          mountPath: /mnt/connectware_postgresql-postgresql-0
        - name: protocol-mapper-agent-001-0
          mountPath: /mnt/connectware_protocol-mapper-agent-001-0
        - name: service-manager
          mountPath: /mnt/connectware_service-manager
        - name: system-control-server-data
          mountPath: /mnt/connectware_system-control-server-data
        - name: workbench
          mountPath: /mnt/connectware_workbench

Copy this as the "volumes:" section:
    ######################################
    volumes:
        - name: brokerdata-broker-0
          persistentVolumeClaim:
              claimName: brokerdata-broker-0
        - name: brokerdata-control-plane-broker-0
          persistentVolumeClaim:
              claimName: brokerdata-control-plane-broker-0
        - name: brokerlog-broker-0
          persistentVolumeClaim:
              claimName: brokerlog-broker-0
        - name: brokerlog-control-plane-broker-0
          persistentVolumeClaim:
              claimName: brokerlog-control-plane-broker-0
        - name: certs
          persistentVolumeClaim:
              claimName: certs
        - name: postgresql-postgresql-0
          persistentVolumeClaim:
              claimName: postgresql-postgresql-0
        - name: protocol-mapper-agent-001-0
          persistentVolumeClaim:
              claimName: protocol-mapper-agent-001-0
        - name: service-manager
          persistentVolumeClaim:
              claimName: service-manager
        - name: system-control-server-data
          persistentVolumeClaim:
              claimName: system-control-server-data
        - name: workbench
          persistentVolumeClaim:
              claimName: workbench

2

Updating and Applying the Kubernetes Job

1. Create a script named kubernetes-job.yml containing the following:

---
apiVersion: batch/v1
kind: Job
metadata:
    name: connectware-fix-permissions
    labels:
        app: connectware-fix-permissions
spec:
    backoffLimit: 3
    template:
        spec:
            restartPolicy: OnFailure
            imagePullSecrets:
                - name: cybus-docker-registry
            containers:
                - image: registry.cybus.io/cybus/connectware-fix-permissions:1.5.0
                  securityContext:
                      runAsUser: 0
                  imagePullPolicy: Always
                  name: connectware-fix-permissions
                  # Insert the volumeMounts section here
                  # volumeMounts:
                  # - name: brokerdata-broker-0
                  #   mountPath: /mnt/connectware_brokerdata-broker-0
                  resources:
                      limits:
                          cpu: 200m
                          memory: 100Mi
            # Insert the volumes section here
            # volumes:
            # - name: brokerdata-broker-0
            #   persistentVolumeClaim:
            #     claimName: brokerdata-broker-0

1. Open kubernetes-job.yml and integrate the output of the create-pvc-yaml.sh script.

2. Shut down all Connectware and agent pods:

kubectl scale sts,deploy -lapp.kubernetes.io/instance=<connectware-installation-name> --replicas 0
kubectl scale sts -lapp.kubernetes.io/instance=<connectware-agent-installation-name> --replicas 0

1. Apply the job to change permissions:

kubectl apply -f kubernetes-job.yml

3

Verifying and Cleaning Up

1. Check the job logs for confirmation:

kubectl logs -f job/connectware-fix-permissions

Example output

Found directory: connectware_brokerdata-broker-0. Going to change permissions
Found directory: connectware_brokerdata-broker-1. Going to change permissions
Found directory: connectware_brokerdata-control-plane-broker-0. Going to change permissions
Found directory: connectware_brokerdata-control-plane-broker-1. Going to change permissions
Found directory: connectware_brokerlog-broker-0. Going to change permissions
Found directory: connectware_brokerlog-broker-1. Going to change permissions
Found directory: connectware_brokerlog-control-plane-broker-0. Going to change permissions
Found directory: connectware_brokerlog-control-plane-broker-1. Going to change permissions
Found directory: connectware_certs. Going to change permissions
Found directory: connectware_postgresql-postgresql-0. Going to change permissions
Postgresql volume identified, using postgresql specific permissions
Found directory: connectware_service-manager. Going to change permissions
Found directory: connectware_system-control-server-data. Going to change permissions
Found directory: connectware_workbench. Going to change permissions
All done. Found 13 volumes.

1. Delete the Kubernetes job afterward:

kubectl delete -f kubernetes-job.yml

1. Delete outdated Kubernetes services:

kubectl delete svc -l app.kubernetes.io/instance=<connectware-installation-name>

4

Upgrading Connectware

1. Run the Helm command to upgrade Connectware to 1.5.0.

helm upgrade -n <namespace> <installation-name> <repo-name>/connectware --version 1.5.0 -f values.yaml

1. 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.