f5devcentral/NGINX-Declarative-API

# NGINX-Declarative-API [](https://www.repostatus.org/#active) [](https://codecov.io/gh/f5devcentral/NGINX-Declarative-API) NGINX Declarative API 允许用户以现代的**声明式风格**管理 **NGINX 配置**。该项目无需手动修改配置或使用底层 API，而是允许用户将所需配置表示为单一的 JSON 对象，从而简化了操作工作流。 该 API 抽象了管理 NGINX 配置的复杂性，使开发者、运维人员和自动化系统能够与 NGINX 无缝集成。 本项目支持 [F5 NGINX Instance Manager](https://docs.nginx.com/nginx-instance-manager/) 和 [F5 NGINX One Console](https://docs.nginx.com/nginx-one/) ## 📚 概述 从核心上讲，NGINX Declarative API 支持**声明式配置管理**，它允许用户定义 NGINX 的状态*应该是什么*，而不是如何达到该状态。它通过将用户定义的 JSON payload 处理为有效且优化的 NGINX 配置，消除了过程化更改的需要。 该工具非常适合在**现代、动态的基础设施**中管理 NGINX，例如 CI/CD 环境、容器化应用程序（如 Kubernetes）或大规模代理服务器设置。 ### ➡️ 为什么使用 NGINX Declarative API？ - ✅ **声明式简易性**：将配置表示为单一的高级 JSON 对象。 - ✅ **自动化优先设计**：以最小的工作量将配置集成到 CI/CD pipeline 中。 - ✅ **减少错误**：内置验证以确保配置准确且优化。 - ✅ **动态更新**：在高度动态的环境中处理频繁的配置更改。 - ✅ **无缝可扩展性**：简化在超大规模分布式架构中管理 NGINX 设置的过程。 支持 GitOps 集成：检查事实来源的更新（F5 WAF for NGINX 策略、TLS 证书、密钥和链/捆绑包、Swagger/OpenAPI 定义、代码片段），并使 NGINX 配置自动保持同步。 ### 📝 用例 - 与 F5 NGINX Instance Manager（实例组）和 F5 NGINX One Console（配置同步组）集成 - F5 WAF for NGINX DevSecOps 集成 - 通过自动化 Swagger / OpenAPI schema 导入进行 API Gateway 部署 - API 开发者门户零接触部署（支持 redocly 和 backstage） - API 可见性（支持 moesif） - 支持事实来源的 GitOps 集成 - F5 WAF for NGINX 策略 - TLS 证书、密钥和链/捆绑包 - mTLS 证书 - `http` 代码片段、upstreams、servers、locations - `stream` 代码片段、upstreams、servers - Swagger / OpenAPI schemas - NGINX Javascript 一篇关于从 OpenAPI schemas 自动化 NGINX API Gateway 管理的**博客文章**可以在[这里](https://www.f5.com/company/blog/nginx/from-openapi-to-nginx-as-an-api-gateway-using-a-declarative-api)找到 ## 🚀 支持的版本 - [F5 NGINX Instance Manager 2.20+](https://docs.nginx.com/nginx-instance-manager/) - [F5 NGINX One Console](https://docs.nginx.com/nginx-one/) - [F5 NGINX Plus R33+](https://docs.nginx.com/nginx/) - [F5 WAF for NGINX](https://docs.nginx.com/waf/) **注意**：F5 NGINX Plus R33 及以上版本[需要有效的许可证](https://docs.nginx.com/solutions/about-subscription-licenses/)，并且声明式 JSON 中必须包含 `.output.license` 部分。 ## 🛠️ 架构 ``` --- 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 自动同步模式 ``` sequenceDiagram title GitOps autosync operations participant CI/CD Pipeline participant Source of Truth participant NGINX Declarative API participant Redis participant Developer Portal Service participant NGINX Instance Manager / NGINX One Console participant NGINX box NGINX Declarative API participant NGINX Declarative API participant Developer Portal Service participant Redis end CI/CD Pipeline ->> Source of Truth: Commit object updates critical Run every "synctime" seconds NGINX Declarative API ->>+ Source of Truth: Check for referenced objects updates Source of Truth ->>- NGINX Declarative API: Latest timestamp Note over NGINX Declarative API, Redis: data synchronization option If updates available NGINX Declarative API ->>+ Source of Truth: Pull updated objects Source of Truth ->>- NGINX Declarative API: Updated objects critical Build Staged Config critical If Developer Portal enabled NGINX Declarative API ->>+ Developer Portal Service: DevPortal generation request Developer Portal Service ->>- NGINX Declarative API: DevPortal definition end end NGINX Declarative API ->>+ 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: Return outcome Note over NGINX Declarative API, Redis: data synchronization end ``` ## 🕒 并发访问和排队模式 ``` sequenceDiagram title Concurrent access and queueing mode participant CI/CD Pipeline participant NGINX Declarative API participant NGINX Instance Manager / NGINX One Console participant NGINX critical Initial configuration deployment CI/CD Pipeline ->> NGINX Declarative API: POST request - base configuration deployment NGINX Declarative API ->>+ 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: Return outcome NGINX Declarative API ->> CI/CD Pipeline: Response end critical Asynchronous configuration submission CI/CD Pipeline ->> NGINX Declarative API: PATCH request - asynchronous configuration update 1 NGINX Declarative API ->>+ NGINX Declarative API: request added to the queue CI/CD Pipeline ->> NGINX Declarative API: PATCH request - asynchronous configuration update 2 NGINX Declarative API ->>+ NGINX Declarative API: request added to the queue loop Queue Manager Thread autonumber 1 NGINX Declarative API ->>+ NGINX Declarative API: get configuration update request from queue NGINX Declarative API ->>+ 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: Return outcome NGINX Declarative API ->> NGINX Declarative API: Update configuration update request status autonumber off end CI/CD Pipeline ->> NGINX Declarative API: Check configuration request status NGINX Declarative API ->> CI/CD Pipeline: Response end ``` ## 🌟 支持的功能 请查看[功能列表](/FEATURES.md) ## 🔧 如何使用 使用详情和 JSON schema 可在此处获取： - [API v5.6](/USAGE-v5.6.md) - 最新版 - [API v5.5](/USAGE-v5.5.md) - 稳定版 可以在[这里](/contrib/postman)找到示例 Postman 集合和使用说明 ## 🏃 如何运行 NGINX Declarative API 可以部署在： * 使用 [docker-compose](/contrib/docker-compose) 的 Linux 虚拟机 * 使用 [manifests](/contrib/kubernetes) 的 Kubernetes * 使用 [Helm chart](contrib/helm/nginx-declarative-api) 的 Kubernetes ## 🧪 运行单元测试 Python 单元测试涵盖了核心实用程序和配置修补模块。可以从仓库根目录运行它们： ``` pip3 install pytest pyyaml python3 -m pytest tests/ -v ``` WebUI 测试使用 [Vitest](https://vitest.dev/)，可以在 `webui/` 目录中运行： ``` cd webui npm install npm test -- --run ``` 这两个测试套件都会在每次 pull request 和发布构建时在 GitHub Actions 中自动运行。 ## 🐳 构建 Docker 镜像 可以使用提供的 Docker compose [脚本](/contrib/docker-compose)来构建和运行 Docker 镜像 ## 📖 REST API 文档 当 NGINX Declarative API 运行时，可以通过以下路径访问 REST API 文档： - 文档和测试：`/docs` - Redoc 文档：`/redoc` - OpenAPI 规范：`/openapi.json` ## 🔒 安全 如需报告安全漏洞，请**不要**公开提 GitHub issue。相反，请遵循 [SECURITY.md](SECURITY.md) 中概述的负责任的披露流程。 ## ⚖️ 许可证 本仓库根据 Apache License, Version 2.0 获得许可。您可以在许可证中概述的条款和条件下自由使用、修改和分发此代码库。更多详细信息，请参阅 [LICENSE](/LICENSE.md) 文件。 ## 🆘 支持 如需获得支持，请提交一个 GitHub issue。请注意，本仓库中的代码由社区提供支持。 ## 💡 贡献 请查看[贡献指南](/CONTRIBUTING.md) ## 🤝 行为准则 请查看[行为准则](/code_of_conduct.md)

标签：GitOps, NGINX, RESTful API, 声明式API, 子域名突变, 提示词优化, 搜索引擎查询, 请求拦截, 运维自动化, 逆向工具