Before the latest release, NGINX had to be controlled exclusively by Unix signals. The most notable one is SIGHUP or the well-known “nginx -s reload” command. This configuration method, while very stable, does not meet modern environment requirements: there are very few available options, no direct feedback messages on errors, and no real extensibility. We fixed that.
NGINX recently published the version 1.31.5 release containing a new feature called the NGINX Control API. This is a new interface for reading configuration and triggering reload operations that presents these functions to the user over a REST API. Filesystem system configuration files and UNIX signal daemon management are not optimal for all users of NGINX. With the rise of Kubernetes and the continued dominance of containers as a deployment target for NGINX we wanted to provide configuration and management interfaces that better support using NGINX in containers or behind managed deployments. The NGINX Control API provides a way to read and reload configuration that is transactional, returning deterministic success or failure codes as any HTTP response would. This Control API can be served across a trusted network. Furthermore, the Control API provides an interface that does not experience any interruption during reload.
Newly released, this Control API provides the ability to read the current in-memory configuration associated with a master process. This is a completely new capability. Since NGINX has always had the potential to reject a new configuration and continue unaffected during a reload, users sometimes fall into a trap where they no longer know what configuration NGINX is then running. The configuration on disk may have completely changed but NGINX is still running some old configuration. Before Control API there was no method of retrieving that current configuration. Finally in these cases the user can simply fetch it with an HTTP request.
The Control API also provides facilities to trigger NGINX reloads. This will capture all logs during reload and return them in the response to the user. Additionally, the HTTP status code in this response will provide a simple way to answer the question “did this reload succeed or fail”. Previously, users may have had to export and search through logs for this information or potentially check PIDs of worker processes. The Control API holds a unique position to capture post-reload failures such as socket permission errors that previously were only observable through the logs of a new master process. These failures, while not loggable by the old master configuration, are reflected in the HTTP status code of the response. This is a new capability for NGINX. Previously users who relied on commands such as “nginx -s reload” or by sending SIGHUP to the master process had to then search the logs to make sure the reload succeeded. Now this information is relayed to them automatically when they request a reload over the Control API.
In our experience, this API makes it trivially simple to create UIs and scripts for advanced NGINX management and control.
From the blog post:
Before the latest release, NGINX had to be controlled exclusively by Unix signals. The most notable one is SIGHUP or the well-known “nginx -s reload” command. This configuration method, while very stable, does not meet modern environment requirements: there are very few available options, no direct feedback messages on errors, and no real extensibility. We fixed that.
NGINX recently published the version 1.31.5 release containing a new feature called the NGINX Control API. This is a new interface for reading configuration and triggering reload operations that presents these functions to the user over a REST API. Filesystem system configuration files and UNIX signal daemon management are not optimal for all users of NGINX. With the rise of Kubernetes and the continued dominance of containers as a deployment target for NGINX we wanted to provide configuration and management interfaces that better support using NGINX in containers or behind managed deployments. The NGINX Control API provides a way to read and reload configuration that is transactional, returning deterministic success or failure codes as any HTTP response would. This Control API can be served across a trusted network. Furthermore, the Control API provides an interface that does not experience any interruption during reload.
Newly released, this Control API provides the ability to read the current in-memory configuration associated with a master process. This is a completely new capability. Since NGINX has always had the potential to reject a new configuration and continue unaffected during a reload, users sometimes fall into a trap where they no longer know what configuration NGINX is then running. The configuration on disk may have completely changed but NGINX is still running some old configuration. Before Control API there was no method of retrieving that current configuration. Finally in these cases the user can simply fetch it with an HTTP request.
The Control API also provides facilities to trigger NGINX reloads. This will capture all logs during reload and return them in the response to the user. Additionally, the HTTP status code in this response will provide a simple way to answer the question “did this reload succeed or fail”. Previously, users may have had to export and search through logs for this information or potentially check PIDs of worker processes. The Control API holds a unique position to capture post-reload failures such as socket permission errors that previously were only observable through the logs of a new master process. These failures, while not loggable by the old master configuration, are reflected in the HTTP status code of the response. This is a new capability for NGINX. Previously users who relied on commands such as “nginx -s reload” or by sending SIGHUP to the master process had to then search the logs to make sure the reload succeeded. Now this information is relayed to them automatically when they request a reload over the Control API.
In our experience, this API makes it trivially simple to create UIs and scripts for advanced NGINX management and control.