Release Notes
These release notes list and describe the new features, enhancements, and resolved issues in NGINX Management Suite App Delivery Manager.
This topic describes an early access feature. These features are provided for you to try before they are generally available. You shouldn't use early access features for production purposes.
Share your thoughts about the documentation by taking this short survey: https://forms.gle/w6eDi53F4UcmDjw68.
App Delivery Manager Trial Download and Installation
For early access to App Delivery Manager, follow the steps in the prerequisites section to download an NGINX Management Suite trial.
Add the NGINX Management Suite and App Delivery Manager repositories to your system:
sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nms.repo
printf "deb https://pkgs.nginx.com/nms/debian `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nms.list
printf "deb https://pkgs.nginx.com/adm/debian `lsb_release -cs` nginx-plus\n" | sudo tee -a /etc/apt/sources.list.d/nms.list
sudo wget -q -O /etc/apt/apt.conf.d/90pkgs-nginx https://cs.nginx.com/static/files/90pkgs-nginx
printf "deb https://pkgs.nginx.com/nms/ubuntu `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nms.list
printf "deb https://pkgs.nginx.com/adm/ubuntu `lsb_release -cs` nginx-plus\n" | sudo tee -a /etc/apt/sources.list.d/nms.list
sudo wget -q -O /etc/apt/apt.conf.d/90pkgs-nginx https://cs.nginx.com/static/files/90pkgs-nginx
After completing the steps in the prerequisites section, follow the steps in the Install or Upgrade App Delivery Manager guide.
Upgrading from previous Early Access releases
The latest (August 24th) release introduces several breaking changes. We strongly recommend a fresh installation of the latest release:
-
Completely uninstall App Delivery Manager by running the following command:
yum remove nms-app-delivery-manager
-
Remove all the files in the
/var/lib/nms/dqlite/adm
directory. -
Install the latest Early Access release.
-
Remove the empty
builtin-*
folders from the/etc/nms/modules/adm/templates/usecases
directory.
-
Completely uninstall App Delivery Manager by running the following command:
sudo apt-get purge nms-app-delivery-manager
-
Remove all the files in the
/var/lib/nms/dqlite/adm
directory. -
Install the latest Early Access release.
Note:
If you choose to upgrade instead, review the Changes in Behavior section below and perform the necessary changes in your environment.
4.0.0 August 24, 2023
What’s New
This release includes the following updates:
-
Added pre-configured roles when App Delivery Manager is installed
We’ve made it easier to get started configuring role permissions by adding two predefined roles, App Delivery Manager Admin and App Delivery Manager Guest, when App Delivery Manager is installed. These roles can be modified to meet your needs.
-
Use of custom WAF policies is now available
We have enabled the use of custom WAF policies to set the appropriate controls for your apps. This feature will let you use your existing declarative JSON policies. To learn more, see the WAF Configuration Management documentation.
-
Added correlation ID to logs to simplify troubleshooting
We have added support for contextual logging, which automatically includes a unique identifier. This identifier gets passed across processes to be able to perform searches for all relevant log entries referencing it.
The correlation ID is added to
stdout
,nms.log
, andagent.log
files. -
Added URI paths to Web Component list
To help build and troubleshoot app delivery services, we have added the ability to view the URI path in the Web Components list of the web interface.
-
New documentation on how to configure keepalived to enable data plane high availability
We have added a tutorial explaining how to configure
keepalived
on NGINX Plus instances so that developers can enable gateway high availability by simply choosing the right instance group. To learn more see Creating Highly Available Gateways. -
Improvements to the OIDC configuration options for the data plane
We have made changes to prevent the misconfiguration or mishandling of SSL/TLS communication:
- We have updated the data plane OIDC template to enable the verification of IDP server certificate (proxy_ssl_trusted_certificate and proxy_ssl_verify).
- We have added the option to configure the DNS of choice (resolver added to server block level).
-
Template documentation now available in-product
Templates are a powerful way to extend App Delivery Manager (ADM) functionality. We’ve made it easier to review the detailed descriptions of templates that are shipped with App Delivery Manager by using the API or web interface.
Changes in Behavior
This release has the following changes in default behavior:
-
Improved usability of the Web Component APIs
We now accept
paths
instead ofuris
andpath
instead oruri
in the Web Component API payload. This will break any existing objects that make use of these APIs.For example:
"paths": [ { "matchMethod": “prefix”, "path": "/foo", "customExtensions": {} } ]
-
Added passive health check options to the
f5-health-monitor-v1
use case, alongside the pre-existinghealthCheck
optionsTo add passive health check options to the use case, the existing
healthCheck
options and the new passive health check options are now encompassed byhealthMonitor
.To preserve pre-existing
healthCheck
options after upgrading to this release, please update your requests. Wrap thehealthCheck
options withhealthMonitor
:EA2 and before:
... "customExtensions": { ... "healthCheck": { ... } }
EA3:
{ ... "customExtensions": { ... "healthMonitor": { "healthCheck": { ... } } }
-
Updated f5-tls-settings-v1 use case options and inheritance behavior
The
proxySetSni
options have been renamed and expanded:- Renamed
NGINX_HOST_VARIABLE
to$host
- Renamed
UPSTREAM_SERVER_ADDRESS
tofirst_upstream_address
- Added
$server_name
- Added
$proxy_host
- Added
custom
- New field
proxySetSniCustomHeader
to specify the custom proxy host header and SNI value
The settings specified at the top-level
customExtensions
apply to all URIs (server blocks). Settings within the ingress URIcustomExtensions
apply only to that particular URI (server block) and will override the top-level settings. We have improved inheritance to be more granular: It is now applied per thesslCiphers
,sslPreferServerCiphers
,sslProtocols
, andsslSessionCache
settings (instead of using all thetlsSettings
at the top level or being overwritten by URI level settings).Example:
{ "metadata": { "uid": "e5eb6e91-2746-4fa4-9655-bf1dca4c7e5c", "name": "gw1", "tags": [] }, "ingress": { "uris": [ { "uri": "https://example.com:80", "matchMethod": "exact", "http2": false, "customExtensions": { "tlsSettings": { "sslProtocols": "TLSv1.3", "sslSessionCache": { "builtin": { "size": 5000 } } } } } ], "tls": { "certRef": { "ref": "0d131b67-f73d-4339-a7a7-c344f9bae945" } }, "placement": { "instanceGroupRefs": [ { "ref": "46e2a2d4-1bfb-43e4-bdad-a6f1416779ed", "listenIps": [] } ] } }, "customExtensions": { "tlsSettings": { "sslCiphers": "HIGH", "sslPreferServerCiphers": "on", "sslProtocols": "TLSv1.1", "sslSessionCache": { "clientSessionReuse": "off" } } } }
The server block for
https://example.com:80
will now inherit the top-level settings forsslCiphers
andsslPreferServerCiphers
because these options were not specified at the URI level.After upgrading to this release, follow these steps to make sure your environment behaves correctly:
- Update web-components that specify
NGINX_HOST_VARIABLE
, forproxySetSni
, to$host
. - Update web-components that specify
UPSTREAM_SERVER_ADDRESS
, forproxySetSni
, tofirst_upstream_address
. - Modify
sslCiphers
,sslPreferServerCiphers
,sslProtocols
, andsslSessionCache
at the top and URI levels to achieve the desired inheritance under the new inheritance model.
- Renamed
-
NGINX rewrite rules configuration template updated
The template used to configure the NGINX rewrite rules has been updated with a new name (
rewrite-rules
) and new return settings, to improve its usability. -
Updated the API to support all of the NGINX Plus load balancing methods
The load balancing API has undergone some changes in this release. Please review the changes below, and update any existing API script accordingly.
Method changes:
- Load balancing method
IPHASH
changed toip_hash
- Load balancing method
LEAST_CONNECTIONS
changed toleast_conn
Arguments to
least_time
method changes:header_inflight
changed toheader inflight
connect_inflight
changed toconnect inflight
first_byte_inflight
changed tofirst_byte inflight
last_byte_inflight
changed tolast_byte inflight
Arguments to
random
methodtwoServerLBMethod
option changes:- Adding option
two
least_connections
changed totwo least_conn
least_time_connect
changed totwo least_time=connect
least_time_header
changed totwo least_time=header
least_time_first_byte
changed totwo least_time=first_byte
least_time_last_byte
changed totwo least_time=last_byte
- Load balancing method
-
HTTP/2 configuration is now a native option in the App Delivery Manager API
Gateway configuration options now include enabling HTTP/2 without requiring a specific use case template. HTTP/2 is now a native configuration option in the App Delivery Manager API, and can also be enabled using the Web interface. When HTTP/2 is enabled, the corresponding
listen
directive will usehttp2
in the resulting config. -
Use case templates have been renamed
We have changed the prefixes of the default templates provided with App Delivery Manager from
builtin
tof5
. After upgrading to the newer versions, both versions will be available. To avoid duplication, we advise using the newerf5
templates and use cases in all environments. We also recommend removing the oldbuiltin
versions from these two locations:/etc/nms/modules/adm/templates/usecases/
/etc/nms/modules/adm/templates/base/
-
Enumerated constants have been changed from uppercase to lowercase
The enums (enumerated constants) in the API have been changed from uppercase to lowercase to better match NGINX terminology. If there are any existing API scripts, please update them with the correct values according to the updated API documentation.
Known Issues
You can find information about known issues in the Known Issues topic.
4.0.0 July 06, 2023
What’s New
This release includes the following updates:
-
Added initial support for NGINX App Protect
We have added the ability to enable NGINX App Protect per location, use the default policy that provides OWASP Top 10 and Bot security protection, and a strict policy containing more restrictive criteria for blocking traffic.
-
Added support for rate limiting
We have added the ability to enable rate limiting per component to limit network traffic, prevent users from exhausting system resources, and make it harder for malicious actors to overburden components and cause attacks like Denial of Service.
-
Added support for configuring OpenID Connect
We have added the ability to configure OIDC integration for NGINX Plus to communicate directly with an Identity Provider to perform authentication.
-
Added new traffic setting template
We have added a new template, traffic-settings, that enables the configuration of
underscores_in_headers
andignore_invalid_headers
directives per URI. Users can now control whether header fields with invalid names should be ignored and if header fields whose names contain underscores are marked as invalid.
Changes in Behavior
This release has the following changes in default behavior:
-
Updated the API to better support automation
We have simplified the APIs for the Gateway and Component objects to use arrays instead of maps when specifying the URIs. This will break any existing automation scripts that make use of these APIs.
-
Improved usability of caching template
The
proxy_cache_valid
setting in the built-incaching
template has been updated to an array so that the directive can be easily used to specify different timeouts per response code. For example:"proxyCacheValids": [ { "responseCodes": "200", "time": "10m" }, { "responseCodes": "300,302", "time": "1m" } ]
Resolved Issues
This release fixes the following issues. Select an issue’s ID link to view its details.
- Duplicate Certificate and Key published for managed certificates (42517)
Known Issues
You can find information about known issues in the Known Issues topic.
4.0.0 May 18, 2023
What’s New
This release includes the following updates:
-
App Delivery Manager Early Access Features
-
Provides an easy-to-use graphical user interface for Application Delivery.
-
Introduces App Delivery Manager abstractions for the configuration and use of NGINX Plus directives:
- Create and manage production and non-production environments for classes of applications, business units, and development teams. Environments are logical containers used to group Applications, and Gateways into a domain associated with common goals, resource needs, usage constraints, and access controls. Environments typically map closely to organizational boundaries such as “dev” and “prod”.
- Create and manage gateways, which correspond to server blocks in nginx.conf file, which represents the initial network entry point of application and/or API traffic into an NGINX instance in the traffic data path. You can share the same gateway for both application and API traffic.
- Create and manage apps that are logical containers for components.
- Create and manage components that support HTTP and TCP/UDP protocols. Web components correspond to location blocks in nginx.conf. Web, for example, HTTP components allow users to define routing behavior for the URIs under the Apps. Each component can define URIs and specify which FQDNs these need to attach to via Gateway references. Components also allow specifying the Backend and can control the configuration for load balancing traffic to the backend servers. TCP/UDP components define stream server blocks. Similar to web components can attach to one or more Gateways.
- Create and manage sites that allow the grouping of instance-groups by a physical location. Sites provide the ability to load balance to backend servers that are geographically close to the data plane.
-
Control the lifecycle of applications across groups of NGINX Plus instances.
-
Apply role-based access controls across all App Delivery Manager features to enable users and teams to self-service app delivery needs.
-
Monitor HTTP system and traffic metrics at the instance level and view aggregated and near-real-time insights into system and app traffic:
- System Metrics: Average CPU and Average Memory
- App Metrics: Network Bytes In and Network Bytes Out
- HTTP Metrics: Total Requests, HTTP 5xx Errors, and HTTP 4xx Errors
-
Deploy app services for load balancing HTTP and TCP/UDP applications and select the appropriate method:
- Round Robin
- Least Connections
- IP Hash
- Hash
- Least Time
- Random
-
Unlock the full capability of NGINX using templates. The following template use cases come prebuilt:
- Enabling cache by configuring proxy_cache_path, split_clients, and map to improve app performance
- Add DNS for service discovery
- Health monitoring of upstreams with health_check and match block
- Extending listen options for HTTP/2, fastopen, sndbuf, and rcvbuf
- Modifying headers and configuring rewrites and redirects
- Configure advanced TLS settings to enable ciphers and protocols for requests to the proxied server
-
Ability to create custom templates to use any NGINX Plus directive.
-
Known Issues
You can find information about known issues in the Known Issues topic.