NGINX-Declarative-API

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, locations
  • stream snippets, upstreams, servers
  • Swagger / OpenAPI schemas
  • NGINX Javascript files

Supported releases

• NGINX Instance Manager 2.14+
• NGINX Plus R30+
• NGINX App Protect WAF 4.8+

Architecture

---
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

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
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

Input formats

• Declarative REST API

Output formats

• Plaintext
• JSON-wrapped Base64-encoded
• Kubernetes Configmap
• POST to Generic REST API endpoint
• Output to NGINX Instance Manager 2.14+ imperative REST API

Supported features

See the features list

How to use

Usage details and JSON schema are available here:

• API v4.2 - latest
• API v4.1

A sample Postman collection and usage instructions can be found here

How to run

Docker-compose is the recommended method to run NGINX Declarative API on a Linux virtual machine. Full details are available here

Building Docker images

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

REST API documentation

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

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

See Support

Contributing

See Contributing

Code of Conduct

See the Code of Conduct