Upgrade

This document describes how to upgrade an existing installation of an on-premises ALM Octane server on Linux.

In this topic:

Upgrade paths

ALM Octane allows you to choose between two upgrade paths:

  • Long-term path (LTP). Upgrade directly from one release to the next (for example from 15.0.20 to 15.1.20, to the next LTP release), without having to upgrade to each of the interim service packs.

  • Short-term path (STP). Upgrade to each new service pack (for example from 15.1.40 to 15.1.60). If you choose this path, you will need to go through all the interim service packs in order to upgrade to the following release.

The current version is a service pack, meaning that you can only upgrade to 15.1.60 from 15.1.40. If you have not yet upgraded to ALM Octane 15.1.40, upgrade now.

Back to top

Before you upgrade: General guidelines

Before upgrading, review the following:

  1. ALM Octane 15.1.60 requires one of the following Elasticsearch versions: 7.9.1, 7.6.2, or 6.8.1 (or higher 6.8.x).

    Caution: The upgrade process may include a significant step relating to Elasticsearch. Make sure you read the section Prepare for Elasticsearch re-indexing (from 5.x to 6.x) before you start the upgrade.

  2. Check that all spaces are up to date, first in Settings Site > Spaces, and then in SettingsSite > POST UPGRADE JOBS. Delete any spaces that you do not want to upgrade to prevent problems in future upgrades.

  3. Verify that your server machine, and if relevant, all cluster nodes, meet all prerequisites.

    This includes checking the supported versions for all third party tools, such as Elasticsearch, and upgrading accordingly. For details, see "Prerequisites" in the ALM Octane Installation Guide for Linux.

  4. Stop the octane service on the server, and if relevant, on all cluster nodes.

  5. Create backups of:

    • The repository

    • Existing ALM Octane configuration files, including octane.conf

    • Your database

    • Elasticsearch

    • If you are using ALM Octane Synchronizer, back up : 

      • C:\octane\wrapper\wrapper.conf

      • service.locator.properties (C:\octane\webapps)

    For recommendations on making these backups, see Best practices for backing up ALM Octane data in the ALM Octane Help Center.

    Caution: During the upgrade, configuration files will be relocated from /opt/octane/conf to the repository directory.

    To roll back the upgrade, you will need your pre-upgrade configuration files from each node. Make sure you save a copy of the configuration files in a secure location before upgrading. You cannot roll back without these files.

    This includes octane.conf, and any other configuration files in /opt/octane/conf.

  6. Take note of any special aspects of your configuration, such as: 

    Special configuration Recommendation
    Did you use a different user, other than the octane user, to install? If you did, the user is set in the OCTANE_USER environment variable. Use this user to upgrade.
    Did you install ALM Octane to a location other than /opt/octane? Refer to the location you used while upgrading.
    What sudoer user did you use to install?  Use the same sudoer user that was used for installation to upgrade.
    Did your organization's DBA make changes to database schemas, such as the addition of tables or columns?

    Define an exception file. The exception file instructs ALM Octane to ignore manual changes to the database schemas during installation. For details, see "Using exception files for manual database changes" in the ALM Octane Installation Guide for Linux.

  7. Before upgrading, remove all patches or hotfixes at WEB-INF/lib and WEB-INF/classes.

Back to top

Prepare for Elasticsearch re-indexing (from 5.x to 6.x)

Caution: The following section is required if you have indexes created in an Elasticsearch version lower than 6.x, that have not yet been re-indexed.

To check if you have such indexes, look at Settings Site > Spaces. In each of your spaces, see if the field ELS maintenance status is set to Done. If not, read the following section and Re-indexing during space upgrade.

In this release, you will not be able to use these spaces without re-indexing them. In a future release, Elasticsearch 7.x will be mandatory.

