Upgrading on-premises Agile Service Manager

Edit online

Learn how to upgrade to the latest version of Agile Service Manager.

About this task

You install a new version or upgrade an existing version of Agile Service Manager (on-premises) using the standard installation procedures for all components. When you use the IBM®® Installation Manager to install the Netcool® Hybrid Deployment Option Integration Kit, you must install a new version.

After you complete the installation, you might need to migrate the configuration settings. Previous configuration settings are preserved during installation, but you might need to manually transfer settings from your previous to your current configuration files.

The yum upgrade (install) process preserves existing configuration settings in two ways.
Replace previous configuration files
If a previous configuration file can be replaced without disabling the Agile Service Manager system, the installation process does so, and saves the old version with the .rpmsave extension.
For example, the old version of poll_docker.sh is replaced with a new version, and backed up as poll_docker.sh.rpmsave.
Preserve current configuration file
If a previous configuration file cannot be replaced without disabling the Agile Service Manager system, the installation process keeps the old configuration file in place and saves the new version with the .rpmnew suffix.
For example, the old version of docker-compose.yml is kept in place, and the new version is deployed as docker-compose.yml.rpmnew.

Procedure

Obtain the Agile Service Manager software.

  1. Obtain the Agile Service Manager installation images for the user interface and core services from the Passport Advantage® site, and extract them to a temporary directory.
    More detailed information can be found in the download document here: http://www-01.ibm.com/support/docview.wss?uid=swg24043717
    Note: You need an IBMid to access the download document.

Backup custom UI configuration settings

  1. To preserve customized UI configuration settings such as user preferences, topology tools, custom icons, relationship types, and global settings, back up these settings. For more information, see the Exporting configuration data (on-premises) topic of the Administration section in the Agile Service Manager documentation:

    Backing up UI configuration data (on-prem) external link

Install (upgrade) Agile Service Manager.

  1. Stop any Agile Service Manager services that are running: 
    /opt/ibm/netcool/asm/bin/asm_stop.sh
  2. Install a new version of Agile Service Manager, or update an existing installation.
    Follow the standard installation procedure as described in the following topics:
    After the upgrade, the yum installation process lists all changed configuration files.

Transfer your configuration settings.

Remember: If you upgraded an existing installation of Agile Service Manager, you must upgrade your configuration files.

  1. Manually migrate your backed up configuration settings to the new configuration files.
    Tip:
    • You can search for affected configuration files with the .rpmsave or .rpmnew extensions.
    • You can compare configuration file versions with a Diff tool before you migrate the required configuration settings to the new configuration files.
  2. Import any previously backed up UI configuration settings into your new system, as described in the following topic:

    Restoring UI configuration data (on-prem) external link
  3. Run the following script to remove unused Agile Service Manager images: 
    export USING_ASM_START_STOP_SCRIPTS=no
$ASM_HOME/bin/remove-old-images.sh

Extra configuration

  1. Depending on your deployment, you might need to complete some of the following configuration tasks:
    Edge types migration
    To migrate any existing edge types from Agile Service Manager 1.1.3 to 1.1.5 (or later), use the following curl command:
    curl -k -X POST -u asm:asm --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-TenantID: cfd95b7e-3bc7-4006-a4a8-a73a79c71255' -d '{}' 'https://localhost:8080/1.0/topology/crawlers/migrateEdgeTypes'
    Match token migration to lowercase
    To convert older resource matchTokens from Agile Service Manager 1.1.3 or 1.1.4 (but not 1.1.4.1) to 1.1.5 (or later) to lowercase, use the following curl command:
    curl -k -X POST -u asm:asm --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-TenantID: cfd95b7e-3bc7-4006-a4a8-a73a79c71255' -d '{}' 'https://localhost:8080/1.0/topology/crawlers/lowercaseMatchTokens'
    Composite end time migration
    To allow composite vertices to show status within the search results, you must migrate any existing composites to the latest version of Agile Service Manager.
    To do so, use the following curl command:
    curl -k -X POST -u asm:asm --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-TenantID: cfd95b7e-3bc7-4006-a4a8-a73a79c71255' -d '{}' 'https://localhost:8080/1.0/topology/crawlers/compositeEndTime'
    Restrict the Transport Layer Security (TLS) version to 1.2 only
    To enforce TLS 1.2 in nginx, change the ssl_protocols setting in the $ASM_HOME/etc/nginx/nginx.conf file:
    server {
listen 8443 ssl;
server_name localhost;
ssl_certificate /opt/ibm/netcool/asm/security/asm-nginx.crt;
ssl_certificate_key /opt/ibm/netcool/asm/security/asm-nginx.key;
ssl_protocols TLSv1.2;
    Docker Observer
    When you update from Agile Service Manager 1.1.7 (or earlier) with existing Docker Observer job data, run the following migration script to avoid the creation of duplicate observer records before you run any new Docker Observer jobs.
    $ASM_HOME/bin/execute_crawler.sh -c docker_provider_transfer

    Failing to run this script before you run any new Docker Observer jobs can result in duplicate resources, as can running an older Docker Observer job after the crawler is run.

    Kubernetes Observer
    When you update from Agile Service Manager 1.1.4.1 (or earlier), ensure that your Weave Scope jobs are running before you update your system.
    • The location of the Weave Scope listen job changes from Agile Service Manager 1.1.5 onwards. The paths of existing Weave Scope jobs, which are running during an upgrade, are automatically renamed when the observer starts.
    • However, Weave Scope jobs that are not running (stopped) are not recognized, and so, their paths are not renamed. As a consequence, the UI is unable to restart them.
    IBM Tivoli® Network Manager Observer
    When you update from Agile Service Manager 1.1.3 (or earlier) to the latest version, you must run a migration script. The script avoids the creation of duplicate ITNM Observer records before any ITNM Observer jobs are run: 
    cd $ASM_HOME/bin
/execute_crawler.sh -c itnm_provider_transfer
    • Running this script before any new observations are made with the ITNM Observer prevents the creation of duplicate records.
    • Running this script after new observations are made with the ITNM Observer removes duplicate records, but might not preserve some historical topology data that is previously gathered by the ITNM Observer.
    The script, which might take some time to complete on large topologies, creates a management artifact in the topology. You can monitor its progress by querying the artifact with Swagger.