Terminology

  • The downlevel (software) version is the version being upgraded from.

  • The uplevel (software) version is the version being upgraded to.

  • The installed (software) version refers to the software currently running on the Rhino cluster, including any customizations, additions and patches that may have been made to deployable units, SLEE components and configuration.

  • Orca is the tool, delivered within the upgrade package, which drives the whole upgrade process, connecting to each of the hosts and running commands on them remotely.

  • A Deployable Unit (DU) is a packaged component that provides a particular feature of the software.

  • A (Rhino) cluster is a group of nodes with the same cluster ID. The cluster ID is an integer between 1 and 255 used to identify nodes that are linked together and share traffic. The cluster is backed by a PostgreSQL database containing the DUs and configuration. This architecture has the following implications, which are the fundamentals of the Cluster Migration Workflow design for upgrades:

    Important In the case of Sh Cache Microservice there is only ever one node in the cluster.

An upgrade can be one of two types: minor or major.

  • A minor upgrade is one where only the final component of the software version number changes, e.g. 1.0.0.1 to 1.0.0.2. It can include bugfixes, new minor functionality and new configuration, but the configuration schemas are always compatible with the downlevel software.

  • A major upgrade (supported in future ShCM releases) is one where any of the first three components of the version number changes, e.g. 1.0.0.1 to 1.1.0.0. It can include bugfixes, new features and new configuration. The new configuration may use a different schema, for example some profile spec IDs and profile table schemas may change. As such the configuration can not simply be imported from the downlevel cluster and needs to be transformed by orca so it is suitable for the uplevel cluster’s schema.

Both minor and major upgrades can include a new Rhino version. Major upgrades may also include a new version of Java. Where present, these are deployed automatically by orca at the appropriate point in the upgrade process.

  • orca is a command-line tool which can perform a variety of maintenance operations on Rhino clusters. It implements the Cluster Migration Workflow.

  • An upgrade bundle is a zip file containing the uplevel software, orca, any new Rhino and/or Java version, plus ancillary resources (such as feature script configuration) required during the upgrade process. Upgrade bundles are provided to customers by Metaswitch Customer Care.

  • A customization package is a package included in an upgrade bundle which applies customer-specific modifications to the product. They come in two types: post-install (applied after product installation) or post-configure (applied after the configuration has been transformed and imported). Your Professional Services representative can assist in creation of customization packages and their inclusion in upgrade bundles.

Upgrade process overview

Upgrading an Sh Cache Microservice product involves the following steps:

  • Read the product changelog to understand the changes introduced in the uplevel software, any new configuration required, and any workarounds/limitations you may encounter

  • Obtain the upgrade package from your Metaswitch Customer Care Representative, including any customization packages and licenses if required

  • Prepare for the upgrade

    • plan a maintenance window for when you expect traffic through the system to be low. (Although the rolling nature of the upgrade means that the system is always able to accept new traffic throughout the upgrade, traffic that is still present on a specific node at the end of its draining timeout will be curtailed, leading for example to terminated phone calls).

    • identify the first node to be upgraded

  • Upgrade the first node

  • Perform validation tests, if required

  • Upgrade the remainder of the nodes

  • Perform validation tests, if required

  • Post-upgrade steps including restoring other network element configuration

The uplevel software is provided in the form of a bundle (zip file). The procedure of upgrading the software is performed using the orca tool, which is included in the bundle. Run orca from a machine (either an operator’s PC or a node in the deployment to be upgraded) that meets the following requirements:

  • Linux OS, with Python 2.7 installed and accessible in the PATH as python2 (you can check by running python2 --version)

  • At least {product-disk-space} of free hard disk space (you can check with df -h)

  • Passwordless SSH connectivity (via SSH keys) to all Rhino nodes in the cluster to be upgraded

    • Configure the SSH agent to log in as the user under which Rhino is installed on the nodes, normally sentinel. This can be configured in ~/.ssh/config in the home directory of the user that will be running orca, for example:

Host host1
  User sentinel
  IdentityFile /path/to/ssh_private_key
  ...

Upgrading will take 1-2 hours for the first node and {product-time-other-nodes} for each subsequent node, not including validation tests or manual reconfiguration steps. It is a current limitation that the upgrade proceeds sequentially across all cluster nodes.

Next steps

To plan your upgrade, see Preparing for an Sh Cache Microservice Upgrade.

Previous page Next page