Upgrading Unified Assurance on an Existing Linux System

You can upgrade Oracle Communications Unified Assurance on an existing Linux system by first upgrading your existing Linux 7 environment to Linux 8 and then updating to the latest version of Unified Assurance. This is also known as an in-place upgrade.

An in-place upgrade involves the following high-level steps:

Preparing for the Linux and Unified Assurance upgrade by backing up key files and removing the old RPM.
Upgrading your Linux 7 environment to Linux 8 using the Leapp utility. For information about using the Leapp utility, see Oracle Linux 8 Upgrading Systems With Leapp.
Updating Unified Assurance packages on all servers.

In-Place Upgrade Process Placeholders

The in-place upgrade procedure uses the following placeholders, marked with angled brackets in the commands (<>):

<UA_home>: Your Unified Assurance home directory. For example, /opt/assure1.
<installation_directory>: The directory where you store installation files, also known as your local depot. For example, /opt/install.

In-Place Upgrade Prerequisites

For complete information about general system requirements for Unified Assurance, including system and hardware requirements, see Unified Assurance Architecture.

Additionally, on servers with the Database.Historical role:

Confirm that you will have enough memory available for the Elasticsearch and OpenSearch databases to be deployed simultaneously. You need both to support the migration process.

Until you finalize the migration process, both types of database will be running. OpenSearch requires approximately the same amount of memory as Elasticsearch, so the migration process requires at least twice the memory of your current Elasticsearch implementation. You can add more memory, or scale back your Elasticsearch heap size as needed. After finalizing the migration and removing Elasticsearch, you can scale up your OpenSearch heap size to use the full amount.

The heap size for Elasticsearch is set in the ES_JAVA_OPTS parameter in the $A1BASEDIR/vendor/elasticsearch/config/custom-env file.

When you run Package update, the application checks whether you have enough memory available for both databases. If so, it proceeds with the update. If not, it stops the update and prompts you to adjust your memory settings.
If you have a redundant setup for the Historical database servers, confirm that redundancy is correctly configured on the secondary server:
1. In the Unified Assurance user interface, from the main navigation menu, select Configuration, then Broker Control, and then Servers.
2. Select the secondary Historical database server and confirm that the correct FQDN for the primary Historical database server is set in the Primary Server field.
  
  If it is not, update the Primary Server field, and then click Submit.

Performing an In-Place Upgrade

Perform all commands in this procedure as the root user, unless otherwise indicated.

To perform an in-place upgrade:

On each Unified Assurance server:
1. Remove the $A1BASEDIR/vendor/perl directory:
```
rm -rf $A1BASEDIR/vendor/perl
```
2. Back up the Assure1.conf file, located in the UA_home/etc directory, to a safe location.
3. For each Unified Assurance server, remove the Unified Assurance RPM using the noscripts flag with the following command:
```
sudo yum --setopt=tsflags=noscripts erase Assure1
```
4. Upgrade your Linux 7 environment to Linux 8 using the Leapp utility as described in Oracle Linux 8 Upgrading Systems With Leapp.
5. Confirm that Linux prerequisites are met. See Linux Prerequisites.
On the primary presentation server:
1. If you are upgrading from version 5 to version 6.1, skip to the next step.
  
  If you are upgrading from version 6.0.x to version 6.1, reset the Unified Assurance packages to their base versions.
```
a1mysql
UPDATE Packages SET PackageVersion = '6.0.0.0.0.0';
```
2. Download the latest Unified Assurance software, including the release package and the latest available patch, and extract the contents of the collection files to an installation directory. This is typically /opt/install, and is referred to as <installation_directory> in the documentation.
  
  See Downloading the Latest Unified Assurance Software for more information about where to get the software and how to extract the collection file.
3. Copy the Assure1-6.X.X.X.X-X.el8.x86_64.rpm patch file from the primary presentation server to <installation_directory> on each other Linux 8 server in the environment. Use the patch RPM rather than the release RPM.
On each of your Unified Assurance servers, starting with the primary presentation server:
1. Install the latest Unified Assurance RPM for Linux 8:
```
sudo dnf -y install Assure1-6.X.X.X.X-X.el8.x86_64.rpm
```
  Use the patch RPM rather than the release RPM.
