Skip to content

Latest commit

 

History

History
64 lines (58 loc) · 5.5 KB

USAGE-v5.2.md

File metadata and controls

64 lines (58 loc) · 5.5 KB
Raw

Usage for NGINX Declarative API v5.2

Version 5.2 supports:

The JSON schema is self explanatory. See also the sample Postman collection for usage examples

  • .output.license defines the JWT license to use for NGINX Plus R33+
    • .output.license.endpoint the usage reporting endpoint (defaults to product.connect.nginx.com). NGINX Instance Manager address can be used here
    • .output.license.token the JWT license token
    • .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.
    • .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
  • .output.type defines how NGINX configuration will be returned:
    • nms - NGINX configuration is published as a Staged Config to NGINX Instance Manager
      • .output.nms.url the NGINX Instance Manager URL
      • .output.nms.username the NGINX Instance Manager authentication username
      • .output.nms.password the NGINX Instance Manager authentication password
      • .output.nms.instancegroup the NGINX Instance Manager instance group to publish the configuration to
      • .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
      • .output.nms.modules an optional array of NGINX module names (ie. 'ngx_http_app_protect_module', 'ngx_http_js_module','ngx_stream_js_module')
      • .output.nms.certificates an optional array of TLS certificates/keys/chains to be published
        • .output.nms.certificates[].type the item type ('certificate', 'key', 'chain')
        • .output.nms.certificates[].name the certificate/key/chain name with no path/extension (ie. 'test-application')
        • .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
      • .output.nms.policies[] an optional array of NGINX App Protect security policies
        • .output.nms.policies[].type the policy type ('app_protect')
        • .output.nms.policies[].name the policy name (ie. 'prod-policy')
        • .output.nms.policies[].active_tag the policy tag to enable among all available versions (ie. 'v1')
        • .output.nms.policies[].versions[] array with all available policy versions
        • .output.nms.policies[].versions[].tag the policy version's tag name
        • .output.nms.policies[].versions[].displayName the policy version's display name
        • .output.nms.policies[].versions[].description the policy version's description
        • .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
    • nginxone - NGINX configuration is published to a NGINX One Console config sync group
      • .output.nginxone.url the NGINX One Console URL
      • .output.nginxone.namespace the NGINX One Console namespace
      • .output.nginxone.token the authentication token
      • .output.nginxone.configsyncgroup the NGINX One Console config sync group name
      • .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
      • .output.nginxone.modules an optional array of NGINX module names (ie. 'ngx_http_app_protect_module', 'ngx_http_js_module','ngx_stream_js_module')
      • .output.nginxone.certificates an optional array of TLS certificates/keys/chains to be published
        • .output.nginxone.certificates[].type the item type ('certificate', 'key', 'chain')
        • .output.nginxone.certificates[].name the certificate/key/chain name with no path/extension (ie. 'test-application')
        • .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
  • .declaration describes the NGINX configuration to be created
    • .declaration.http[] NGINX HTTP definitions
    • .declaration.layer4[] NGINX TCP/UDP definitions
    • .declaration.resolvers[] DNS resolvers definitions

API endpoints

  • POST /v5.2/config/ - Publish a new declaration
  • PATCH /v5.2/config/{config_uid} - Update an existing declaration
    • Per-HTTP server CRUD
    • Per-HTTP upstream CRUD
    • Per-Stream server CRUD
    • Per-Stream upstream CRUD
    • Per-NGINX App Protect WAF policy CRUD
  • GET /v5.2/config/{config_uid} - Retrieve an existing declaration
  • DELETE /v5.2/config/{config_uid} - Delete an existing declaration