Release Notes 2.1.0

These release notes contain information about new features, improvements, known issues, and bug fixes in NGINX Instance Manager.

April 5, 2022

Upgrade Paths

NGINX Instance Manager 2.1.0 supports upgrades from these previous versions:

  • 2.0.1
  • 2.0.0

We recommend you upgrade the NGINX Agent whenever you upgrade NGINX Instance Manager.

If you’re running NGINX Instance Manager 1.0 or earlier, follow the steps in the Migration Guide to migrate your system to NGINX Instance Manager 2.1.0. Direct upgrades from NGINX Instance Manager 1.0 and earlier to 2.1.0 are not supported.

Changes in Default Behavior

NGINX Instance Manager 2.1.0 has the following changes in default behavior:

  • Tags are no longer enforced for RBAC or set when creating or updating a role

    If you’re using tags for RBAC on an earlier version of NGINX Instance Manager, you’ll need to re-create your roles after upgrading. Tags assigned to instances for the purpose of RBAC won’t be honored after you upgrade.

    See the What’s New section for details about the new NGINX Instance Manager RBAC authorization system.

  • The DeploymentDetails API now requires values for failure and success

    The DeploymentDetails API spec has changed. Now, the failure and success fields are required. The values can be an empty array or an array of UUIDs of NGINX instances; null is not a valid value.

    Endpoint: /systems/instances/deployments/{deploymentUid}

    Example JSON Response

      "createTime": "2022-04-18T23:09:16Z",
      "details": {
        "failure": [ ],
        "success": [
            "name": "27de7cb8-f7d6-3639-b2a5-b7f48883aee1"
      "id": "07c6101e-27c9-4dbb-b934-b5ed75e389e0",
      "status": "finalized",
      "updateTime": "2022-04-18T23:09:16Z"

What’s New

This release includes the following updates:

  • Adds Docker support for NGINX Agent

    Now you can collect metrics about the Docker containers that the NGINX Agent is running in. The NGINX Agent uses the available cgroup files to calculate metrics like CPU and memory usage.

    If you have multiple Docker containers on your data plane host, each container registers with NGINX Instance Manager as unique.

    Refer to the NGINX Agent Docker Support guide for details.

    Containerizing the NGINX Agent is supported only with Docker at the moment. Look for additional container support in future releases of NGINX Instance Manager.
  • New RBAC lets you limit access to NGINX Instance Manager features

    RBAC has been updated and improved. Add users to roles – or add users to user groups if you’re using an external identity provider – to limit access to NGINX Instance Manager features.

    For more information, see the tutorial Set Up RBAC.

  • Deploy NGINX Instance Manager on Kubernetes using a helm chart

    We recommend using the NGINX Instance Manager helm chart to install NGINX Instance Manager on Kubernetes.

    Among the benefits of deploying from a helm chart, the chart includes the required services, which you can scale independently as needed; upgrades can be done with a single helm command; and there’s no requirement for root privileges.

    For instructions, see Install from a Helm Chart.

  • Improved certificate handling

    Stability and performance improvements for managing certificates using the web interface.

  • View events for your NGINX instances

    Now you can use the NGINX Instance Manager API or web interface to view events for your NGINX instances.

    See the View Events and View Events (API) topics for instructions.

  • Redesigned metrics views in the web interface

    The metrics pages in the web interface have been revised and improved.

    See the View Metrics topic to get started.

Resolved Issues

This release fixes the following issues. To view the history for an issue, search the NGINX Docs website for the issue ID.

  • Unable to register multiple NGINX Agents in containers on the same host (30780)

  • Include cycles in the configuration cause analyzer to spin. (31025)

  • System reports “error granting scope: forbidden” if user granting permissions belongs to more than one role (31215)

  • When using Instance Groups, tag-based access controls are not enforced (31267)

  • Bad Gateway (502) errors with Red Hat 7 (31277)

Known Issues

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

  • gRPC errors occur when starting NGINX Instance Manager (28683)

    When starting NGINX Instance Manager, you may see errors similar to the following in /etc/nginx/conf.d/nms-http.conf:227:

    nginx[1234]: nginx: [emerg] unknown directive "grpc_socket_keepalive"


    Make sure your version of NGINX is v1.18 or later. See the Technical Specifications guide for details.

  • NGINX/NGINX Plus is not a requirement when installing NGINX Instance Manager on CentOS 7, RHEL 7, and Amazon Linux 2 (28758)

    When installing on CentOS 7, RHEL 7, and Amazon Linux 2, the package manager doesn’t prevent installing NGINX Instance Manager with unsupported versions of NGINX or NGINX Plus. As a consequence, it is possible that nms-instance-manager is installed without an NGINX gateway. Resulting in a less than optimal experience.


    Install a supported version of NGINX (v1.18 or later) or NGINX Plus (R22 or later). See the Technical Specifications guide for details.

  • The web interface doesn’t report an error when uploading config files larger than 50 MB (31081)

    In the web interface, when uploading a config file that’s larger than 50 MB (max size), the system incorrectly reports the state as Analyzing (Status code 403), although the upload failed.


    Keep config files under 50 MB.

  • After upgrading NGINX, NGINX Instance Manager reports the old NGINX version (31225)

    After upgrading NGINX to a new version, the NGINX Instance Manager web interface and API report the old NGINX version until the NGINX Agent is restarted.


    Restart the Agent to have the new version reflected properly:

    systemctl restart nginx-agent
  • NGINX App Protect WAF blocks NGINX Instance Manager from publishing configurations (32718)

    NGINX Instance Manager does not currently support managing NGINX App Protect WAF instances. NGINX App Protect WAF may block attempts to publish configurations to NGINX App Protect WAF instances.

  • Password error “option unknown” occurs when installing NGINX Instance Manager on Ubuntu with OpenSSL v1.1.0 (33055)

    When installing NGINX Instance Manager on Ubuntu with OpenSSL v1.1.0, you might see an error similar to the following example:

    Generating default password for ‘admin’ user account
    Using openssl version 1.1
    passwd: Option unknown option -6
    passwd: Use -help for summary.
    dpkg: error processing package nms-instance-manager

    If you receive this error during the installation, your version of OpenSSL is not compatible with the password hashing algorithm used to generate an initial admin password.


    Upgrade your OpenSSL version to v1.1.1 or later:

    sudo apt-get install openssl

    After updating OpenSSL this way, apt will re-try installing NGINX Instance Manager.

  • “Config apply failed (write) no such process” error occurs when publishing a configuration (33160)

    When publishing a configuration, you might encounter an error similar to the following example:

    config action failed: Config apply failed (write): no such process

    This error can occur when there is a desyncronization between the NGINX Agent and NGINX PID, often after manually restarting NGINX when the Agent is running.


    Restart the NGINX Agent:

    sudo systemctl restart nginx-agent
  • OIDC is not supported for helm chart deployments (33248)

    OIDC is not supported for helm chart deployments of NGINX Instance Manager on Kubernetes. Only basic auth is supported.

  • An unexpected number of instances are shown after upgrading nginx-agent to 2.1.0 (33307)

    After upgrading to NGINX Instance Manager 2.1.0, and updating nginx-agent from platform packaging, duplicate instances may appear on the Instance overview page. This issue is caused by a change in how the NGINX Agent generates the system_uid.


    You can safely delete the older entries or wait for them to expire.

  • Running the NGINX Agent install script with sh returns the error "[[: not found" (33385)

    When running the NGINX Agent install script with the sh command, an error similar to the following is reported: "171: [[: not found".

    This message is only a warning and does not interrupt the installation processes.


    Run the script with bash.

  • Access rules are misapplied for roles that define multiple access types for the same feature (33480)

    When creating a role, if you assign multiple access types to the same feature, resources in the role definition will be bound to a single access type. For example, if you add a role that gives CREATE, READ, UPDATE, and DELETE access to INSTANCE-MANAGEMENT for a resource called nginx1 and gives READ access to INSTANCE-MANAGEMENT for All, READ access is applied to all the resources.


    Create separate roles to assign different permissions for the same feature. For example, create a role for nginx1 with CRUD access for INSTANCE-MANAGEMENT and a second role for All that has READ access.

Supported NGINX Versions

Refer to the NGINX Instance Manager Tech Spec Guide to learn about the NGINX OSS and NGINX Plus versions supported by this release.

See Also:
See the NGINX Instance Manager Tech Spec Guide for additional requirements and supportability information.

NGINX Instance Manager (Control Plane)

The NGINX Instance Manager server uses NGINX as a frontend proxy and supports the following versions of NGINX OSS and NGINX Plus:

Table: NGINX Instance Manager – Supported NGINX Versions

NGINX Model Supported Versions
NGINX OSS 1.18 and later
NGINX Plus R21 and later

NGINX Agent (Data Plane)

The NGINX Agent works with all versions of NGINX OSS and NGINX Plus.