> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/1-11-0/documentation/installation-and-upgrades/upgrading-connectware/upgrading-connectware-kubernetes/version-specific-upgrades-kubernetes.md).

# Version-Specific Upgrades (Kubernetes)

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

{% hint style="info" %}
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.11.0)
* [Upgrading Connectware to 1.7.0](#upgrading-connectware-to-1.7.0)
* [Upgrading from Connectware 1.x to 1.5.0](#upgrading-connectware-from-1.x-to-1.5.0)
  {% endhint %}

## Upgrading Connectware to 1.11.0

{% hint style="danger" %}
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.
{% endhint %}

{% hint style="info" %}
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.
{% endhint %}

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](#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](#upgrading-connectware-from-1.x-to-1.5.0) and [Upgrading Connectware to 1.7.0](#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

{% stepper %}
{% step %}

#### 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.
{% endstep %}

{% step %}

#### 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](#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:

{% code lineNumbers="true" %}

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

{% endcode %}
{% endstep %}

{% step %}

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

{% hint style="info" %}
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.
{% endhint %}

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

{% code lineNumbers="true" %}

```yaml
global:
    ingressDnsNames:
        - company.io
```

{% endcode %}

**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**

{% code lineNumbers="true" %}

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

{% endcode %}
{% endstep %}

{% step %}

#### 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**

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

{% endstep %}

{% step %}

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

{% code lineNumbers="true" %}

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

{% endcode %}

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

{% code lineNumbers="true" %}

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

{% endcode %}

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

{% hint style="warning" %}
`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.
{% endhint %}

| 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
  {% endstep %}

{% step %}

#### 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`.

```yaml
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**

{% code lineNumbers="true" %}

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

{% endcode %}

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

{% hint style="warning" %}
`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.
{% endhint %}

| 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
  {% endstep %}

{% step %}

#### Upgrading Connectware to 1.11.0

* To upgrade Connectware to 1.11.0, see [Upgrading Connectware (Kubernetes)](broken://pages/061V20RfsUsygAPD5tim).
  {% endstep %}
  {% endstepper %}

## 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](#upgrading-from-1x-to-150) 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](https://www.cybus.io/learn/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.

{% hint style="info" %}
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.
{% endhint %}

### 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

{% stepper %}
{% step %}
**Creating YAML Snippets for relevant PersistentVolumeClaim names**

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

{% code lineNumbers="true" %}

```yaml
#!/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"
```

{% endcode %}

2. Select the target environment:

{% code lineNumbers="true" %}

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

{% endcode %}

3. Make the script executable and run it:

{% code lineNumbers="true" %}

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

{% endcode %}

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

Example output:

{% code lineNumbers="true" %}

```yaml
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
```

{% endcode %}
{% endstep %}

{% step %}
**Updating and Applying the Kubernetes Job**

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

{% code lineNumbers="true" %}

```yaml
---
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
```

{% endcode %}

2. Open `kubernetes-job.yml` and integrate the output of the `create-pvc-yaml.sh` script.
3. Shut down all Connectware and agent pods:

{% code lineNumbers="true" %}

```yaml
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
```

{% endcode %}

4. Apply the job to change permissions:

{% code lineNumbers="true" %}

```yaml
kubectl apply -f kubernetes-job.yml
```

{% endcode %}
{% endstep %}

{% step %}
**Verifying and Cleaning Up**

1. Check the job logs for confirmation:

{% code lineNumbers="true" %}

```yaml
kubectl logs -f job/connectware-fix-permissions
```

{% endcode %}

**Example output**

{% code lineNumbers="true" %}

```yaml
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.
```

{% endcode %}

2. Delete the Kubernetes job afterward:

{% code lineNumbers="true" %}

```yaml
kubectl delete -f kubernetes-job.yml
```

{% endcode %}

3. Delete outdated Kubernetes services:

{% code lineNumbers="true" %}

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

{% endcode %}
{% endstep %}

{% step %}
**Upgrading Connectware**

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

{% code lineNumbers="true" %}

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

{% endcode %}

2. 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.
{% endstep %}
{% endstepper %}

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cybus.io/1-11-0/documentation/installation-and-upgrades/upgrading-connectware/upgrading-connectware-kubernetes/version-specific-upgrades-kubernetes.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.