Moving colonies to the upgrade environment

After creating the upgrade environment, move the colonies that you want to upgrade from the production environment to the upgrade environment.

About this task

To move colonies to the upgrade environment, follow these steps:

Procedure

  1. In sharded mode, install a new version run time in upgrade mode. For purposes of describing this new run time, let us refer to it as Upgrade_V2.

    For example, if you are running a sharded deployment on Release 9.5, and upgrading some colonies to Release 10.0, perform a complete sharded installation of Release 10.0 in upgrade mode.

    Note: The sharded installation process requires that you provide database parameters for the METADATA shard. Ensure that the METADATA database information refers to the METADATA shard of Upgrade_V1.
  2. Configure Upgrade_V2's database parameters in the sandbox.cfg file to refer to Production_V1's METADATA by performing the following tasks:
    1. Create a backup of the sandbox.cfg file that is located in Upgrade_V2's <INSTALL_DIR>/properties directory.
    2. In the <INSTALL_DIR>/properties/sandbox.cfg file for Upgrade_V2, configure the following properties to match the corresponding properties in the <INSTALL_DIR>/properties/sandbox.cfg file for Production_V1:
      • DB_PASS
      • DB_USER
      • DB_SCHEMA_OWNER
      • DB_DATA
      • DB_PORT
      • YANTRA_DB_PASS
      • YANTRA_DB_USER

      On Oracle:

      • ORA_PASS
      • ORA_HOST
      • ORA_USER

      On Db2®:

      • DB2_PASS
      • DB2_HOST
      • DB2_USER
    3. From Upgrade_V2, run the <INSTALL_DIR>/bin/setupfiles.sh script (Linux® or UNIX) or the <INSTALL_DIR>\bin\setupfiles.cmd script (Windows).
  3. In the <INSTALL_DIR>/Migration/9.5 directory for Upgrade_V2, run the following command, where <INSTALL_DIR_OLD> corresponds to Production_V1: 
    
${ANT_HOME}/bin/ant -Druntime=<INSTALL_DIR> -Druntime.old=<INSTALL_DIR_OLD>
 -f buildmigration.xml -logfile <logfile> -Dtarget=initcolonypool migrate

    This command creates the <INSTALL_DIR>/Migration/9.5/database/scripts/multischema.xml file in Upgrade_V2. The XML file contains a list of colonies on Production_V1.

    The *.done file that is created in the 9.5 status folder for the initcolonypool task is ant_initcolonypool.xml.done.

  4. Before you move colonies from Production_V1 to Upgrade_V2, you must disable those colonies in the Production_V1 environment.
    To disable colonies in the Production_V1 environment, perform these tasks:
    1. In the Migration/9.5/database/scripts/multischema.xml file, perform the following edits:
      • Specify a status of "UPGRADE" for the colonies that you are upgrading.
      • Remove all references to the colonies that you are not upgrading, and also to the colonies' table types.

      For example, if you are upgrading Colony-01, but not Colony-02, set the status for Colony-01 as "UPGRADE" in the XML file, and remove Colony-02 and its corresponding table type from the XML file.

    2. In the <INSTALL_DIR>/Migration/9.5 directory for Upgrade_V2, run the following command, where <INSTALL_DIR_OLD> corresponds to Production_V1: 
      
${ANT_HOME}/bin/ant -Druntime=<INSTALL_DIR> -Druntime.old=<INSTALL_DIR_OLD>
 -f buildmigration.xml -logfile <logfile> -Dtarget=updatecolonypool migrate

      For the colonies that you are moving from Production_V1 to Upgrade_V2, this command sets the colonies to "UPGRADE" status, which disables the colonies in Production_V1 and updates the colony parameters.

      The *.done file that is created in the 9.5 status folder of Upgrade_V2's Migration/9.5 directory for the updatecolonypool task is ant_updatecolonypool.xml.done.

      Note: After you disable the colonies, the application server can take up to 10 minutes to recognize that the colonies are down.
  5. Reset the database parameters in Upgrade_V2's sandbox.cfg file to refer to Upgrade_V2's METADATA by performing the following tasks:
    1. Use the backup file from step 2 to restore the original sandbox.cfg file for Upgrade_V2.
    2. From Upgrade_V2, run the <INSTALL_DIR>/bin/setupfiles.sh script (Linux or UNIX) or the <INSTALL_DIR>\bin\setupfiles.cmd script (Windows).
  6. For the colonies that you are moving from Production_V1 to Upgrade_V2, update the database parameters in Upgrade_V2 by performing the following tasks:
    1. In the Migration/9.5/database/scripts/multischema.xml file on Upgrade_V2, perform the following edits:
      • Change each colony's status from "UPGRADE" to "".
      • Change the references for colony-specific shards, such as METADATA, CONFIGURATION, and STATISTICS, to point to the Upgrade_V1 shards.
      • Change the references for the DEFAULT colony to point to the Upgrade_V1 shards.

      For example, if you are moving Colony-01 from Production_V1 to Upgrade_V2, set the status of Colony-01 to "" in the XML file, and change the references for the METADATA, CONFIGURATION, and STATISTICS shards to point to the Upgrade_V1 shards. Additionally, the DEFAULT_TRANSACTION shard should point to Upgrade_V1.

    2. Rename the ant_updatecolonypool.xml.done file, generated in step 4 , to ant_updatecolonypool.xml.done.bak.
    3. In the <INSTALL_DIR>/Migration/9.5 directory for Upgrade_V2, run the following command, where <INSTALL_DIR_OLD> corresponds to Upgrade_V1: 
      
${ANT_HOME}/bin/ant -Druntime=<INSTALL_DIR> -Druntime.old=<INSTALL_DIR_OLD>
 -f buildmigration.xml -logfile <logfile> -Dtarget=updatecolonypool migrate

      This command updates the colony parameters in Upgrade_V2 to refer to the TRANSACTION and MASTER shards for the colonies you are upgrading.

      The *.done file created in the 9.5 status folder of Upgrade_V2's Migration/9.5 directory for the updatecolonypool task is ant_updatecolonypool.xml.done.