{"id":20329854,"url":"https://github.com/f5devcentral/nginx-declarative-api","last_synced_at":"2025-04-11T20:53:09.722Z","repository":{"id":53778208,"uuid":"486402347","full_name":"f5devcentral/NGINX-Declarative-API","owner":"f5devcentral","description":"Declarative REST API and GitOps automation layer for NGINX Instance Manager and NGINX One Console","archived":false,"fork":false,"pushed_at":"2025-04-11T14:07:56.000Z","size":16679,"stargazers_count":39,"open_issues_count":1,"forks_count":17,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-11T20:52:59.472Z","etag":null,"topics":["api","apigateway","ci-cd","declarative-api","developer-portal","devsecops","nginx","nginx-app-protect","nginx-configuration","nginx-instance-manager","nginx-one","rest-api"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/f5devcentral.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"code_of_conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-04-28T01:12:48.000Z","updated_at":"2025-04-11T14:06:23.000Z","dependencies_parsed_at":"2023-10-11T23:15:29.765Z","dependency_job_id":"b4f75cbf-6d93-4c56-af2c-c0d93f24ea39","html_url":"https://github.com/f5devcentral/NGINX-Declarative-API","commit_stats":null,"previous_names":["f5devcentral/nginx-declarative-api"],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f5devcentral%2FNGINX-Declarative-API","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f5devcentral%2FNGINX-Declarative-API/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f5devcentral%2FNGINX-Declarative-API/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f5devcentral%2FNGINX-Declarative-API/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/f5devcentral","download_url":"https://codeload.github.com/f5devcentral/NGINX-Declarative-API/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248480515,"owners_count":21110936,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","apigateway","ci-cd","declarative-api","developer-portal","devsecops","nginx","nginx-app-protect","nginx-configuration","nginx-instance-manager","nginx-one","rest-api"],"created_at":"2024-11-14T20:13:48.364Z","updated_at":"2025-04-11T20:53:09.693Z","avatar_url":"https://github.com/f5devcentral.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NGINX-Declarative-API\n\n[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)\n\nThis project provides a set of declarative REST API for [NGINX Instance Manager](https://docs.nginx.com/nginx-management-suite/nim/) and [NGINX One Console](https://docs.nginx.com/nginx-one/)\n\nIt can be used to manage NGINX Plus configuration lifecycle and to create NGINX Plus configurations using JSON service definitions.\n\nGitOps 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.\n\nUse cases include:\n\n- Integration with NGINX Instance Manager (instance group) and NGINX One Console (config sync group)\n- NGINX App Protect DevSecOps integration (NGINX Instance Manager only)\n- API Gateway deployments with automated Swagger / OpenAPI schema import\n- API Developer portals zero-touch deployment (redocly and backstage supported)\n- API Visibility (moesif supported)\n- GitOps integration with source of truth support for\n  - NGINX App Protect WAF policies\n  - TLS certificates, keys and chains/bundles\n  - mTLS certificates\n  - `http` snippets, upstreams, servers, locations\n  - `stream` snippets, upstreams, servers\n  - Swagger / OpenAPI schemas\n  - NGINX Javascript\n\nA **blog article** to automate NGINX API Gateway management from OpenAPI schemas is available [here](https://www.f5.com/company/blog/nginx/from-openapi-to-nginx-as-an-api-gateway-using-a-declarative-api)\n\n## Supported releases\n\n- [NGINX Instance Manager 2.14+](https://docs.nginx.com/nginx-management-suite/nim/)\n- [NGINX One Console](https://docs.nginx.com/nginx-one/)\n- [NGINX Plus R30+](https://docs.nginx.com/nginx/)\n- NGINX App Protect WAF [4](https://docs.nginx.com/nginx-app-protect-waf/v4/) and [5](https://docs.nginx.com/nginx-app-protect-waf/v5/)\n\n**Note**: NGINX Plus R33 and above [require a valid license](https://docs.nginx.com/solutions/about-subscription-licenses/) and the `.output.license` section in the declarative JSON is required. See the [usage notes](/USAGE-v5.3.md) for further details. [Postman collection](/contrib/postman) examples are provided for R33.\n\n## Architecture\n\n```mermaid\n---\ntitle: NGINX Declarative API architecture\n---\nstateDiagram-v2\n    DevOps: User\n    Client: REST Client\n    Pipeline: CI/CD Pipeline\n    NIM: NGINX Instance Manager\n    N1: NGINX One Console\n    AGENT1: NGINX Agent\n    NGINX1: NGINX\n    AGENT2: NGINX Agent\n    NGINX2: NGINX\n    INPUT: Input\n    SOT: Source of Truth\n    NDAPI: NGINX Declarative API\n    DEVP: Developer Portal Service\n    OUTPUT: Output\n    REDIS: Redis\n    3RDPARTY: 3rd Party integrations\n\n    DevOps --\u003e Pipeline\n    Pipeline --\u003e INPUT\n    Client --\u003e INPUT\n    INPUT --\u003e NDAPI\n    NDAPI --\u003e OUTPUT\n    NDAPI --\u003e SOT\n    SOT --\u003e NDAPI\n    NDAPI --\u003e 3RDPARTY\n    3RDPARTY --\u003e NDAPI\n    NDAPI --\u003e REDIS\n    REDIS --\u003e NDAPI\n    OUTPUT --\u003e NIM\n    OUTPUT --\u003e N1\n    NDAPI --\u003e DEVP\n    DEVP --\u003e NDAPI\n    NIM --\u003e AGENT1\n    AGENT1 --\u003e NGINX1\n    N1 --\u003e AGENT2\n    AGENT2 --\u003e NGINX2\n```\n\n## GitOps Autosync Mode\n\n```mermaid\nsequenceDiagram\n\ntitle GitOps autosync operations\n\nparticipant CI/CD Pipeline\nparticipant Source of Truth\nparticipant NGINX Declarative API\nparticipant Redis\nparticipant Developer Portal Service\nparticipant NGINX Instance Manager / NGINX One Console\nparticipant NGINX\n\nbox NGINX Declarative API\n    participant NGINX Declarative API\n    participant Developer Portal Service\n    participant Redis\nend\n\nCI/CD Pipeline -\u003e\u003e Source of Truth: Commit object updates\n\ncritical Run every \"synctime\" seconds\n\nNGINX Declarative API -\u003e\u003e+ Source of Truth: Check for referenced objects updates\nSource of Truth -\u003e\u003e- NGINX Declarative API: Latest timestamp\n\nNote over NGINX Declarative API, Redis: data synchronization\n\noption If updates available\nNGINX Declarative API -\u003e\u003e+ Source of Truth: Pull updated objects\nSource of Truth -\u003e\u003e- NGINX Declarative API: Updated objects\n\ncritical Build Staged Config\ncritical If Developer Portal enabled\n    NGINX Declarative API -\u003e\u003e+ Developer Portal Service: DevPortal generation request\n    Developer Portal Service -\u003e\u003e- NGINX Declarative API: DevPortal definition\nend\nend\n\nNGINX Declarative API -\u003e\u003e+ NGINX Instance Manager / NGINX One Console: Publish staged config to instance group / config sync group\nNGINX Instance Manager / NGINX One Console -\u003e\u003e NGINX: Publish config to NGINX instances\nNGINX Instance Manager / NGINX One Console -\u003e\u003e- NGINX Declarative API: Return outcome\n\nNote over NGINX Declarative API, Redis: data synchronization\n\nend\n```\n\n## Concurrent access and queuing mode\n\n```mermaid\nsequenceDiagram\n\ntitle Concurrent access and queueing mode\n\nparticipant CI/CD Pipeline\nparticipant NGINX Declarative API\nparticipant NGINX Instance Manager / NGINX One Console\nparticipant NGINX\n\ncritical Initial configuration deployment\n\nCI/CD Pipeline -\u003e\u003e NGINX Declarative API: POST request - base configuration deployment\n\nNGINX Declarative API -\u003e\u003e+ NGINX Instance Manager / NGINX One Console: Publish staged config to instance group / config sync group\nNGINX Instance Manager / NGINX One Console -\u003e\u003e NGINX: Publish config to NGINX instances\nNGINX Instance Manager / NGINX One Console -\u003e\u003e- NGINX Declarative API: Return outcome\n\nNGINX Declarative API -\u003e\u003e CI/CD Pipeline: Response\n\nend\n\ncritical Asynchronous configuration submission\n\nCI/CD Pipeline -\u003e\u003e NGINX Declarative API: PATCH request - asynchronous configuration update 1\nNGINX Declarative API -\u003e\u003e+ NGINX Declarative API: request added to the queue\nCI/CD Pipeline -\u003e\u003e NGINX Declarative API: PATCH request - asynchronous configuration update 2 \nNGINX Declarative API -\u003e\u003e+ NGINX Declarative API: request added to the queue\n\n\nloop Queue Manager Thread\nautonumber 1\n\nNGINX Declarative API -\u003e\u003e+ NGINX Declarative API: get configuration update request from queue\n\nNGINX Declarative API -\u003e\u003e+ NGINX Instance Manager / NGINX One Console: Publish staged config to instance group / config sync group\nNGINX Instance Manager / NGINX One Console -\u003e\u003e NGINX: Publish config to NGINX instances\nNGINX Instance Manager / NGINX One Console -\u003e\u003e- NGINX Declarative API: Return outcome\nNGINX Declarative API -\u003e\u003e NGINX Declarative API: Update configuration update request status\n\nautonumber off\nend\n\nCI/CD Pipeline -\u003e\u003e NGINX Declarative API: Check configuration request status\nNGINX Declarative API -\u003e\u003e CI/CD Pipeline: Response\n\nend\n```\n\n## Input formats\n\n- [X] Declarative JSON\n\n## Output formats\n\n- [X] Output to NGINX Instance Manager 2.14+ imperative REST API (instance group)\n- [X] Output to NGINX One Console REST API (config sync group)\n  \n## Supported features\n\nSee the [features list](/FEATURES.md)\n\n## How to use\n\nUsage details and JSON schema are available here:\n\n- [API v5.3](/USAGE-v5.3.md) - latest - required for NGINX Plus R33+\n- [API v5.2](/USAGE-v5.2.md) - stable - required for NGINX Plus R33+\n- [API v5.1](/USAGE-v5.1.md) - deprecated\n\nA sample Postman collection and usage instructions can be found [here](/contrib/postman)\n\n## How to run\n\nNGINX Declarative API can be deployed on a Linux virtual machine using [docker-compose](/contrib/docker-compose) or on [Kubernetes](/contrib/kubernetes)\n\n## Building Docker images\n\nDocker images can be built and run using the Docker compose [script](/contrib/docker-compose) provided\n\n## REST API documentation\n\nWhen NGINX Declarative API is running, REST API documentation can be accessed at:\n\n- Documentation and testing: `/docs`\n- Redoc documentation: `/redoc`\n- OpenAPI specification: `/openapi.json`\n\n## License\n\nThis 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](/LICENSE.md) file.\n\n## Support\n\nFor support, please open a GitHub issue. Note that the code in this repository is community supported.\n\n## Contributing\n\nSee [Contributing](/CONTRIBUTING.md)\n\n## Code of Conduct\n\nSee the [Code of Conduct](/code_of_conduct.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ff5devcentral%2Fnginx-declarative-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ff5devcentral%2Fnginx-declarative-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ff5devcentral%2Fnginx-declarative-api/lists"}