|
| 1 | +# Usage for NGINX Declarative API v5.2 |
| 2 | + |
| 3 | +Version 5.2 supports: |
| 4 | + |
| 5 | +- [NGINX Instance Manager](https://docs.nginx.com/nginx-management-suite/nim/) 2.14+. Version 2.18+ is required for NGINX R33 and above |
| 6 | +- [NGINX One Console](https://docs.nginx.com/nginx-one/) |
| 7 | +- [NGINX Plus](https://docs.nginx.com/nginx/) R31, R32, R33+ |
| 8 | +- [NGINX App Protect WAF](https://docs.nginx.com/nginx-app-protect-waf/) 4 with precompiled [policy bundles](https://docs.nginx.com/nginx-app-protect-waf/v5/admin-guide/compiler/) |
| 9 | + |
| 10 | +The JSON schema is self explanatory. See also the [sample Postman collection](/contrib/postman) for usage examples |
| 11 | + |
| 12 | +- `.output.license` defines the JWT license to use for NGINX Plus R33+ |
| 13 | + - `.output.license.endpoint` the usage reporting endpoint (defaults to `product.connect.nginx.com`). NGINX Instance Manager address can be used here |
| 14 | + - `.output.license.token` the JWT license token |
| 15 | + - `.output.license.ssl_verify` set to `false` to trust all SSL certificates (not recommended). Useful for reporting to NGINX Instance Manager without a local PKI. |
| 16 | + - `.output.license.grace_period` Set to 'true' to begin the 180-day reporting enforcement grace period. Reporting must begin or resume before the end of the grace period to ensure continued operation |
| 17 | +- `.output.type` defines how NGINX configuration will be returned: |
| 18 | + - *nms* - NGINX configuration is published as a Staged Config to NGINX Instance Manager |
| 19 | + - `.output.nms.url` the NGINX Instance Manager URL |
| 20 | + - `.output.nms.username` the NGINX Instance Manager authentication username |
| 21 | + - `.output.nms.password` the NGINX Instance Manager authentication password |
| 22 | + - `.output.nms.instancegroup` the NGINX Instance Manager instance group to publish the configuration to |
| 23 | + - `.output.nms.synctime` **optional**, used for GitOps autosync. When specified and the declaration includes HTTP(S) references to NGINX App Protect policies, TLS certificates/keys/chains, the HTTP(S) endpoints will be checked every `synctime` seconds and if external contents have changed, the updated configuration will automatically be published to NGINX Instance Manager |
| 24 | + - `.output.nms.modules` an optional array of NGINX module names (ie. 'ngx_http_app_protect_module', 'ngx_http_js_module','ngx_stream_js_module') |
| 25 | + - `.output.nms.certificates` an optional array of TLS certificates/keys/chains to be published |
| 26 | + - `.output.nms.certificates[].type` the item type ('certificate', 'key', 'chain') |
| 27 | + - `.output.nms.certificates[].name` the certificate/key/chain name with no path/extension (ie. 'test-application') |
| 28 | + - `.output.nms.certificates[].contents` the content: this can be either base64-encoded or be a HTTP(S) URL that will be fetched dynamically from a source of truth |
| 29 | + - `.output.nms.policies[]` an optional array of NGINX App Protect security policies |
| 30 | + - `.output.nms.policies[].type` the policy type ('app_protect') |
| 31 | + - `.output.nms.policies[].name` the policy name (ie. 'prod-policy') |
| 32 | + - `.output.nms.policies[].active_tag` the policy tag to enable among all available versions (ie. 'v1') |
| 33 | + - `.output.nms.policies[].versions[]` array with all available policy versions |
| 34 | + - `.output.nms.policies[].versions[].tag` the policy version's tag name |
| 35 | + - `.output.nms.policies[].versions[].displayName` the policy version's display name |
| 36 | + - `.output.nms.policies[].versions[].description` the policy version's description |
| 37 | + - `.output.nms.policies[].versions[].contents` this can be either base64-encoded or be a HTTP(S) URL that will be fetched dynamically from a source of truth |
| 38 | + - *nginxone* - NGINX configuration is published to a NGINX One Console config sync group |
| 39 | + - `.output.nginxone.url` the NGINX One Console URL |
| 40 | + - `.output.nginxone.namespace` the NGINX One Console namespace |
| 41 | + - `.output.nginxone.token` the authentication token |
| 42 | + - `.output.nginxone.configsyncgroup` the NGINX One Console config sync group name |
| 43 | + - `.output.nginxone.synctime` **optional**, used for GitOps autosync. When specified and the declaration includes HTTP(S) references to NGINX App Protect policies, TLS certificates/keys/chains, the HTTP(S) endpoints will be checked every `synctime` seconds and if external contents have changed, the updated configuration will automatically be published to NGINX One Cloud Console |
| 44 | + - `.output.nginxone.modules` an optional array of NGINX module names (ie. 'ngx_http_app_protect_module', 'ngx_http_js_module','ngx_stream_js_module') |
| 45 | + - `.output.nginxone.certificates` an optional array of TLS certificates/keys/chains to be published |
| 46 | + - `.output.nginxone.certificates[].type` the item type ('certificate', 'key', 'chain') |
| 47 | + - `.output.nginxone.certificates[].name` the certificate/key/chain name with no path/extension (ie. 'test-application') |
| 48 | + - `.output.nginxone.certificates[].contents` the content: this can be either base64-encoded or be a HTTP(S) URL that will be fetched dynamically from a source of truth |
| 49 | +- `.declaration` describes the NGINX configuration to be created |
| 50 | + - `.declaration.http[]` NGINX HTTP definitions |
| 51 | + - `.declaration.layer4[]` NGINX TCP/UDP definitions |
| 52 | + - `.declaration.resolvers[]` DNS resolvers definitions |
| 53 | + |
| 54 | +### API endpoints |
| 55 | + |
| 56 | +- `POST /v5.2/config/` - Publish a new declaration |
| 57 | +- `PATCH /v5.2/config/{config_uid}` - Update an existing declaration |
| 58 | + - Per-HTTP server CRUD |
| 59 | + - Per-HTTP upstream CRUD |
| 60 | + - Per-Stream server CRUD |
| 61 | + - Per-Stream upstream CRUD |
| 62 | + - Per-NGINX App Protect WAF policy CRUD |
| 63 | +- `GET /v5.2/config/{config_uid}` - Retrieve an existing declaration |
| 64 | +- `DELETE /v5.2/config/{config_uid}` - Delete an existing declaration |
0 commit comments