2. Restore the backup of the Assure1.conf file and place it in the UA_home/etc/ directory.
3. Start the Unified Assurance Broker:
```
sudo systemctl start assure1-broker
```
4. Set environment variables:
```
source <UA_home>/.bashrc
```
5. Remove all Linux 7 Unified Assurance packages by removing the contents of the $A1BASEDIR/distrib/packages directory:
```
rm -f $A1BASEDIR/distrib/packages/*
```
On the primary presentation server, remove references to Elasticsearch, Kibana, and Filebeat, as well as any custom packages, from the Packages table by running the following commands:
```
$A1BASEDIR/vendor/<database_type>/bin/mysql --defaults-file=$A1BASEDIR/etc/my.cnf Assure1 -e "DELETE FROM Packages WHERE PackageName in ('vendorElasticsearch-app','vendorKibana-app','vendorFilebeat-app')"
$A1BASEDIR/vendor/<database_type>/bin/mysql --defaults-file=$A1BASEDIR/etc/my.cnf Assure1 -e "DELETE FROM Packages WHERE PackageName in ('<custom_package_a>','<custom_package_b>')"
```
where:
- <database_type> is one of the following, depending on your upgrade path:
  - mariadb if you are upgrading from version 5 to version 6.1.
  - mysql if you are upgrading from version 6.0.x to version 6.1.
- <custom_package_a> and <custom_package_b> are the names of custom packages.
  
  You will need to recreate any custom packages after the upgrade is complete.
On any collection server where you have the Flow Collector microservice deployed, stop all data coming from all deployed Flow Collector instances to the Historical database. Scale down the microservice by running the following command for all instances of Flow Collector, as the assure1 user:
```
a1k scale --replicas=0 deploy <flow-collector-release-name> -n <namespace>
```
where:
- <flow-collector-release-name> is the name of the microservice instance. This is typically flow-collector, but may be slightly different if you have multiple instances of the microservice deployed to the same cluster.
- <namespace> is the namespace where the microservice is deployed. This is typically a1-zone1-pri, but may be slightly different if you deployed the microservice to a different zoned namespace or a redundant cluster.
See Managing Microservices and Flow Collector in Unified Assurance Implementation Guide for information about microservices.
Run Package update for each of your Unified Assurance servers:
- On the primary presentation server:
  1. Run Package update:
```
$A1BASEDIR/bin/Package update --depot <installation_directory>
```
    Updated packages are copied from the directory you extracted them to into the internal package location on the primary presentation server, then packages that have updates on the primary presentation server are installed.
  2. If you are upgrading from version 5 to version 6, run flush-hosts:
```
$A1BASEDIR/vendor/mysql/bin/mysqladmin flush-hosts
```
- On the secondary presentation server, if you are upgrading from version 5 to version 6, restart the assure1 database, and then run Package update:
```
systemctl start assure1-db
$A1BASEDIR/bin/Package update
```
- On all other servers:
```
$A1BASEDIR/bin/Package update
```
  Packages that have updates are downloaded from the primary presentation server and installed on the other server.
On servers with the Database.Historical role, Package update also runs AnalyticsWizard, which updates the ports for Elasticsearch and Kibana, installs OpenSearch, and performs some automatic migration tasks.
- If your Historical database does not have enough memory for both Elasticsearch and OpenSearch, Package update fails. To resolve this:
  1. In the $A1BASEDIR/tmp/elasticsearch/custom-env file, update the value of the ES_JAVA_OPTS parameter to allocate enough memory. It must be at least 2GB.
  2. Re-run Package update:
```
$A1BASEDIR/bin/Package update
```
    The process picks up where it left off.
- You can monitor or review the artifact migration progress by tailing the following log file:
```
$A1BASEDIR/logs/MigrateHistoricalObjects.log
```
  For any failures, you can find the Elasticsearch export and OpenSearch import files in the following directory:
```
$A1BASEDIR/tmp/migration/
```
  AnalyticsWizard does not migrate the documents in the indexes. You do this using the MigrateHistoricalData utility, after completing the upgrade. See About Migration and Automatically Migrated Artifacts in Unified Assurance Migration Guide for more information about the migration process.
If you are upgrading from version 5 to version 6:
1. Run RedundancyWizard on each redundant presentation server pair and each Event, Graph, and Metric database server pair to resynchronize them. See:
  - Running RedundancyWizard on the Presentation Servers
  - Running RedundancyWizard on the Database Servers
  Note:
  
  You do not need to run RedundancyWizard for Historical database server pairs. Redundant Historical databases are not aware of each other in the same way as other databases. See Historical Database Scalability and Redundancy in Unified Assurance Concepts for details.
2. Enable DatabaseWatchdog on all servers. You can do this by using the Services UI.
3. Remove all version 5 related directories. On each server, run:
```
$A1BASEDIR/bin/SetupWizard --Finalize-Upgrade
```
4. Remove all Neo4j version 4 related directories. On each Graph database server, run:
```
$A1BASEDIR/bin/Package finalize-neo4j-upgrade
```
If you had any custom packages, recreate them.

Although you removed the .pkg and .def files when you removed the contents of the $A1BASEDIR/distrib/packages directory, the files that were part of those packages in other directories still exist.

See Creating Custom Packages in Unified Assurance Developer's Guide for more information about creating custom packages.
Complete the Post Update Tasks, including migrating your Historical database.

The in-place upgrade is complete.

Title and Copyright Information

Installation Guide

G18218-05