NGINX Documentation

NGINX Controller Releases

NGINX Controller Version 2.7.0

These release notes provide general information and describe known issues for NGINX Controller version 2.7.0, in the following categories:

Updates

Analytics

  • This release introduces the new NGINX Controller Analytics module. With an Analytics module license, users can monitor, troubleshoot, and get insights into their NGINX Plus environments. For more information, please reach out to [email protected].

Platform

  • Bug Fixes

Load Balancer

  • Bug fixes

API Management

  • Read-Only Mode for API Management:

    User accounts with the “Read-Only” role are able to view API Management configurations but cannot make any edits.

  • Default Proxy Mode:

    HTTP keepalive policies can now be applied to upstream groups. Proxied requests are now made with HTTP/1.1 (previously HTTP/1.0).

  • Audit Log:

    The Audit Log lets you view all actions performed by Controller users over a set date range. Audit log results can be sorted and filtered by each column.

  • Reusable TLS Policies:

    TLS policies are now managed independently and can be associated with one or more Entry Points. A TLS policy includes the protocols, cipher settings, and session cache settings. The TLS certificate and private key are still Entry Point attributes.

Known Issues

  • Controller 2.7 release is incompatible with Controller Agent v2.5.0:

    There was a non-backwards-compatible change between Agent 2.5.0 and later Agent versions. As a result, API Management configuration publish events from a Controller 2.7 to a v2.5.0 Agent fail with a timeout error.

    Workaround:

    Upgrade the Agent to the latest version by following the instructions provided below to bring the system back into working order.

  • Audit Log’s “Apply” button is disabled when redefining a custom range:

    Steps to reproduce:

    • Create a custom date range on the new Audit Log page and click “Apply”.
    • Make changes to the custom date range.
    • The “Apply” button is not active.

    Workaround:

    • Select and apply a predefined date range, then select a custom range.
  • Upgrade to 2.7.0 doesn’t remove unused Docker container:

    During an update from any earlier version of the controller to v2.7, a previously-used Docker container is left running and emits a warning during the upgrade as follows:

    “Found orphan containers (controller_amplify-extapi_1) for this project. If you removed or renamed this service in your compose file, you can run this command with the –remove-orphans flag to clean it up.”

    In the next release, this container will be cleaned up automatically. To remove it manually in v2.7, you can run the commands shown below:

    sudo docker stop controller_amplify-extapi_1
    sudo docker rm controller_amplify-extapi_1
    
  • Controller-agent update overwrites agent.conf customizations:

    The controller-agent update process does not respect any manual edits you might have made to the agent.conf file. If you have made manual edits to the agent.conf file, please take the following steps when you update the agent:

    1. Backup your current agent.conf file prior to executing the agent upgrade procedure.
    2. Perform the upgrade by reapplying the steps in the “Add new instance” dialog (as noted below).
    3. Restore your agent.conf file over the file in /etc/controller-agent/agent.conf.
    4. Restart the controller-agent process.

  • Documentation for upgrading the controller agent is out-of-date:

    The instructions provided in the Admin guide and in the in-product documentation contain outdated instructions for upgrading the controller agent.

    To upgrade the agent, you should run the commands provided in the “Add new instance” dialog from your agent host. This will download and run a newer version of the agent.

  • Delay in API initialization post upgrade:

    For a period of about five minutes following updating the controller installation, a generic “Unknown” error banner appears in the UI when accessing the API Management pages. Approximately five minutes following update completion, this self-resolves and the application behaves normally.

    Workaround: You can manually dismiss the “Unknown” error banner.

  • Deletion of API Definition not reflected in GUI until page refresh:

    When you delete an API Definition in the API Module (which is present only if licensed), the deleted definition still appears in the GUI. The definition is, in fact, being deleted correctly. The UI is not updating to reflect this fact.

    Workaround: You can refresh the page, or navigate away and then return, to view the correct state of the application.

Supported Versions

  • NGINX Plus R15, R16, R17, R18

NGINX Controller Version 2.6.0

These release notes provide general information and describe known issues for NGINX Controller version 2.6.0, in the following categories:

Updates

Platform

  • Bug fixes

Load Balancer

  • Bug fixes

