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 Core
    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 Core
participant Redis
participant Developer Portal Service
participant NGINX Instance Manager / NGINX One Console
participant NGINX

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

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

critical Run every "synctime" seconds

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

Note over NGINX Declarative API Core, Redis: data synchronization

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

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

NGINX Declarative API Core ->>+ 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 Core: Publish outcome

Note over NGINX Declarative API Core, Redis: data synchronization

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.2 - latest - required for NGINX Plus R33+
• API v5.1
• API v5.0 - 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