Apiman Migration Guide

Notes for upgrading to newer versions of Apiman. Unless stated otherwise, the instructions assume that you are upgrading sequentially version to version.

Migrating to 3.1.2.Final

No special action should be required, although backing up is always recommended.

Migrating to 3.1.0.Final

No special action should be required, although backing up is always recommended.

Migrating to 3.0.0.Final

To migrate from Apiman 2.x to 3.0.0.Final, please use Apiman’s export-import function.

Breaking Changes

Elasticsearch support removed for Apiman Manager backend storage

This does not affect Apiman Metrics or any of the Apiman Gateway.

Elasticsearch is no longer supported as a primary datastore for the Apiman Manager. Only relational databases are supported.

For a fuller explanation of why we made this decision, please refer to AEP 2: Drop Elasticsearch as Manager API database in Apiman 3 (keep for metrics, gateway, etc).

In your apiman.properties, you must now use JPA for the storage type:

apiman-manager.storage.type=jpa

Please refer to the documentation to see how you can configure Apiman to use your database of choice.

To reiterate, this does not affect metrics or the Apiman Gateway registry, components, etc.

Apiman WildFly quickstart overlays are no longer bundled with Keycloak

Keycloak has deprecated the Keycloak server overlay, which allowed us to bundle Keycloak and Apiman in the same overlay.

This is no longer supported by the Keycloak team, and hence we have been forced to follow suit to avoid shipping an insecure version of Keycloak.

We have replaced this with a Docker Compose quickstart distribution that runs Keycloak as a standalone container. This should be equally convenient for users, whilst also being more secure and a better representation of a production setup.

Apiman Docker all-in-one images are deprecated

Historically, for quickstart purposes we shipped all components required for a simple Apiman deployment into the same container.

Whilst convenient for a quick tryout, it causes significant issues with security and configuration, whilst making it awkward to transition to a full production setup.

We have replaced this with a Docker Compose quickstart distribution comprised of individual components, each hosted in their own container.

This also makes scaling Apiman easier out-of-the-box, as the gateway containers can be scaled independently of the manager.

Please refer to the Apiman documentation for further information.

Minimum database versions

For PostgreSQL, 11 is now the minimum required database version. All versions from 11 to 14 seem to work well (the latest major version as of writing).

Migrating to 2.2.3.Final

No special action should be required, although backing up is always recommended.

Migrating to 2.2.2.Final

Issues with the release process meant this version number was skipped.

Migrating to 2.2.1.Final

No special action should be required, although backing up is always recommended.

Migrating to 2.2.0.Final

WildFly & Keycloak

We have bumped WildFly to 23.0.2.Final and Keycloak to 15.1.1.Final for security reasons.

If you are using the Apiman WildFly distribution and customised apiman-standalone.xml you may need to update your configuration file. This is because of changes in the WildFly platform rather than Apiman itself.

Presently, we bundle Keycloak in some of our Apiman quickstart distributions. This is now Keycloak version 15.1.1.Final.

See the diff of the standalone-apiman.xml to understand what has changed. This mostly relates to changes in the way SSL/TLS is configured in the underlying WildFly platform.

Most production deployments should unbundle Keycloak and Apiman.

In a release in the near future, we will stop bundling Keycloak and Apiman in the quickstarts, and instead we will provide a Docker Compose file that is much more representative of a real-world deployment.

This will also mean Apiman is not forced to stay in sync with Keycloak Server releases. We hope this will be more convenient for Apiman users and the Apiman team.

Please visit our GitHub Discussions forum if you have issues.

Migrating to 2.1.5.Final

No special action should be required, although backing up is always recommended.

Migrating to 2.1.4.Final

No special action should be required, although backing up is always recommended.

Migrating to 2.1.3.Final

No special action should be required, although backing up is always recommended.

Migrating to 2.1.2.Final

No special action should be required, although backing up is always recommended.

Migrating to 2.1.1.Final

No special action should be required, although backing up is always recommended.

Migrating to 2.1.0.Final

If upgrading to Apiman 2.1.0.Final from a prior version.

Manual action required

Fixing pre-2.1.0.Final Apiman export files

In older versions of Apiman Manager export files were missing their Api Definition schemas (Swagger, OpenAPI, etc).

We have provided a migration assistant CLI tool in order to fix this.

Download an Apiman distro (e.g. Tomcat, Wildfly).
In the apiman folder you will find a file called migration-assistant-cli.jar.
You can run the tool as follows. Note that it should be run against the older/existing installation (i.e. pre-2.1.0.Final):

$ java -jar migration-assistant-cli.jar export upgrade \
  --username=admin (1)
  --password=admin123! (2)
  --endpoint=http://localhost:8080/apiman (3)
  --output=/home/myuser/fixed-export.json (4)
  --trust-all (5)

# or use it directly as a docker container
$ docker run --rm -it ghcr.io/ghcr.io/apiman/migration-assistant export upgrade <...>

1	An Apiman user with administrator privileges.
2	Password.
3	Apiman Manager API endpoint of your old version of Apiman, often this is your bound hostname followed by `/apiman`.
4	Where to write the enriched export JSON.
5	Whether to trust all certificates and hostnames (when using TLS).

This initial version of the migration assistant tool does nothing other than this enrichment operation.

Once the operation is completed, you can import the file into Apiman 2.1.0.Final and the API definitions will be present.

Elasticsearch

Apiman 2.1.0.Final requires now Elasticsearch 7.x

If you are using Elasticsearch for the Apiman Manager API backend and/or metrics, the following sections are important to pay close attention to.

Over time, it has become increasingly more difficult to maintain backwards compatibility between different versions of Elasticsearch due to frequent changes to all aspects of the database in the upstream (schemas, types, etc).

Please pay close attention to the instructions, as Elasticsearch can be very selective which versions work properly during an upgrade process.

Consider backing up your data before taking any action.

Option 1: Discarding Metrics (5.X to 7.X)

This will result in data loss, please ensure this data is not important before dropping any indices.

If the existing metrics are not important for you:

Drop your current 5.X installation completely or delete the indexes:
1. apiman_metrics
2. apiman_manager
3. apiman_gateway
Use the latest 7.X version of Elasticsearch for a fresh start

Option 2: Keeping Metrics (5.X to 7.X)

Enabling the Elasticsearch xpack features may change the license that you are running Elasticsearch under. Users should perform appropriate due diligence.

If you want to keep your metrics follow the steps:

Make sure you have the latest version of Elasticsearch 5.x (5.6.16). You have to be at least on this version.
Update Elasticsearch 5.6.16 to 6.8.16 with xpack enabled.
Make sure you have installed kibana in the same version (6.8.16 with xpack enabled)
Run the migration assistant as explained here to prepare to update to the required version of Elasticsearch 7.X www.elastic.co/guide/en/kibana/6.8/upgrade-assistant.html
Delete the index apiman_manager and apiman_gateway in kibana. Do not delete apiman_metrics

7.X Notes

A bug was introduced in the schema definition in 2.0.0.Final.

If you are already on Elasticsearch 7.X, then make sure you run an export, and drop/reindex the indexes apiman_manager and apiman_gateway.

Metrics should be unaffected.