NGINX Documentation

NGINX Controller Releases

NGINX Controller version 0.1.0

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

Notes and Known Issues: Configuration

  • Controller inserts a number of directives into the configuration based on best practices. The directives inserted in the http{} and stream{} contexts are not editable.
  • Similarly, Controller changes the default values for some directives to reflect current use cases, for example changing the number of worker_connections from 512 to 8192. Some operating systems (for example, Security Enhanced versions of Linux distributions) issue warnings about settings that use more resources.
  • Some panels in the Configurator GUI have a Manual Config field in the Advanced section where you can add to, change, or remove the directives inserted by Controller. These fields are for experienced NGINX and NGINX Plus users only! While Controller does minimal syntax checking, it is very possible for invalid values to make NGINX Plus stop working correctly. Make sure you thoroughly understand the directives you change and how they affect NGINX Plus operation.

Notes and Known Issues: Certificates

  • To edit or replace an uploaded SSL/TLS certificate for a vLB, on the Specify SSL Certs panel you must perform these steps:

    1. Select the Generate Using Let’s Encrypt radio button.
    2. Click the Save and Exit button.
    3. Re-open the Specify SSL Certs panel.
    4. Select the Upload Certs radio button.
    5. Upload the new certificates.
    6. Click the Save and Exit button.
  • The certificates provided for Controller itself are self‑signed. To replace them with certificates from a CA, contact your NGINX Account Executive to have NGINX Professional Services install the CA‑issued certificates for you at no charge.

  • The certificates and keys to the NGINX Plus repo that come with Controller enable you to install NGINX Plus on any system managed by Controller, but are limited to use on testing or demonstration systems only, not production systems.

  • Let’s Encrypt has strict requirements for issuing certificates, which are also detailed on the Specify SSL Certs panel. Before Let’s Encrypt issues a certificate, it requires the requester to prove control over the domain or hostname for which the certificate is requested. Specifically, it requires the requester to create a DNS record that maps the domain or hostname to a single IP address. (For more detail, see the Let’s Encrypt documentation.) As a consequence:

    • You can use a Let’s Encrypt certificate only for a service group with a single assigned NGINX Plus instance (not more).
    • Ports 80 and 443 must be open to all clients (not behind a firewall) so Let’s Encrypt can deliver the certificate.

    We are exploring ways to expand the set of use cases for Let’s Encrypt certificates.

  • Let’s Encrypt issues a maximum of 20 certificates per week for a top‑level domain (for example, example.com) and its subdomains (www.example.com).

  • Let’s Encrypt re‑issues a maximum of 5 certificates per week for a particular domain (for example, www.example.com).

Notes and Known Issues: Operating System and Infrastructure

  • The Controller Agent is supported on Ubuntu 16.04 and RHEL 7.x.

  • Repeatedly installing and removing the Controller Agent, especially as new versions are deployed, can cause unexpected behavior. If the agent stops working, it is best to start with a fresh instance.

  • To support monitoring, Python 2.6 or 2.7 must be installed on every NGINX Plus instance managed by Controller. If it is not, the Controller agent installation script issues a warning and the installation does not complete.

  • To enable installation of the NGINX Plus software along with the agent (when NGINX Plus is not already installed), instances managed by Controller must be able to access the Internet, and specifically http://nginx.org, https://cs.nginx.com, and https://plus-pkgs.nginx.com.

    To enable updates to the NGINX Plus software, only access to https://plus-pkgs.nginx.com is required.

  • To download the Controller agent package, the installation script must be able to access the AWS S3 service.

  • To enable automatic updates of the Controller software, the system where Controller is running must be able to access the Internet, and specifically registry.ctrl.nginx.com and nexus.ctrl.nginx.com.

  • On Security Enhanced Linux distributions, the Controller agent modifies httpd ACLs to enable use of ports other than 80 and 443. The httpd ACL mode is changed to permissive.

Notes and Known Issues: General

  • On the Monitoring page, after 30 seconds the NGINX Connections/s graph switches from showing the connections per second to showing the cumulative number of dropped connections instead. To display connections per second again, refresh the Monitoring page.