Upgrading

Upgrade your config development environment to use the latest version of the analyze-deployment-tooling repository, or i2 Analyze update the images, secrets, and deploy your configs.

The process of upgrading the config development environment is completed in a different directory from your current environment.

Before you begin

Make a copy of your existing analyze-deployment-tooling directory as a backup.

Prerequisites

  1. Download the tar.gz from https://github.com/i2group/analyze-deployment-tooling/releases/tag/v3.0.3.

  2. Extract the tar.gz file by using the following steps:

    1. On Windows, copy the analyze-deployment-tooling-3.0.3.tar.gz file to your WSL filesystem. For example: \\wsl.localhost\Ubuntu\home\<user>

    2. Extract the tar.gz file (On Windows, run the commands from a WSL terminal. Start > wsl):

      cd /home/<user>

      tar -xvzf analyze-deployment-tooling-3.0.3.tar.gz

      mv analyze-deployment-tooling-3.0.3/ analyze-deployment-tooling-303

  3. If the version of i2 Analyze has not changed, you can copy the i2analyzeMinimal.tar.gz from your analyze-deployment-tooling directory to the analyze-deployment-tooling-303/pre-reqs directory. To see which version of i2 Analyze is required by each version of analyze-deployment-tooling, see compatibility table.

    1. Download the i2 Analyze V4.4.4 Minimal for Linux.
    2. Rename the downloaded file to i2analyzeMinimal.tar.gz, then copy it to the analyze-deployment-tooling-303/pre-reqs directory.

  4. Open a new VS Code window.

    1. On Windows, press F1 and type WSL: Connect to WSL and select it.
    2. Press F1 (or Cmd+Shift+P in MacOS) and type Dev Containers: Open Folder in Container and select it.
      In the file explorer, navigate to your newly created analyze-deployment-tooling-303 directory.
    3. You might see a prompt is displayed, this means a new dev environment is available, click rebuild to rebuild the remote dev container.

  5. To create the configuration development environment open a terminal and run:

    ./bootstrap

    The script performs the following actions:

    • Extracts the required files from the i2 Analyze deployment toolkit
    • Builds the required Docker images for the development environment
    • Generates the secrets that are used in the environment
    • Creates the configuration template
      • The configuration template is located in /templates/config-development.

  6. Before you can use i2 Analyze and the tools, you must read the license agreement and copyright notices then accept them.

    1. To accept the license agreement, change the value of the LIC_AGREEMENT variable to ACCEPT in the licenses.conf file.
      To read the license, open the file in the pre-reqs/i2analyze/license directory.

  7. Before you can use Microsoft SQL Server, you must accept the license agreement and the EULA. For more information about using the MSSQL_PID and ACCEPT_EULA environment variables, see Configure SQL Server settings with environment variables on Linux

    • To accept the license in this environment, change the value of the MSSQL_PID and ACCEPT_EULA environment variables. The variables are in the licenses.conf file.

      For example:

      LIC_AGREEMENT=ACCEPT
MSSQL_PID=Developer
ACCEPT_EULA=Y

  8. Update the path-configuration.json file inside analyze-deployment-tooling-303 directory to reference the path to your previous analyze-deployment-tooling version:

    1. Open a terminal on your host machine.

      • On Windows, use a WSL terminal. Press Start -> wsl

    2. Navigate to the analyze-deployment-tooling-303/scripts directory.

    3. Run the configure-paths script with the upgrade task.
      For example:

      ./configure-paths -t upgrade

      By default, the script assumes that your previous version of Analyze deployment tooling is in the /home/<user-name>/analyze-deployment-tooling directory. If your previous version is in another directory, use the -p <path> argument to specify the path.

    4. Reopen the analyze-deployment-tooling folder in a dev container.
      Press F1 (or Cmd+Shift+P in MacOS), type Dev Containers: Rebuild and Reopen in Container and select it

There are 2 options that you can choose from when you upgrade your config development environment.

  • Option 1: Upgrade all of your configs to use the latest version of analyze-deployment-tooling and the latest version of i2 Analyze if it has changed. You must use this option if you are using shared configurations.
  • Option 2: Upgrade a subset of your configs to use the latest version of i2 Analyze, and keep the remaining configs using the previous version of i2 Analyze.

If the version of i2 Analyze has not changed, you must use option 1 to upgrade your deployment. To see which version of i2 Analyze a version of analyze-deployment-tooling requires, see compatibility table.

Option 1

  1. If you want to upgrade all of the configs in your environment to use the latest version, run the following command:

    manage-environment -t upgrade

    During the upgrade process the system will ask you to respond to the following prompts:

    • To confirm you want to upgrade each config.
    • To confirm you want to upgrade all database backups for a config.

    • If you want to overwrite the previous version of analyze-deployment-tooling and continue working in your previous directory. Respond y to complete an in-place upgrade.

      If you want to answer yes to these questions for all your configs, you can run the command with the -y flag. This means that you can leave the script running without having to monitor it to respond to prompts.

      This script completes the following actions:

    • Creates a backup of the ISTORE database for each config that contains one

    • Copies the following directories from the previous project to the current project:
      • additional-resources
      • backups
      • configs
      • connector-images
      • environment-secrets
      • gateway-schemas
      • i2a-data
      • i2a-extensions
      • i2a-plugins
    • Upgrades the configs to the latest version of i2 Analyze and analyze-deployment-tooling

  2. Reopen the analyze-deployment-tooling folder in a dev container.
    Press F1 (or Cmd+Shift+P in MacOS), type Dev Containers: Rebuild and Reopen in Container and select it

  3. To start the deployment at the latest version with a config, run:

    deploy -c <config-name>

Option 2

  1. If you want to upgrade a subset of configs to use the latest version of i2 Analyze, run the following commands:

    1. Backup the database for the configs you want to upgrade:

      manage-environment -p <path-to-previous-project> -i <config-name> -b global-upgrade -t backup

      Where:

      • <path-to-previous-project> is the absolute path to your previous analyze-deployment-tooling repository
      • <config-name> is the name of a config to backup. You can provide multiple -i options for each config you want to upgrade.

    2. Copy the configs and dependencies from the previous project to the current project:

      manage-environment -p <path-to-previous-project> -i <config-name> -t copy

      Where:

      • <path-to-previous-project> is the absolute path to your previous analyze-deployment-tooling repository
      • <config-name> is the name of a config to copy. You can provide multiple -i options for each config you want to upgrade.

    3. Run the create-dev-environment command to create the images for i2 Analyze 4.4.4.

      create-dev-environment

    4. Upgrades your configs to the latest version. For each config that you want to upgrade, run:

      deploy -c <config-name>

      Where:

      • <config-name> is the name of the config to upgrade.

Troubleshooting

If the upgrade process fails, you can use the following procedure to recover.

  1. Delete the analyze-deployment-tooling-3.0.3 folder.
  2. In the backup from the previous version, ensure that you can deploy the configuration that failed.
    If you cannot deploy in the previous version, fix the errors before you upgrade or remove the config so that it isn't upgraded.
  3. Restart the upgrade process from the beginning.