API Design
Overview of the NGINX Management Suite App Delivery Manager module.
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.
API Object Model
The App Delivery Manager API extends the Instance Manager API to provide additional endpoints, which enables a user to manage NGINX configurations using an app-centric approach.
The following diagram shows a graphical view of the App Delivery Manager API endpoints as well as the relationships between them:
Note:
Solid lines indicate references to other endpoint objects in the overall system (App Delivery Manager, Instance Manager), whereas dotted lines indicate parent/child container relationships within App Delivery Manager.
Summary of the Objects:
| API Object | Affected NGINX Contexts | Description |
|---|---|---|
| Environments | - | Logical separation of objects by organizations or deployment types. |
| Gateways | server (http) | Definition of network entry point (ingress for NGINX Plus) for the app(s). |
| Apps | - | Logical grouping of components that define an individual app. |
| Web components | upstream (http), location | Definition of a microservice or part of a microservice that implements a HTTP or HTTPS app. |
| TCP/UDP components | server (stream), upstream (stream) | Definition of a microservice or part of a microservice that implements a TCP, TC+TLS, or UDP app. |
| Sites | - | Logical separation of instance groups, typically based on locality. |
Note:
Not all contexts are in the list, just the core ones that are affected. The use of custom templates can extend the list of affected contexts.
Each of these objects adds additional dimension data to the metrics and events generated by the NGINX Plus instances. This helps you visualize how your component, app or environment performing over time. This in turn can help you fine-tune your configuration or the app itself.
Environments
An environment is a logical container for grouping objects, such as apps, components, and gateways, according to organizational boundaries or deployment types (for example, development, test, or production). You can create customized templates for environments. If you don’t specify any templates, the default built-in templates are used (see Template Overview for more details).
Typically, the platform admin will create one or more environments for the app teams to access. The app teams will then assign roles and objects within the environment to establish adequate isolation.
Apps
The App Delivery Manager module organizes apps as individual objects, allowing teams to keep their own app distinct from the apps of other teams.
Depending on its complexity, an app may be composed of one or more components. For example, an app with various microservices may have each microservice represented by a component. The app object allows the controller to add special tags to the NGINX configuration file, which enables the collection of NGINX metrics that can subsequently be filtered by the specific app.
All apps and components are contained within an environment. To access a particular app, a user needs permission to access its environment. If you need access to an environment or app, contact your administrator.
Components
There are two types of components associated with the HTTP and stream contexts:
- The web component is for servicing HTTP and HTTPS traffic that needs to use level 7 features provided by the NGINX http core module.
- The TCP/UDP component is for servicing TCP (including TLS) and UDP traffic at level 4 and uses the NGINX stream core module.
The component objects describe the desired traffic-shaping behavior for the app. In the simplest case, all the traffic for a given path is sent to the same group of servers (called an upstream in NGINX terminology or a workload in App Delivery Manager terminology). The component also controls more advanced shaping features like header manipulation, URL rewriting, backend load‑balancing behaviors, cookie handling, and other settings.
For more information on the NGINX contexts affected by the components, see the following:
- http upstream module
- http upstream health check module
- stream upstream module
- stream health check module
Gateways
The gateway container controls the initial network entry point of the app traffic into the NGINX system (the ingress traffic as opposed to the component, which deals with the egress traffic). The gateway also specifies the NGINX instances that will participate in the routing of traffic using instance groups. Each gateway can have one or more instance groups.
Additionally, for web components, the gateway is used for setting up the hostname and connections that will be used by the NGINX instances and the TLS certificates that should be used (the TCP/UDP component object handles these directly for the stream protocols).
Sites
Sites allow the grouping of instance groups based on geographical locations or other criteria. By associating an instance group to a specific Site, a feature called “Workload Affinity” can be implemented in the components, which allows traffic to be routed to specific workload groups based on the NGINX instance processing the request.
Access the API Documentation
You can view the App Delivery Manager API documentation in the NGINX Management Suite user interface. To access the API Docs, follow the steps below:
- Log in to the NGINX Management Suite user interface.
- From the Launchpad, select the API Documentation card.
- Select App Delivery Manager REST API Spec from the API Documentation list in the sidebar to display the API Reference documentation.