Upgrading to IAM Version 3.0

This topic describes how to upgrade the InterSystems API Manager (IAM) from version 2.8 to version 3.0.

New in IAM 3.0

Kong Gateway 3.0 is a major release and contains changes that may break existing applications. See the changelog at https://docs.konghq.com/gateway/changelog/#3000Opens in a new tab for details.

Postgres will automatically be upgraded to version 14.5 during the migration; version 9.6 is no longer supported.

Support for Podman and Podman Compose. If you choose to use Podman and Podman Compose, you must install the dnsname plugin GitHub - containers/dnsname: name resolution for containersOpens in a new tab, or create your own compose file that works with Podman

Upgrade Steps

To migrate from 2.8 to 3.0:

Download the installation tar file from the InterSystems Worldwide Response Center (WRC) download page: https://wrc.intersystems.com/wrc/coDistGen.cspOpens in a new tab. To show only the IAM kits, type IAM in the Name column.
Uncompress the file and extract the contents.
See Installing IAM for a list of the contents.
Perform the upgrade which consists of the following high level steps:
1. Stop IAM 2.8
2. Load the IAM 3.0 image and set up environment variables for IAM 3.0
3. Upgrade the database volume
4. Start IAM 3.0

Perform the Upgrade

Stop IAM 2.8

Before upgrading to IAM 3.0, you must ensure your current version of IAM is no longer running. To stop the IAM container you must be in a shell where you have previously run the setup script for your current version of IAM, or you will need to define the ISC_IAM_IMAGE and ISC_IRIS_URL environment variables. Navigate to the scripts directory containing the docker-compose.yml file for your current IAM version, and stop it, for example:

cd iam2.8/scripts
docker compose down

cd iam2.8/scripts
docker-compose down

cd iam2.8scripts
podman-compose down

Load the IAM 3.0 Image and Set Up Environment Variables for IAM 3.0

Load the IAM image into your local repository by executing the following command in the directory where you extracted the IAM archive:
```
docker load -i iam_image.tar
```
```
podman load -i iam_image.tar
```
Make a note of the value of Loaded image from the output of the docker load command. It is required in step 3b.
Run the IAM setup script and enter the requested information at the prompts.
1. In a UNIX bash shell, enter:
```
source ./scripts/iam-setup.sh
```
2. At the first prompt, enter the container image name. The container image name can be found in the output of the docker load command, as the value of Loaded image. For example, it could be:
  intersystems/iam:3.0.2.0-2
3. Enter the IP address for your InterSystems IRIS instance. If your instance is on your local machine, use your externally visible local IP address, not localhost or 127.0.0.1. If the instance is running in a container, use the IP address of the host environment, not the IP address of the container. To avoid any DNS issues, use the numeric form of the IP address.
4. Enter the web server port for your InterSystems IRIS instance.
5. Enter the password for the IAM user on your InterSystems IRIS instance.
6. Re-enter the password.
7. If you want IAM to request the license from InterSystems IRIS using HTTPS instead of HTTP, provide the full path to your CA Certificate file; otherwise, press Enter.
8. With certain InterSystems IRIS configurations, the instance is not accessible by using the instance server name. In these cases, your InterSystems IRIS instance is only accessible via its CSPConfigName URL prefix (see Changing the InterSystems IRIS Server Name in the URLOpens in a new tab) and you need to provide the prefix with a trailing slash (/) now. If this does not apply, press Enter.
9. To continue and use the information you entered, press y then press enter.

This script sets the ISC_IAM_IMAGE and ISC_IRIS_URL environment variables required by the docker-compose.yml file.

Upgrade the Database Volume

This step will upgrade Kong Gateway and Postgres. To perform these steps, you must be in the same shell as the one in which you ran the setup script or you will need to define the ISC_IAM_IMAGE and ISC_IRIS_URL environment variables.

Navigate to the directory where you extracted the IAM archive, for example, /users/iam/iam30.
From there, navigate to the scripts directory in the iam-upgrade-db directory, for example, /users/iam/iam30/scripts/iam-upgrade-db/scripts. You will find the following files: Dockerfile, docker-compose.yml, docker-upgrade

To perform the upgrade, execute the following commands:

docker compose up
docker compose down

docker-compose up
docker-compose down

podman-compose up
podman-compose down

Start IAM 3.0

Navigate to the directory where you extracted the IAM archive. For example, /users/iam/iam30. Run the following commands:

cd scripts
docker compose up -d

cd scripts
docker-compose up -d

cd scripts
podman-compose up -d

After waiting a minute, go to http://localhost:8002/overview to verify that everything is running.