Installation Use Case: Hybrid Installation

This document provides reference information and examples relating to installing and configuring a hybrid installation.

Table of Contents

Introduction

This document summarizes the installation of Akana Platform API Gateway on a CentOS7 or RHEL7 environment for hybrid deployment purposes.

This scenario presumes availability of an Akana SaaS tenant environment (API Portal).

What is a hybrid installation?

In the context of the Akana API platform, a hybrid installation is an implementation that uses the Akana Cloud (SaaS) platform, and also has additional infrastructure elements (Network Director instances) deployed in the customer's own data center or cloud of choice. A hybrid installation might partially use the API Gateway provided for the Akana Cloud platform, or might exclusively use its own components.

In a completely on-prem solution, all implementation components are installed and configured directly on hardware resources provided by the customer. In a SaaS-only implementation, the customer uses the SaaS cloud platform for all underlying infrastructure (Policy Manager/Network Director). The hybrid installation is a mix of these two.

In functional terms, in a hybrid scenario you can delegate Akana Platform administration to the Akana Cloud, but have your runtime API traffic flowing exclusively through your data centers only.

Advantages of a hybrid installation

Some reasons to choose a hybrid installation:

  • Regulations mandating that data must not be processed in a (public) cloud location.
  • Having the API Gateway close to the downstream services that are accessed by the APIs, with corresponding improved latency.
  • Wanting more control over runtime data processing in terms of performance, throughput, and scalability; if you have a hybrid instance, it only deals with your own message traffic.
  • A hybrid installation means that you don't need to have your own implementation of the Community Manager developer portal.
  • The following extended functionality is supported in the Akana SaaS platform but is not supported in an on-premises deployment:
    • Normalize
    • FreeMarker
    • Modify Headers
    • Map Headers

Disadvantages of a hybrid installation

Some limitations of a hybrid installation:

  • You must make sure that the Network Director version in your on-prem deployment is the same version as the SaaS platform or earlier. A scenario where your local ND is a later version will not work. However, since the SaaS platform is almost always on the latest version, this is not likely to be an issue.
  • A hybrid implementation does not support custom policies or activities in the local ND.

Prerequisites

You'll need the following:

Hybrid server

The hybrid server is the hardware or virtual machine used for API Gateway installation and configuration.

Your hybrid server must meet the Akana API Platform hardware requirements, including CPU, operating system, and memory configuration.

For information on the system requirements, refer to the System Requirements doc. The applicable sections are Akana Platform Host and Memory Configuration only).

Download of Akana software packages (Akana Platform and Akana API Platform)

You'll need to download several ZIP files from the Rogue Wave Support Center. Note that this site is for Akana customers and requires a login.

The file names given in this document are examples. Always download the latest version available, to get the latest features and updates.

Log in to the Perforce Support Center (https://library.roguewave.com). In the My Resources section, click Product Downloads, then click Akana - Product Downloads.

Choose the major product version. Then, expand the links at the top of the page to access the download files. Get the main file, and cumulative update, for the Akana Platform and the Akana API Platform. For instructions, refer to the installation documentation: go to Installing the Akana API Platform and open the installation instructions file.

Note: Verify the MD5 checksums after download, to be sure you have the complete download files.

Installation first steps

First, complete the following steps:

  • Verify connectivity between the hybrid server and Akana SaaS.

    Note: the hybrid Gateway will call out to the Akana SaaS platform. The metadata exchange service mentioned under Step 5 of Configuring the Network Director must be accessible from the hybrid server.

  • Verify the file handles O/S setting. For instructions, see Configuring O/S File Handles in the Performance Tuning doc.

A sample hybrid deployment requires Akana containers for the following Akana Platform component:

  • Network Director

Akana Home

All Akana software will be created in a folder which we will refer to as the {AkanaHome} folder. For example, this folder might be:

/home/akana/platform84

Properties files

In this example, we will do a silent installation. This means that it runs in the background; it does not require a GUI.

For silent installation, we need to create a properties file for each container. For example, ND84-1.properties represents the properties file for a single ND installation.

A properties file will have content similar to the following example:

container.instance.name=instancename
credential.username = administrator
credential.password = SecurePassword_12345
default.host=localhost
default.port=9900

For the ND container, the properties file might look something like the below:

container.instance.name=ND84-1
credential.username=admin
credential.password=SecurePassword_67890
default.host=0.0.0.0
default.port=9904

Note: It's important to choose a strong password and make sure that the password and the properties files are secure.

For more information about silent installation, see Configure Container (Silent Option).

Installing the Core Platform

Follow the steps below.

To install the core platform

  1. Unzip your Akana Platform ZIP file into the Akana Home directory. After unzipping, your directory structure should look as follows:

    Hybrid installation: folder structure

  2. Unzip your Akana Platform cumulative update ZIP file into the same Akana Home folder.

    After completing these steps, we have essentially created a basic Platform container. Additional features are made accessible to the container by uploading repositories to the container. The repositories are contained in the Akana-API-Platform zip files. These will be uploaded in the next step.

    Different Platform components (for example, Policy Manager or API Gateway/Network Director) require different features.

  3. Unzip your Akana API Platform ZIP file into the same Akana Home folder.
  4. Unzip your Akana API Platform cumulative update ZIP file into the same Akana Home folder.
  5. Go to the {AkanaHome}/bin directory. Here, run the configurator using the following command. It's best to manually type the command, rather than copying, to ensure you don't have any extra non-visible characters).
    ./startup.sh configurator –Dsilent=true –Dproperties={full path to properties file}/{filename}.properties

    Example:

    ./startup.sh configurator -Dsilent=true -Dproperties=/home/akana/aap/properties/ND84-1.properties
  6. Once the configurator has finished, your Akana Home folder will show the created instance in the /{AkanaHome}/instances folder.
  7. Start the container by running the following command:
    ./startup.sh {MyInstanceName} -bg

    Once started, you should be able to access the Akana Administration Console for the container through this URL:

    http://{my hostname}:9904/admin

    The Akana Administration Console will be accessible using the credentials specified in the properties file that was used to configure the container (for example, admin / SecurePassword_67890).

  8. In the Akana Administration Console, go to the Repository tab. It should show the Akana Platform Repository and Akana API Platform Repository, as shown below (page refresh may be needed):

    Hybrid installation: Repository features

    Note: the version numbers will be different from the ones shown above.

