Upgrade

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

Flexible upgrade paths

Starting with release 15.0.20, you can choose from one of 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), without having to upgrade to each of the interim service packs.
  • Short-term path (STP). Upgrade to the next service pack (for example, 15.0.40). If you choose this path, you will need to go through all the interim service packs in order to upgrade to the following release.

Back to top

Before you upgrade: General guidelines

  1. You can upgrade to ALM Octane 15.1.20 either directly from 15.0.40, or from 15.0.60.

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

    Caution: The upgrade process includes 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.

  3. Verify that all spaces upgraded successfully from the previous version in Settings > Site > POST UPGRADE JOBS.

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

  5. Create backups of:

    • The repository

    • Existing ALM Octane configuration files, including setup.xml and octane.yml

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

  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 you modifiy the /opt/octane/webapps/root/WEB-INF/classes/hpssoconfig.xml file to control session timeouts? 

    If you modified the /opt/octane/webapps/root/WEB-INF/classes/hpssoconfig.xml file to control session timeouts, your updates will be overwritten by the upgrade.

    After upgrading, control session timeouts by setting the MINUTES_UNTIL_GLOBAL_SESSION_TIMEOUT and MINUTES_UNTIL_IDLE_SESSION_TIMEOUT configuration parameters instead. For details, see Configuration parameters.

    Do you want to switch from native user management to LDAP user management with this upgrade? 

    If you are upgrading from an ALM Octane version using native user management, and want to start using LDAP user management with this new ALM Octane version:

    1. Realize that once you configure for LDAP user management, you cannot return back to native, internal user management.

    2. Upgrade ALM Octane without configuring for LDAP.

    3. After the upgrade is complete, configure for LDAP.

    4. Deactivate any native, internal users after LDAP configuration. These users can no longer log into ALM Octane (except for the adminDN user).
    Did your organization's DBA made 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.

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

Back to top

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

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 this parameter in ELASTIC_MAINTENANCE_MAX_WORKERS_PER_NODE.

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

Back to top

Deploy the new version

Download and deploy the rpm package for the new version of ALM Octane using:

rpm -U <name of the RPM file>

For details, see Deploy ALM Octane.

Back to top

Start the ALM Octane server

  1. Start the ALM Octane server.

    systemctl start octane
  2. 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.

    Instructions for troubleshooting upgrade errors and warnings:

Caution:  

  • Do not modify any configuration settings until you start the server. Starting the server populates the settings defined in your old setup.xml and octane.yml files to the new files, as described in the following section.

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

Back to top

Configuration changes when upgrading directly from ALM Octane 15.0.40

In ALM Octane 15.0.40, configuration settings were defined in the setup.xml and octane.yml files.

In the current release, the main site settings are defined in the octane.conf file. Optional additional settings are defined in the following files:

  • elasticsearch-security.conf to configure secure Elasticsearch.

  • proxy.conf to use a proxy server.

  • ldap.conf to use LDAP authentication.

  • sso.conf to use SSO authentication.

When you start the server, the upgrade process automatically populates your pre-upgrade settings into their corresponding locations in the new configuration files. After you start the server, you can modify settings as needed using the new configuration files.

For a full list of settings for the current ALM Octane installation, see Configure site settings.

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.

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

  2. Copy the configuration files from octane\conf to each node.

  3. On each node, start the ALM Octane server on each node.

    systemctl start octane

For details, see Cluster installation flow.

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

Back to top

Upgrade spaces in ALM Octane

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

  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 the space and click Upgrade.

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

    Click Refresh to see the updated status for the space.

  5. Individual workspaces are upgraded in the background. In Settings > Spaces, click Background Jobs to track the progress of the workspace upgrades.

    Note: Until all of the background jobs have completed, some data may be unavailable in trend graphs.

Back to top

Verify that spaces upgraded successfully

Verify that all spaces upgraded successfully from the previous version. Check that post-upgrade jobs completed in ALM Octane Settings > Site > POST UPGRADE JOBS.

After the upgrade has completed successfully:

  • The space status becomes Active.

  • The space version is updated to the current version.

Back to top

Re-indexing during space upgrade

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 prevent 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. 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 ALM Octane 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 ALM Octane 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 ALM Octane 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 Jetty servers

Clear caches by stopping all Jetty servers.

Note: Make sure all Jetty servers are stopped before restarting even one of them.

Back to top

Restart all Jetty servers

Restart each Jetty server.

Note: Make sure all Jetty servers are stopped before restarting even one of 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 (Enterprise Edition).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

Next steps:

  • Update mandatory configuration parameters, such as SMTP_NOTIFICATION_SENDER_EMAIL. See
    Configuration parameters.
  • Download the newest IDE plugins for this ALM Octane version. See IDE integrations.
  • 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 the corresponding REST API example and how to use the interactive API client in the ALM Octane Developer Help, What's changed in the REST API.
  • Rollback