Apiman Manager Production Guide

Deployment Tooling for Apiman

This guide should serve as a guide to manually deploy Apiman into production.

The production guide assumes you are installing into WildFly. The instructions are slightly different if you are using some other platform (Tomcat, older WildFly versions, EAP 7).

Database

You have a number of persistence options in both Keycloak and Apiman, but this guide will focus on using an RDBMS instead of other options (e.g. Elasticsearch for Apiman or MongoDB for KC).

On a separate server, install a production ready database such as MySQL, Oracle, or PostgreSQL. You will want to create two schemas/databases:

  • keycloak

  • apiman

Make sure your DB is accessible remotely and enable whatever security options you need (SSL, users/passwords). We recommend using two different users and permissioning them appropriately (e.g. create a "sa_apiman" account and a "sa_keycloak" account).

After creating the ‘apiman' database, you can initialize it using the appropriate DDL for the database you selected. We currently support MySQL 5, Oracle 12, and PostgreSQL 9. The DDLs for these databases can be found in the quickstart overlay ZIP file, or you can grab them directly from GitHub.

For example:

github.com/apiman/apiman/tree/master/distro/data/src/main/resources/ddls

Make sure you grab the right one for whichever version of Apiman you are going to be installing (hint: use the appropriate GitHub tag).

Installation

The easiest way to install just the API Manager is to download and install the Apiman quickstart overlay ZIP and then remove the extraneous components. Follow that up with a few configuration modifications, and you should have the Manager running in no time!

Here are the steps you should take to install a standalone API Manager:

  1. Download and unpack WildFly

  2. Download Apiman

  3. Unpack Apiman into WildFly

  4. Remove unused Apiman deployments from standalone/deployments

Which Apiman deployments should you delete? These:

standalone/deployments/apiman-es.war
standalone/deployments/apiman-gateway-api.war
standalone/deployments/apiman-gateway.war

Configuration

Disabling the Keycloak Server

Because you will be using an external/standalone Keycloak server, it is useful to disable the Keycloak components that are bundled with the Apiman quickstart overlay ZIP. To do that, make the following modification to the standalone-apiman.xml file:

<subsystem xmlns="urn:jboss:domain:keycloak-server:1.1">
  <web-context>auth</web-context>
</subsystem>

Connecting to the Database

This guide assumes you are using a production ready RDBMS as the storage layer for the API Manager. Note that other options exist, but configuring them is out of scope for this guide.

Hopefully you’ve already created and initialized the database in the earlier section labeled "Installing a Database". So at this point you really only need to connect the API Manager up to the already existing database. The following must be done in order to connect to your database:

  • Deploy a JDBC driver compatible with your database

  • Update the apiman-ds.xml datasource file (to point it at your database)

  • Update the Hibernate dialect in apiman.properties

First, you will need to deploy a JDBC driver that is compatible with whichever database you have chosen. Here are two popular drivers:

MySQL 5

repo1.maven.org/maven2/mysql/mysql-connector-java/5.1.33/mysql-connector-java-5.1.33.jar

PostgreSQL 9

repo1.maven.org/maven2/org/postgresql/postgresql/9.3-1102-jdbc41/postgresql-9.3-1102-jdbc41.jar

The easiest way to deploy the driver is to simply download it and copy it into the wildfly/standalone/deployments directory.

Next, you must update or replace the apiman-ds.xml file to something that is configured for your particular database. Examples of appropriate datasource files for mysql and postgresql can be found here:

github.com/apiman/apiman/tree/master/distro/data/src/main/resources/sample-configs

These examples are also included in the apiman quickstart overlay ZIP download.

Finally, you must update the apiman.properties file to configure the Hibernate dialect for your database. Apiman includes specific dialects that should be used when installing your database via the included DDL files:

  • H2: io.apiman.manager.api.jpa.ApimanH2Dialect

  • MySQL: io.apiman.manager.api.jpa.ApimanMySQL5Dialect

  • Oracle: io.apiman.manager.api.jpa.ApimanOracle12Dialect

  • Postgresql: io.apiman.manager.api.jpa.ApimanPostgreSQLDialect

For example, here is the line you should change in the apiman.properties file:

apiman.hibernate.dialect=io.apiman.manager.api.jpa.ApimanH2Dialect

Change the value of that property to the appropriate dialect for your database.

Point the API Manager to the API Gateway

Now that both your API Manager and API Gateway are running, you need to hook them up. This just means telling API Manager where the gateway lives. There is an admin UI page in apiman that will let you do this. Simply navigate here:

api-manager-host.org:8443/apimanui/api-manager/admin/gateways

From there you will be able to click on the gateway and modify its settings. Make sure to use the Test button on the Edit Gateway UI page to make sure you got the settings right! Don’t worry, the Test button will simply try to make a connection to the API Gateway’s configuration URL, asking it for the current Gateway status. If the Gateway responds as expected, then you can be confident that your settings are correct.

You will need to log into the UI. The default credentials are: admin/admin123!
You may have changed the default user credentials when you installed and configured Keycloak. If so, make sure you use those credentials.

Configuring Keycloak Authentication for the Manager API and UI

The API Manager has a REST based API which the User Interface uses for all actions taken. It can also be used directly for automation and/or integration purposes. This API is protected by Keycloak authentication. The configuration included in the apiman quickstart overlay ZIP assumes that the Keycloak server is local, so you will need to modify the standalone-apiman.xml file to point to the remote Keycloak instance.

Here is the relevant portion of the standalone-apiman.xml file that you must change:

<realm name="apiman">
  <realm-public-key>MIIB..snip..QAB</realm-public-key>
  <auth-server-url>https://keycloak-host.org:8443/auth</auth-server-url>
  <ssl-required>none</ssl-required>
  <enable-cors>false</enable-cors>
  <principal-attribute>preferred_username</principal-attribute>
</realm>

Pointing the API Manager to a Remote Elasticsearch

The API Manager uses Elasticsearch for analysis of metrics. This metrics data is stored in Elasticsearch by the API Gateway whenever API requests are handled. Therefore, the API Manager and API Gateway must talk to the same Elasticsearch instance/cluster.

To configure Elasticsearch for the API Manager, modify these properties in the apiman.properties file:

apiman.es.protocol=http
apiman.es.host=es.myorg.com
apiman.es.port=9200
apiman.es.username=es_admin
apiman.es.password=es_admin_password

You will need to replace the values in the properties above with those appropriate for your installation of Elasticsearch.