NGINX Controller API Management Module

Learn about the new features, enhancements, resolved issues, and known issues in the NGINX Controller API Management module.

Release Notes

These are the release notes for the NGINX Controller v3 API Management module.

NGINX Controller is NGINX’s control-plane solution that manages the NGINX data plane. Built on a modular architecture, NGINX Controller enables you to manage the entire lifecycle of NGINX Plus, whether it’s deployed as a load balancer, API gateway, or a proxy in a service mesh environment.

We encourage you to install the latest version of NGINX Controller to take advantage of the newest features and updates.

Technical support is provided for earlier versions of NGINX Controller that were released within two years of the current release.

See Also:

For related installation documentation, refer to the following publications:

Important:

Upgrading from NGINX Controller 3.x to NGINX Controller API Management module 3.18 or later

NGINX Controller 3.x includes the NGINX Controller Application Delivery module (ADC) and NGINX Controller API Management module (APIM).

Starting with APIM 3.18, the ADC and APIM modules are released independently on different schedules.

If you’ve installed NGINX Controller 3.18 or earlier before July 2021, we recommend you use the ADC module going forward.

However, if you want to upgrade to APIM 3.18 or later, we recommend that you upgrade to NGINX Controller 3.17 first.

After upgrading NGINX Controller, you must upgrade the NGINX Controller Agent, too. The Controller Agent may go offline during the upgrade process.

 


NGINX Controller API Management 3.18.1

July 23, 2021

New Issues

The following issues are known to be present in this release. Look for updates to these issues in future NGINX Controller APIM release notes.

  • Upgrade from NGINX Controller v3.10 to NGINX Controller API Management module v3.18.1 will fail (26957)

    Upgrading NGINX Controller 3.10 to NGINX Controller API Management Module 3.x is not supported. Upgrade attempts will fail.

  • Additional steps required to upgrade Controller Agents when updating from NGINX Controller 3.9.0 to NGINX API Management Module 3.18.1 (27030)

    After updating NGINX Controller 3.9 to NGINX APIM 3.18.1, it is not possible to upgrade the controller-agent completely without additional steps

    Workaround:

    To make sure that the Controller Agents are upgraded completely:

    • Upgrade NGINX Controller the normal documented way
    • Upgrade the Controller Agents the normal documented way

    At this stage you will see the Agents are still not online in the Infrastructure > Instances section and you will not be able to make config changes. Follow these additional steps to complete the upgrade:

    • ssh into each Instance and edit the /etc/controller-agent/agent.conf file and append the following lines in the [cloud] section, after the line requests_ca_bundle =

      grpc = true
      grpc_common_server_name =
      grpc_command_server_name = dataplane-manager
      grpc_metrics_server_name = agent-ingest
      
    • Restart each controller-agent service with the command sudo service controller-agent restart.

    Now, in Infrastructure > Instances, the Instances will appear as Running and you can push config changes.

Supported NGINX Plus Versions

NGINX Controller works with the following NGINX Plus versions:

  • NGINX Plus R24
  • NGINX Plus R23
  • NGINX Plus R22
  • NGINX Plus R21
  • NGINX Plus R20
  • NGINX Plus R19

 


NGINX Controller API Management 3.18.0

June 30, 2021

The NGINX Controller API Management module version 3.18.0 includes the following new features, improvements, known issues, and bug fixes:

Updates

  • Improved user experience for working with APIs

    We’ve made working with APIs easier by simplifying how to navigate API definitions and related objects such as versions and published APIs.

  • Adds native Kubernetes API Gateway

    You can run an API gateway natively in Kubernetes by using Instance Groups and DNS service discovery.

  • Create a RESTful facade for a SOAP service

    Now you can create API versions from well-formed WSDL files that define a SOAP service. This allows incoming REST requests to be proxied to a SOAP backend with necessary JSON-to-XML transformations applied.

  • Adds Instance Groups

    Gateway objects can now be added to Instance Groups. Instance Groups are groups of instances that share the same configuration dynamically.

Resolved Issues

This release includes the following fixes.

  • Specifying a URI to a JWK Set file is not supported on instances with multiple gateways (17124 )

New Issues

The following issues are known to be present in this release. Look for updates to these issues in future NGINX Controller APIM release notes.

  • Configuration changes aren’t pushed after upgrading from NGINX Controller v3.18 to NGINX Controller API Management module v3.18. (25705)

    If you upgrade from NGINX Controller v3.18 to NGINX Controller API Management module v3.18, you need to upgrade your Controller Agents to successfully push configuration changes from NGINX Controller.

  • SOAP-REST proxy is incompatible with njs module version 0.6 (26088)

    Published APIs that include SOAP-REST proxies will not pass traffic if njs-0.6 is running on the gateway instance.

    Workaround:

    Open an SSH connection into the NGINX Plus instance that’s used as the API gateway and upgrade the njs module to the latest version, which at the time of publication is 0.6.1.

  • REST match method defaults to PREFIX for SOAP (26154)

    When importing an API definition from a WSDL, the match method for each REST resource defaults to PREFIX. Additional options are planned for future releases.

  • Authentication policies are not yet supported for SOAP-REST proxy (26211)

    When configuring a published API that includes SOAP services in backend workloads, authentication policies are not supported.

  • Instructions for restoring external config database may not restore published APIs (26280)

    The commands in the Back Up & Restore External Config Database guide may not restore published APIs from the backup archive.

    Workaround:

    Follow the steps in the “Before You Begin” section in the (/nginx-controller/admin-guides/backup-restore/backup-restore-external-config-db/) guide.

    In the section titled “Back Up External Config Database,” replace step 2 with the following step, then proceed as per the documentation.

    1. Run the following script to back up the NGINX Controller database. The backup files are saved in a directory that looks like pgbackup_<timestamp>.

      DATE=$(date +"%Y%m%d%H%M")
      mkdir ~/pgbackup_${DATE}
      
      for db in common data system; do
        pg_dump -c -C -w -E utf8 -d ${db} -F c -f ~/pgbackup_${DATE}/${db}-${DATE}.backup
      done
      

    In the section titled “Back Up External Config Database,” replace step 2 with the following step, then proceed as per the documentation.

    1. Run the following script to back up the NGINX Controller database. The backup files are saved in a directory that looks like pgbackup_.

      for backup_file in "$BACKUP_PATH"/*.backup; do
        db="$(basename "$backup_file" | cut -d '-' -f 1)"
        pg_restore -c  -d "$db" "$backup_file"
      done
      

Supported NGINX Plus Versions

NGINX Controller works with the following NGINX Plus versions:

  • NGINX Plus R24
  • NGINX Plus R23
  • NGINX Plus R22
  • NGINX Plus R21
  • NGINX Plus R20
  • NGINX Plus R19