diff --git a/content/includes/nginx-one/staged-config-overview.md b/content/includes/nginx-one/staged-config-overview.md new file mode 100644 index 000000000..759503087 --- /dev/null +++ b/content/includes/nginx-one/staged-config-overview.md @@ -0,0 +1,18 @@ +--- +docs: DOCS-000 +files: + - content/nginx-one/how-to/staged-configs/add-staged-config.md + - content/nginx-one/how-to/staged-configs/edit-staged-config.md +--- + +It takes time to set up NGINX configuration files can take time. Staged Configurations can help. They work like a draft that uses the features of NGINX One Console. The Staged Configuration does not have to be valid. +You can save your work before you push a configuration to an instance of NGINX. + +With Staged Configurations, you can use these features of NGINX One Console: + +- Automatic syntax checking +- Contextual documentation +- Dynamic analysis of your work in progress +- Suggestions from our AI assistant + +Once you've finished your work and have pushed the changes to an Instance or a Config Sync Group, you can next delete that Staged Configuration. diff --git a/content/nginx-one/changelog.md b/content/nginx-one/changelog.md index 6ddc2f585..20c63c2cb 100644 --- a/content/nginx-one/changelog.md +++ b/content/nginx-one/changelog.md @@ -30,6 +30,16 @@ h2 { Stay up-to-date with what's new and improved in the F5 NGINX One Console. +## March 11, 2025 + +### Set up Staged Configurations + +It allows you to: + +- Save Your Progress: Staged Configurations allow you to work on configuration changes without the need for a fully functional setup. You can create these drafts from scratch, an existing Instance, another Staged Configuration, or a Config Sync Group. +- No Immediate Validation Required: You don't have to immediately address syntax or configuration issues. Your Staged Configuration doesn't have to be valid until you publish it to an Instance or a Config Sync Group. +- Manage through our API: You can easily manage your Staged Configurations programmatically through our [API]({{< ref "/nginx-one/api/api-reference-guide/#tag/StagedConfigs" >}}). + ## January 20, 2025 ### Manage certificates with Config Sync Groups diff --git a/content/nginx-one/glossary.md b/content/nginx-one/glossary.md index 87efdc680..f0d220bb0 100644 --- a/content/nginx-one/glossary.md +++ b/content/nginx-one/glossary.md @@ -18,6 +18,7 @@ This glossary defines terms used in the F5 NGINX One Console and F5 Distributed | **Data Plane** | The data plane is the part of a network architecture that carries user traffic. It handles tasks like forwarding data packets between devices and managing network communication. In the context of NGINX, the data plane is responsible for tasks such as load balancing, caching, and serving web content. | | **Instance** | An instance is an individual system with NGINX installed. You can group the instances of your choice in a Config Sync Group. When you add an instance to NGINX One, you need to use a data plane key. | | **Namespace** | In F5 Distributed Cloud, a namespace groups a tenant’s configuration objects, similar to administrative domains. Every object in a namespace must have a unique name, and each namespace must be unique to its tenant. This setup ensures isolation, preventing cross-referencing of objects between namespaces. | +| **Staged Configurations** | Also known as **Staged Configs**. Allows you to save "work in progress." You can create it from scratch, an Instance, another Staged Config, or a Config Sync Group. It does _not_ have to be a working configuration until you publish it to an instance or a Config Sync Group. You can even manage your **Staged Configurations** through our [API]({{< ref "/nginx-one/api/api-reference-guide/#tag/StagedConfigs" >}}). | | **Tenant** | A tenant in F5 Distributed Cloud is an entity that owns a specific set of configuration and infrastructure. It is fundamental for isolation, meaning a tenant cannot access objects or infrastructure of other tenants. Tenants can be either individual or enterprise, with the latter allowing multiple users with role-based access control (RBAC). | {{}} diff --git a/content/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md b/content/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md index 9d0964c88..2a4b308f7 100644 --- a/content/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md +++ b/content/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md @@ -1,13 +1,28 @@ --- -docs: null +# We use sentence case and present imperative tone title: View and edit NGINX configurations -toc: true +# Weights are assigned in increments of 100: determines sorting order weight: 300 -type: -- how-to +# Creates a table of contents and sidebar, useful for large documents +toc: true +# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this +type: tutorial +# Intended for internal catalogue and search, case sensitive: +product: NGINX One --- + + +## Overview + +This guide explains how to add a **Instances** to your NGINX One Console. -Once you've registered your NGINX instances with the F5 NGINX One Console, you can view and edit their NGINX configurations on the **Instances** details page. +## Before you start + +Before you add **Instances** to NGINX One Console, ensure: + +- You have an NGINX One Console account with staged configuration permissions.``` + +Once you've registered your NGINX Instances with the F5 NGINX One Console, you can view and edit their NGINX configurations on the **Instances** details page. To view and edit an NGINX configuration, follow these steps: @@ -19,6 +34,8 @@ To view and edit an NGINX configuration, follow these steps: 6. When you are satisfied with the changes, select **Next**. 7. Compare and verify your changes before selecting **Save and Publish** to publish the edited configuration. +Alternatively, you can select **Save Changes As**. In the window that appears, you can set up this instance as a [**Staged Configuration**]({{< relref "/nginx-one/how-to/staged-configs/_index.md" >}}). + ## See also - [Manage Config Sync Groups]({{< relref "/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md" >}}) diff --git a/content/nginx-one/how-to/staged-configs/_index.md b/content/nginx-one/how-to/staged-configs/_index.md new file mode 100644 index 000000000..51e07d1aa --- /dev/null +++ b/content/nginx-one/how-to/staged-configs/_index.md @@ -0,0 +1,6 @@ +--- +description: +title: Staged Configurations +weight: 800 +url: /nginx-one/how-to/staged-configs +--- diff --git a/content/nginx-one/how-to/staged-configs/add-staged-config.md b/content/nginx-one/how-to/staged-configs/add-staged-config.md new file mode 100644 index 000000000..129cde78b --- /dev/null +++ b/content/nginx-one/how-to/staged-configs/add-staged-config.md @@ -0,0 +1,88 @@ +--- +# We use sentence case and present imperative tone +title: Add a Staged Configuration +# Weights are assigned in increments of 100: determines sorting order +weight: 100 +# Creates a table of contents and sidebar, useful for large documents +toc: true +# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this +type: tutorial +# Intended for internal catalogue and search, case sensitive: +# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit +product: +--- + +## Overview + +This guide explains how to add a Staged Configuration to your NGINX One Console. + +{{< include "nginx-one/staged-config-overview.md" >}} + +## Before you start + +Before you add a Staged Configuration to NGINX One Console, ensure: + +- You have an NGINX One Console account with staged configuration permissions. + +## Add a Staged Configuration + +You can add a Staged Configuration from: + +- Empty files +- An existing Instance +- An existing Config Sync Group +- An existing Staged Configuration + +To start the process from NGINX One Console, select **Manage > Staged Configruations**. Select **Add Staged Configuration**. + +The following sections start from the **Add Staged Configuration** window that appears. + +### Start from an empty file + +To start a new Staged Configuration: + +1. Select **New Configuration**. +1. Enter a name. +1. Select **Next**. + + You will see a new Staged Configuration with the default NGINX configuration file, `/etc/nginx/nginx.conf`, in edit mode. +1. Type or paste content for `/etc/nginx/nginx.conf`. +1. Select **Add File** to add the configuration, certificate, or other file(s) of your choice. +1. When you're done, select **Save**. + +### Start from an existing Instance + +To start from an existing Instance: + +1. Select **Existing Source**. +1. Enter a name for your new Staged Configuration. +1. Select **Instance**. +1. In the Choose Instance menu that appears, select an existing Instance. +1. Select **Next**. + +NGINX One Console imports the configuration from the existing Instance. You can now edit the configuration. When you're ready to stop and save your work, select Save. + +### Start from an existing Config Sync Group + +To start from an existing Config Sync Group: + +1. Select **Existing Source**. +1. Select **Config Sync Group**. +1. In the Choose Config Sync Group menu that appears, select an existing Config Sync Group. +1. Enter a name for your new Staged Configuration. +1. Select **Next**. + +NGINX One Console imports the configuration from the existing Config Sync Group. You can now edit the configuration. When you're ready to stop and save your work, select Save. + +### Start from an existing Staged Config + +To start from an existing Staged Config: + +1. Select **Existing Source**. +1. Select **Staged Configuration**. +1. In the Choose Staged Configuratiog menu that appears, select an existing Staged Configuration. +1. Enter a name for your new Staged Configuration. +1. Select **Next**. + +NGINX One Console imports the configuration from the existing Staged Configuration. You can now edit the configuration. When you're ready to stop and save your work, select Save. + diff --git a/content/nginx-one/how-to/staged-configs/api-staged-config.md b/content/nginx-one/how-to/staged-configs/api-staged-config.md new file mode 100644 index 000000000..ab74dd36c --- /dev/null +++ b/content/nginx-one/how-to/staged-configs/api-staged-config.md @@ -0,0 +1,20 @@ +--- +# We use sentence case and present imperative tone +title: Use the API to manage your Staged Configurations +# Weights are assigned in increments of 100: determines sorting order +weight: 300 +# Creates a table of contents and sidebar, useful for large documents +toc: true +# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this +type: tutorial +# Intended for internal catalogue and search, case sensitive: +product: NGINX One +--- + +You can use F5 NGINX One Console API to manage your Staged Configurations. With our API, you can: + +- [Create an NGINX Staged Configuration]({{< relref "/nginx-one/api/api-reference-guide/#operation/createStagedConfig" >}}) + - The details allow you to add existing configuration files. +- [Get a list of existing Staged Configruations]({{< relref "/nginx-one/api/api-reference-guide/#operation/listStagedConfigs" >}}) + - Be sure to record the `object_id` of your target Staged Configuration for your analysis report. +- [Get an analysis report for an existing Staged Configuration]({{< relref "/nginx-one/api/api-reference-guide/#operation/getStagedConfigReport" >}}) diff --git a/content/nginx-one/how-to/staged-configs/edit-staged-config.md b/content/nginx-one/how-to/staged-configs/edit-staged-config.md new file mode 100644 index 000000000..8f101a0fd --- /dev/null +++ b/content/nginx-one/how-to/staged-configs/edit-staged-config.md @@ -0,0 +1,38 @@ +--- +# We use sentence case and present imperative tone +title: View and edit a Staged Configuration +# Weights are assigned in increments of 100: determines sorting order +weight: 200 +# Creates a table of contents and sidebar, useful for large documents +toc: true +# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this +type: tutorial +# Intended for internal catalogue and search, case sensitive: +product: NGINX One +--- + +## Overview + +This guide explains how to edit an existing Staged Configuration in your NGINX One Console. + +{{< include "nginx-one/staged-config-overview.md" >}} + +## Before you start + +Before you edit a Staged Configuration, ensure: + +- You have an NGINX One Console account with staged configuration permissions.``` + +## View and edit a Staged Configuration + + +Once you've registered your NGINX Staged Configs with the F5 NGINX One Console, you can view and edit their NGINX configurations on the **Staged Configurations** details page. + +To view and edit an NGINX configuration, follow these steps: + +1. On the left menu, select **Staged Configurations**. +1. Select the staged configuration you want to view or modify. +1. Select **Edit** to make changes to the current configuration. +1. Make your changes to the configuration files. The configuration analyzer will let you know if there are any errors. +1. When you are satisfied with the changes, select **Next**. +1. Compare and verify your changes before selecting **Save** to publish the edited Staged configuration. diff --git a/go.mod b/go.mod index 573590eee..20d014a86 100644 --- a/go.mod +++ b/go.mod @@ -2,4 +2,4 @@ module github.com/nginxinc/docs go 1.19 -require github.com/nginxinc/nginx-hugo-theme v0.42.1 // indirect \ No newline at end of file +require github.com/nginxinc/nginx-hugo-theme v0.42.1 // indirect diff --git a/static/nginx-one/api/one.json b/static/nginx-one/api/one.json index ebe0aa702..500ad58aa 100644 --- a/static/nginx-one/api/one.json +++ b/static/nginx-one/api/one.json @@ -38,7 +38,7 @@ }, { "name": "Certificates", - "description": "The `Certificates` object in NGINX One Console represents an SSL certificate, covering both managed and unmanaged types. \nYou can view essential details like issuer, expiration status, and the instances or config sync groups where each certificate is deployed.\n", + "description": "The `Certificates` object in the NGINX One console represents an SSL certificate, covering both managed and unmanaged types. \nYou can view essential details like issuer, expiration status, and the instances or config sync groups where each certificate is deployed.\n", "x-displayName": "Certificates" }, { @@ -48,12 +48,15 @@ }, { "name": "Events", - "description": "Get a list of system events in NGINX One Console.\n", + "description": "Get a list of system events in the NGINX One console.\n", "x-displayName": "Events" }, + { + "name": "Staged Configs", + "x-displayName": "Staged Configs" + }, { "name": "Metrics", - "description": "Get system metrics for your NGINX data plane instances. These metrics are collected by the NGINX Agent and reported to NGINX One.\n", "x-displayName": "Metrics" }, { @@ -616,8 +619,23 @@ ], "summary": "Delete an SSL certificate", "operationId": "deleteCertificate", - "description": "Deletes a managed SSL certificate from NGINX One Console. This operation is disabled for unmanaged certificates, as they get cleaned up automatically when they are not used in any NGINX configuration.", + "description": "* Deletes a managed SSL certificate from the NGINX One console. This operation is disabled for unmanaged certificates, as they get cleaned up automatically when they are not used in any NGINX configuration. \n* An optional flag `deleteFromDataPlanes` when set to true, can be used to remove the certificate from data plane instances to where it was deployed.\n * Deleting from data planes triggers publications on either instances or Config Sync Groups. After the managed cert object is deleted from NGINX One Console, a `PublicationBulkResponse` is returned along with status code 202, indicating whether an error occurred while issuing a publication to a data plane target.\n * If this cert is not associated with any data plane, status code 204 is returned when `deleteFromDataPlanes` set to true.\n", + "parameters": [ + { + "$ref": "#/components/parameters/DeleteFromDataPlanesParamFlag" + } + ], "responses": { + "202": { + "description": "Successfully deleted the SSL certificate. Handling deletion of certificate from data planes in the background.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PublicationBulkResponse" + } + } + } + }, "204": { "description": "Successfully deleted the SSL certificate." }, @@ -1127,7 +1145,7 @@ "Config Sync Groups" ], "summary": "Delete an NGINX config sync group", - "description": "Delete a NGINX config sync group from NGINX One Console. You can delete a config sync group, only if it contains no NGINX instances.\n", + "description": "Delete a NGINX config sync group from the NGINX One console. You can delete a config sync group, only if it contains no NGINX instances.\n", "operationId": "deleteConfigSyncGroup", "responses": { "204": { @@ -1702,7 +1720,7 @@ "Config Sync Groups" ], "summary": "Retrieves stored NGINX configurations for a NGINX config sync group", - "description": "Returns a list of all configurations for a NGINX config sync group. Only the last 5 are kept on NGINX One Console for a NGINX config sync group.", + "description": "Returns a list of all configurations for a NGINX config sync group. Only the last 5 are kept on the NGINX One Console for a NGINX config sync group.", "operationId": "listConfigSyncGroupConfigurations", "responses": { "200": { @@ -2811,7 +2829,7 @@ "Instances" ], "summary": "Retrieves the stored NGINX configurations for an instance", - "description": "Returns a list of all configurations for a NGINX instance. Only the last 5 are kept on NGINX One Console for a NGINX instance.", + "description": "Returns a list of all configurations for a NGINX instance. Only the last 5 are kept on the NGINX One Console for a NGINX instance.", "operationId": "listInstanceConfigurations", "responses": { "200": { @@ -3137,47 +3155,101 @@ } } }, - "/monitor/metrics_query": { + "/staged-configs": { + "get": { + "x-feature-flag": "staged-configs", + "tags": [ + "Staged Configs" + ], + "summary": "List all staged configs", + "operationId": "listStagedConfigs", + "description": "Returns a list of all NGINX staged configs, providing details such as:\n * Name and object_id of staged config\n * Created and modified timestamps\n", + "parameters": [ + { + "$ref": "#/components/parameters/Paginated" + }, + { + "$ref": "#/components/parameters/Limit" + }, + { + "$ref": "#/components/parameters/Offset" + }, + { + "$ref": "#/components/parameters/FilterFieldStagedConfigs" + }, + { + "$ref": "#/components/parameters/FilterOperands" + }, + { + "$ref": "#/components/parameters/FilterValues" + }, + { + "$ref": "#/components/parameters/SortDirection" + }, + { + "$ref": "#/components/parameters/SortNameStagedConfigs" + } + ], + "responses": { + "200": { + "description": "Successfully retrieved the list of NGINX staged configs.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StagedConfigListResponse" + } + } + } + }, + "401": { + "description": "Access denied.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "An unexpected error occurred on the server. Please try the request again later.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, "post": { + "x-feature-flag": "staged-configs", + "x-nginx-one-action": "create", + "x-nginx-one-entity": "NGINX staged configs", "tags": [ - "Metrics" + "Staged Configs" ], - "summary": "Retrieve system metrics for instances", - "operationId": "queryMetricsInput", - "description": "Returns (up to 10,000) system metrics for NGINX instances based on query parameters.\n\nYou can filter metrics by name and timestamp, aggregate metrics over a configurable period of time, and group metrics by dimension.\n", + "summary": "Create an NGINX staged config", + "operationId": "createStagedConfig", + "description": "Create NGINX staged config with a unique ID to identify it within the tenant namespace.\n", "requestBody": { + "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/MetricQueryRequest" - }, - "example": { - "start_time": "now-1h", - "end_time": "now", - "resolution": "5m", - "metrics": [ - { - "name": "nginx.http.requests", - "aggregate": "sum" - } - ], - "order_by": [ - { - "direction": "asc", - "dimension": "instance_object_id" - } - ] + "$ref": "#/components/schemas/StagedConfigCreateRequest" } } } }, "responses": { "200": { - "description": "Successfully retrieved system metrics.", + "description": "Successfully created NGINX staged configs", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/MetricQueryResultEx" + "$ref": "#/components/schemas/StagedConfigCreateResponse" } } } @@ -3192,8 +3264,8 @@ } } }, - "404": { - "description": "The requested metric resource was not found. Check that the resource name provided is correct and corresponds to an existing resource.", + "401": { + "description": "Access denied", "content": { "application/json": { "schema": { @@ -3215,49 +3287,74 @@ } } }, - "/monitor/metrics_query_topx": { - "post": { + "/staged-configs/{stagedConfigObjectID}": { + "delete": { + "x-feature-flag": "staged-configs", + "x-nginx-one-action": "delete", + "x-nginx-one-entity": "NGINX staged config", "tags": [ - "Metrics" + "Staged Configs" ], - "summary": "Retrieve system metrics for instances with series limit", - "operationId": "queryMetricsInputTopX", - "description": "Returns (up to 10,000) system metrics for NGINX instances with series limit based on query parameters.\n\nYou can filter metrics by name and timestamp, aggregate metrics over a configurable period of time, and group metrics by dimension.\n", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/MetricTopXQueryRequest" - }, - "example": { - "start_time": "now-1h", - "end_time": "now", - "resolution": "1m", - "metrics": [ - { - "aggregate": "sum", - "name": "nginx.http.requests" - } - ], - "series_limit": 1, - "group_series_by": "instance_object_id" + "summary": "Delete an NGINX staged config", + "description": "Delete a NGINX staged config from the NGINX One console.\n", + "operationId": "deleteStagedConfig", + "responses": { + "204": { + "description": "Successfully deleted the NGINX staged configs" + }, + "401": { + "description": "Access denied", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "The NGINX staged config with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "An unexpected error occurred on the server. Please try the request again later.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } } } } - }, + } + }, + "get": { + "x-feature-flag": "staged-configs", + "tags": [ + "Staged Configs" + ], + "summary": "Retrieve an NGINX staged config meta", + "description": "Retrieve the meta details for an NGINX staged config.\n", + "operationId": "getStagedConfigMeta", "responses": { "200": { - "description": "Successfully retrieved system metrics.", + "description": "Successfully retrieved the details of the NGINX staged config meta.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/MetricQueryResultEx" + "$ref": "#/components/schemas/StagedConfigMeta" } } } }, - "400": { - "description": "Request cannot be processed due to invalid input or parameters. Verify the request format and provided data.", + "401": { + "description": "Access denied", "content": { "application/json": { "schema": { @@ -3267,7 +3364,7 @@ } }, "404": { - "description": "The requested metric resource was not found. Check that the resource name provided is correct and corresponds to an existing resource.", + "description": "The NGINX staged config with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", "content": { "application/json": { "schema": { @@ -3287,61 +3384,478 @@ } } } - } + }, + "parameters": [ + { + "$ref": "#/components/parameters/StagedConfigParamObjectID" + } + ] }, - "/settings/instance-cleanup": { + "/staged-configs/{stagedConfigObjectID}/config": { "get": { "tags": [ - "Settings" + "Staged Configs" ], - "summary": "Retrieve settings", - "description": "Retrieves settings for NGINX Instance cleanup\n", - "operationId": "getSettingInstanceCleanup", + "x-feature-flag": "staged-configs", + "summary": "Retrieve an NGINX staged config", + "description": "Retrieve the details for an NGINX staged config.\n", + "operationId": "getStagedConfig", "responses": { "200": { - "description": "Successfully retrieved the setting for NGINX Instance cleanup.", + "description": "Successfully retrieved the details of the NGINX staged config.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SettingsInstanceCleanup" + "$ref": "#/components/schemas/StagedConfigResponse" } } } }, - "400": { - "$ref": "#/components/responses/InvalidRequest" + "401": { + "description": "Access denied", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "The NGINX staged config with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "500": { - "$ref": "#/components/responses/InternalServerErr" + "description": "An unexpected error occurred on the server. Please try the request again later.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } } } }, - "put": { - "x-nginx-one-action": "update", - "x-nginx-one-entity": "NGINX Instance Cleanup Setting", + "parameters": [ + { + "$ref": "#/components/parameters/StagedConfigParamObjectID" + } + ], + "patch": { "tags": [ - "Settings" + "Staged Configs" ], - "summary": "Update settings", - "description": "Update settings for NGINX Instance cleanup\n", - "operationId": "updateSettingInstanceCleanup", + "x-feature-flag": "staged-configs", + "x-nginx-one-action": "update", + "x-nginx-one-entity": "NGINX staged config", + "summary": "Apply partial updates to staged config", + "description": "Applies the specified partial updates to an existing NGINX staged config Details:\n * This endpoint accepts additive updates to `NginxConfig`. Base `nginx.conf` file must always be provided along with additives.\n * To delete files, omit the `file.contents` field.\n * `config_version` is used to ensure the requested patch is applied against the same version.\n", + "operationId": "patchStagedConfig", "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SettingsInstanceCleanup" + "$ref": "#/components/schemas/StagedConfigChangeRequest" } } } }, "responses": { "200": { - "description": "Successfully updated settings for NGINX Instance cleanup.", + "description": "Successfully stored the NGINX staged configuration.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SettingsInstanceCleanup" + "$ref": "#/components/schemas/StagedConfigMeta" + } + } + } + }, + "400": { + "description": "Request cannot be processed due to invalid input or parameters. Verify the request format and provided data.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Access denied", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "The NGINX staged config with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "NGINX config version mismatch. Provided config_version does not match recent config_version for the NGINX staged config, possible conflict.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "An unexpected error occurred on the server. Please try the request again later.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "put": { + "tags": [ + "Staged Configs" + ], + "x-feature-flag": "staged-configs", + "x-nginx-one-action": "create", + "x-nginx-one-entity": "NGINX staged config", + "summary": "Replace existing state", + "description": "Completely replaces existing staged config with payload of new request.\n", + "operationId": "replaceStagedConfig", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StagedConfigUpdateRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Successfully updated the NGINX configuration.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StagedConfigMeta" + } + } + } + }, + "400": { + "description": "Request cannot be processed due to invalid input or parameters. Verify the request format and provided data.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Access denied", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "The NGINX staged config with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "An unexpected error occurred on the server. Please try the request again later.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/staged-configs/{stagedConfigObjectID}/config-report": { + "get": { + "tags": [ + "Staged Configs" + ], + "x-feature-flag": "staged-configs", + "summary": "Retrieve an analysis report for the NGINX staged config", + "description": "Analyzes the NGINX staged config and returns a detailed report.\nThe report includes insights, identified issues, and recommendations for optimizing and troubleshooting.\n", + "operationId": "getStagedConfigReport", + "responses": { + "200": { + "description": "Successfully retrieved the NGINX configuration analysis for the specified staged config.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NginxConfigReports" + } + } + } + }, + "204": { + "description": "The requested staged config exists, but analysis of the NGINX configuration is not yet completed. Please retry the request at a later time to retrieve the report." + }, + "404": { + "description": "The NGINX staged config with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "An unexpected error occurred on the server. Please try the request again later.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "parameters": [ + { + "$ref": "#/components/parameters/StagedConfigParamObjectID" + } + ], + "patch": { + "x-feature-flag": "staged-configs", + "x-nginx-one-action": "analyze", + "x-nginx-one-entity": "NGINX staged configuration", + "tags": [ + "Staged Configs" + ], + "summary": "Generate an analysis report for the modified NGINX staged config", + "description": "Analyzes the provided partial updates merging with an existing configuration of an NGINX config sync group. Generates a report detailing potential issues along with optimization suggestions. \nThis analysis accounts for additive updates made to NGINX configuration. To delete files, omit the `file.contents` field. \nNote that this operation is for analysis purposes only and does not apply any changes to the configuration. \nThe report is not stored and is provided only in the API response.\nTo publish the configuration, use the `PATCH /staged-configs/{stagedConfigObjectID}/config` endpoint.\n", + "operationId": "analyzeStagedConfigPatch", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NginxConfigRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Successfully analyzed the provided NGINX configuration", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NginxConfigReports" + } + } + } + }, + "400": { + "description": "Request cannot be processed due to invalid input or parameters. Verify the request format and provided data.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Access denied", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "The NGINX staged config with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "An unexpected error occurred on the server. Please try the request again later.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/monitor/metrics_query_topx": { + "post": { + "tags": [ + "Metrics" + ], + "summary": "Retrieve system metrics for instances with series limit", + "operationId": "queryMetricsInputTopX", + "description": "Returns (up to 10,000) system metrics for NGINX instances with series limit based on query parameters.\n\nYou can filter metrics by name and timestamp, aggregate metrics over a configurable period of time, and group metrics by dimension.\n", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MetricTopXQueryRequest" + }, + "example": { + "start_time": "now-1h", + "end_time": "now", + "resolution": "1m", + "metrics": [ + { + "aggregate": "sum", + "name": "nginx.http.requests" + } + ], + "series_limit": 1, + "group_series_by": "instance_object_id" + } + } + } + }, + "responses": { + "200": { + "description": "Successfully retrieved system metrics.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MetricQueryResultEx" + } + } + } + }, + "400": { + "description": "Request cannot be processed due to invalid input or parameters. Verify the request format and provided data.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "The requested metric resource was not found. Check that the resource name provided is correct and corresponds to an existing resource.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "An unexpected error occurred on the server. Please try the request again later.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/settings/instance-cleanup": { + "get": { + "tags": [ + "Settings" + ], + "summary": "Retrieve settings", + "description": "Retrieves settings for NGINX Instance cleanup\n", + "operationId": "getSettingInstanceCleanup", + "responses": { + "200": { + "description": "Successfully retrieved the setting for NGINX Instance cleanup.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SettingsInstanceCleanup" + } + } + } + }, + "400": { + "$ref": "#/components/responses/InvalidRequest" + }, + "500": { + "$ref": "#/components/responses/InternalServerErr" + } + } + }, + "put": { + "x-nginx-one-action": "update", + "x-nginx-one-entity": "NGINX Instance Cleanup Setting", + "tags": [ + "Settings" + ], + "summary": "Update settings", + "description": "Update settings for NGINX Instance cleanup\n", + "operationId": "updateSettingInstanceCleanup", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SettingsInstanceCleanup" + } + } + } + }, + "responses": { + "200": { + "description": "Successfully updated settings for NGINX Instance cleanup.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SettingsInstanceCleanup" } } } @@ -3485,6 +3999,14 @@ "description": "A globally unique identifier for the certificate.\n", "required": true }, + "DeleteFromDataPlanesParamFlag": { + "name": "deleteFromDataPlanes", + "in": "query", + "schema": { + "type": "boolean" + }, + "description": "Flag indicating whether the certificate should be deleted from its associated data planes.\n" + }, "FilterFieldCertificateDeployments": { "name": "filter_fields", "in": "query", @@ -3689,6 +4211,43 @@ }, "description": "A globally unique identifier for the NGINX instance configuration.\n", "required": true + }, + "FilterFieldStagedConfigs": { + "name": "filter_fields", + "in": "query", + "description": "An array of strings indicating which fields to filter by (for example, `name`). This parameter works in conjunction with `filter_values` and `filter_ops`.\n", + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/FilterStagedConfigs" + } + } + }, + "SortNameStagedConfigs": { + "name": "sort_staged_configs", + "in": "query", + "description": "Sort staged configs by enumerate value(s). Ordinal position determines primary, secondary, etc.\n", + "schema": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "name" + ], + "x-enum-varnames": [ + "sort_name_staged_config_name" + ] + } + } + }, + "StagedConfigParamObjectID": { + "name": "stagedConfigObjectID", + "in": "path", + "schema": { + "$ref": "#/components/schemas/StagedConfigObjectID" + }, + "description": "A globally unique identifier for the NGINX staged config.\n", + "required": true } }, "schemas": { @@ -3731,7 +4290,7 @@ "properties": { "total": { "type": "integer", - "description": "The absolute total number of the resource in NGINX One Console.\n" + "description": "The absolute total number of the resource in the NGINX One Console.\n" }, "count": { "type": "integer", @@ -4078,7 +4637,7 @@ }, "CertificateType": { "type": "string", - "description": "Certificate type:\n * `ca_bundle` - This certificate object is a CA bundle.\n * `cert_key` - This certificate object is consisted of public certificates and key.\n * `unmanaged` - This certificate is not managed by NGINX One Console and its type is unmanaged.\n", + "description": "Certificate type:\n * `ca_bundle` - This certificate object is a CA bundle.\n * `cert_key` - This certificate object is consisted of public certificates and key.\n * `unmanaged` - This certificate is not managed by NGINX One console and its type is unmanaged.\n", "enum": [ "ca_bundle", "cert_key", @@ -4511,6 +5070,13 @@ "created_at": "2023-10-01T00:00:00Z" } }, + "PublicationBulkResponse": { + "description": "The publication bulk operation outcome.\n", + "type": "array", + "items": { + "$ref": "#/components/schemas/BulkRequestObjectStatus" + } + }, "CertificateUpdateContent": { "type": "object", "description": "Defines the PEM-formatted certificate content which includes the certificates and corresponding private key, all encoded in base64.\n", @@ -5535,7 +6101,7 @@ }, "NginxConfigPayloads": { "type": "array", - "description": "An array of payloads that track the file paths of each SSL certificates and key, indicating where to deploy\nthem onto the data plane instance.\n* If the `type` is `managed_certificate` or `managed_key`, you need to specify an `object_id`.\n * The `object_id` must represent a managed certificate object, or a `400 Bad Request` is returned. \n * The `contents` field is optional and is ignored if included.\n* NGINX One Console manages deployed file paths only for managed certificates and keys. If you don't want \nthem to be managed by NGINX One Console, `inline_content` and `inline_secret` can be used for certificates or \nkeys, respectively. When you retrieve certificate deployment details, only the file paths of managed \ncertificates and keys will be shown.\n* If you use `inline_content` and `inline_secret` in your NGINX configuration, NGINX One Console \nwill detect them. When they are used as SSL directives of the NGINX configuration \nfor certificates and keys, the certificates will be listed as `unmanaged_certificate` in the certificate \ndeployment details.\n", + "description": "An array of payloads that track the file paths of each SSL certificates and key, indicating where to deploy\nthem onto the data plane instance.\n* If the `type` is `managed_certificate` or `managed_key`, you need to specify an `object_id`.\n * The `object_id` must represent a managed certificate object, or a `400 Bad Request` is returned. \n * The `contents` field is optional and is ignored if included.\n* The NGINX One Console manages deployed file paths only for managed certificates and keys. If you don't want \nthem to be managed by NGINX One Console, `inline_content` and `inline_secret` can be used for certificates or \nkeys, respectively. When you retrieve certificate deployment details, only the file paths of managed \ncertificates and keys will be shown.\n* If you use `inline_content` and `inline_secret` in your NGINX configuration, the NGINX One Console \nwill detect them. When they are used as SSL directives of the NGINX configuration \nfor certificates and keys, the certificates will be listed as `unmanaged_certificate` in the certificate \ndeployment details.\n", "items": { "$ref": "#/components/schemas/NginxConfigPayload" }, @@ -6221,11 +6787,13 @@ "description": "type of event, indication for affected object type.", "enum": [ "instance_cleanup", - "certificates" + "certificates", + "publications" ], "x-enum-varnames": [ "event_type_instance_cleanup", - "event_type_certificates" + "event_type_certificates", + "event_type_publications" ] }, "object_id": { @@ -6684,19 +7252,287 @@ "statuses": { "$ref": "#/components/schemas/StatusSummary" }, - "cves": { - "description": "An array summarizing identified Common Vulnerabilities and Exposures (CVEs) across the NGINX data plane.", - "type": "array", - "items": { - "$ref": "#/components/schemas/CveSummary" - } + "cves": { + "description": "An array summarizing identified Common Vulnerabilities and Exposures (CVEs) across the NGINX data plane.", + "type": "array", + "items": { + "$ref": "#/components/schemas/CveSummary" + } + }, + "recommendations": { + "description": "An array summarizing the suggestions from the configuration analysis report.", + "type": "array", + "items": { + "$ref": "#/components/schemas/IssueSummary" + } + } + } + }, + "FilterStagedConfigs": { + "type": "string", + "description": "Keywords for staged configs filters.\n", + "enum": [ + "name", + "object_id" + ], + "x-enum-varnames": [ + "filter_name_staged_config_name", + "filter_name_staged_config_object_id" + ] + }, + "StagedConfigObjectID": { + "description": "A globally unique identifier for the NGINX staged config.", + "type": "string", + "format": "object_id", + "pattern": "^sc_.*", + "x-go-type": "objects.ID", + "x-go-type-import": { + "name": "objects", + "path": "gitlab.com/f5/nginx/one/saas/control-plane/pkg/collections/objects" + } + }, + "StagedConfigCertificateSummary": { + "type": "object", + "description": "Provides a summary of the current status of certificates used in NGINX configurations. It includes the total number of certificates, as well as the counts of expired certificates, those nearing expiration, valid certificates, certificates that are not found, and those that are not ready for use.", + "required": [ + "total", + "expired", + "expiring", + "valid", + "not_found", + "not_ready" + ], + "properties": { + "total": { + "description": "Total count of certificates used as `payloads` in Nginx config.", + "type": "integer" + }, + "expired": { + "description": "The number of certificates that have expired and are no longer valid.", + "type": "integer" + }, + "expiring": { + "description": "The number of certificates due to expire in the next 30 days.", + "type": "integer" + }, + "valid": { + "description": "The number of certificates that are valid and in good standing.", + "type": "integer" + }, + "not_found": { + "description": "The number of certificates that are not found on NGINX One Console.", + "type": "integer" + }, + "not_ready": { + "description": "The number of certificates that are not ready to be used.", + "type": "integer" + } + } + }, + "StagedConfigMeta": { + "type": "object", + "description": "Summary information of the NGINX staged config.", + "required": [ + "object_id", + "name", + "created_at", + "modified_at" + ], + "properties": { + "object_id": { + "$ref": "#/components/schemas/StagedConfigObjectID" + }, + "name": { + "description": "Name of the NGINX staged config", + "type": "string" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "The date and time when the NGINX configuration object was created for the instance." + }, + "modified_at": { + "type": "string", + "format": "date-time", + "description": "The date and time when the NGINX configuration object was last modified for the instance." + }, + "cert_summary": { + "$ref": "#/components/schemas/StagedConfigCertificateSummary" + } + } + }, + "StagedConfigListResponse": { + "allOf": [ + { + "$ref": "#/components/schemas/PaginationResponse" + }, + { + "type": "object", + "description": "List of NGINX staged configs.", + "required": [ + "items" + ], + "properties": { + "items": { + "description": "An array of Staged Config objects.", + "type": "array", + "items": { + "$ref": "#/components/schemas/StagedConfigMeta" + } + } + } + } + ], + "example": { + "total": 10, + "count": 1, + "start_index": 1, + "items_per_page": 100, + "items": [ + { + "object_id": "sc_Tet21AeYTHCj7taOwVfzyw", + "name": "my-nginx-staged-config", + "created_at": "2023-08-10T16:59:15Z", + "modified_at": "2023-08-10T16:59:15Z" + } + ] + } + }, + "StagedConfigName": { + "type": "string", + "description": "A name to identify the NGINX staged config.", + "minLength": 1, + "maxLength": 256, + "pattern": "^[^\\s]+$" + }, + "StagedConfigCreateRequest": { + "description": "Body to create a NGINX staged config. A staged config can be empty; config payload is optional.", + "required": [ + "name" + ], + "properties": { + "name": { + "$ref": "#/components/schemas/StagedConfigName" + }, + "config": { + "$ref": "#/components/schemas/NginxConfigRequest" + } + }, + "example": { + "name": "my-nginx-staged-config", + "config": { + "aux": [], + "conf_path": "/etc/nginx/nginx.conf", + "config_version": "c039fbbd5d7f73d894390fb446bd3690da099ed8862b2527299bc2ba", + "configs": [ + { + "files": [ + { + "contents": "string", + "name": "default.conf" + } + ], + "name": "/etc/nginx/conf.d" + } + ] + } + } + }, + "StagedConfigCreateResponse": { + "description": "Response to a create NGINX staged config request.", + "required": [ + "object_id", + "name" + ], + "properties": { + "object_id": { + "$ref": "#/components/schemas/StagedConfigObjectID" + }, + "name": { + "description": "Name of the NGINX staged config.", + "type": "string" + } + }, + "example": { + "name": "my-nginx-staged-config", + "object_id": "sc_Tet21AeYTHCj7taOwVfzyw" + } + }, + "StagedConfigResponse": { + "description": "Get an NGINX staged config.", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the NGINX staged config." + }, + "config": { + "$ref": "#/components/schemas/NginxConfig" + } + } + }, + "StagedConfigUpdateRequest": { + "description": "Body to update a NGINX staged config name and config contents.", + "required": [ + "name", + "config" + ], + "properties": { + "name": { + "$ref": "#/components/schemas/StagedConfigName" + }, + "config": { + "$ref": "#/components/schemas/NginxConfigRequest" + } + }, + "example": { + "name": "my-nginx-staged-config", + "config": { + "aux": [], + "conf_path": "/etc/nginx/nginx.conf", + "config_version": "c039fbbd5d7f73d894390fb446bd3690da099ed8862b2527299bc2ba", + "configs": [ + { + "files": [ + { + "contents": "string", + "name": "default.conf" + } + ], + "name": "/etc/nginx/conf.d" + } + ] + } + } + }, + "StagedConfigChangeRequest": { + "description": "Update an NGINX staged config.", + "properties": { + "name": { + "$ref": "#/components/schemas/StagedConfigName" }, - "recommendations": { - "description": "An array summarizing the suggestions from the configuration analysis report.", - "type": "array", - "items": { - "$ref": "#/components/schemas/IssueSummary" - } + "config": { + "$ref": "#/components/schemas/NginxConfigRequest" + } + }, + "example": { + "config": { + "aux": [], + "conf_path": "/etc/nginx/nginx.conf", + "config_version": "c039fbbd5d7f73d894390fb446bd3690da099ed8862b2527299bc2ba", + "configs": [ + { + "files": [ + { + "contents": "string", + "name": "default.conf" + } + ], + "name": "/etc/nginx/conf.d" + } + ] } } }, @@ -7192,298 +8028,876 @@ "direction": { "$ref": "#/components/schemas/OrderDirection" }, - "dimension": { - "$ref": "#/components/schemas/MetricDimension" + "dimension": { + "$ref": "#/components/schemas/MetricDimension" + } + } + }, + "OrderSeriesBy": { + "type": "object", + "description": "Sort order of the metric series in your results.\n\nUsage:\n* Provide all required elements. \n * `direction`: The sorting direction either `desc` or `asc`.\n * `aggregate`: The aggregating function.\n", + "required": [ + "direction", + "aggregate" + ], + "properties": { + "direction": { + "$ref": "#/components/schemas/OrderDirection" + }, + "aggregate": { + "$ref": "#/components/schemas/MetricAggregation", + "default": "sum" + } + } + }, + "MetricName": { + "type": "string", + "description": "Metric names available for querying.\n", + "example": "nginx.http.requests", + "oneOf": [ + { + "$ref": "#/components/schemas/MetricSystemCpuTime" + }, + { + "$ref": "#/components/schemas/MetricSystemFilesystemUsage" + }, + { + "$ref": "#/components/schemas/MetricSystemMemoryUsage" + }, + { + "$ref": "#/components/schemas/MetricSystemCpuLogicalCount" + }, + { + "$ref": "#/components/schemas/MetricSystemNetworkIo" + }, + { + "$ref": "#/components/schemas/MetricNginxHttpRequests" + }, + { + "$ref": "#/components/schemas/MetricNginxHttpResponseStatus" + } + ] + }, + "MetricSystemCpuTime": { + "type": "string", + "description": "Total system CPU utilization for 'system' or 'user', percentage. A filter differentiator is needed for specific mode(s).\n\nReplacement for depreciated variant(s):\n * system.cpu.system\n * system.cpu.user\n\nAggregation(s) supported:\n * min\n * max\n * sum\n * avg\n * rate\n\nCatalog dimension filter differentiator:\n * mode (applicable filter values: 'system', 'user')\n\nCatalog dimension(s) supported:\n * instance_object_id\n * csg_object_id\n * system_id\n * parent_hostname\n * display_name\n * nginx_id\n", + "enum": [ + "system.cpu.time" + ] + }, + "MetricSystemFilesystemUsage": { + "type": "string", + "description": "System disk usage statistic, percentage. A filter differentiator is needed for specific state(s).\n\nReplacement for depreciated variant(s):\n * system.disk.in_use\n * system.disk.total\n * system.disk.used\n\nAggregation(s) supported:\n * min\n * max\n * sum\n * avg\n * rate\n\nCatalog dimension filter differentiator:\n * state (applicable filter values: 'used', 'free', 'in_use')\n\nCatalog dimension(s) supported:\n * instance_object_id\n * csg_object_id\n * system_id\n * parent_hostname\n * display_name\n * nginx_id\n * mount_point\n", + "enum": [ + "system.filesystem.usage" + ] + }, + "MetricSystemMemoryUsage": { + "type": "string", + "description": "Total available statistic about system memory usage, bytes. A filter differentiator is needed for specific state(s).\n\nReplacement for depreciated variant(s):\n * system.mem.pct_used\n * system.mem.total\n * system.mem.used\n\nAggregation(s) supported:\n * min\n * max\n * sum\n * avg\n * rate \n\nCatalog dimension filter differentiator:\n * state (applicable filter values: 'used', 'free', 'total', 'pct_used')\n\nCatalog dimension(s) supported:\n * instance_object_id\n * csg_object_id\n * system_id\n * parent_hostname\n * display_name\n * nginx_id\n", + "enum": [ + "system.memory.usage" + ] + }, + "MetricSystemCpuLogicalCount": { + "type": "string", + "description": "Number of logical (virtual) processor cores created by the operating system.\n\nAggregation(s) supported:\n * min\n * max\n * sum\n * avg\n * rate \n\nCatalog dimension(s) supported:\n * instance_object_id\n * csg_object_id\n * system_id\n * parent_hostname\n * display_name\n * nginx_id\n", + "enum": [ + "system.cpu.logical.count" + ] + }, + "MetricSystemNetworkIo": { + "type": "string", + "description": "Network I/O statistics. Number of bytes sent or received per network interface. A filter differentiator is needed for specific I/O direction(s).\n\nReplacement for depreciated variant(s):\n * system.net.bytes_rcvd\n * system.net.bytes_sent\n\nAggregation(s) supported:\n * min\n * max\n * sum\n * avg\n * rate\n\nCatalog dimension filter differentiator:\n * io_direction (applicable filter values: 'transmit', 'receive')\n\nCatalog dimension(s) supported:\n * instance_object_id\n * csg_object_id\n * system_id\n * parent_hostname\n * display_name\n * nginx_id\n * network_interface\n", + "enum": [ + "system.network.io" + ] + }, + "MetricNginxHttpRequests": { + "type": "string", + "description": "Total number of client requests received from clients.\n\nReplacement for depreciated variant(s):\n * nginx.http.request.count\n * plus.http.request.count\n\nAggregation(s) supported:\n * min\n * max\n * sum\n * avg\n * rate\n\nCatalog dimension(s) supported:\n * instance_object_id\n * csg_object_id\n * system_id\n * parent_hostname\n * display_name\n * nginx_id\n * server_zone\n * location_zone\n", + "enum": [ + "nginx.http.requests" + ] + }, + "MetricNginxHttpResponseStatus": { + "type": "string", + "description": "Number of responses for by status code range. A filter differentiator is needed for specific status range(s).\n\nReplacement for depreciated variant(s):\n * nginx.http.status.4xx\n * plus.http.status.4xx\n\nAggregation(s) supported:\n * min\n * max\n * sum\n * avg\n * rate\n\nCatalog dimension filter differentiator:\n * status_range (applicable filter values: '4xx', '5xx')\n\nCatalog dimension(s) supported:\n * instance_object_id\n * csg_object_id\n * system_id\n * parent_hostname\n * display_name\n * nginx_id \n * server_zone\n * location_zone\n", + "enum": [ + "nginx.http.response.status" + ] + }, + "SettingsInstanceCleanup": { + "type": "object", + "description": "Preferences for automatic cleanup of stale NGINX One Instances.", + "required": [ + "age_out_duration" + ], + "properties": { + "age_out_duration": { + "type": "integer", + "format": "int32", + "description": "Specify the age of `unavailable` NGINX instances for clean up. NGINX instances older than this value in hours will be deleted automatically. Events related to automatically deleted NGINX instances will show up in `/events` API. '0' value disables the automatic clean up of `unavailable` NGINX instances.", + "default": 3, + "minimum": 0, + "maximum": 720 + } + }, + "example": { + "age_out_duration": 3 + } + }, + "HttpUsage": { + "type": "object", + "properties": { + "client": { + "allOf": [ + { + "$ref": "#/components/schemas/UsageMetrics" + }, + { + "type": "object", + "properties": { + "requests": { + "type": "integer", + "description": "Total requests handled by an NGINX Instance", + "minimum": 0 + } + } + } + ] + }, + "upstream": { + "$ref": "#/components/schemas/UsageMetrics" + } + } + }, + "StreamUsage": { + "type": "object", + "properties": { + "client": { + "$ref": "#/components/schemas/UsageMetrics" + }, + "upstream": { + "$ref": "#/components/schemas/UsageMetrics" + } + } + }, + "UsageMetrics": { + "type": "object", + "properties": { + "received": { + "type": "integer", + "description": "Total bytes received by an NGINX Instance from clients/upstreams", + "minimum": 0 + }, + "sent": { + "type": "integer", + "description": "Total bytes sent by the NGINX Instance to clients/upstreams", + "minimum": 0 + }, + "connections": { + "type": "integer", + "description": "Total connections of the NGINX Instance with clients/upstreams", + "minimum": 0 + } + } + }, + "NginxUsageHttp": { + "$ref": "#/components/schemas/HttpUsage" + }, + "NginxUsageStream": { + "$ref": "#/components/schemas/StreamUsage" + }, + "MetricStartTime": { + "description": "The start time of your metrics query.\n\nUsage:\n* `start_time` is required if `end_time` is specified.\n* If `start_time` and `end_time` isn't provided, the API returns metrics from the current time to the month before the current time.\n* The `start_time` cannot be older than 120 days before the current time.\n\nYou can set the `start_time` in these ways:\n* In ISO 8601 format. For example, \"2019-08-07T09:57:36.088757764Z\".\n* As an offset from the current time. For the offset, use `+` or `-`, followed by a number and unit [`y` (years), `M` (months), `w` (weeks), `d` (days), `h` (hours), `m` (minutes), or `s` (seconds)]. \n* Example of an offset: \"now-3h\" (3 hours before now).\n", + "type": "string", + "example": "2019-08-07T09:57:36.088757764Z" + }, + "MetricEndTime": { + "description": "The end time of your metrics query.\n\nUsage:\n* Must be greater than `start_time`.\n* The time difference between `start_time` and `end_time` should be greater than an hour.\n* The default `end_time` is the current time.\n* The `end_time` cannot be older than 120 days before the current time.\n\nYou can set the `end_time` in these ways:\n* In ISO 8601 format. For example, \"2019-08-07T09:57:36.088757764Z\".\n* As an offset from the current time. For the offset, use `+` or `-`, followed by a number and unit [`y` (years), `M` (months), `w` (weeks), `d` (days), `h` (hours), `m` (minutes), or `s` (seconds)]. \n* Example of an offset: \"now-3h\" (3 hours before now).\n", + "type": "string", + "example": "2019-08-07T09:57:36.088757764Z" + }, + "InventoryMetricAggregation": { + "type": "string", + "description": "Static list of aggregation functions that can be applied to a compatible metric.\n * count\n * sum\n * avg\n * min\n * max\n", + "enum": [ + "count", + "sum", + "avg", + "min", + "max" + ], + "x-enum-varnames": [ + "metric_aggregation_count", + "metric_aggregation_sum", + "metric_aggregation_avg", + "metric_aggregation_min", + "metric_aggregation_max" + ] + }, + "BaseInventoryQueryRequest": { + "type": "object", + "required": [ + "metrics" + ], + "properties": { + "metrics": { + "$ref": "#/components/schemas/InventoryMetricNames" + }, + "start_time": { + "$ref": "#/components/schemas/MetricStartTime" + }, + "end_time": { + "$ref": "#/components/schemas/MetricEndTime" } } }, - "OrderSeriesBy": { + "InventoryMetricQueryRequest": { + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/BaseInventoryQueryRequest" + } + ] + }, + "InventoryMetricNames": { + "type": "array", + "description": "Specify the metrics to collect.\n\nUsage: \n* List multiple metrics as JSON objects.\n* You can aggregate metrics with `count`, `sum`, `avg`, `min`, `max`.\n", + "items": { + "$ref": "#/components/schemas/InventoryMetricQuery" + }, + "example": [ + { + "name": "nginx.plus.instances", + "aggregate": [ + "count" + ] + } + ] + }, + "InventoryMetricQuery": { "type": "object", - "description": "Sort order of the metric series in your results.\n\nUsage:\n* Provide all required elements. \n * `direction`: The sorting direction either `desc` or `asc`.\n * `aggregate`: The aggregating function.\n", "required": [ - "direction", - "aggregate" + "name" ], "properties": { - "direction": { - "$ref": "#/components/schemas/OrderDirection" + "name": { + "$ref": "#/components/schemas/InventoryMetricName" }, "aggregate": { - "$ref": "#/components/schemas/MetricAggregation", - "default": "sum" + "type": "array", + "items": { + "$ref": "#/components/schemas/InventoryMetricAggregation" + } } } }, - "MetricName": { + "InventoryMetricName": { "type": "string", "description": "Metric names available for querying.\n", - "example": "nginx.http.requests", + "example": "nginx.plus.instances", "oneOf": [ { - "$ref": "#/components/schemas/MetricSystemCpuTime" - }, - { - "$ref": "#/components/schemas/MetricSystemFilesystemUsage" - }, - { - "$ref": "#/components/schemas/MetricSystemMemoryUsage" - }, - { - "$ref": "#/components/schemas/MetricSystemCpuLogicalCount" - }, - { - "$ref": "#/components/schemas/MetricSystemNetworkIo" - }, - { - "$ref": "#/components/schemas/MetricNginxHttpRequests" + "$ref": "#/components/schemas/MetricNginxInstancesPlus" }, { - "$ref": "#/components/schemas/MetricNginxHttpResponseStatus" + "$ref": "#/components/schemas/MetricK8sClusterNodes" } ] }, - "MetricSystemCpuTime": { - "type": "string", - "description": "Total system CPU utilization for 'system' or 'user', percentage. A filter differentiator is needed for specific mode(s).\n\nReplacement for depreciated variant(s):\n * system.cpu.system\n * system.cpu.user\n\nAggregation(s) supported:\n * min\n * max\n * sum\n * avg\n * rate\n\nCatalog dimension filter differentiator:\n * mode (applicable filter values: 'system', 'user')\n\nCatalog dimension(s) supported:\n * instance_object_id\n * csg_object_id\n * system_id\n * parent_hostname\n * display_name\n * nginx_id\n", - "enum": [ - "system.cpu.time" - ] - }, - "MetricSystemFilesystemUsage": { + "MetricNginxInstancesPlus": { "type": "string", - "description": "System disk usage statistic, percentage. A filter differentiator is needed for specific state(s).\n\nReplacement for depreciated variant(s):\n * system.disk.in_use\n * system.disk.total\n * system.disk.used\n\nAggregation(s) supported:\n * min\n * max\n * sum\n * avg\n * rate\n\nCatalog dimension filter differentiator:\n * state (applicable filter values: 'used', 'free', 'in_use')\n\nCatalog dimension(s) supported:\n * instance_object_id\n * csg_object_id\n * system_id\n * parent_hostname\n * display_name\n * nginx_id\n * mount_point\n", + "description": "Total number of nginx plus instances.\n\nAggregation(s) supported:\n * count\n * sum\n * avg\n * min\n * max\n", "enum": [ - "system.filesystem.usage" + "nginx.plus.instances" ] }, - "MetricSystemMemoryUsage": { + "MetricK8sClusterNodes": { "type": "string", - "description": "Total available statistic about system memory usage, bytes. A filter differentiator is needed for specific state(s).\n\nReplacement for depreciated variant(s):\n * system.mem.pct_used\n * system.mem.total\n * system.mem.used\n\nAggregation(s) supported:\n * min\n * max\n * sum\n * avg\n * rate \n\nCatalog dimension filter differentiator:\n * state (applicable filter values: 'used', 'free', 'total', 'pct_used')\n\nCatalog dimension(s) supported:\n * instance_object_id\n * csg_object_id\n * system_id\n * parent_hostname\n * display_name\n * nginx_id\n", + "description": "Sum of the Kubernetes worker nodes where nginx plus instances are deployed in a Kubernetes cluster.\n\nAggregation(s) supported:\n * count\n * sum\n * avg\n * min\n * max\n", "enum": [ - "system.memory.usage" + "k8s.cluster.nodes" ] }, - "MetricSystemCpuLogicalCount": { + "NapPolicyEnforcementMode": { + "description": "The current enforcement mode of the NGINX App Protect policy, with the following possible values:\n* `blocking` - Any illegal or suspicious requests are logged and blocked.\n* `monitoring` - Any illegal or suspicious requests are logged but not blocked.\n", "type": "string", - "description": "Number of logical (virtual) processor cores created by the operating system.\n\nAggregation(s) supported:\n * min\n * max\n * sum\n * avg\n * rate \n\nCatalog dimension(s) supported:\n * instance_object_id\n * csg_object_id\n * system_id\n * parent_hostname\n * display_name\n * nginx_id\n", "enum": [ - "system.cpu.logical.count" + "blocking", + "monitoring" + ], + "x-enum-varnames": [ + "nap_enforcement_mode_blocking", + "nap_enforcement_mode_monitoring" ] }, - "MetricSystemNetworkIo": { + "NapDeploymentStatus": { + "description": "The current enforcement mode of the NGINX App Protect policy, with the following possible values:\n* `deployed` - The NGINX App Protect policy has been deployed.\n* `not_deployed` - The NGINX App Protect policy has not been deployed.\n* `deploying` - The NGINX App Protect policy is currently being deployed.\n* `failed` - The NGINX App Protect policy failed deploying.\n", "type": "string", - "description": "Network I/O statistics. Number of bytes sent or received per network interface. A filter differentiator is needed for specific I/O direction(s).\n\nReplacement for depreciated variant(s):\n * system.net.bytes_rcvd\n * system.net.bytes_sent\n\nAggregation(s) supported:\n * min\n * max\n * sum\n * avg\n * rate\n\nCatalog dimension filter differentiator:\n * io_direction (applicable filter values: 'transmit', 'receive')\n\nCatalog dimension(s) supported:\n * instance_object_id\n * csg_object_id\n * system_id\n * parent_hostname\n * display_name\n * nginx_id\n * network_interface\n", "enum": [ - "system.network.io" + "deployed", + "not_deployed", + "deploying", + "failed" + ], + "x-enum-varnames": [ + "nap_deployment_status_deployed", + "nap_deployment_status_not_deployed", + "nap_deployment_status_deploying", + "nap_deployment_status_failed" ] }, - "MetricNginxHttpRequests": { + "NapDeploymentType": { + "description": "The type of the deployment, with the following possible values:\n * `instance` - The deployment is of type instance.\n * `config_sync_group` - The deployment is of type config sync group.\n", "type": "string", - "description": "Total number of client requests received from clients.\n\nReplacement for depreciated variant(s):\n * nginx.http.request.count\n * plus.http.request.count\n\nAggregation(s) supported:\n * min\n * max\n * sum\n * avg\n * rate\n\nCatalog dimension(s) supported:\n * instance_object_id\n * csg_object_id\n * system_id\n * parent_hostname\n * display_name\n * nginx_id\n", "enum": [ - "nginx.http.requests" + "instance", + "config_sync_group" + ], + "x-enum-varnames": [ + "nap_policy_deployment_type_instance", + "nap_policy_deployment_type_csg" ] }, - "MetricNginxHttpResponseStatus": { + "Version": { + "description": "The version of the NGINX App Protect resource.", "type": "string", - "description": "Number of responses for by status code range. A filter differentiator is needed for specific status range(s).\n\nReplacement for depreciated variant(s):\n * nginx.http.status.4xx\n * plus.http.status.4xx\n\nAggregation(s) supported:\n * min\n * max\n * sum\n * avg\n * rate\n\nCatalog dimension filter differentiator:\n * status_range (applicable filter values: '4xx', '5xx')\n\nCatalog dimension(s) supported:\n * instance_object_id\n * csg_object_id\n * system_id\n * parent_hostname\n * display_name\n * nginx_id \n * server_zone\n * location_zone\n", - "enum": [ - "nginx.http.response.status" - ] + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", + "example": "2023.12.06" }, - "SettingsInstanceCleanup": { + "VersionsList": { "type": "object", - "description": "Preferences for automatic cleanup of stale NGINX One Instances.", "required": [ - "age_out_duration" + "items" ], "properties": { - "age_out_duration": { - "type": "integer", - "format": "int32", - "description": "Specify the age of `unavailable` NGINX instances for clean up. NGINX instances older than this value in hours will be deleted automatically. Events related to automatically deleted NGINX instances will show up in `/events` API. '0' value disables the automatic clean up of `unavailable` NGINX instances.", - "default": 3, - "minimum": 0, - "maximum": 720 + "items": { + "description": "An array of versions.", + "type": "array", + "items": { + "$ref": "#/components/schemas/Version" + } } }, "example": { - "age_out_duration": 3 + "items": [ + "2023.12.06" + ] } }, - "HttpUsage": { + "ThreatCampaignVersionsListResponse": { + "description": "List of Threat Campaign versions.", + "$ref": "#/components/schemas/VersionsList" + }, + "AttackSignatureVersionsListResponse": { + "description": "List of Attack Signature versions.", + "$ref": "#/components/schemas/VersionsList" + }, + "BotSignatureVersionsListResponse": { + "description": "List of Bot Signature versions.", + "$ref": "#/components/schemas/VersionsList" + }, + "NapPolicy": { + "description": "The JSON contents of the NGINX App Protect policy.", "type": "object", + "required": [ + "policy" + ], "properties": { - "client": { - "allOf": [ - { - "$ref": "#/components/schemas/UsageMetrics" + "policy": { + "description": "The NGINX App Protect policy configuration.", + "type": "object", + "minProperties": 1 + } + } + }, + "NapPolicyMetadata": { + "description": "Summary information about NGINX App Protect policy.", + "type": "object", + "required": [ + "object_id", + "name", + "deployment_count", + "last_updated_by", + "latest" + ], + "properties": { + "object_id": { + "$ref": "#/components/schemas/NapPolicyObjectID" + }, + "name": { + "description": "The name of the NGINX App Protect policy.", + "type": "string" + }, + "deployment_count": { + "description": "The number of NGINX One instances or config sync groups associated with the NGINX App Protect policy.", + "type": "integer" + }, + "last_updated_by": { + "description": "The NGINX One user who last modified the NGINX App Protect policy.", + "type": "string" + }, + "latest": { + "type": "object", + "required": [ + "enforcement_mode", + "deployed_on", + "version", + "created_on", + "last_updated_by" + ], + "properties": { + "enforcement_mode": { + "$ref": "#/components/schemas/NapPolicyEnforcementMode" }, - { - "type": "object", - "properties": { - "requests": { - "type": "integer", - "description": "Total requests handled by an NGINX Instance", - "minimum": 0 - } + "deployed_on": { + "description": "The date and time when the NGINX App Protect policy was last deployed.", + "type": "string", + "format": "date-time" + }, + "version": { + "description": "The latest version of the NGINX App Protect policy.", + "type": "string" + }, + "created_on": { + "description": "The date and time when the NGINX App Protect policy was created.", + "type": "string", + "format": "date-time" + } + } + }, + "description": { + "type": "string", + "description": "Some detail on the NGINX App Protect policy." + } + }, + "example": { + "object_id": "pol_-uvR3F2TQGm18jnl7bpaGw", + "name": "test-policy", + "last_updated_by": "john.doe@example.com", + "deployment_count": 5, + "decription": "test policy", + "latest": { + "enforcement_mode": "blocking", + "deployed_on": "2023-12-06T22:37:24.120114Z", + "version": "2023-12-06 22:37:24", + "created_on": "2023-12-06T22:37:24.120114Z" + } + } + }, + "NapPolicyResponse": { + "description": "Summary information about NGINX App Protect policy.", + "allOf": [ + { + "$ref": "#/components/schemas/NapPolicyMetadata" + }, + { + "$ref": "#/components/schemas/NapPolicy" + } + ] + }, + "NapPoliciesListResponse": { + "description": "List of all NGINX App Protect policies.", + "allOf": [ + { + "$ref": "#/components/schemas/PaginationResponse" + }, + { + "description": "List of NGINX App Protect policies.", + "type": "object", + "required": [ + "items" + ], + "properties": { + "items": { + "description": "An array of NGINX App Protect policy objects.", + "type": "array", + "items": { + "$ref": "#/components/schemas/NapPolicyMetadata" + } + } + }, + "example": { + "items": [ + { + "object_id": "pol_-uvR3F2TQGm18jnl7bpaGw", + "name": "test-policy", + "decription": "test policy", + "created_on": "2023-12-06T22:37:24.120114Z", + "latest_version": "2023.12.06", + "last_updated_by": "john.doe@example.com", + "enforcement_mode": "blocking", + "last_deployed": "2023-12-06T22:37:24.120114Z" + } + ] + } + } + ] + }, + "NapPolicyDeploymentMetadata": { + "type": "object", + "required": [ + "object_id", + "enforcement_mode", + "name", + "type", + "status", + "policy_version", + "threat_campaign_version", + "attack_signature_version", + "bot_signature_version" + ], + "properties": { + "object_id": { + "$ref": "#/components/schemas/PublicationObjectID" + }, + "enforcement_mode": { + "$ref": "#/components/schemas/NapPolicyEnforcementMode" + }, + "name": { + "description": "The name of the NGINX One instance or config sync group.", + "type": "string" + }, + "type": { + "$ref": "#/components/schemas/NapDeploymentType" + }, + "status": { + "$ref": "#/components/schemas/NapDeploymentStatus" + }, + "policy_version": { + "description": "The version associated with the NGINX App Protect policy.", + "type": "string" + }, + "deployed_on": { + "description": "The date and time when the NGINX App Protect policy was deployed.", + "type": "string", + "format": "date-time" + }, + "threat_campaign_version": { + "$ref": "#/components/schemas/Version" + }, + "attack_signature_version": { + "$ref": "#/components/schemas/Version" + }, + "bot_sigature_version": { + "$ref": "#/components/schemas/Version" + } + }, + "example": { + "object_id": "pub_-uvR3F2TQGm18jnl7bpaGw", + "name": "test-instance", + "type": "instance", + "status": "deployed", + "policy_version": "2023-12-06 22:37:24", + "deployed_on": "2023-12-06T22:37:24.120114Z", + "enforcement_mode": "blocking", + "threat_campaign_version": "2023.12.06", + "attack_signature_version": "2023.12.06", + "bot_sigature_version": "2023.12.06" + } + }, + "NapPolicyDeploymentsListResponse": { + "description": "List of all NGINX App Protect deployments.", + "allOf": [ + { + "$ref": "#/components/schemas/PaginationResponse" + }, + { + "type": "object", + "required": [ + "items" + ], + "properties": { + "items": { + "description": "An array of NGINX App Protect deployments.", + "type": "array", + "items": { + "$ref": "#/components/schemas/NapPolicyDeploymentMetadata" } } - ] - }, - "upstream": { - "$ref": "#/components/schemas/UsageMetrics" + }, + "example": { + "items": [ + { + "object_id": "pub_-uvR3F2TQGm18jnl7bpaGw", + "name": "test-instance", + "type": "instance", + "status": "deployed", + "policy_version": "2023-12-06 22:37:24", + "deployed_on": "2023-12-06T22:37:24.120114Z", + "enforcement_mode": "blocking", + "threat_campaign_version": "2023.12.06", + "attack_signature_version": "2023.12.06", + "bot_sigature_version": "2023.12.06" + } + ] + } } - } + ] }, - "StreamUsage": { + "NapPolicyVersionMetadata": { "type": "object", + "required": [ + "object_id", + "enforcement_mode", + "deployment_status", + "instance_count", + "config_sync_group_count", + "created_on", + "created_by", + "latest" + ], "properties": { - "client": { - "$ref": "#/components/schemas/UsageMetrics" + "object_id": { + "$ref": "#/components/schemas/NapPolicyVersionObjectID" }, - "upstream": { - "$ref": "#/components/schemas/UsageMetrics" - } - } - }, - "UsageMetrics": { - "type": "object", - "properties": { - "received": { - "type": "integer", - "description": "Total bytes received by an NGINX Instance from clients/upstreams", - "minimum": 0 + "enforcement_mode": { + "$ref": "#/components/schemas/NapPolicyEnforcementMode" }, - "sent": { - "type": "integer", - "description": "Total bytes sent by the NGINX Instance to clients/upstreams", - "minimum": 0 + "deployment_status": { + "$ref": "#/components/schemas/NapDeploymentStatus" }, - "connections": { - "type": "integer", - "description": "Total connections of the NGINX Instance with clients/upstreams", - "minimum": 0 + "instance_count": { + "description": "The number of NGINX One instances associated with the NGINX App Protect policy version", + "type": "integer" + }, + "config_sync_group_count": { + "description": "The number of NGINX One config sync groups associated with the NGINX App Protect policy version", + "type": "integer" + }, + "created_on": { + "description": "The date and time when the NGINX App Protect policy version was created.", + "type": "string", + "format": "date-time" + }, + "created_by": { + "description": "The NGINX One user who created the NGINX App Protect policy.", + "type": "string" + }, + "latest": { + "description": "Indicates whether the NGINX App Protect policy version is latest. Default (`false`) returns the current policy. \nWhen set to `true`, returns the latest policy.\n", + "type": "boolean", + "default": false } - } - }, - "NginxUsageHttp": { - "$ref": "#/components/schemas/HttpUsage" - }, - "NginxUsageStream": { - "$ref": "#/components/schemas/StreamUsage" - }, - "MetricStartTime": { - "description": "The start time of your metrics query.\n\nUsage:\n* `start_time` is required if `end_time` is specified.\n* If `start_time` and `end_time` isn't provided, the API returns metrics from the current time to the month before the current time.\n* The `start_time` cannot be older than 120 days before the current time.\n\nYou can set the `start_time` in these ways:\n* In ISO 8601 format. For example, \"2019-08-07T09:57:36.088757764Z\".\n* As an offset from the current time. For the offset, use `+` or `-`, followed by a number and unit [`y` (years), `M` (months), `w` (weeks), `d` (days), `h` (hours), `m` (minutes), or `s` (seconds)]. \n* Example of an offset: \"now-3h\" (3 hours before now).\n", - "type": "string", - "example": "2019-08-07T09:57:36.088757764Z" + }, + "example": { + "object_id": "pv_-uvR3F2TQGm18jnl7bpaGw", + "created_on": "2023-12-06T22:37:24.120114Z", + "created_by": "john.doe@example.com", + "deployment_status": "deployed", + "enforcement_mode": "blocking", + "instance_count": 10, + "config_sync_group_count": 15, + "latest": false + } + }, + "NapPolicyVersionResponse": { + "description": "Summary information about NGINX App Protect policy version.", + "allOf": [ + { + "$ref": "#/components/schemas/NapPolicyVersionMetadata" + }, + { + "$ref": "#/components/schemas/NapPolicy" + } + ] }, - "MetricEndTime": { - "description": "The end time of your metrics query.\n\nUsage:\n* Must be greater than `start_time`.\n* The time difference between `start_time` and `end_time` should be greater than an hour.\n* The default `end_time` is the current time.\n* The `end_time` cannot be older than 120 days before the current time.\n\nYou can set the `end_time` in these ways:\n* In ISO 8601 format. For example, \"2019-08-07T09:57:36.088757764Z\".\n* As an offset from the current time. For the offset, use `+` or `-`, followed by a number and unit [`y` (years), `M` (months), `w` (weeks), `d` (days), `h` (hours), `m` (minutes), or `s` (seconds)]. \n* Example of an offset: \"now-3h\" (3 hours before now).\n", - "type": "string", - "example": "2019-08-07T09:57:36.088757764Z" + "NapPolicyVersionsListResponse": { + "description": "List of all NGINX App Protect versions.", + "allOf": [ + { + "$ref": "#/components/schemas/PaginationResponse" + }, + { + "type": "object", + "required": [ + "items" + ], + "properties": { + "items": { + "description": "An array of NGINX App Protect version objects.", + "type": "array", + "items": { + "$ref": "#/components/schemas/NapPolicyVersionMetadata" + } + } + }, + "example": { + "items": [ + { + "object_id": "appv_-uvR3F2TQGm18jnl7bpaGw", + "created_on": "2023-12-06T22:37:24.120114Z", + "created_by": "john.doe@example.com", + "deployment_status": "deployed", + "enforcement_mode": "blocking", + "instance_count": 10, + "config_sync_group_count": 15, + "latest": false + } + ] + } + } + ] }, - "InventoryMetricAggregation": { - "type": "string", - "description": "Static list of aggregation functions that can be applied to a compatible metric.\n * count\n * sum\n * avg\n * min\n * max\n", - "enum": [ - "count", - "sum", - "avg", - "min", - "max" - ], - "x-enum-varnames": [ - "metric_aggregation_count", - "metric_aggregation_sum", - "metric_aggregation_avg", - "metric_aggregation_min", - "metric_aggregation_max" + "NapLogProfileListResponse": { + "allOf": [ + { + "$ref": "#/components/schemas/PaginationResponse" + }, + { + "type": "object", + "required": [ + "items" + ], + "properties": { + "items": { + "description": "An array of NGINX App Protect log profiles.", + "type": "array", + "items": { + "$ref": "#/components/schemas/NapLogProfileMetadata" + } + } + }, + "example": { + "items": [ + { + "name": "test-log-profile" + }, + { + "object_id": "lp_-uvR3F2TQGm18jnl7bpaGw" + } + ] + } + } ] }, - "BaseInventoryQueryRequest": { + "NapLogProfileResponse": { + "$ref": "#/components/schemas/NapLogProfileMetadata" + }, + "NapLogProfileMetadata": { "type": "object", "required": [ - "metrics" + "name", + "object_id" ], "properties": { - "metrics": { - "$ref": "#/components/schemas/InventoryMetricNames" + "name": { + "type": "string", + "description": "The name of the NGINX App Protect log profile." }, - "start_time": { - "$ref": "#/components/schemas/MetricStartTime" + "object_id": { + "$ref": "#/components/schemas/NapLogProfileObjectID" }, - "end_time": { - "$ref": "#/components/schemas/MetricEndTime" + "description": { + "description": "Optional field to describe the NGINX App Protect log profile.", + "type": "string", + "minLength": 5, + "maxLength": 256 } } }, - "InventoryMetricQueryRequest": { - "type": "object", + "NapGlobalSettingsListResponse": { "allOf": [ { - "$ref": "#/components/schemas/BaseInventoryQueryRequest" - } - ] - }, - "InventoryMetricNames": { - "type": "array", - "description": "Specify the metrics to collect.\n\nUsage: \n* List multiple metrics as JSON objects.\n* You can aggregate metrics with `count`, `sum`, `avg`, `min`, `max`.\n", - "items": { - "$ref": "#/components/schemas/InventoryMetricQuery" - }, - "example": [ + "$ref": "#/components/schemas/PaginationResponse" + }, { - "name": "nginx.plus.instances", - "aggregate": [ - "count" - ] + "type": "object", + "required": [ + "items" + ], + "properties": { + "items": { + "description": "An array of NGINX App Protect global settings.", + "type": "array", + "items": { + "$ref": "#/components/schemas/NapGlobalSettingsMetadata" + } + } + }, + "example": { + "items": [ + { + "name": "test-global-settings" + }, + { + "object_id": "gs_-uvR3F2TQGm18jnl7bpaGw" + } + ] + } } ] }, - "InventoryMetricQuery": { + "NapGlobalSettingsResponse": { + "$ref": "#/components/schemas/NapGlobalSettingsMetadata" + }, + "NapGlobalSettingsMetadata": { "type": "object", "required": [ - "name" + "name", + "object_id" ], "properties": { "name": { - "$ref": "#/components/schemas/InventoryMetricName" + "type": "string", + "description": "The name of the NGINX App Protect global settings object." }, - "aggregate": { - "type": "array", - "items": { - "$ref": "#/components/schemas/InventoryMetricAggregation" - } + "description": { + "description": "Optional field to describe the NGINX App Protect global setting object.", + "type": "string", + "minLength": 5, + "maxLength": 256 + }, + "object_id": { + "$ref": "#/components/schemas/NapGlobalSettingsObjectID" } } }, - "InventoryMetricName": { + "NapPolicyObjectID": { + "description": "A globally unique identifier for the App Protect policy.", "type": "string", - "description": "Metric names available for querying.\n", - "example": "nginx.plus.instances", - "oneOf": [ - { - "$ref": "#/components/schemas/MetricNginxInstancesPlus" - }, - { - "$ref": "#/components/schemas/MetricK8sClusterNodes" - } - ] + "format": "object_id", + "pattern": "^pol_.*", + "x-go-type": "objects.ID", + "x-go-type-import": { + "name": "objects", + "path": "gitlab.com/f5/nginx/one/saas/control-plane/pkg/collections/objects" + } }, - "MetricNginxInstancesPlus": { + "NapPolicyVersionObjectID": { + "description": "A globally unique identifier for the App Protect policy version.", "type": "string", - "description": "Total number of nginx plus instances.\n\nAggregation(s) supported:\n * count\n * sum\n * avg\n * min\n * max\n", - "enum": [ - "nginx.plus.instances" - ] + "format": "object_id", + "pattern": "^pv_.*", + "x-go-type": "objects.ID", + "x-go-type-import": { + "name": "objects", + "path": "gitlab.com/f5/nginx/one/saas/control-plane/pkg/collections/objects" + } }, - "MetricK8sClusterNodes": { + "NapLogProfileObjectID": { + "description": "A globally unique identifier for the App Protect log profile.", "type": "string", - "description": "Sum of the Kubernetes worker nodes where nginx plus instances are deployed in a Kubernetes cluster.\n\nAggregation(s) supported:\n * count\n * sum\n * avg\n * min\n * max\n", - "enum": [ - "k8s.cluster.nodes" - ] + "format": "object_id", + "pattern": "^lp_.*", + "x-go-type": "objects.ID", + "x-go-type-import": { + "name": "objects", + "path": "gitlab.com/f5/nginx/one/saas/control-plane/pkg/collections/objects" + } + }, + "NapGlobalSettingsObjectID": { + "description": "A globally unique identifier for the App Protect global settings object.", + "type": "string", + "format": "object_id", + "pattern": "^gs_.*", + "x-go-type": "objects.ID", + "x-go-type-import": { + "name": "objects", + "path": "gitlab.com/f5/nginx/one/saas/control-plane/pkg/collections/objects" + } } }, "examples": { @@ -7585,7 +8999,8 @@ "Config Sync Groups", "Certificates", "CVEs", - "Events" + "Events", + "Staged Configs" ] }, {