Elasticsearch 7.x supports indexes created in 7.x or 6.x only. In preparation for moving to Elasticsearch 7.x, ALM Octane will reindex the old indexes during upgrade, as follows:

  • Site index. The site index (event store) is re-indexed as part of site upgrade, so site upgrade will take longer than usual.

  • Space indexes. The space indexes will be re-indexed within a post-upgrader that is triggered at the end of the space upgrade. Reindexing a space can be a time-consuming process (depending on the size of your database), and during this time Elasticsearch functionality in ALM Octane will be disabled in the space. This includes search, trend and analytics graphs, pipelines, and audit. For more details, see Re-indexing during space upgrade.

  • Re-indexing is mandatory. You will not be able to upgrade Elasticsearch to 7.x if you still have indexes created in an Elasticsearch version lower than 6.x. In the next version of ALM Octane, you will not be able to proceed with space upgraders unless all spaces are re-indexed.

  • The Elasticsearch server must have ~60% free space to enable re-indexing. The ALM Octane server will not start if there are old indexes in Elasticsearch and the space condition is not fulfilled.

    If you do not have sufficient space on the Elasticsearch server, allocate space before proceeding with the upgrade. You can run the following command from Kibana to check:

    GET /_cat/allocation?v

    Or the following CURL command:

    CURL -XGET "http://{elastic host}:9200/_cat/allocation?v
  • After upgrading the server to the new version, but before upgrading the spaces, you will need to set the value for the ELASTIC_MAINTENANCE_MAX_WORKERS_PER_NODE based on the number of cluster nodes for ALM Octane. For details, see Configuration parameters in the ALM Octane Help Center.

Note: Indexes must be open and not in read-only mode.

Back to top

Deploy the new version and start ALM Octane

  1. Download the ALM Octane RPM package:

    https://www.microfocus.com/en-us/products/application-lifecycle-management-octane-on-prem/download

  2. Deploy the rpm package for the new version of ALM Octane using:
    rpm -U <name of the RPM file>
  3. Start the ALM Octane server.

    systemctl start octane
  4. Check the /opt/octane/log/wrapper.log file. If you encounter a recoverable error in the wrapper.log or upgrade.log files, fix the problem and restart the server to resume upgrade.

    If the log file contains the error message “The value https://<server URL> is invalid URL”, refer to the section Upgrading non-standard top-level domains.

Caution: Do not use ALM Octane until you have completed Upgrade spaces in ALM Octane.

Back to top

Upgrade cluster nodes

After the upgrade on the first node has completed successfully, you can upgrade the remaining nodes in a cluster.

To upgrade cluster nodes:

  1. Deploy the new version of ALM Octane to each node.

  2. On each node, start the ALM Octane server.

    systemctl start octane

  3. Check the /opt/octane/log/wrapper.log file. If you do not see the "Server is ready!" message, correct the errors shown in the log.

    • If you encounter a recoverable error in the wrapper.log or upgrade.log files, fix the problem and restart the server to resume upgrade.

    • If the log file contains the error message “The value https://<server URL> is invalid URL”, refer to the section Upgrading non-standard top-level domains.

Caution: Do not use ALM Octane until you have completed Upgrade spaces in ALM Octane.

Post-upgrade changes to configuration files

In ALM Octane 15.1.40, the configuration files were located in /opt/octane/conf.

Following upgrade, they are automatically moved to <Repository folder>/conf.

In the future, if you need to make changes to any of the configuration settings, you only need to do this once in the relevant file located in <Repository folder>/conf. When you restart each of the nodes, ALM Octane pulls the configuration change automatically from the repository.

Back to top

Upgrade spaces in ALM Octane

After upgrading, log into ALM Octane as the site admin to upgrade each space.

To upgrade spaces in ALM Octane:

  1. In a browser, navigate to <ServerURL>:<port>/ui?site.

  2. Log in as the space admin, with the user name and password defined in the octane.conf file.

  3. Click Site and then click the Spaces tab.

  4. Select one or more spaces and click Upgrade.

    Upgrade is available only if the space needs to be upgraded.

  5. Individual workspaces are upgraded in the background.

    (Optional) You can track a specific space's background jobs in Settings > Site > Spaces > Background Jobs. You can also track all spaces at once, as described in the following section.

    Note: Until all of the background jobs have completed, some data may be unavailable in trend graphs and other Elasticsearch-related features.

Back to top

Verify that spaces upgraded successfully

Verify that all spaces were upgraded successfully from the previous version. To verify that a space has been upgraded, check that:

  • The space status is Active (or Inactive if it was previously deactivated).

  • The space version is updated to the current version.

In addition, check that all post-upgrade jobs were completed in Settings > Site > POST UPGRADE JOBS.

Note: If Elasticsearch maintenance post-upgrader(s) are taking long, you can stop them as described in the following section. After stopping them, restart the server as described below, and then re-run the post-upgraders after the server is up.

Back to top

