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
- Download the
tar.gz
from https://github.com/i2group/analyze-deployment-tooling/releases/tag/v3.0.1. Extract the
tar.gz
file by using the following steps:- On Windows, copy the
analyze-deployment-tooling-3.0.1.tar.gz
file to your WSL filesystem. For example:\\wsl.localhost\Ubuntu\home\<user>
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.1.tar.gz
mv analyze-deployment-tooling-3.0.1/ analyze-deployment-tooling-301
- On Windows, copy the
If the version of i2 Analyze has not changed, you can copy the
i2analyzeMinimal.tar.gz
from youranalyze-deployment-tooling
directory to theanalyze-deployment-tooling-301/pre-reqs
directory. To see which version of i2 Analyze is required by each version of analyze-deployment-tooling, see compatibility table.- Download the i2 Analyze V4.4.4 Minimal for Linux.
- To download i2 Analyze, follow the procedure described in Where can I download the latest i2 Products?
- Populate the subject of the form with
Request for i2 Analyze 4.4.4 minimal toolkit for Linux
.
- Rename the downloaded file to
i2analyzeMinimal.tar.gz
, then copy it to theanalyze-deployment-tooling-301/pre-reqs
directory.
- Download the i2 Analyze V4.4.4 Minimal for Linux.
Open a new VS Code window.
- On Windows, press F1 and type
WSL: Connect to WSL
and select it. - 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 createdanalyze-deployment-tooling-301
directory. - You might see a prompt is displayed, this means a new dev environment is available, click rebuild to rebuild the remote dev container.
- On Windows, press F1 and type
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
.
- The configuration template is located in
Before you can use i2 Analyze and the tools, you must read the license agreement and copyright notices then accept them.
- To accept the license agreement, change the value of the
LIC_AGREEMENT
variable toACCEPT
in thelicenses.conf
file.
To read the license, open the file in thepre-reqs/i2analyze/license
directory.
- To accept the license agreement, change the value of the
Before you can use Microsoft SQL Server, you must accept the license agreement and the EULA. For more information about using the
MSSQL_PID
andACCEPT_EULA
environment variables, see Configure SQL Server settings with environment variables on LinuxTo accept the license in this environment, change the value of the
MSSQL_PID
andACCEPT_EULA
environment variables. The variables are in thelicenses.conf
file.For example:
LIC_AGREEMENT=ACCEPT MSSQL_PID=Developer ACCEPT_EULA=Y
Update the
path-configuration.json
file insideanalyze-deployment-tooling-301
directory to reference the path to your previous analyze-deployment-tooling version:Open a terminal on your host machine.
- On Windows, use a WSL terminal. Press Start -> wsl
Navigate to the
analyze-deployment-tooling-301/scripts
directory.Run the
configure-paths
script with theupgrade
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.Reopen the analyze-deployment-tooling folder in a dev container.
Press F1 (or Cmd+Shift+P in MacOS), typeDev 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
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
Reopen the analyze-deployment-tooling folder in a dev container.
Press F1 (or Cmd+Shift+P in MacOS), typeDev Containers: Rebuild and Reopen in Container
and select itTo start the deployment at the latest version with a config, run:
deploy -c <config-name>
Option 2
If you want to upgrade a subset of configs to use the latest version of i2 Analyze, run the following commands:
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 previousanalyze-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.
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 previousanalyze-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.
Run the
create-dev-environment
command to create the images for i2 Analyze 4.4.4.create-dev-environment
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.
- Delete the
analyze-deployment-tooling-3.0.1
folder. - 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. - Restart the upgrade process from the beginning.