APIcast self-managed upgrade

Updated -

Who does this affect?

This tutorial is addressed to those who are using 3scale’s Nginx downloadable files and managing the gateways themselves (native, Docker, or OpenShift deployments) and wish to update to the latest version.

If using APIcast hosted, it’s completely safe to upgrade and it shouldn’t affect the behaviour of the gateway. Just go to [your_API_name] > Integration > Configuration section and click on the ‘Start using the latest APIcast’ button. (This change can be reverted and will only empty the Public Base URL value - the rest of the configuration will remain).


Running the gateway in a supported environment is ideal for both parties. The old version of the APIcast gateway will be deprecated at the end of March 2019 and ultimately become unsupported. So, making the move sooner rather than later will make things much easier in the long term when assistance is required from Support Delivery.

  • A revamped UI to configure the gateway from, separating the staging and production environments makes it easier to distinguish what changes are applied and where to.
  • A configurable Public Base URL for the staging gateway configuration.
  • The gateway can be configured to reload configuration changes automatically.
  • Container-based, so it can be deployed on OpenShift too.
  • New APIcast policies system including out-of-the-box policies configurable via UI (Admin Portal). Including policies such as: “CORS support”, “URL rewriting, “Headers modification”, etc.

How it works?

The integration page will generate a configuration file in JSON format once saved and update the changes made. This is then stored within the 3scale account. The latest version of APIcast has been rewritten in such a way the configuration is separated from the gateway code, this has numerous benefits that won't be discussed in this document but importantly the new gateway will plugin the JSON config file on start up. The old version of APIcast can only be downloaded from the integration page, no JSON configuration was used there, just the nginx.conf and nginx.lua. It’s important to note also that both the staging and production configurations are versioned independently in the latest APIcast.

How to upgrade?

You can choose between the following deployment options:

  • Docker: The latest APIcast Docker image can be found in the Red Hat Container Catalogue. Follow the tutorial on APIcast on Docker to install and start the gateway and point it to the relevant 3scale account.
  • OpenShift: The latest APIcast OpenShift template can be found in the 3scale AMP GitHub repository. Download the template named apicast.yaml from there and follow this tutorial to install and start the gateway pointing it to the relevant 3scale account.

If specifically testing either the Staging or Production configuration, the environment variable THREESCALE_DEPLOYMENT_ENV should be passed with the start up command, for example; THREESCALE_DEPLOYMENT_ENV=staging. This example explicitly tells the API on the 3scale platform to retrieve the Staging configuration file. Note that after the upgrade, the staging environment will also be self-managed and not hosted by 3scale.
Finally, note that if any customizations have been applied to the gateway, those will need to be merged into the new APIcast code. Examples on how to customise the gateway can be found in the APIcast GitHub repo examples.


  • What will happen when upgrading to the latest APIcast in the UI?

    This is what happens when switching to the new APIcast, it prompts to set the Public Base URL, also the API used to download the configuration will not work until the Public Base URL is set, and the configuration has been saved.

  • Will it affect the current gateway configuration?

    When upgrading to the latest APIcast from the UI, it won’t affect the current gateway configuration. However, the latest UI changes are not backwards compatible and therefore the newly generated JSON configuration cannot be used with the old version of APIcast.

  • What if the latest APIcast code is already deployed before upgrading via the UI?

    If already using the latest version of APIcast then this is backwards compatible with the old UI. Principally the difference in this case is that it will not be possible to differentiate between the Staging & Production environments to test on the gateway, using the previously mentioned environment variable THREESCALE_DEPLOYMENT_ENV. This does mean it's feasible to at least try the latest version of APIcast without changing anything in the GUI. It's important to note that with the latest version of APIcast and the old UI you must set the Public Base URL as it is required for correct routing of any inbound requests to the gateway.