Upgrading to IAM Version 2.8.1

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

To see what features have been added, see the changelogOpens in a new tab.

Migration Steps

To migrate from 2.3.3.2 to 2.8.1 (specifically to 2.8.1.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.
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
```
Perform the upgrade. To do this, you can create and run a series of docker-compose files or you can migrate manually using instructions at https://docs.konghq.com/gateway/2.8.x/install-and-run/upgrade-enterprise/#migrate-dbOpens in a new tab.

Running a Migration Using Docker Compose

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 (iam-migrations in the example here) of the target version that points to the same datastore, and run kong migrations up. This may look like:

version: '3.2'
services:
  iam-migrations:
    image: intersystems/iam:2.8.1.0-3
    command: kong migrations up
    depends_on:
      - db
    environment:
     [...]
    restart: on-failure
    links:
      - db:db
  iam:
    image: intersystems/iam:2.3.3.2-1
    depends_on:
      - db
    environment:
     [...]
    links:
      - db:db
    ports:
     [...]
    restart: on-failure
  db:
    image: postgres:9.6
    [...]
volumes:
  pgdata:

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 node is decommissioned, and a new node is provisioned with the newer version of IAM.
```
version: '3.2'
services:
  iam:
    image: intersystems/iam:2.8.1.0-3
    depends_on:
      - db
    environment:
    [...]
    links:
      - db:db
    ports:
    [...]
    restart: on-failure
  db:
    image: postgres:9.6
    [...]
volumes:
  pgdata:
```
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 last docker-compose file, step3.yml. This file should finish the current migration when run.

version: '3.2'
services:
  iam-migrations:
    image: intersystems/iam:2.8.1.0-3
    command: kong migrations finish 
    depends_on:
      - db
    environment:
    [...]
    restart: on-failure
    links:
      - db:db
  iam:
    image: intersystems/iam:2.8.1.0-3
    depends_on:
      - db
    environment:
    [...]
    links:
      - db:db
    ports:
    [...]
    restart: on-failure
  db:
    image: postgres:9.6
    [...]
volumes:
  pgdata:

Running the Docker Compose Files

Once all the files are created, run them in sequence. The command to run a given docker-compose file is:

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

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