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.
No special action should be required, although backing up is always recommended.
If upgrading to Apiman 2.1.0.Final from a prior version.
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).
apimanfolder you will find a file called
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.|
|3||Apiman Manager API endpoint of your old version of Apiman, often this is your bound hostname followed by
|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.
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.|
|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:
Use the latest 7.X version of Elasticsearch for a fresh start
Enabling the Elasticsearch
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
Make sure you have installed kibana in the same version (6.8.16 with
Run the migration assistant as explained here to prepare to update to the required version of Elasticsearch 7.X https://www.elastic.co/guide/en/kibana/6.8/upgrade-assistant.html
Delete the index
apiman_gatewayin kibana. Do not delete