API Management

  • Global DNS Resolver – configure an external resolver that can be optionally enabled within each Upstream Group.

Known Issues

  • API Management policies applied may inherit a broader scope than intended.

    To resolve this issue, upgrade to Controller version 2.7.

  • Controller-agent update overwrites agent.conf customizations:

    The controller-agent update process does not respect any manual edits you might have made to the agent.conf file. If you have made manual edits to the agent.conf file, please take the following steps when you update the agent:

    1. Backup your current agent.conf file prior to executing the agent upgrade procedure.
    2. Perform the upgrade by reapplying the steps in the “Add new instance” dialog (as noted below).
    3. Restore your agent.conf file over the file in /etc/controller-agent/agent.conf.
    4. Restart the controller-agent process.
  • Documentation for upgrading the controller agent is out-of-date:

    The instructions provided in the Admin guide and in the in-product documentation contain outdated instructions for upgrading the controller agent.

    To upgrade the agent, you should run the commands provided in the “Add new instance” dialog from your agent host. This will download and run a newer version of the agent.

  • API Management returns 504 Gateway Timeout for a period of minutes following upgrade from 2.5.0 –> 2.6.0:

    For a period of about five minutes following updating the controller installation, a generic “Unknown” error appear in the GUI when accessing the API Management pages. Approximately five minutes following update completion, this self-resolves and the application behaves normally.

    Note that the “Unknown” error, which presents as a banner in the UI, must be manually dismissed.

  • Deleted API definition remains on the page:

    When you delete an API Definition in the API Module (present only if licensed), the deleted definition still appears in the GUI. The definition is, in fact, being deleted correctly. The UI is not updating to reflect this fact. You can refresh the page or navigate away and then return to show the correct state of the application.

Supported Versions

  • NGINX Plus R15, R16, R17, R18

NGINX Controller Version 2.5.0

These release notes provide general information and describe known issues for NGINX Controller version 2.5.0, in the following categories:

Updates

Platform

  • New end user license agreement

Load Balancer

  • Bug fixes

API Management

  • Notifications will appear as you approach and exceed your license limit
  • To view license status , click on your API Management license within Settings > Licenses

Known Issues

  • Clients deploying controller-agent on CentOS 6 need to manually modify the logging level of controller-agent to ERROR level from INFO and restart controller-agent.
  • Administrators who delete a JWT policy will still see that policy in the environment select list. They should not select/configure a deleted policy.
  • NGINX Plus instances managed by the API Management module must be associated with a single Entry Point
  • Amazon Linux 2. Docker installation issues: Controller install script cannot handle the setup of docker. Please install docker before running the controller install script.

Supported Versions

  • NGINX Plus R15, R16, R17, R18

NGINX Controller Version 2.4.0

These release notes provide general information and describe known issues for NGINX Controller version 2.4.0, in the following categories:

Updates

Platform

  • Support contact information is now accessible from User Menu > Support

Load Balancer

  • The Instances page is now read-only, displaying the configuration that is currently running on each instance. This will help ensure nobody accidentally overwrites expected policy. To edit instance configurations, you must use Configuration Templates (Load Balancing > Configurations).
    • If an instance is associated to a Load Balancing Configuration Template or an API Management Entry Point, that information is reflected at the bottom of the page.
    • Instances that are not associated with a module can be promoted to Configuration Templates at the bottom of the Instances page for load balancing purposes, or associated with an Entry Point for API Management purposes.
  • Configuration Templates > Instances
    • You can now associate instances to a Configuration using tags.
    • Last Modified timestamp now shows the last time the configuration was changed, whether manually or through Controller.

API Management

  • Invalid Resource (404) Policy
    • From the Entry Point configuration page, you can specify an alternate HTTP error code, rather than the default 404 response to requests for invalid resources.

Known Issues

  • Amazon Linux 2. Docker installation issues: Controller install script cannot handle the setup of docker. Please install docker before running the controller install script.
  • NGINX Plus instances managed by the API Management module must be associated with a single Entry Point.

Supported Versions

  • NGINX Plus R15, R16, R17, R18

NGINX Controller Version 2.3.0

These release notes provide general information and describe known issues for NGINX Controller version 2.3.0, in the following categories:

Updates

