Upgrading Akana API Platform from Version 8.4x to Version 2018.0.x

Learn how to upgrade from Akana API Platform 8.4x to 2018.0.x.

In previous versions, upgrade instructions addressed upgrading existing containers. When moving to version 2018.0.x, we recommend that you create new containers. These instructions address the scenario of upgrading from an 8.4x version to 2018.0.0 by creating new containers.

This upgrade addresses a simple container scenario of:

  • One container with Policy Manager and Community Manager installed
  • One container running the API Gateway (Network Director)

The documentation includes some notes and additional information that would be applicable if you're creating other container scenarios—for example, if you have multiple PM/CM containers, or a separate Scheduled Jobs container—but the main path is to create these two containers.

Note: If you're upgrading Policy Manager for DataPower, follow the steps in this document that you would use for upgrading Network Director.

Note: This document covers instructions for 2018.0.0. For 8.4x, see Upgrading Akana API Platform from Version 8.2 to Version 8.4x.

Using Admin Console Installing Tools Installing Plug-ins Configuration Actions

Supported Platforms: 2018.0.x

Table of Contents

Planning the Upgrade
  1. Overview
  2. Step 1-1: Review release notes
  3. Step 1-2: Plan the upgrade
  4. Step 1-3: Install and configure Elasticsearch (if not already done)
Performing the Upgrade
  1. Overview
  2. Step 2-1: Gather ZIP file or files and download to a temporary folder
  3. Step 2-2: Shut down, back up, and delete the previous version
  4. Step 2-3: Extract installation files in the correct sequence
  5. Step 2-4: Verify that Elasticsearch is running
  6. Step 2-5: Create and configure the first container
  7. Step 2-6: Create and configure additional containers
Post-Upgrade Tasks
  1. Step 3-1: Check for pending installation tasks
  2. Step 3-2: Perform configuration actions
  3. Step 3-3: Update container properties
  4. Step 3-4: Check system health
  5. Step 3-5: Configure Elasticsearch
  6. Step 3-6: Restart all containers
  7. Step 3-7: Configure API Gateway/Network Director
Upgrade Procedures/Reference:
  1. Launching the Akana Administration Console
  2. Checking that features were installed correctly
  3. Turning the scheduled jobs off
  4. Turning the scheduled jobs back on
  5. Unregistering and re-registering the Windows service
  6. Clearing Configurator cache
  7. Starting a container
  8. Refreshing the repository
  9. Upgrading by creating new containers: notes
  10. Contacting Rogue Wave Technical Support

Planning the Upgrade

Overview

In previous versions, upgrade instructions addressed upgrading existing containers. When moving to version 2018.0.0, we recommend that you create new containers. These instructions address the scenario of creating new containers for your 2018.0.x installation.

There are some steps you might need to take before starting the upgrade process, and some information you'll need to consider that might affect how you proceed, including:

back to top

Step 1-1: Review release notes

Review the release notes so that you are aware of changes to the platform. Check for upgrade notes.

