NGINX-Declarative-API

This project provides a set of declarative REST API for NGINX Instance Manager and NGINX One Console

It can be used to manage NGINX Plus configuration lifecycle and to create NGINX Plus configurations using JSON service definitions.

GitOps integration is supported: source of truth is checked for updates (NGINX App Protect policies, TLS certificates, keys and chains/bundles, Swagger/OpenAPI definitions, snippets) and NGINX configurations are automatically kept in sync.

Use cases include:

• Integration with NGINX Instance Manager (instance group) and NGINX One Console (config sync group)
• NGINX App Protect DevSecOps integration (NGINX Instance Manager only)
• API Gateway deployments with automated Swagger / OpenAPI schema import
• API Developer portals zero-touch deployment (redocly and backstage supported)
• API Visibility (moesif supported)
• GitOps integration with source of truth support for
  • NGINX App Protect WAF policies
  • TLS certificates, keys and chains/bundles
  • mTLS certificates
  • http snippets, upstreams, servers, locations
  • stream snippets, upstreams, servers
  • Swagger / OpenAPI schemas
  • NGINX Javascript

A blog article to automate NGINX API Gateway management from OpenAPI schemas is available here

Supported releases

• NGINX Instance Manager 2.14+
• NGINX One Console
• NGINX Plus R30+
• NGINX App Protect WAF 4 and 5

Note: NGINX Plus R33 and above require a valid license and the .output.license section in the declarative JSON is required. See the usage notes for further details. Postman collection examples are provided for R33.

Architecture

---
title: NGINX Declarative API architecture
---
stateDiagram-v2
    DevOps: User
    Client: REST Client
    Pipeline: CI/CD Pipeline
    NIM: NGINX Instance Manager
    N1: NGINX One Console
    AGENT1: NGINX Agent
    NGINX1: NGINX
    AGENT2: NGINX Agent
    NGINX2: NGINX
    INPUT: Input
    SOT: Source of Truth
    NDAPI: NGINX Declarative API
    DEVP: Developer Portal Service
    OUTPUT: Output
    REDIS: Redis
    3RDPARTY: 3rd Party integrations

    DevOps --> Pipeline
    Pipeline --> INPUT
    Client --> INPUT
    INPUT --> NDAPI
    NDAPI --> OUTPUT
    NDAPI --> SOT
    SOT --> NDAPI
    NDAPI --> 3RDPARTY
    3RDPARTY --> NDAPI
    NDAPI --> REDIS
    REDIS --> NDAPI
    OUTPUT --> NIM
    OUTPUT --> N1
    NDAPI --> DEVP
    DEVP --> NDAPI
    NIM --> AGENT1
    AGENT1 --> NGINX1
    N1 --> AGENT2
    AGENT2 --> NGINX2

Loading

GitOps Autosync Mode

sequenceDiagram

title GitOps autosync operations

participant CI/CD Pipeline
participant Source of Truth
participant NGINX Declarative API
participant Redis
participant Developer Portal Service
participant NGINX Instance Manager / NGINX One Console
participant NGINX

box NGINX Declarative API
    participant NGINX Declarative API
    participant Developer Portal Service
    participant Redis
end

CI/CD Pipeline ->> Source of Truth: Commit object updates

critical Run every "synctime" seconds

NGINX Declarative API ->>+ Source of Truth: Check for referenced objects updates
Source of Truth ->>- NGINX Declarative API: Latest timestamp

Note over NGINX Declarative API, Redis: data synchronization

option If updates available
NGINX Declarative API ->>+ Source of Truth: Pull updated objects
Source of Truth ->>- NGINX Declarative API: Updated objects

critical Build Staged Config
critical If Developer Portal enabled
    NGINX Declarative API ->>+ Developer Portal Service: DevPortal generation request
    Developer Portal Service ->>- NGINX Declarative API: DevPortal definition
end
end

NGINX Declarative API ->>+ NGINX Instance Manager / NGINX One Console: Publish staged config to instance group / config sync group
NGINX Instance Manager / NGINX One Console ->> NGINX: Publish config to NGINX instances
NGINX Instance Manager / NGINX One Console ->>- NGINX Declarative API: Return outcome

Note over NGINX Declarative API, Redis: data synchronization

end

Loading

Concurrent access and queuing mode

sequenceDiagram

title Concurrent access and queueing mode

participant CI/CD Pipeline
participant NGINX Declarative API
participant NGINX Instance Manager / NGINX One Console
participant NGINX

critical Initial configuration deployment

CI/CD Pipeline ->> NGINX Declarative API: POST request - base configuration deployment

NGINX Declarative API ->>+ NGINX Instance Manager / NGINX One Console: Publish staged config to instance group / config sync group
NGINX Instance Manager / NGINX One Console ->> NGINX: Publish config to NGINX instances
NGINX Instance Manager / NGINX One Console ->>- NGINX Declarative API: Return outcome

NGINX Declarative API ->> CI/CD Pipeline: Response

end

critical Asynchronous configuration submission

CI/CD Pipeline ->> NGINX Declarative API: PATCH request - asynchronous configuration update 1
NGINX Declarative API ->>+ NGINX Declarative API: request added to the queue
CI/CD Pipeline ->> NGINX Declarative API: PATCH request - asynchronous configuration update 2 
NGINX Declarative API ->>+ NGINX Declarative API: request added to the queue


loop Queue Manager Thread
autonumber 1

NGINX Declarative API ->>+ NGINX Declarative API: get configuration update request from queue

NGINX Declarative API ->>+ NGINX Instance Manager / NGINX One Console: Publish staged config to instance group / config sync group
NGINX Instance Manager / NGINX One Console ->> NGINX: Publish config to NGINX instances
NGINX Instance Manager / NGINX One Console ->>- NGINX Declarative API: Return outcome
NGINX Declarative API ->> NGINX Declarative API: Update configuration update request status

autonumber off
end

CI/CD Pipeline ->> NGINX Declarative API: Check configuration request status
NGINX Declarative API ->> CI/CD Pipeline: Response

end

Loading

Input formats

• Declarative JSON

Output formats

• Output to NGINX Instance Manager 2.14+ imperative REST API (instance group)
• Output to NGINX One Console REST API (config sync group)

Supported features

See the features list

How to use

Usage details and JSON schema are available here:

• API v5.3 - latest - required for NGINX Plus R33+
• API v5.2 - stable - required for NGINX Plus R33+
• API v5.1 - deprecated

A sample Postman collection and usage instructions can be found here

How to run

NGINX Declarative API can be deployed on a Linux virtual machine using docker-compose or on Kubernetes

Building Docker images

Docker images can be built and run using the Docker compose script provided

REST API documentation

When NGINX Declarative API is running, REST API documentation can be accessed at:

• Documentation and testing: /docs
• Redoc documentation: /redoc
• OpenAPI specification: /openapi.json

License

This repository is licensed under the Apache License, Version 2.0. You are free to use, modify, and distribute this codebase within the terms and conditions outlined in the license. For more details, please refer to the LICENSE file.

Support

For support, please open a GitHub issue. Note that the code in this repository is community supported.

Contributing

See Contributing

Code of Conduct

See the Code of Conduct