Skill Level: Intermediate

Any person with IBM Cloud Orchestrator understanding would be able to perform the set of actions.

This article talks about the problems you may face during migration on a distributed topology and then applying given steps you can migrate from SCO 2.3 to ICO 2.4 successfully.


IBM Cloud Orchestrator topology, Distributed Environment, Openstack, Public Cloud Gateway, Business Process Manager, Keystone.

Self-Service UI, Architectural difference between ICO v2.3 and ICO v2.5.x.


  1. Introduction

    The IBM Cloud Orchestrator is a cloud management platform that automates the provision of cloud services. It enables to configure, provision, deploy development environments, integrate service management, monitor, back-up and security whenever you need in minutes. Yes , in minutes and all from a single self-service interface.

    The SmartCloud Orchestrator v2.3(SCO) is rechristened as IBM Cloud Orchestrator V2.3. The latest versions of IBM Cloud Orchestrator are V2.4.x and 2.5.x. Architecturally, SCO v2.3 has distributed topology with 4 nodes, namely Central Server1 (CS1 contains DB2), Central Server2 (CS2 contains keystone, PCG), Central Server3(CS3 contains SCUI, IWD) and Central Server4 (CS4 contains BPM). As ICO 2.4 contains only 3 central servers (cs1, cs2.,cs3), there is a architectural shift that involves major differences in topology.  Hence, you must perform a lot of steps to upgrade from ICO 2.3 to ICO 2.4. There is a major difference in topology for 2.3 and 2.4. The data migration must be done properly such that the ICO 2.4 works properly after upgrade.


    Fig 1: Topological difference in SCO 2.3 and ICO 2.4

     In the diagram “Topological difference in SCO 2.3 and ICO 2.4”, the first set of blocks show SCO 2.3 topology with 4 Central Servers, whereas the later set of blocks show ICO 2.4 topology with 3 Central Servers.

     This article talks about the problems you may face during migration on a distributed topology. By applying the given steps, you can migrate from SCO 2.3 to ICO 2.4 successfully. The information mentioned here discusses the problems you may encounter during the migration and their workarounds. Some are real-time problems faced by ICO customers.


  2. Procedure - Four Central Servers instead of three

    Four Central Servers instead of three :

    The customer ICO 2.4 system consists of four central servers. This is because it was upgraded from version 2.3. Your environment will continue to have four central servers even after upgrade, and the discovery step incorrectly identifies the servers and their information. As the export step in turn uses the information from the discovery, it fails to interrogate the correct server for information.

    As a workaround for this problem, manually edit the discovery file to match the location of a particular information and export each piece of information separately.

    The discovery step identifies all the region servers and for each region it records the central server that provides the following services:

    • Business Process Manager Server
    • Public Cloud Gateway
    • UI customization
    • LDAP

    The export uses the generated file, /tmp/discovery/ discovered24Regions.json, to identify the method to export BPM, PCG, and UI information. A sample discovered24Regions.JSON file:


    Fig 2:  discovered24Regions.json file sample

    Open the discovered24Regions.json file and update the location of the following files:

    • centralserverhost identifies the server for BPM, PCG, and UI.
    • multiregionidentity identifies the server that provides LDAP.


    For a standard ICO 2.4 system, these files are all on the same server. For an upgraded system, the BPM is on a different server. BPM is used to identify the server with all these services. In this example, mpllnx0124 is the name of the CS2 server.


    As a workaround, the file generated by discovery is manually edited to hold the correct values.

    For example :

    1. Set the multiregionidentity to the CS2 server mpllnx0122.

    2. Run an export for BPM by using the following command:

        /upgrade.py ico_upgrade.rsp –export-toolkits

    3. Run the exports for pcg and scui by using the following commands:

        ./upgrade.py ico_upgrade.rsp –export-pcg

        ./upgrade.py ico_upgrade.rsp –export-scui

    Note: In the absence of PCG configuration and UI customization, the last two exports are not required.


  3. Procedure - Missing keystone export workaround

    Missing keystone export workaround:

    If your system has keystone schema, then the user name for database connection is different from the one that the script is looking for. The export of the keystone data fails partially due to missing information.

    As a workaround, manually copy the upgrade directory that contains the export scripts to the Database server. The keystone script is modified to use the correct schema, user, and password. It is run and the resultant zip file is copied back to the ICO server’s upgrade directory.

    1. As a workaround, manually copy the upgrade directory that contains the export scripts to the database server. Copy the       /opt/ico_install/2.5.0-CSI-ICO-FP0002/installer/upgrade directory from ICO 2.5 to CS1 (The DB server) :

       scp -rp upgrade mpllnx0121:/tmp

    2. Get the connection string for connecting keystone to DB2 on CS2:

        grep connection /etc/keystone/keystone.conf | awk -F= ‘{print “openstack-obfuscate -u” $2}’ | sh


     Fig 3. Command to get the connection string

    Note : The password is masked for confidentially reasons in Fig 3 ‘Command to get the connection string’ screenshot. 

    3. Modify the export_ eystone.sh file and run the following commands on CS1:

         vi /tmp/upgrade/export_keystone.sh

    4.Change the DB and Schema values for the following 4 lines


     (PWD taken from step 2 above)


    Fig 4.keystone.sh file

    5.Run the following commands to change the permissions and to export keystone script:

      chown -R db2inst1:db2iadm1 /tmp/upgrade/

      su – db2inst1   

      cd /tmp/upgrade



    Fig 5: Export command for keystone script

    6.  Copy the result back as root user:

        scp /tmp/upgrade/KSDB_24.zip mpllnx0277:/opt/ico_install/2.5.0-CSI-ICO-FP0002/installer/upgrade/KEYSTONE_24.zip               


    Fig 6: Created  keystone zip


  4. Summary

    Apply the suggested fixes and manually edit the files for the three central server topology. After a successful migration, the cloud data is available in ICO 2.4.

Join The Discussion