Platform

  • Configure dashboard graph sets using one or more tags
  • Support spaces in upstream group name, route alias, system alias

Load Balancer

  • Configuration Templates
    • Ability to preview config file
    • Additional feedback around in-progress config push

API Management

  • Ability to edit environment policies
  • Usability improvements to API Definitions page
    • Entry point hostname color-coding:
      • Grey - config not pushed to the entry point
      • Green - config pushed, all associated instances are online
      • Yellow - config pushed, one or more instances offline & one or more instances online
      • Red - config pushed, all instances offline
    • Number of unrouted resources is displayed for each environment

Known Issues

  • Amazon Linux 2. Docker installation issues: Controller install script cannot handle the setup of docker. Please install docker before running the controller install script.

Supported Versions

  • NGINX Plus R15, R16, R17, R18

NGINX Controller Version 2.2.0

These release notes provide general information and describe known issues for NGINX Controller version 2.2.0, in the following categories:

Updates

Platform

  • Ability to configure the ServiceNow alert integration within Controller

Load Balancer

  • Configuration Templates - ability to name versions
  • Instances are sorted by display name (system alias, or hostname if no alias is set) in the inventory list and dropdown menus
    • Inventory menu in the app header defaults to sorting by display name, with options to change sort parameter

API Management

  • New “card” layout for the API Definition list view

Known Issues

No known major issues in this release

Supported Versions

  • NGINX Plus R15, R16, R17

NGINX Controller Version 2.1.0

These release notes provide general information and describe known issues for NGINX Controller version 2.1.0, in the following categories:

Updates

Platform

  • Ubuntu 18 is qualified for hosting Controller Agents

Load Balancer

  • Configuration Templates can now be deleted

Known Issues

No known major issues in this release

NGINX Controller Version 2.0.0

These release notes provide general information and describe known issues for NGINX Controller version 2.0.0, in the following categories:

Updates

Load Balancer

  • Configuration Templates
    • Config
    • Associated Instances
    • Version History
    • Version Differencing
    • Arbitrary Reverting
  • Multi-push from Load Balancing → Instances
  • Notifications for multi-push status
  • ServiceNow alerting integration
  • Ability to enable error_log and access_log in virtual server
  • Renamed Amplify metrics
  • Rename tab from “Configure” → “Load Balancing”
  • Ability to tag instances from the ‘Load Balancing → Instances’ tab
  • Config-push deferral - ability to change a config and save it without pushing
  • Promote session persistence to its own section (Upstream Group config)
  • Offline installer / updater
  • Various bug-fixes

API Management

  • New API Management tab in Controller primary navigation
  • Create and manage API Definitions
  • Create and manage Upstream Groups
  • Create and manage Entry Points
  • Manage Clients and Client Groups
  • Policies can be applied to various objects in API Management

Known Issues

  • If upgrading from a previous version of Controller, password needs to be updated/reset.
  • Load Balancing - Instances page hangs when there are no hosts registered in Controller.
  • Load Balancing - Orange indicators will appear when you have unsaved changes, and may take several minutes to accurately reflect the correct status.
  • API Management - When configuring multiple rate limit policies for an Environment, each must use the same status code.

NGINX Controller Version 1.0.1

These release notes provide general information and describe known issues for NGINX Controller version 1.0.1, in the following categories:

Updates

  • Alerts - fix issue where editing an alert with threshold could result in an error
  • Analyzer - fix issue where old SSL cert could still be evident in the report alongside the new cert that replaced it
  • Analyzer - show appropriate message when port is missing for the listen directive
  • Configure - provide better error descriptions in the UI
  • Configure - fix issue where error notifications disappeared too quickly before they could be fully read
  • Configure - fix issue where user would see “undefined” error when loading a config that included a stream block
  • Configure - fix issue where virtual server SSL block is inactive after a page reload
  • Configure - fix issue where empty directives were not copied to the generated config file
  • Configure - fix issue where proxy is not allowed in regex location
  • Configure - fix issue where the validation for healthcheck URI does not allow for query params
  • Configure - fix issue of no validation for duplicate upstreams
  • Configure - fix the wrong visualisation of healthcheck config after a push config action fails
  • Configure - fix error about server name being too long in the generated config

Known Issues

No known major issues in this release