Re-indexing during space upgrade

Caution: The following section is required if you have indexes created in an Elasticsearch version lower than 6.x, that have not yet been re-indexed.

In the next release, you will not be able to use these spaces without re-indexing them.

If you are upgrading spaces that use Elasticsearch indexes created in version 5.x (ALM Octane 12.60.35 or earlier), the space upgrade step includes Elasticsearch re-index as described in Prepare for Elasticsearch re-indexing (from 5.x to 6.x).

  • Space indexes are automatically re-indexed as part of a post-upgrader job that is triggered after the space is upgraded. (If a space’s indexes are all up-to-date, the post-upgrader will immediately complete successfully.)

  • While a space's post-upgrader is running, its Elasticsearch features are disabled. This includes search, trend and analytics graphs, pipelines, and audit. A message to this effect will be displayed at the top of users’ screens.

  • You can set the ELASTIC_STOP_EXECUTE_REINDEX_POST_UPGRADERS site parameter to true in order to stop the re-index from running (either for the site or per space). The post-upgrader will complete as FAILED when the parameter is on.

    This can be helpful if you want to schedule re-indexing at a time that has the lowest impact on your users, or if you started the re-index and need to suspend it. In this case, when you are ready to re-index set the parameter to false, and re-run the post-upgrader.

  • Post-upgrader jobs can be viewed and managed in Settings > Site > POST UPGRADE JOBS.

  • After a space's indexes have been re-indexed (or if all its indexes were created in Elasticsearch 6.x), the ELS Maintenance Status field will be set to done. This field is visible in Settings > Site > Spaces.

Troubleshooting the re-index:

Some Elasticsearch failures might be due to momentary load on the Elasticsearch cluster. You can try re-running the post-upgrader to see if this solves the problem.

If a post-upgrader fails, collect logs for support. The status in Settings > Site > POST UPGRADE JOBS will display FAILED. Check the error message, fix the indicated problem, and re-run the upgrader. The Elasticsearch features will be enabled again until you re-run the post-upgrader.

Back to top

Stop all ALM Octane servers

Clear caches by stopping all ALM Octane servers.

Note: All of the servers must be stopped before you restart any of them.

Back to top

Restart the ALM Octane servers

After you stop all of the servers, you can restart them.

Back to top

Bulk update data access control

Note: This section is relevant only if you want to apply data access control for the first time to an upgraded system.

For data access control to work properly, both roles and entities must be assigned with data access control categories. After an upgrade, entities do not yet have a data access control category assigned to them. This means that roles that already have data access restrictions, will not be able to access these entities.

We recommend using the bulk update functionality to update entities efficiently.

Follow the instructions in Set up data access in the ALM Octane Help Center. When you reach the Assign data access categories to items section, use the Bulk Update option to assign data access categories to items, so that all the items are accessible only to the relevant roles.

Back to top

Upgrading non-standard top-level domains

When upgrading, ALM Octane validates that the top-level domain (TLD) entered in the SERVER_BASE_URL parameter is listed in https://www.iana.org/domains/root/db. If your URL includes a TLD that is not listed there, the upgrade will fail with the following message in the log file:

ERROR: The value https://<server URL> is invalid URL.
com.hp.mqm.platform.params.ParamValidationException: The value https://<server URL> is invalid URL

If this occurs, we recommend that you change your TLD to one of the TLDs listed in https://www.iana.org/domains/root/db.

Alternatively, perform the following steps:

  1. Open the schema of the site admin and add a new entry to the params table.

  2. In the pm_id column of the new entry, enter ADDITIONAL_ALLOWED_TLD.

  3. In the pm_value column enter the desired TLD value. For example, here the added TLD is corp:

  4. Start the server.

For more details about the ADDITIONAL_ALLOWED_TLD configuration parameter, see Configuration parameters.

Back to top

Next steps:

  • Update mandatory configuration parameters, such as SMTP_NOTIFICATION_SENDER_EMAIL. See Configuration parameters in the ALM Octane Help Center.
  • Download the newest IDE plugins for this ALM Octane version. See IDE integrations in the ALM Octane Help Center.
  • If you work with the REST API, you might want to check if any API resources have been deprecated. While the deprecated resources are supported for a while, we recommend that you start updating your code so that you use the resource aliases instead. To see deprecated resources for a particular version, see What's changed in the REST API in the ALM Octane Help Center.