Chapter 9. APIcast Migration Guide

This migration guide can be applied to any gateway running on the version that uses the downloadable Nginx configuration files. If you are using APIcast from versions 2.0 to 3.1, you can refer to the Migrating from customized approaches.


Links contained herein to external websites are provided for convenience only. Red Hat has not reviewed the links and is not responsible for the content or its availability. The inclusion of any link to an external website does not imply endorsement by Red Hat of the website or their entities, products or services. Red Hat is not responsible or liable for any loss or expenses that may result due to your use of (or reliance on) the external site or content.

9.1. Preliminary considerations

The following are aspects to consider when analyzing a scenario of a migration:

  • The latest APIcast gateway architecture differs from previous versions. Most of the logic regarding routing and authorization is done purely in Lua. This keeps the Nginx configuration files efficient and reusable.
  • Many of the new features added to the latest version of APIcast can replace most of the custom logic built into your current gateway. You need to check all the features and behavior included in the out-of-the-box version of APIcast. Also verify that any other features required are included in the OOTB policies.
  • There are multiple deployment options available, whereas in previous versions it was possible only the Native Openresty installation.

As a result of the changes in the APIcast gateway architecture, multiple services are supported through a single gateway instance. This means that when exposing multiple 3scale services through one gateway, it is not necessary to customize the nginx.conf to support multiple services. However, before migrating any custom features, you need to test any standard behavior that previously required some custom logic or configuration with the latest version for compatibility.

9.2. Testing the latest APIcast configuration

To test the latest APIcast configuration, you need to do the following:

  1. Check if you have the latest APIcast configuration in the 3scale GUI. You can follow the instructions listed in APIcast self-managed upgrade.
  2. Once you have confirmed you have the latest version, test APIcast according to the documentation which covers each of the deployment options.

You can create a new service in your existing 3scale account to isolate the testing traffic from any production traffic attributed to other services. If you are unable to create additional services then you can use the staging configuration from an existing service to test the new gateway. If you have some automation, such as a CI/CD pipeline built into your 3scale integration that depends on the Integration page, it might just be safer to[create a trial account] to perform the testing.

9.3. Missing features in the latest APIcast

If the latest version of APIcast does not meet all your requirements then refer to the following sections on how to implement your own custom features into the APIcast gateway. Additionally, you can open an issue either in the upstream repository or in JIRA under the Gateway component.

9.3.1. Customizing Lua

Our gateway is built on the opensource Openresty platform and Lua modules are available to further extend the Nginx gateway features. APIcast comes with a subset of those modules which can be reused to add custom features to the gateway. The custom Lua logic built into your current gateway should be migrated to custom policies. The latest APIcast uses policies for extending and/or overriding the existing APIcast behavior. You can read more about how this works in the documentation about policies.

9.3.2. Customizing Nginx configuration files

Given that some use cases might not have been considered, you will need to customize Nginx configuration files to maintain the current integration’s behavior. The following are examples where this might apply:

  • External service integrations: Integrations with Jenkins, health-check services such as Pingdom etc. You can move all these (one server block) to a separate configuration file and include it under the sites.d directory. If possible, it is suggested to handle these requests on a completely different Nginx server but this is not critical.
  • Custom Nginx directives: Any custom or additional Nginx directives that you want to apply to the API managed by APIcast need to be included in a custom configuration, under the apicast.d/location.d directory. This will apply to the main “/” location block.
  • Custom error pages: These need to be included in a custom configuration under the apicast.d/location.d directory but be aware this applies to the main “/” location block also. In this case this does not refer to errors served by the gateway, such as 403 Authentication failed and 401 Authentication parameters missing. If the server on which the gateway is running returns some other HTTP error code, then those custom pages would be returned to the client.

9.4. Migrating from customized approaches

Previous versions of APIcast use custom-module and custom-config methods to extend the feature set of the gateway. There are not many differences with the new policy method, and should therefore be an easier migration path than from previous versions of the gateway.

The most remarkable change in the way OOTB policies are configured is using the user interface in the Administration Portal. So first refer to point 2 to determine whether any of the custom features in your gateway are now either a part of the APIcast feature set or one of the OOTB policies. For custom features that are not covered here they will need to be migrated as custom policies, and it might be a simple like-for-like migration for each custom-module to custom-policy.