diff --git a/README.md b/README.md index ec0d4fe..169b469 100644 --- a/README.md +++ b/README.md @@ -9,50 +9,51 @@ This project supports [F5 NGINX Instance Manager](https://docs.nginx.com/nginx-i ## ๐Ÿ“š Overview -At its core, the NGINX Declarative API supports **declarative configuration management** by letting users define what the state of NGINX *should 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. +At its core, the NGINX Declarative API supports **declarative configuration management** by letting users define what the state of NGINX *should 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 in **modern, 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. +- โœ… **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 +- 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 A **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) ## ๐Ÿš€ Supported releases -* [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 Instance Manager 2.14+](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/) -**Note**: F5 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.4.md) for further details. [Postman collection](contrib/postman) examples are provided for NGINX Plus R33+. +**Note**: F5 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.4.md) for further details. [Postman collection](/contrib/postman) examples are provided for NGINX Plus R33+. ## ๐Ÿ› ๏ธ Architecture -``` +```mermaid --- title: NGINX Declarative API architecture --- @@ -97,7 +98,7 @@ stateDiagram-v2 ## ๐Ÿค– GitOps Autosync Mode -``` +```mermaid sequenceDiagram title GitOps autosync operations @@ -147,7 +148,7 @@ end ## ๐Ÿ•’ Concurrent access and queuing mode -``` +```mermaid sequenceDiagram title Concurrent access and queueing mode @@ -198,41 +199,41 @@ end ## ๐Ÿงฉ Input formats -* Declarative JSON +- [X] Declarative JSON ## ๐Ÿงพ Output formats -* Output to [F5 NGINX Instance Manager](https://docs.nginx.com/nginx-instance-manager/) 2.20+ imperative REST API (instance group) -* Output to [F5 NGINX One Console](https://docs.nginx.com/nginx-one-console/) REST API (config sync group) +- [X] Output to F5 NGINX Instance Manager 2.14+ imperative REST API (instance group) +- [X] Output to F5 NGINX One Console REST API (config sync group) ## ๐ŸŒŸ Supported features -See the [features list](FEATURES.md) +See the [features list](/FEATURES.md) ## ๐Ÿ”ง How to use Usage details and JSON schema are available here: -* [API v5.5](USAGE-v5.5.md) - latest -* [API v5.4](USAGE-v5.4.md) - stable +- [API v5.4](/USAGE-v5.4.md) - latest +- [API v5.3](/USAGE-v5.3.md) - stable -A sample Postman collection and usage instructions can be found [here](contrib/postman) +A sample Postman collection and usage instructions can be found [here](/contrib/postman) ## ๐Ÿƒ How to run -NGINX Declarative API can be deployed on a Linux virtual machine using [docker-compose](contrib/docker-compose) or on [Kubernetes](contrib/kubernetes) +NGINX Declarative API can be deployed on a Linux virtual machine using [docker-compose](/contrib/docker-compose) or on [Kubernetes](/contrib/kubernetes) ## ๐Ÿณ Building Docker images -Docker images can be built and run using the Docker compose [script](contrib/docker-compose) provided +Docker images can be built and run using the Docker compose [script](/contrib/docker-compose) 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` +- Documentation and testing: `/docs` +- Redoc documentation: `/redoc` +- OpenAPI specification: `/openapi.json` ## ๐Ÿ”’ Security @@ -240,7 +241,7 @@ To report a security vulnerability, please do **not** open a public GitHub issue ## โš–๏ธ 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](LICENSE.md) file. +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](/LICENSE.md) file. ## ๐Ÿ†˜ Support @@ -248,8 +249,8 @@ For support, please open a GitHub issue. Note that the code in this repository i ## ๐Ÿ’ก Contributing -See [Contributing](CONTRIBUTING.md) +See [Contributing](/CONTRIBUTING.md) ## ๐Ÿค Code of Conduct -See the [Code of Conduct](code_of_conduct.md) +See the [Code of Conduct](/code_of_conduct.md)