Upgrading IAM

This topic describes how to upgrade the InterSystems API Manager (IAM) from version 0.34–1 to version 1.5.

Migration Steps from 0.34 to 1.5

Due to iterative changes between IAM version 0.34-1 and IAM version 1.5, it is necessary to complete four total migrations through three intermediary releases. The steps for each migration between versions are identical, and can be found in the Kong documentation. You may perform each step manually, or create docker-compose files to assist you (as described in Running a Migration Using Docker Compose).

To upgrade from version 0.34-1 to version 1.5, you must perform the following migrations in order:

Order	Start Version	End Version	Migration Instructions
1	0.34-1	0.35	https://docs.konghq.com/enterprise/0.35-x/deployment/migrations/Opens in a new tab
2	0.35	0.36-x	https://docs.konghq.com/enterprise/0.36-x/deployment/migrations/Opens in a new tab
3	0.36-x	1.3.x	https://docs.konghq.com/enterprise/1.3-x/deployment/migrations/Opens in a new tab
4	1.3.x	1.5	https://docs.konghq.com/enterprise/1.5.x/deployment/migrations/Opens in a new tab

To upgrade IAM from 0.34 to 1.5, you can download the installation tar files 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. You need to download the compressed tarball archives for the 1.5.0.9 version and the three “for upgrade only versions,” 0.35–5, 0.36.6, and 1.3.0.2. Once you uncompress and extract the files for each distribution kit, 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

Then perform the upgrade following the procedures in this topic. See “Installing IAM” for a list of the contents in each distribution kit.

To see what features have been added in these releases see the Kong Enterprise changelog from release 1.5.0.9Opens in a new tab to release 0.35Opens in a new tab.

Running a Migration Using Docker Compose

Upgrading from IAM version 0.34-1-x to version 1.5.0.3-x requires several incremental migrations, as described above. One way to run these migrations is by creating a series of docker-compose files to perform each step. Using docker-compose files to run the migrations can streamline the process.

The following two sections describe how to create the docker-compose files, and then how to run them.

Creating the Docker Compose Files

As each IAM cluster is unique, you must create the docker-compose files based on the configuration of your IAM cluster. You should create all these files before you start the migration. Be sure to locate all the docker-compose files in the same directory as the main docker-compose.yml file used to start and stop IAM; this ensures the files share the same network.

As an example, this section describes the process for a single-node IAM cluster:

Begin by creating a copy of the main docker-compose.yml file. Name the copy step1.yml.
Next, edit step1.yml to perform the first step of the migration: create a new node of the target version (for the first migration, 0.35) that points to the same datastore, and run kong migrations up. This may look like:
```
version: '3.2'
services:
  iam-migrations:
    image: intersystems/iam:0.35-5-1
    command: kong migrations up
    depends_on:
      - db
[...]
  iam-1:
    image: intersystems/iam:0.34-1-1
[...]
```
Then, create another new docker-compose file and name it step2.yml. When run, this file should provision a node of the target version to replace the older node. In the example below, the old “iam-1” node is decommissioned, and a new “iam-1” node is provisioned with the newer version of IAM.
```
version: '3.2'
services:
  iam-1:
    image: intersystems/iam:0.35-5-1
    depends_on:
      - db
[...]
```
For multi-node clusters, you will need to create additional docker-compose files to reprovision each node in your cluster. As this is a single-node example, we can move on to the last step of the migration.

Finally, create the next docker-compose file, step3.yml. This file should finish the current migration when run (in the case of this example, 0.34-1 => 0.35).

version: '3.2'
services:
  iam-migrations:
    image: intersystems/iam:0.35-5-1
    command: kong migrations finish
    depends_on:
      - db
[...]
  iam-1:
    image: intersystems/iam:0.34-1-1
[...]

Now, repeat this entire process for the next migration, starting by creating a copy of step3.yml and naming it step4.yml. Continue until you have created a set of docker-compose files for each incremental migration.

When you are done, you should have four sets of docker-compose files (one for each incremental migration). In this example of a single-node cluster, you should have files from step1.yml to step12.yml.

Running the Docker Compose Files

Once all the files are created, you can run them in sequence to follow the instructions in Migration Steps. The command to run the docker-compose file is:

docker-compose -f step#.yml up -d

where step#.yml is the name of the file to run.