Upgrading a Previous Installation

Overview

This topic describes how to upgrade your existing configuration data (policies, filters, certificate store, and so on) from a previous version to API Gateway version 11.1.2.1.0. This enables you to migrate the policies that you configured in a previous version to API Gateway version 11.1.2.1.0.

API Gateway 11.1.2.1.0 provides a script to upgrade existing configuration from previous versions, which is the recommended approach. This script generates a .fed file, which you can deploy using the Policy Studio, the managedomain script, or the Web-based API Gateway Manager tool.

Upgrade Steps

The main steps required for upgrading are as follows:

Install Oracle API Gateway 11.1.2.1.0 (see Installing the API Gateway).
Create a managed domain for your deployment topology (see Configuring a Managed Domain).
Upgrade your existing configuration using the API Gateway upgrade script.
Upgrade Role-Based Access Control (if upgrading from version 11.1.1.6.x).
Upgrade your reports database (if Oracle API Gateway Analytics is installed).

This topic assumes that you have already performed steps 1-2, and describes how to perform steps 3-5. For details on product components and concepts, see the Oracle API Gateway User Guide.

Prerequisites

You must have already installed API Gateway 11.1.2.1.0, and configured a managed domain.

Important

These steps describe only how to upgrade the configuration data from a previous version to 11.1.2.1.0. The supplied upgrade scripts do not upgrade the version of the Oracle server software installed on the machine.

You must ensure that API Gateway 11.1.2.1.0 is installed into a different directory from the existing (pre-11.1.2.1.0) version.

Upgrading to Version 11.1.2.1.0

Complete the following steps to upgrade a version 5.x or 6.x installation to API Gateway version 11.1.2.1.0 using the upgrade script:

Stop your pre-version 11.1.2.1.0 server.
Make a backup copy of the following existing directory that needs to be upgraded:
```
INSTALL_DIR/apigateway/conf
```
Create a directory to store the output .fed file (for example, C:\upgraded).
Open a command prompt at the following directory in your 11.1.2.1.0 installation:

Windows
```
INSTALL_DIR\apigateway\Win32\bin
```
UNIX/Linux
```
INSTALL_DIR/apigateway/posix/bin
```
Run the upgradeconfig command. For example:

Windows
```
upgradeconfig -d C:\oraclegateway -o C:\upgraded
```
UNIX/Linux
```
./upgradeconfig -d /opt/oraclegateway -o /opt/upgraded
```
When the script has finished running, the .fed file is generated in the specified destination (for example, C:\upgraded).
Deploy the .fed file. For details, see the section called “Deploying the .fed File”.
Upgrade your RBAC configuration. For details, see the section called “Upgrading Role-Based Access Control”.
If you wish upgrade the database used for Oracle API Gateway Analytics, see the section called “Upgrading a Reports Database”.

For full details on all command options, enter upgradeconfig --help at the command prompt.

Deploying the .fed File

You can deploy the generated .fed file using the Policy Studio, the Web-based API Gateway Manager tools, or the managedomain script.

Deploying with the Policy Studio

To deploy an upgraded .fed file using the Policy Studio, perform the following steps:

Ensure that the Admin Node Manager and API Gateway instances that you wish to deploy to are running.
Start the Policy Studio, and click Connect To Server, or click an existing server session.
In the Topology view, click the Deploy button in the toolbar.
In the Select the servers(s) you wish to deploy to section, select a server group from the list, and select the server instance(s) in the box below.
In the Select the configuration you wish to deploy section, select I wish to deploy an existing archive.
In the Location of archive field, click Browse, and select the generated .fed file.
Click Deploy to upload the archive to the Admin Node Manager, and deploy it to the currently active selected server(s).
When the archive has deployed, click Finish.

Deploying with API Gateway Manager

API Gateway Manager is a centralized Web-based dashboard that enables administrators to control and manage API Gateway and groups in a domain. You can access the API Gateway Manager tools at https://localhost:8090. To deploy an upgraded .fed file using API Gateway Manager, perform the following steps:

On the Dashboard tab, in the Topology section, select the group to which you wish to deploy the configuration.
Click the icon to the right of the group name, and select Deploy Configuration.
Select I wish to deploy an existing archive, and browse to select the .fed that you generated.
Click Next.
Select the server instances in the group that you want to deploy to and click Deploy.
Click Finish, and test your configuration.

Deploying with the managedomain Script

You can also deploy a generated .fed file using the managedomain script in the following directory:

Windows

INSTALL_DIR\apigateway\Win32\bin\managedomain

UNIX/Linux

INSTALL_DIR/apigateway/posix/bin/managedomain

When you run managedomain, you can select a set of options. Option 18 is for deploying from a .fed file. Enter 18, and follow the instructions in the output (user input in bold):

Select option: 18
Select a group:
  1) Group1
  2) Enter group name
Enter selection from 1-2 [2]: 1
Select one of the following options for deployment:
  1) Enter name of directory containing federated store config files
  2) Enter name of deployment archive file
  3) Enter tagname
Enter selection [1]: 1
Enter name of directory containing configuration files 
[/Oracle-11.1.2.1.0/apigateway/skel/system/conf/templates]: /path/to/fed/file/   
Enter name: Upgraded Config
Enter description: the upgraded configuration
Enter version: v1.5
Enter version comment: Upgraded of v1  
Do you wish to deploy to all API Gateways in the group ? [y]: y
Loading configuration '7b2f0a3b-89cd-4bdb-8b66-732992400d47' to hosts running group...
Loaded configuration '7b2f0a3b-89cd-4bdb-8b66-732992400d47' to hosts running group.
Deploying to API Gateway 'APIServer1'...
Deployed to API Gateway 'APIServer1' successfully.
Deploying to API Gateway 'APIServer2'...
Deployed to API Gateway 'APIServer2' successfully.
Hit enter to continue...

Upgrading Role-Based Access Control

In API Gateway version 11.1.2.0.0, the Role-Based Access Control (RBAC) support changed to use a JSON-based implementation with new API Gateway user roles. If you are upgrading from version 11.1.1.6.x, you must reconfigure your RBAC settings.

The API Gateway provides the following sample script to migrate your existing users:

INSTALL_DIR/samples/migrate/pdMigrate.py

This script extracts the existing users from the following file:

INSTALL_DIR/apigateway/conf/pdEntities.xml

and places them into the following file:

INSTALL_DIR/apigateway/conf/adminUsers.json

For example, you can run this script as follows:

Windows

INSTALL_DIR\Win32\bin\jython ..\..\samples\scripts\migrate\pdMigrate.py
C:\from\oraclegateway; C:\to\apigateway

Linux/UNIX

INSTALL_DIR/posix/bin/jython ../../samples/scripts/migrate/pdMigrate.py
from/oraclegateway; to/apigateway

For more details on RBAC, see the chapter on "Configuring Role-Based Access Control" in the Oracle API Gateway User Guide.

Upgrading a Reports Database

If you have an existing installation of Oracle API Gateway Analytics version 11.1.1.6.x, and wish to upgrade your existing reports database to version 11.1.2.0.x, you can upgrade your database tables using the dbsetup script. For more details, see Configuring the Database for Oracle API Gateway Analytics.

	Important
	Only upgrades of version 11.1.1.6.x databases are supported. Upgrades of earlier versions are not supported. Upgrades of version 11.1.2.0.x are not required.

Further Information

If you encounter any problems with upgrading from a previous version, contact the Oracle Support team with your queries (see Oracle Contact Details).

Oracle® Fusion MiddlewareUpgrading a Previous Installation