Upgrading Configuration from a Previous Version

Contents

Overview
Prerequisites
Upgrading to Version 11.1.2.2.0
Deploying the Configuration Package
Upgrading Role-Based Access Control
Upgrading a Reports Database
Upgrading API Gateway Analytics
Further Information

Overview

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

API Gateway 11.1.2.2.0 provides a script to upgrade existing configuration from previous versions, and which is the recommended approach. This script generates configuration packages (.fed, .pol, and .env files), which you can deploy using Policy Studio, the managedomain script, or the API Gateway Manager web console. This topic shows examples of deploying a .fed file. For more details on configuration packages, see the Deployment and Promotion Guide.

[Note] Note

For details on patching an existing API Gateway version 11.1.2.2.0 installation, see Installing the API Gateway Core Server.

Upgrade Steps

The main steps required for upgrading are as follows:

  1. Install Oracle API Gateway 11.1.2.2.0 (see Installing the API Gateway Core Server).

  2. Create a managed domain for your deployment topology (see Configuring a Managed Domain).

  3. Upgrade your existing configuration using the API Gateway upgrade script.

  4. Upgrade Role-Based Access Control (if upgrading from version 11.1.1.6.x).

  5. Upgrade your reports database (if API Gateway Analytics is installed).

[Important] Important

This topic assumes that you have already performed steps 1-2, and describes how to perform steps 3-5. The upgrade mechanism does not recreate your existing deployment topology. You must create your deployment topology using the managedomain command (see Configuring a Managed Domain).

For details on product components and concepts, see the Oracle API Gateway Concepts Guide.

Prerequisites

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

[Note] Note

These steps describe how to upgrade the configuration data from a previous version to 11.1.2.2.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.2.0 is installed into a different directory from the existing (pre-11.1.2.2.0) version.

Upgrading to Version 11.1.2.2.0

Complete the following steps to upgrade to API Gateway version 11.1.2.2.0 using the upgrade script:

  1. Stop your pre-version 11.1.2.2.0 server.

  2. Make a backup copy of the following existing directory that needs to be upgraded: 

    INSTALL_DIR/apigateway/conf

  3. Create a directory to store the output configuration packages (for example, C:\upgraded).

  4. Open a command prompt at the following directory in your 11.1.2.2.0 installation:

    Windows 

    INSTALL_DIR\apigateway\Win32\bin

    UNIX/Linux 

    INSTALL_DIR/apigateway/posix/bin

  5. Run the upgradeconfig command. For example:

    Windows 

    upgradeconfig -d C:\vordelgateway -o C:\upgraded

    UNIX/Linux 

    ./upgradeconfig -d /opt/vordelgateway -o /opt/upgraded

    When the script has finished running, the configuration packages (.fed, .pol, and .env files) are generated in the specified destination (for example, C:\upgraded).

  6. Deploy the .fed file. For details, see the section called “Deploying the Configuration Package”.

  7. Upgrade your RBAC configuration. For details, see the section called “Upgrading Role-Based Access Control”.

  8. If you wish upgrade the database used for API Gateway Analytics, see the section called “Upgrading a Reports Database”.

Further Information

By default, the upgradeconfig script outputs an upgrade log file with a trace level of INFO to the directory from which it runs. You can specify a different trace level and directory using the --tracelevel and --tracedir options. For full details on all command options, enter upgradeconfig --help at the command prompt.

Deploying the Configuration Package

You can deploy the generated configuration package (.fed, .pol, or .env file) using Policy Studio, the Web-based API Gateway Manager tools, or the managedomain script. This section shows an example of deploying a .fed file (equivalent to the combined contents of .pol and .env files).

Deploying with Policy Studio

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

  1. Ensure that the Admin Node Manager and API Gateway instances that you wish to deploy to are running.

  2. Start Policy Studio, and click Connect To Server, or click an existing server session.

  3. In the Topology view, click the Deploy button in the toolbar.

  4. 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.

  5. In the Select the configuration you wish to deploy section, select I wish to deploy an existing archive.

  6. In the Location of archive field, click Browse, and select the generated .fed file.

  7. Click Deploy to upload the archive to the Admin Node Manager, and deploy it to the currently active selected server(s).

  8. 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:

  1. On the Dashboard tab, in the Topology section, select the group to which you wish to deploy the configuration.

  2. Click the icon to the right of the group name, and select Deploy Configuration.

  3. Select I wish to deploy an existing archive, and browse to select the .fed that you generated.

  4. Click Next.

  5. Select the server instances in the group that you want to deploy to and click Deploy.

  6. 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.2.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...

Further Information

For examples of deploying .pol and .env files, see the Deployment and Promotion Guide.

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 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 API Gateway Analytics.

[Important] 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.

Upgrading API Gateway Analytics

If you have made changes to the configuration of an existing installation of API Gateway Analytics, and you do not wish to reconfigure these changes, you can also use the upgradeconfig script to upgrade API Gateway Analytics. You can do this by running upgradeconfig from the following location:

Windows 

INSTALL_DIR\oaganalytics\Win32\bin

UNIX/Linux 

INSTALL_DIR/oaganalytics/posix/bin

For more details on running this script, see the section called “Upgrading to Version 11.1.2.2.0”.

[Note] Note

This step is normally not required unless you have made significant changes to the configuration of an existing installation of API Gateway Analytics (for example, for Role-Based Access Control).

Further Information

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

Prev     Next
  Home