We will now start by installing the features required for the hybrid ND container.

Configuring the Network Director (ND)

To configure the first ND instance, follow the steps below.

  1. Once the configurator has finished (Step 5 in the previous procedure), your Akana Home folder will show the created instance in the /{AkanaHome}/instances folder.
  2. If you haven't already done so, start the container by running the following command:
    ./startup.sh {MyInstanceName} -bg

    Once started, you should be able to access the Akana Administration Console for the container:

    http://{my hostname}:9904/admin

    The Akana Administration Console will be accessible using the credentials specified in the properties file that was used to configure the container (for example, admin / SecurePassword_67890).

  3. Install the necessary features. For a Network Director container, the essential feature is Network Director. Select only this feature, and then run the installer. Once done, you will be prompted for feature configuration.

    When prompted for the Meta Data Exchange Service, provide the URL for the instance of the Akana Cloud SaaS platform that the hybrid installation will connect to. For example, for the EU cloud:

    https://platform-eu.apiportal.akana.com/wsmex

    For the global cloud:

    https://platform.apiportal.akana.com/wsmex
  4. Configuration will be completed by installing an additional plug-in. Through the Akana Administration Console for the ND container, from the drop-down list on the Available Features tab, select Plug-ins rather than Features and install the following:
    • Akana API Platform ND Extensions Feature

    After installing, the Installed Features list should look something like the below:

    Installed features list

  5. Restart the container.
  6. In the Akana Administration Console for the ND container, go to the Configuration tab and look for the Configuration Category com.soa.monitor.usage. Click Category and change two properties, as shown below:
    • Set usage.local.writer.enabled to false.
    • Set usage.remote.writer.enabled to true.

    Hybrid installation: setting properties

  7. Click Apply Changes.

Once the above steps are completed, the ND container is ready to be registered with the SaaS Platform.

If applicable, repeat the above steps to configure an additional ND container.

Registering ND with the Akana SaaS Platform

The ND container configured above can be added as an API Gateway through the API Portal (Site Admin privileges required).

  1. Once logged in, click the vertical ellipsis icon and choose Admin. In the left-side navigation menu, click API Gateways.
  2. Click Register API Gateway. Provide a meaningful name; for example, Hybrid-1. In the Metadata Auto-Discovery field, provide the following URL value, substituting valid hostname and port:
    http://{my hostname}:{my port}/metadata

    Hostname and port refer to the host where ND container has been configured and port the process is listening on.

    You can verify the contents of the metadata file by accessing this URL through a browser. It should return an XML file with container metadata. Alternatively, you can save the XML file to a secure and convenient location so that it will be accessible; depending on network configuration, the Community Manager developer portal might not have access to the default file location.

  3. Save the API Gateway configuration.

    Note: To have the Deployment Zone associated with this Gateway appear in the correct geographical location in the Community Manager developer portal's Deployment Zones widget (visual map element), configure the lat-long value when defining the API Gateway. If you don't configure the lat-long, the Deployment Zone will appear as Unknown Location.

  4. Next, go to Deployment Zones in the left nav and click Add. Provide a meaningful Deployment Zone name and optional description. In the API Gateway drop-down list, select the API Gateway that was added in the above steps. Keep the other default settings and save the Deployment Zone.
  5. By default, the HTTP listener generated for the API Gateway configuration will show an internal IP representation. Usually, it is preferable to replace this with the DNS hostname of the server that the Gateway is deployed on.

    To modify the listener hostname, navigate through Admin > API Gateways > {the API Gateway you added}. On the API Gateway Details page, navigate to the Inbound Listeners section and click Edit. Click the listener you'd like to update and click Edit again. In the Edit Listener page, make the following changes and then click Save:

    • Modify the Hostname property (for example, replace the internal IP value with the DNS hostname).
    • Add a forward slash (/) to the Context Path property.
  6. If applicable, repeat the above step to register additional ND nodes.

Appendix 1: using a proxy server for API Gateway call-out

Use case: installation includes a proxy server for outgoing traffic. In this case, you'll need to configure the Gateway to use the proxy server to call-out to the Akana Cloud.

Summary:

  1. Create two cfg files; one file will include the port configuration (:443) in the URL, and the other will not.

    Example 1, com.soa.http.proxy-portno.cfg:

    url=https://platform-eu.apiportal.akana.com
    proxy=https://proxy.customer.local:8880

    Example 2, com.soa.http.proxy-portyes.cfg:

    url=https://platform-eu.apiportal.akana.com:443
    proxy=https://proxy.customer.local:8880

    This example includes two files because some platform services have the port number, :443, explicitly in the URL, whereas others do not.

  2. Place these files in the {ND instance directory}/deploy folder.

    This will give you the com.soa.http.proxy property in the Akana Administration Console for the ND container (instructing ND to use the proxy for given hosts). ND should now be able to access the required Platform services through the proxy.