Revision as of 03:57, November 6, 2024 by Xavier (talk | contribs)
Jump to: navigation, search

Upgrading Cassandra to 4.1.4

Genesys Interaction Recording Web Services (GIR RWS) version 8.5.205.64 (or higher) supports Cassandra 4.1.4 only.

If you are using Cassandra 2.2, you must upgrade to Cassandra 4.1.4. Upgrading directly from 2.2.x to 4.1.4 is not supported. You must upgrade your Cassandra versions incrementally for schema portability, for example, from version 2.2.x -> 3.11.11 -> 4.1.4.

For more information about upgrading Cassandra, refer the Upgrade to Cassandra 4.1.4 section.

Important

No screen recordings are made during the upgrade of Cassandra.

To minimize the risk of losing screen recordings, upgrade Cassandra during off-hours. It’s a best practice to perform a cluster upgrade during a scheduled maintenance window that occurs when application loads are typically lower. During the migration, GIR still operates with voice recording capabilities. After the Cassandra cluster is back in service, you can process the metadata information for voice recordings that was saved during the migration by initiating the recovery procedure of the Recording Processor Script.

Pre-requisites:

  1. Ensure that the Recording Processor Script (RPS) and Recording Web Services (RWS) nodes debug level logs are stored for any debugging or troubleshooting issues related to migration.
  2. Back up all your Cassandra configuration files.
  3. Take snapshots of all keyspaces on each existing Cassandra node. For more information, refer Cassandra Documentation.
  4. Confirm that your Cassandra environment satisfies all of the necessary prerequisites.

Upgrade to Cassandra 4.1.4:

The following section provides the instructions for performing in-place upgrade from Cassandra 2.2.X to Cassandra 4.1.4. The recommendation procedure should be followed for quicker rollback and minimal downtime.

Recommendation:

Warning
Genesys is not responsible for migration of existing data to the replicated Cassandra cluster on premise environments.
  1. Create a replica of existing Cassandra 2.2 cluster with the data. For more information refer to Cassandra Documentation.
  2. Ensure that replicated Cassandra 2.2 cluster data is validated with existing RWS nodes by updating the following parameters in application.yaml .

nodes: [ToBeChanged: <CASSANDRA_PRIMARY_DC_NODES>] and backup_nodes: [ToBeChangedOrRemoved: <CASSANDRA_BACKUP_DC_NODES>] to respective replicated nodes. For more information, check RWS Options for cassandraCluster.

  1. Execute Migration plan on replicated Cassandra 2.2 new Cluster.

Migration Plan:

  1. Stop all Interaction Recording Web Services nodes.

  2. Run the schema upgrade application. This will be packaged with the RWS IP installation files.
    This application need to be run against one of the Cassandra 2.2 cluster nodes.
    java -jar upgrade.jar [options]
    options:
    -cassandraHost <host> - required, no default
    -thriftPort <port number> - optional, default=9160
    -nativePort <port number> - optional, default=9042
    -keyspace <keyspace name> - optional, default=sipfs
    -datacenter <datacenter name> - optional, default=datacenter1. The required value can be found via “nodetool status”.
    -cassandraUser <username> - optional, but required if -cassandraPassword is set in cassandra.yaml
    -cassandraPassword <password> - optional, but required if -cassandraUser is set in cassandra.yaml
    Example: java -jar upgrade.jar -cassandraHost <hostname> -datacenter DC1

    Earlier versions of RWS communicated with Cassandra 2 using the thrift protocol. Cassandra has discontinued support for the thrift protocol, so the new version of RWS uses CQL. The upgrade application will make schema changes to the call_recording_by_contact_center table and all call/screen recording and log tables referenced by this table so that the data inserted via thrift will be available via CQL.

  3. Perform Cassandra upgrade according to the Cassandra Upgrade Guide.

  4. When configuring Cassandra 4.1.4, you must set the following both parameters in the cassandra.yaml file:

    • batch_size_warn_threshold to 200KiB
    • batch_size_fail_threshold to 250KiB
    • Save and apply all the changes.
      These parameters are related to the size of CQL batches. The default for these parameters is quite low and need to be increased to accommodate RWS inserts and update batches.

  5. Upgrade the Interaction Recording Web Service nodes to the latest IP version.

  6. Change the following parameters in application.yaml of Interaction Recording Web Service nodes.
    remove thrift_port, add native_transport_port, dataCenterName, backupDataCenterName, switchOverUnHealthyNodes and set cassandraVersion to 4.1.4

    • The native_transport_port is the port used by CQL. The default is 9042. This is required if not using the default port.
    • The dataCenterName is the name of the primary datacenter used by the new CQL driver The needed value can be found by running “nodetool status” on the cassandra instance. The default value is datacenter1. This is required if not using the default datacenter name.
    • The backupDataCenterName is the name of the secondary datacenter used by the new CQL driver if there is a secondary datacenter. The needed value can be found by running “nodetool status” on the cassandra instance. The default value is datacenter1. This is required if using a secondary datacenter and not using the default secondary datacenter name.
    • The switchOverUnHealthyNodes is the number of nodes in the primary cassandra datacenter that need to fail before RWS will attempt to switch to the backup datacenter. The default value is -1, meaning that no attempt to switchover will be made. This is required if using a secondary datacenter.
    • The cassandraVersion is the version of cassandra being run. The default value is 4.1.4.
    • Save and apply all the changes.

  7. Start all Interaction Recording Web Service nodes. Validate the health of RWS and Cassandra.

  8. After the upgrade, run the LVR Recovery Script to recover recordings from the each Recording Processor Script failed folder and repost the recordings to Interaction Recording Web Services, as failed voice recordings accumulate while the Cassandra cluster is unavailable.

Rollback:

If we are seeing unresolved errors at any phase of the migration, please rollback back the Interaction Recording Web Service nodes to the previous RWS version and previous existing Cassandra 2.2 cluster until the issue is resolved.

Limitation:

If rollback is performed once the migration procedure is done and new voice recordings are directed to Cassandra 4.1.4, the following scenarios will result in errors :

  • Playback of the new recordings
  • Backup and purge of the new recordings
  • Querying of the new recordings through API.
Comments or questions about this documentation? Contact us for support!