Release notes are available from the Rogue Wave Support Center (https://library.roguewave.com).

back to top

Step 1-2: Plan the upgrade

Before you start downloading and installing, plan your upgrade. In particular, you'll need to:

  1. Examine your existing installation and make sure you've saved out the following information:
    • Number of containers.
    • A list of the features and add-ons installed in each container.
  2. Conditional: If standalone Elasticsearch is new for your implementation, determine where you'll install Elasticsearch, needed for the search feature. For full information on Elasticsearch, see Installing and Configuring Elasticsearch.
  3. In the Admin Console for each of your containers, review the features and add-ons that are installed, and note that information so that you can replicate it in the new containers.

    Note: If the features installed in your own implementation don't match the examples given in the procedures below, when creating your new containers, install the features that were in the previous implementation.

  4. Take all steps needed to save out container settings so that you can reproduce the configuration on the new container, where applicable. You'll need this information for Step 3-3: Update container properties. Do the following:
    • Save the context root.
    • Save all other container properties that you've customized.
    • Save out the container certificates in the Policy Manager console (see Managing Keys and Certificates). You can then upload the same certificates when configuring the container.
  5. Update the properties file for each existing container to add a new property, container.key, that specifies the existing container IDs. For example:
    container.key="fcd54dc8-ccd2-439f-a580-436d3ef2"

back to top

Step 1-3: Install and configure Elasticsearch (if not already done)

Version 2018.0.0 requires standalone Elasticsearch.

For instructions, see Installing and Configuring Elasticsearch.

back to top

Performing the Upgrade

Overview

Note: The instructions in this document are for upgrade from Akana API Platform 8.4x to Akana API Platform 2018.x. If you're upgrading from an earlier version, you'll need to perform additional steps first, to upgrade to version 8.4. See Upgrading Akana API Platform from Version 8.2 to Version 8.4x.

At a high level, to perform the upgrade, you'll complete the following actions:

  1. Shut down the previous version, make a complete backup, and then delete the contents of the original installation folder.
  2. Extract installation files in the correct sequence.
  3. Verify that Elasticsearch is running.
  4. Create containers.
  5. Configure the containers and test the installation

back to top

Step 2-1: Gather ZIP file or files and download to a temporary folder

The first step is to download the required ZIP files to a temporary folder. From there, you'll unzip the files into your installation folder. You'll need to:

  • Create a temporary folder for the downloaded ZIP file.
  • Create a folder for your 2018.0.x installation; for example, aap2018.
  • Download the ZIP file for version 2018.0.0.

For detailed instructions on this step, refer to the installation guide, Gather ZIP file or files and download to a temporary folder.

Note: For notes about limitations and extra steps for specific databases, see Supported databases (installation doc). If you're using a MySQL database with API Platform and the Lifecycle Repository feature, see Database notes: MySQL with Lifecycle Repository.

Depending on the scenario, you might also need one or more of the following files:

  • Plug-ins: The ZIP file, and any updates, for any plug-ins you want to use in your installation.
  • Updates: not applicable to version 2018.0.0 itself, but for future updates.

If you have a specific add-on feature installed, such as the Integration Services option pack, SiteMinder Security Provider, or SAML Web SSO Security Provider feature, it's important that you download the new release version package for the same feature.

back to top

Step 2-2: Shut down, back up, and delete the previous version

  1. Shut down all containers in your installation.
  2. Copy the entire installation folder structure to a secure backup location.
  3. Make sure you have a backup of your database also.
  4. When you're completely sure that the backup is complete, successful, and secure, delete the contents of your original installation folder.
  5. Create a new folder for your new installation, or use the existing, empty folder.

Back to top

Step 2-3: Extract installation files in the correct sequence

The next step is to extract the files, following the exact sequence below.

Note: You'll need a password to unzip the files. If you don't know the password, contact your Akana representative.

To unzip the installation files
  1. In the temporary folder that you created for the downloaded ZIP file in step 2-1, unzip the downloaded ZIP file.
  2. Unzip the Akana Platform 2018.0.0 file to the folder for your installation.
  3. When the previous step is complete, unzip the Akana API Platform 2018.0.0 file to the folder for your installation.

    For example:

    unzip -o /akana/downloads/akana-platform-linux-jre-2018.0.0.18.zip -d /akana/aap2018
    unzip -o /akana/downloads/akana-api-platform-2018.0.0.340.zip -d /akana/aap2018

    For information about the folders and folder contents for the Akana Platform, see Installation folder structure.

  4. If applicable, unzip any add-on products, such as the SAML Web SSO Security Provider.

Back to top

Step 2-4: Verify that Elasticsearch is running

Elasticsearch is a separate installation. Make sure it's installed successfully and is running.

For example, run this command:

ps -ef

If there is response content, Elasticsearch is running. For example:

/usr/share/elasticsearch/modules/x-pack/x-pack-ml/platform/linux-x86_64/bin/controller

See also:

Back to top

Step 2-5: Create and configure the first container

Create the first Community Manager/Policy Manager container. For features to install, see Community Manager/Policy Manager container features with access to MongoDB. Follow the linked steps in the Installation Guide.

Note: In creating the containers, make sure that you set up at least one container running Policy Manager before you set up the Network Director container.

To create and configure the first container
  1. Run Configurator to create the first container, either via the GUI or using silent install. See Step 3: Run Configurator to create the first container.
  2. Copy the configuration properties file from the old container, which you saved out and updated with a new container.key property in Step 1-2: Plan the upgrade (procedure step #5), to the new container. Then start the new container.
  3. Install Policy Manager/Community Manager. See Step 4: Install Policy Manager/Community Manager features on the container (installation doc).
  4. At the Installation Complete summary, click Configure to complete pending tasks. See Step 6: Complete pending tasks to configure container features. The pending tasks are:
    1. Manage PKI Keys wizard (Generate PKI Keys & X.509 Certificate page).

      See Installation wizard: Manage PKI Keys (installation doc).

    2. Configure Database Options wizard (Select Database Options page): here, choose Use Existing Database and put in the values and credentials for the database from your prior version of the Akana API Platform.

      See Installation wizard: Add Database (installation doc).

      Note: Depending on the database you're using, you might need to put a database driver in place, or take some other steps.

      See Database notes and Database drivers (installation doc).

    3. Manage Schemas wizard (Install Schemas page): Manages the database schemas for the container.

      See Installation wizard: Manage Schemas (installation doc).

    4. Create Policy Manager Admin User (Define Policy Manager Administrator Credentials page): Creates the top-level Policy Manager user.

      See Installation wizard: Define Policy Manager Administrator Credentials (installation doc).

    5. Provisioning: Initializes resources associated with the features installed on the container.

      See Installation wizard: Provisioning (installation doc).

  5. At the Restart prompt, to install the plug-ins before restarting, press Cancel.
  6. If applicable, install plug-ins. See Step 5: (as needed) Install plug-ins on the container.
  7. Restart the container. For instructions, see:

back to top

Step 2-6: Create and configure additional containers

Once you have the first container set up, it's time to create and configure additional containers. Essentially you'll follow the same set of steps as above, for these additional containers:

  1. Optional: Subsequent Community Manager/Policy Manager containers. If you're following the sample deployment scenario, see Community Manager/Policy Manager container features with access to MongoDB.
  2. Network Director container. For features to install, see API Gateway/Internal Gateway (Network Director). For Network Director, pending tasks include:
    1. WS-Metadata Exchange Options: see Installation wizard, ND container: Configure WS-Metadata Exchange Options.
    2. Manage PKI Keys wizard (Select Key Management Option page): see Installation wizard: Manage PKI Keys.
  3. OAuth container. For features to install, see OAuth Provider.
  4. Scheduled Jobs container. For features to install, see Job Scheduler.

Note: In each case, be sure to copy the configuration properties file from the old container, which you saved out and updated with a new container.key property in Step 1-2: Plan the upgrade (procedure step #5), to the new container.

Create containers in this sequence:

  1. First, create all Policy Manager/Community Manager containers.
  2. Then, create all Network Director containers.

    You can create a Network Director container using either GUI or Silent options. For instructions on how to install a Network Director Container (ND1), install and configure the Network Director feature, and register the ND1 container in Policy Manager, refer to Using Network Director Feature.

For information about the features and plug-ins to install for additional container configurations, see Sample Deployment Scenarios (Install doc).

back to top

Post-Upgrade Tasks

Post-upgrade tasks: overview

Once you've completed the product version update, there are additional post-upgrade tasks you'll need to complete. Some of these steps are conditional depending on platform features you're using. They include:

back to top

Step 3-0: Upload container certificate

Upload the container certificate that you exported in Step 1-2: Plan the upgrade, #3.

For detailed instructions, see Managing Keys and Certificates.

back to top

Step 3-1: Check for pending installation tasks

When you've created all containers, check for pending installation tasks in each container.

In the Akana Administration Console, under Installed Features, check at the bottom of the page under Pending Installation Tasks.

If any are listed, click Complete Configuration.

An example is shown below.

Pending installation tasks
  • Manage PKI keys: Specifies key management options.
  • Add Database: Creates the database for the installation.
  • Manage Schemas: Manages the database schemas for the container.
  • Create Policy Manager Admin User: Creates the top-level Policy Manager user.
  • Provisioning: Initializes resources associated with the features installed on the container.

Note: All these configuration actions are also available under Configuration > Configuration Actions. For more information on configuration actions, see Using Configuration Actions.

back to top

Step 3-2: Perform configuration actions

If you're upgrading from a previous version, it's a good idea to run the following configuration actions, even if they were not listed under Pending Installation Tasks:

To perform provisioning
  1. In the Akana Administration Console, click the Configuration tab.
  2. In the Configuration Actions section, choose the Provisioning configuration action, as shown below.

    Running Provisioning manually

  3. On the Provisioning page, make sure Perform Provisioning is checked, as shown below, and then click Finish.

    Note: Make sure the Provisioning task is 100% complete before moving to the next task.

    Provisioning Summary

  4. When provisioning is 100% complete, click Close.
To complete the Upgrade CM Models configuration action
  1. In the Akana Administration Console, click the Configuration tab.
  2. In the Configuration Actions section, choose Upgrade CM Models.
  3. When done, click Close.

The Rebuild CM Styles task makes sure that you have the latest style updates, for all themes and tenants.

To rebuild CM styles
  1. In the Akana Administration Console, click the Configuration tab.
  2. In the Configuration Actions section, choose Rebuild CM Styles.
  3. When done, click Finish.

back to top

Step 3-3: Update container properties

When you've created the new container and installed the features, it's time to set the configuration properties. You'll need to transfer any customized settings that were set on the old container, to the new container.

Use the setting values that you saved out in Step 1-2: Plan the upgrade, point #4, and set them on the new container.

For example, if you customized the Content Root value for the developer portal, you'll need to re-set it.

In the Akana Administration Console for each container with Community Manager installed:

Configuration > com.soa.atmosphere.console > atmosphere.context.root.

For example, /acmepaymentscorp.

For detailed instructions, see Conditional: updating configuration setting for new context root (installation doc).

back to top

Step 3-4: Check system health

Log into the Akana Administration Console for the PM/CM container and check the system health (Health tab).

back to top

Step 3-5: Configure Elasticsearch

The developer portal is now available, but search will not work until you configure Elasticsearch.

Note: These steps assume that Elasticsearch is already installed and configured. See Step 1-3: Install and configure Elasticsearch (if not already done).

Steps:

  1. Configure global settings
  2. Clear the Elasticsearch index
  3. Check Elasticsearch status
  4. Restart the container
  5. Verify that search is working
Configure global settings

As part of installation or upgrade, you'll need to configure a couple of global settings in the Akana Administration Console so that the Elasticsearch feature will work correctly.

In the Akana Administration Console for any one container:

Configuration > Configuration Actions > Configure Elasticsearch Global Configuration.

For instructions, see How do I configure Elasticsearch?

Clear the Elasticsearch index

You'll need to clear out the old Elasticsearch index so it can be refreshed. To do this, complete these two steps, at the same time:

  • Empty the INDEX_STATUS table in the database by running this database command:
    delete from {database_name}.INDEX_STATUS;

    For example:

    Clearing the Elasticsearch index

  • Delete the index folders from their storage location, so that new index folders will be created when the index is regenerated.
Check Elasticsearch status

You can use the Elasticsearch API to check the status of your Elasticsearch, to make sure all is running smoothly. In the below, substitute the node where Elasticsearch is running:

GET {protocol}://{hostname}:{port}/

The response is a JSON object with information about your Elasticsearch. For more information, refer to the Elasticsearch website: Connect to Elasticsearch.

Restart the container

Stop and restart the container.

For instructions, see:

Verify that search is working

Log in to the developer portal user interface and verify that search is now working. For example, search for an API or an app.

This completes the Elasticsearch steps.

back to top

Step 3-6: Restart all containers

After running the configuration actions on all containers, stop and restart all containers.

For instructions, see:

back to top

Step 3-7: Configure Network Director

The next step is to create the API Gateway, in the developer portal.

To set up the API Gateway in the developer portal
  1. Go to the URL you set up for the developer portal, and log in using the default credentials you used to create the developer portal.
  2. Go to Admin > API Gateways and choose Register API Gateway.
  3. On the Register API Gateway page, set up the following values:
    • A short intuitive name. For example: ND1.
    • Metadata Auto-Discovery: Set up the metadata URL for the Network Director container in Step 2-6: Create and configure additional containers, using the URL you set up for the container and appending /metadata. For example: http://localhost:9902/metadata. If the URL is secure, click Specify Credentials and enter username and password.
  4. For more information about the fields on this page, see How do I register an API Gateway? (developer portal help).
  5. Click Save.
  6. In the developer portal user interface, modify the deployment zone to use the new Network Director (Admin > Deployment Zones). For instructions, see How do I make changes to a deployment zone? (developer portal help).
  7. Test to make sure that the new Network Director is working correctly.

back to top

Upgrade Procedures/Reference

Launching the Akana Administration Console

Installation and configuration tasks are performed in the Akana Administration Console for the container. First you create the container, and then you install features into the container and configure them.

To launch the Akana Administration Console
  1. Launch the Akana Administration Console for the container instance:
    http://{hostname}:{port}/admin
  2. Log in to the Akana Administration Console as an Administrator. The Akana Administration Console launches and displays the Available Features tab. See Installation Options: Full List (installation doc).

back to top

Checking that features were installed correctly

When you've installed features in a container, it's a good idea to check to make sure that features have been installed correctly.

  1. In the Akana Administration Console, go to Installed Features.
  2. Look at the Version column to make sure each feature has the correct version number. An example is shown below.

    Features installed tab: 2018.0.0

If there are any issues, check that you followed all steps correctly.

If needed, contact Technical Support.

back to top

Turning the scheduled jobs off

If you turn off the scheduled jobs, turn off these two jobs, for all containers with Policy Manager installed, in this sequence:

  1. com.soa.scheduler.quartz
  2. simple.scheduler.enabled
To turn off scheduled jobs
  1. Log in to the Akana Administration Console using Administrator credentials.
  2. Click the Configuration tab.
  3. In the Configuration Categories section, find com.soa.scheduler.quartz.
  4. Locate the org.quartz.scheduler.enabled property and change it to false.
  5. Click Apply Changes.
  6. In the Configuration Categories section, find com.soa.scheduler.
  7. Locate the simple.scheduler.enabled property and change it to false, as shown below.

    Turning off scheduled jobs

  8. Click Apply Changes.

back to top

Turning the scheduled jobs back on

If you turned the scheduled jobs off, and are ready to turn them back on again, turn them on in this sequence, the reverse of the sequence in which you turned them off, for all containers with Policy Manager installed:

  1. simple.scheduler.enabled
  2. com.soa.scheduler.quartz
To turn scheduled jobs back on
  1. Log in to the Akana Administration Console using Administrator credentials.
  2. Click the Configuration tab.
  3. In the Configuration Categories section, find com.soa.scheduler.
  4. Locate the simple.scheduler.enabled property and change it to true.
  5. Click Apply Changes.
  6. In the Configuration Categories section, find com.soa.scheduler.quartz.
  7. Locate the org.quartz.scheduler.enabled property and change it to true.
  8. Click Apply Changes.

back to top

Unregistering and re-registering the Windows service

If your containers are registered as a Windows service, so that the container will start automatically when Windows starts, you must unregister the old version and register the new version, for each container.

If you're not sure which containers are registered as a Windows service, you can check in the Windows Control Panel (Administrative Tools > Services). To change the services, you must run as Administrator.

To unregister and register the Windows service
  1. Open a command prompt in Administrator mode (If you don't use Administrator mode, Windows prompts for Admin permission before unregistering/registering the service, but doesn't actually start the service).
  2. Unregister the previous version as a windows service:
    .\{install_folder}\bin\unregisterContainerServiceYAJWS.bat {instance_name}
  3. Register the new version as a Windows service:
    .\{install_folder}\bin\registerContainerServiceYAJWS.bat {instance_name}
  4. If you're running in Administrator mode, Windows registers the service and also starts it.
  5. Repeat steps 2 and 3 for each additional container that's registered as a Windows service.

back to top

Clearing Configurator cache

Before performing the upgrade, make sure the configurator cache is clear. At this point, there won't be any cache unless you launched the Configurator at the end of Step 2-3. To be sure, follow the steps below.

To clear configurator cache
  1. Locate the configurator cache folder: \instances\configurator\cache, as shown below.

    Configurator cache folder

  2. Delete the folder if it exists (if there is no cache, the folder will not be there).

back to top

Starting a container

There are several ways you can start a container: Windows, as Windows service, or Unix. Follow the applicable procedure:

To start the container (Windows)
  1. Navigate to the \{install_folder}\bin\ folder.
  2. Type the following:
    startup {instance_name}
To start the container (as Windows service)
  1. Launch the Program Group (Settings > Control Panel > Administrative Tools > Services).
  2. Select the Akana Container Instance (the instance name is displayed as the Container Key).
  3. From the Actions menu, select Start.
To start the container (Unix)
  1. Navigate to the /{install_folder}/bin/ folder.
  2. Type the following:
    startup.sh {instance_name}
To start the container (Unix, Background)
  1. Navigate to the /bin folder.
  2. Type the following:
    startup.sh {instance_name} -bg

back to top

Refreshing the repository

Verify that the repository is there. Refresh if needed.

To verify/refresh the repository
  1. Click the Repository tab and verify that the Akana Platform Repository and the Akana API Platform Repository are both present, as shown below.

    Repository tab: 2018.0.0

  2. Conditional: if you don't see both these repositories, click Refresh to update.

Further installation steps are conditional:

  • If your container doesn't have Policy Manager features installed (Akana Policy Manager Console and Akana Policy Manager Services), the upgrade is complete.
  • If your container does have Policy Manager features installed (Akana Policy Manager Console and Akana Policy Manager Services), continue.

back to top

Upgrading by creating new containers: notes

When you're upgrading by creating new containers, it's important that you delete the existing container from the Policy Manager workbench before creating the new container.

If you don't delete the old container before creating the new one, you might encounter an error on the provisioning step, similar to the one shown below (WSDL binding cannot be disassociated from service):

[425] com.digev.fw.exception.GException: Wsdl binding [uddi:4b0aba1c-8ca7-e61c-5575-25361578c179] 
cannot be disassociated from service [uddi:soa.com:metadataattachment-servicekey]. 
Binding is attached to service endpoint.

If you encounter this message, delete the old container, and then retry the provisioning.

Back to top

Contacting Rogue Wave Technical Support

If you need to contact Technical Support, submit an email to support@akana.com.

When sending a support query, please provide the following information:

  • Your name
  • Email address
  • Subject
  • As much information as possible regarding your question.

You'll receive an acknowledgment email and one of our support staff will contact you.

You can also access the Support site at https://servicedesk.akana.com/servicedesk/customer/user/login.

Back to top