f5devcentral/NGINX-Declarative-APIPublic

NotificationsYou must be signed in to change notification settings
Fork17
Star41

Declarative REST API and GitOps automation layer for NGINX Plus, NGINX Instance Manager and NGINX One Console

License

Apache-2.0 license

41 stars 17 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 268 Commits
.github/ISSUE_TEMPLATE		.github/ISSUE_TEMPLATE
contrib		contrib
etc		etc
src		src
templates		templates
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
FEATURES.md		FEATURES.md
LICENSE.md		LICENSE.md
README.md		README.md
USAGE-v5.3.md		USAGE-v5.3.md
USAGE-v5.4.md		USAGE-v5.4.md
code_of_conduct.md		code_of_conduct.md

Repository files navigation

NGINX-Declarative-API

NGINX Declarative API enables users to manageNGINX configurations in a moderndeclarative style. Instead of modifying configurations manually or using low-level APIs, this project simplifies operational workflows by allowing users to express desired configurations as a single JSON object.The API abstracts the complexity of managing NGINX configurations, empowering developers, operators, and automation systems to integrate seamlessly with NGINX.

This project supportsF5 NGINX Instance Manager andF5 NGINX One Console

📚 Overview

At its core, the NGINX Declarative API supportsdeclarative configuration management by letting users define what the state of NGINXshould be, rather than how to get there. It eliminates the need for procedural changes by processing user-defined JSON payloads into valid and optimized NGINX configurations.

This tool is ideal for managing NGINX inmodern, dynamic infrastructures such as CI/CD environments, containerized applications (like Kubernetes), or large-scale proxy server setups.

➡️ Why Use the NGINX Declarative API?

✅Declarative Simplicity: Express configurations as a single, high-level JSON object.
✅Automation-First Design: Integrate configurations into CI/CD pipelines with minimal effort.
✅Error Reduction: Built-in validation for accurate and optimized configurations.
✅Dynamic Updates: Handle frequent configuration changes in highly dynamic environments.
✅Seamless Scalability: Simplifies managing NGINX setups in high-scale distributed architectures.

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

📝 Use Cases

Integration with F5 NGINX Instance Manager (instance group) and F5 NGINX One Console (config sync group)
F5 WAF for NGINX DevSecOps integration
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
- F5 WAF for NGINX policies
- TLS certificates, keys and chains/bundles
- mTLS certificates
- http snippets, upstreams, servers, locations
- stream snippets, upstreams, servers
- Swagger / OpenAPI schemas
- NGINX Javascript

Ablog article to automate NGINX API Gateway management from OpenAPI schemas is availablehere

🚀 Supported releases

Note: F5 NGINX Plus R33 and aboverequire a valid license and the.output.license section in the declarative JSON is required. See theusage notes for further details.Postman collection examples are provided for NGINX Plus 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

🤖 GitOps Autosync Mode

sequenceDiagramtitle GitOps autosync operationsparticipant CI/CD Pipelineparticipant Source of Truthparticipant NGINX Declarative APIparticipant Redisparticipant Developer Portal Serviceparticipant NGINX Instance Manager / NGINX One Consoleparticipant NGINXbox NGINX Declarative API    participant NGINX Declarative API    participant Developer Portal Service    participant RedisendCI/CD Pipeline ->> Source of Truth: Commit object updatescritical Run every "synctime" secondsNGINX Declarative API ->>+ Source of Truth: Check for referenced objects updatesSource of Truth ->>- NGINX Declarative API: Latest timestampNote over NGINX Declarative API, Redis: data synchronizationoption If updates availableNGINX Declarative API ->>+ Source of Truth: Pull updated objectsSource of Truth ->>- NGINX Declarative API: Updated objectscritical Build Staged Configcritical If Developer Portal enabled    NGINX Declarative API ->>+ Developer Portal Service: DevPortal generation request    Developer Portal Service ->>- NGINX Declarative API: DevPortal definitionendendNGINX Declarative API ->>+ NGINX Instance Manager / NGINX One Console: Publish staged config to instance group / config sync groupNGINX Instance Manager / NGINX One Console ->> NGINX: Publish config to NGINX instancesNGINX Instance Manager / NGINX One Console ->>- NGINX Declarative API: Return outcomeNote over NGINX Declarative API, Redis: data synchronizationend

🕒 Concurrent access and queuing mode

sequenceDiagramtitle Concurrent access and queueing modeparticipant CI/CD Pipelineparticipant NGINX Declarative APIparticipant NGINX Instance Manager / NGINX One Consoleparticipant NGINXcritical Initial configuration deploymentCI/CD Pipeline ->> NGINX Declarative API: POST request - base configuration deploymentNGINX Declarative API ->>+ NGINX Instance Manager / NGINX One Console: Publish staged config to instance group / config sync groupNGINX Instance Manager / NGINX One Console ->> NGINX: Publish config to NGINX instancesNGINX Instance Manager / NGINX One Console ->>- NGINX Declarative API: Return outcomeNGINX Declarative API ->> CI/CD Pipeline: Responseendcritical Asynchronous configuration submissionCI/CD Pipeline ->> NGINX Declarative API: PATCH request - asynchronous configuration update 1NGINX Declarative API ->>+ NGINX Declarative API: request added to the queueCI/CD Pipeline ->> NGINX Declarative API: PATCH request - asynchronous configuration update 2 NGINX Declarative API ->>+ NGINX Declarative API: request added to the queueloop Queue Manager Threadautonumber 1NGINX Declarative API ->>+ NGINX Declarative API: get configuration update request from queueNGINX Declarative API ->>+ NGINX Instance Manager / NGINX One Console: Publish staged config to instance group / config sync groupNGINX Instance Manager / NGINX One Console ->> NGINX: Publish config to NGINX instancesNGINX Instance Manager / NGINX One Console ->>- NGINX Declarative API: Return outcomeNGINX Declarative API ->> NGINX Declarative API: Update configuration update request statusautonumber offendCI/CD Pipeline ->> NGINX Declarative API: Check configuration request statusNGINX Declarative API ->> CI/CD Pipeline: Responseend

🧩 Input formats

Declarative JSON

🧾 Output formats

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

🌟 Supported features

See thefeatures list

🔧 How to use

Usage details and JSON schema are available here:

API v5.4 - latest
API v5.3 - stable

A sample Postman collection and usage instructions can be foundhere

🏃 How to run

NGINX Declarative API can be deployed on a Linux virtual machine usingdocker-compose or onKubernetes

🐳 Building Docker images

Docker images can be built and run using the Docker composescript 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 theLICENSE file.