This project provides a set of declarative REST API for NGINX Instance Manager.
It can be used to manage NGINX Plus configuration lifecycle and to create NGINX Plus configurations using JSON service definitions.
GitOps integration is supported when used with NGINX Instance Manager: source of truth is checked for updates (NGINX App Protect policies, TLS certificates, keys and chains/bundles, Swagger/OpenAPI definitions) and NGINX configurations are automatically kept in sync.
Use cases include:
- Rapid configuration generation and templating
- CI/CD integration with NGINX Instance Manager (instance groups and staged configs)
- NGINX App Protect DevSecOps integration
- API Gateway deployments with automated Swagger / OpenAPI schema import
- API Developer portals zero-touch deployment
- 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, locationsstream
snippets, upstreams, servers- Swagger / OpenAPI schemas
- NGINX Javascript files
- NGINX Instance Manager 2.14+
- NGINX Plus R30+
- NGINX App Protect WAF 4.8+
---
title: NGINX Declarative API architecture
---
stateDiagram-v2
DevOps: User
Client: REST Client
Pipeline: CI/CD Pipeline
NIM: NGINX Instance Manager
AGENT: NGINX Agent
NGINX: NGINX
INPUT: Input
SOT: Source of Truth
NDAPI: NGINX Declarative API Core
DEVP: Developer Portal Service
OUTPUT: Output
REDIS: Redis
POST: Generic POST endpoint
CONFIGMAP: Kubernetes ConfigMap
PLAINTEXT: Plaintext
BASE64: Base64-encoded
DevOps --> Pipeline
Pipeline --> INPUT
Client --> INPUT
INPUT --> NDAPI
NDAPI --> OUTPUT
NDAPI --> SOT
SOT --> NDAPI
NDAPI --> REDIS
REDIS --> NDAPI
OUTPUT --> BASE64
OUTPUT --> POST
OUTPUT --> CONFIGMAP
OUTPUT --> PLAINTEXT
OUTPUT --> NIM
NDAPI --> DEVP
DEVP --> NDAPI
NIM --> AGENT
AGENT --> NGINX
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
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: Publish staged config to instance group
NGINX Instance Manager ->> NGINX: Publish config to NGINX instances
NGINX Instance Manager ->>- NGINX Declarative API Core: Publish outcome
Note over NGINX Declarative API Core, Redis: data synchronization
end
- Declarative REST API
- Plaintext
- JSON-wrapped Base64-encoded
- Kubernetes Configmap
- POST to Generic REST API endpoint
- Output to NGINX Instance Manager 2.14+ imperative REST API
See the features list
Usage details and JSON schema are available here:
A sample Postman collection and usage instructions can be found here
Docker-compose is the recommended method to run NGINX Declarative API on a Linux virtual machine. Full details are available here
Docker images can be built and run using:
git clone https://github.com/f5devcentral/NGINX-Declarative-API
cd NGINX-Declarative-API
docker build --no-cache -t nginx-declarative-api -f ./Dockerfile .
docker run --name nginx-declarative-api -d -p 5000:5000 nginx-declarative-api
cd contrib/redocly/devportal
docker build --no-cache -t nginx-declarative-api-devportal .
docker run --name devportal -d -p 5001:5000 nginx-declarative-api-devportal
Configuration can be customized mounting config.toml
as a volume nginx-declarative-api
docker image as a volume to customize
When NGINX Declarative API is running, REST API documentation can be accessed at:
- Documentation and testing:
http://<NGINX_DECLARATIVE_API_ADDRESS>:5000/docs
- Redoc documentation:
http://<NGINX_DECLARATIVE_API_ADDRESS>:5000/redoc
- OpenAPI specification:
http://<NGINX_DECLARATIVE_API_ADDRESS>:5000/openapi.json
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.
See Support
See Contributing
See the Code of Conduct