From 1086812b68b0edd63e70c66bb551aa83d4ccabf7 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Tue, 31 Dec 2024 13:27:41 -0800 Subject: [PATCH] feat: NGINX One Console. Deploy certs/keys on CSGs, part one --- content/nginx-one/changelog.md | 6 +- content/nginx-one/glossary.md | 4 +- .../certificates/manage-certificates.md | 24 +- .../how-to/config-sync-groups/_index.md | 6 + .../manage-config-sync-groups.md | 264 + .../nginx-one/how-to/nginx-configs/_index.md | 2 +- .../how-to/nginx-configs/add-file.md | 6 +- .../how-to/nginx-configs/add-instance.md | 75 + .../clean-up-unavailable-instances.md | 42 + .../view-edit-nginx-configurations.md | 4 +- content/nginx-one/how-to/settings/_index.md | 1 + static/nginx-one/api/one.json | 5771 ++++++++--------- 12 files changed, 3255 insertions(+), 2950 deletions(-) create mode 100644 content/nginx-one/how-to/config-sync-groups/_index.md create mode 100644 content/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md create mode 100644 content/nginx-one/how-to/nginx-configs/add-instance.md create mode 100644 content/nginx-one/how-to/nginx-configs/clean-up-unavailable-instances.md diff --git a/content/nginx-one/changelog.md b/content/nginx-one/changelog.md index e036522f7..2d3b85483 100644 --- a/content/nginx-one/changelog.md +++ b/content/nginx-one/changelog.md @@ -46,11 +46,11 @@ For more information, see the full documentation on how you can [Manage Certific ## August 22, 2024 -### Config sync groups +### Config Sync Groups -Config sync groups are now available in the F5 NGINX One Console. This feature allows you to manage and synchronize NGINX configurations across multiple instances as a single entity, ensuring consistency and simplifying the management of your NGINX environment. +Config Sync Groups are now available in the F5 NGINX One Console. This feature allows you to manage and synchronize NGINX configurations across multiple instances as a single entity, ensuring consistency and simplifying the management of your NGINX environment. -For more information, see the full documentation on [Managing Config Sync Groups]({{< relref "/nginx-one/how-to/nginx-configs/manage-config-sync-groups.md" >}}). +For more information, see the full documentation on [Managing Config Sync Groups]({{< relref "/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md" >}}). ## August 8, 2024 diff --git a/content/nginx-one/glossary.md b/content/nginx-one/glossary.md index 49cc944b0..a37ef9b19 100644 --- a/content/nginx-one/glossary.md +++ b/content/nginx-one/glossary.md @@ -16,7 +16,9 @@ This glossary defines terms used in the F5 NGINX One Console and F5 Distributed {{}} | Term | Definition | |-------------|-------------| +| **Config Sync Group** | A group of NGINX systems (or instances) with identical configurations. They may also share the same certificates. However, the instances in a Config Sync Group could belong to different systems and even different clusters. For more information, see this explanation of [Important considerations]({{< relref "/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md#important-considerations" >}}) | | **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. | | **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). | {{}} @@ -25,4 +27,4 @@ This glossary defines terms used in the F5 NGINX One Console and F5 Distributed ## References -- [F5 Distributed Cloud: Core Concepts](https://docs.cloud.f5.com/docs/ves-concepts/core-concepts) \ No newline at end of file +- [F5 Distributed Cloud: Core Concepts](https://docs.cloud.f5.com/docs/ves-concepts/core-concepts) diff --git a/content/nginx-one/how-to/certificates/manage-certificates.md b/content/nginx-one/how-to/certificates/manage-certificates.md index 8032370ea..c51e6627c 100644 --- a/content/nginx-one/how-to/certificates/manage-certificates.md +++ b/content/nginx-one/how-to/certificates/manage-certificates.md @@ -20,7 +20,7 @@ From the NGINX One Console you can: - Ensure that your certificates are current and correct. - Manage your certificates from a central location. This can help you simplify operations and remotely update, rotate, and deploy those certificates. -For more information on how you can use these certificates to secure your servers, refer to the section on [NGINX SSL termination]({{< relref "../../../nginx/admin-guide/security-controls/terminating-ssl-http.md" >}}). +For more information on how you can use these certificates to secure your servers, refer to the section on [NGINX SSL termination]({{< relref "/nginx/admin-guide/security-controls/terminating-ssl-http.md" >}}). {{< tip >}} @@ -128,9 +128,23 @@ In each case, you can upload files directly, or enter the content of the certifi You can modify existing certificates from the **Certificates** screen. Select the certificate of your choice. Depending on the type of certificate, you'll then see either a **Edit Certificate** or **Edit CA Bundle** option. The NGINX One Console then presents a window with the same options as shown when you [Add a new certificate](#add-a-new-certificate-or-bundle). -## Delete a certificate +If that certificate is already managed as part of a Config Sync Group, the changes you make affect all instances in that group. -To delete a certificate, find the name in the **Certificates** screen. Find the **Actions** column associated with the certificate. Select the ellipsis and then select **Delete**. +## Remove a deployed certificate + +You can remove a deployed certificate from an independent instance or from a Config Sync Group. This will remove the certificate's association with the instance or group, but it does not delete the certificate files from the instance(s). + +Every instance with a deployed certificate includes paths to certificates in their configuration files. If you remove the deployed file path to one certificate, that change is limited to that one instance. + +Every Config Sync Group also includes paths to certificates in its configuration files. If you remove the deployed path to one certificate, that change affects all instances which belong to that Config Sync Group. + +## Delete a deployed certificate + +To delete a certificate, find the name in the **Certificates** screen. Find the **Actions** column associated with the certificate. Select the ellipsis (`...`) and then select **Delete**. Before deleting that certificate, you should see a warning. + +If that certificate is managed and is part of a Config Sync Group, that change affects all instances in that group. + +{{< warning >}} Do not delete certificates that are being used by an instance or a Config Sync Group. Deleting such certificates leads to failure in affected NGINX deployments. {{< /warning >}} ## Managed and unmanaged certificates @@ -141,7 +155,7 @@ If you register an instance to NGINX One Console, as described in [Add your NGIN These certificates appear in the list of unmanaged certificates. -We recommend that you convert your unmanaged certificates. Converting to a managed certificate allows you to centrally manage, update, and deploy a certificate to your NGINX instances from the NGINX One Console. +We recommend that you convert your unmanaged certificates. Converting to a managed certificate allows you to centrally manage, update, and deploy a certificate to your data plane from the NGINX One Console. To convert these cerificates to managed, start with the Certificates menu, and select **Unmanaged**. You should see a list of **Unmanaged Certificates or CA Bundles**. Then: @@ -149,7 +163,7 @@ To convert these cerificates to managed, start with the Certificates menu, and s - Select **Convert to Managed** - In the window that appears, you can now include the same information as shown in the [Add a new certificate](#add-a-new-certificate) section - + ## See also diff --git a/content/nginx-one/how-to/config-sync-groups/_index.md b/content/nginx-one/how-to/config-sync-groups/_index.md new file mode 100644 index 000000000..31f258b69 --- /dev/null +++ b/content/nginx-one/how-to/config-sync-groups/_index.md @@ -0,0 +1,6 @@ +--- +description: +title: Config Sync Groups +weight: 250 +url: /nginx-one/how-to/config-sync-groups +--- diff --git a/content/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md b/content/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md new file mode 100644 index 000000000..66e8a082d --- /dev/null +++ b/content/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md @@ -0,0 +1,264 @@ +--- +docs: +doctypes: + - task +tags: + - docs +title: Manage Config Sync Groups +toc: true +weight: 300 +--- + + +## Overview + +If you work with several instances of NGINX, it can help to organize these instances in Config Sync Groups. Each instance in a Config Sync Group has the same configuration. + +This guide explains how to create and manage Config Sync Groups in the F5 NGINX One Console. Config Sync Groups synchronize NGINX configurations across multiple NGINX instances, ensuring consistency and ease of management. + +If you’ve used [instance groups in NGINX Instance Manager]({{< relref "/nim/nginx-instances/manage-instance-groups.md" >}}), you’ll find Config Sync Groups in NGINX One similar, though the steps and terminology differ slightly. + +Config Sync Groups are functionally different from syncing instances in a cluster. They let you to manage and synchronize configurations across multiple NGINX instances, all at once. + +This is particularly useful when your NGINX instances are load-balanced by an external load balancer, as it ensures consistency across all instances. In contrast, cluster syncing, like [zone syncing]({{< relref "nginx/admin-guide/high-availability/zone_sync_details.md" >}}), ensures data consistency and high availability across NGINX instances in a cluster. While Config Sync Groups focus on configuration management, cluster syncing supports failover and data consistency. + +## Before you start + +Before you create and manage Config Sync Groups, ensure: + +- You have access to the NGINX One Console. +- You have the necessary permissions to create and manage Config Sync Groups. +- If you plan to add existing instances to a Config Sync Group, make sure those NGINX instances are properly registered with NGINX One. + +## Configuration management + +Config Sync Groups support configuration inheritance and persistance. If you've just created a Config Sync Group, you can define the configuration for that group in the following ways: + +- Before adding an instance to a group, you can [Define the Config Sync Group configuration manually](#define-the-config-sync-group-configuration-manually). +- When you add the first instance to a group, that instance defines the configuration for that Config Sync Group. +- Afterwards, you can modify the configuration of the Config Sync Group. That modifies the configuration of all member instances. Future members of that group inherit that modified configuration. + +On the other hand, if you remove all instances from a Config Sync Group, the original configuration persists. In other words, the group retains the configuration from that first instance (or the original configuration). Any new instance that you add later still inherits that configuration. + +{{< tip >}}You can use _unmanaged_ certificates. Your actions can affect the [Config Sync Group status](#config-sync-group-status). For future instances on the data plane, if it: + +- Has unmanaged certificates in the same file paths as defined by the NGINX configuration as the Config Sync Group, that instance will be [**In Sync**](#config-sync-group-status). +- Will be [**Out of Sync**](#config-sync-group-status) if the instance: + - Does not have unmanaged certificates in the same file paths + - Has unmanaged certificates in a different directory from the Config Sync Group +{{< /tip >}} + +### Risk when adding multiple instances to a Config Sync Group + +If you add multiple instances to a single Config Sync Group, simultaneously (with automation), there's a risk that the instance selects a random configuration. To prevent this problem, you should: + +1. Create a Config Sync Group. +1. Add a configuration to the Config Sync Group, so all instances inherit it. +1. Add the instances in a separate operation. + +Your instances should synchronize with your desired configuration within 30 seconds. + +### Use an instance to define the Config Sync Group configuration + +1. Follow the steps in the [**Add an existing instance to a Config Sync Group**](#add-an-existing-instance-to-a-config-sync-group) or [**Add a new instance to a Config Sync Group**](#add-a-new-instance-to-a-config-sync-group) sections to add your first instance to the group. +2. The NGINX configuration from this instance will automatically become the group's configuration. +3. You can further edit and publish this configuration by following the steps in the [**Publish the Config Sync Group configuration**](#publish-the-config-sync-group-configuration) section. + +### Define the Config Sync Group configuration manually + +You can manually define the group's configuration before adding any instances. When you add instances to the group later, they automatically inherit this configuration. + +To manually set the group configuration: + +1. Follow steps 1–4 in the [**Create a Config Sync Group**](#create-a-config-sync-group) section to create your Config Sync Group. +2. After creating the group, select the **Configuration** tab. +3. Since no instances have been added, the **Configuration** tab will show an empty configuration with a message indicating that no config files exist yet. +4. To add a configuration, select **Edit Configuration**. +5. In the editor, define your NGINX configuration as needed. This might include adding or modifying `nginx.conf` or other related files. +6. After making your changes, select **Next** to view a split screen showing your changes. +7. If you're satisfied with the configuration, select **Save and Publish**. + +## Important considerations + +When you plan Config Sync Groups, consider the following factors: + +- **Single Config Sync Group membership**: You can add an instance to only one Config Sync Group. + +- **NGINX Agent configuration file location**: When you run the NGINX Agent installation script to register an instance with NGINX One, the script creates the `agent-dynamic.conf` file, which contains settings for the NGINX Agent, including the specified Config Sync Group. This file is typically located in `/var/lib/nginx-agent/` on most systems; however, on FreeBSD, it's located at `/var/db/nginx-agent/`. + +- **Mixing NGINX Open Source and NGINX Plus instances**: You can add both NGINX Open Source and NGINX Plus instances to the same Config Sync Group, but there are limitations. If your configuration includes features exclusive to NGINX Plus, synchronization will fail on NGINX Open Source instances because they don't support these features. NGINX One allows you to mix NGINX instance types for flexibility, but it’s important to ensure that the configurations you're applying are compatible with all instances in the group. + +## Create a Config Sync Group + +When you create a Config Sync Group, you can manage the configurations of multiple NGINX instances as a single entity. + +1. On the left menu, select **Config Sync Groups**. +2. Select **Add Config Sync Group**. +3. In the **Name** field, type a name for your Config Sync Group. +4. Select **Create** to add the Config Sync Group. + +## Manage Config Sync Group membership + +Now that you created a Config Sync Group, you can add instances to that group. As described in [Configuration management](#configuration-management), the first instance you add to a group, when you add it, defines the initial configuration for the group. You can update the configuration for the entire Config Sync Group. + +Any instance that joins the group afterwards inherits that configuration. + +### Add an existing instance to a Config Sync Group {#add-an-existing-instance-to-a-config-sync-group} + +You can add existing NGINX instances that are already registered with NGINX One to a Config Sync Group. + +1. Open a command-line terminal on the NGINX instance. +2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. +3. At the end of the file, add a new line beginning with `instance_group:`, followed by the Config Sync Group name. + + ``` text + instance_group: + ``` + +4. Restart NGINX Agent: + + ``` shell + sudo systemctl restart nginx-agent + ``` + +### Add a new instance to a Config Sync Group {#add-a-new-instance-to-a-config-sync-group} + +When adding a new NGINX instance that is not yet registered with NGINX One, you need a data plane key to securely connect the instance. You can generate a new data plane key during the process or use an existing one if you already have it. + +1. On the left menu, select **Config Sync Groups**. +2. Select the Config Sync Group in the list. +3. In the **Instances** pane, select **Add Instance to Config Sync Group**. +4. In the **Add Instance to Config Sync Group** dialog, select **Register a new instance with NGINX One then add to Config Sync Group**. +5. Select **Next**. +6. **Generate a new data plane key** (choose this option if you don't have an existing key): + + - Select **Generate new key** to create a new data plane key for the instance. + - Select **Generate Data Plane Key**. + - Copy and securely store the generated key, as it is displayed only once. + +7. **Use an existing data plane key** (choose this option if you already have a key): + + - Select **Use existing key**. + - In the **Data Plane Key** field, enter the existing data plane key. + +{{}} + +{{%tab name="Virtual Machine or Bare Metal"%}} + +8. Run the provided command, which includes the data plane key, in your NGINX instance terminal to register the instance with NGINX One. +9. Select **Done** to complete the process. + +{{%/tab%}} + +{{%tab name="Docker Container"%}} + +8. **Log in to the NGINX private registry**: + + - Replace `YOUR_JWT_HERE` with your JSON Web Token (JWT) license from [MyF5](https://my.f5.com/manage/s/). + + ```shell + sudo docker login private-registry.nginx.com --username=YOUR_JWT_HERE --password=none + ``` + +9. **Pull the Docker image**: + + - From the **OS Type** list, choose the appropriate operating system for your Docker image. + - After selecting the OS, run the provided command to pull the Docker image. + + **Note**: Subject to availability, you can modify the `agent: ` to match the specific NGINX Plus version, OS type, and OS version you need. For example, you might use `agent: r32-ubi-9`. For more details on version tags and how to pull an image, see [Deploying NGINX and NGINX Plus on Docker]({{< relref "nginx/admin-guide/installing-nginx/installing-nginx-docker.md#pulling-the-image" >}}). + + + - From the **OS Type** list, choose the appropriate operating system for your Docker image. + - After selecting the OS, run the provided command to pull the Docker image. + + **Note**: Subject to availability, you can modify the `agent: ` to match the specific NGINX Plus version, OS type, and OS version you need. For example, you might use `agent: r32-ubi-9`. For more details on version tags and how to pull an image, see [Deploying NGINX and NGINX Plus on Docker]({{< relref "nginx/admin-guide/installing-nginx/installing-nginx-docker.md#pulling-the-image" >}}). + +10. Run the provided command, which includes the data plane key, in your NGINX instance terminal to start the Docker container. + +11. Select **Done** to complete the process. + +{{%/tab%}} + +{{}} + +{{}} + +Data plane keys are required for registering NGINX instances with the NGINX One Console. These keys serve as secure tokens, ensuring that only authorized instances can connect and communicate with NGINX One. + +For more details on creating and managing data plane keys, see [Create and manage data plane keys]({{}}). + +{{}} + +### Move an instance to a different Config Sync Group + +If you need to move an NGINX instance to a different Config Sync Group, follow these steps: + +1. Open a command-line terminal on the NGINX instance. +2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. +3. Locate the line that begins with `instance_group:` and change it to the name of the new Config Sync Group. + + ``` text + instance_group: + ``` + +4. Restart NGINX Agent by running the following command: + + ```shell + sudo systemctl restart nginx-agent + ``` + +If you move an instance with certificates from one Config Sync Group to another, NGINX One adds or removes those certificates from the data plane, to synchronize with the deployed certificates of the group. + +### Remove an instance from a Config Sync Group + +If you need to remove an NGINX instance from a Config Sync Group without adding it to another group, follow these steps: + +1. Open a command-line terminal on the NGINX instance. +2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. +3. Locate the line that begins with `instance_group:` and either remove it or comment it out by adding a `#` at the beginning of the line. + + ```text + # instance_group: + ``` + +4. Restart NGINX Agent: + + ```shell + sudo systemctl restart nginx-agent + ``` + +By removing or commenting out this line, the instance will no longer be associated with any Config Sync Group. + +## Publish the Config Sync Group configuration {#publish-the-config-sync-group-configuration} + +After the Config Sync Group is created, you can modify and publish the group's configuration as needed. Any changes made to the group configuration will be applied to all instances within the group. + +1. On the left menu, select **Config Sync Groups**. +2. Select the Config Sync Group in the list. +3. Select the **Configuration** tab to view the group's NGINX configuration. +4. To modify the group's configuration, select **Edit Configuration**. +5. Make the necessary changes to the configuration. +6. When you're finished, select **Next**. A split view displays the changes. +7. If you're satisfied with the changes, select **Save and Publish**. + +Publishing the group configuration ensures that all instances within the Config Sync Group are synchronized with the latest group configuration. This helps maintain consistency across all instances in the group, preventing configuration drift. + +## Config Sync Group status + +The **Config Sync Status** column on the **Config Sync Groups** page provides insight into the synchronization state of your NGINX instances within each group. + +{{}} +| **Status** | **Description** | +|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| +| **In Sync** | All instances within the Config Sync Group have configurations that match the group configuration. No action is required. | +| **Out of Sync** | At least one instance in the group has a configuration that differs from the group's configuration. You may need to review and resolve discrepancies to ensure consistency. | +| **Sync in Progress** | An instance is currently being synchronized with the group's configuration. This status appears when an instance is moved to a new group or when a configuration is being applied. | +| **Unknown** | The synchronization status of the instances in this group cannot be determined. This could be due to connectivity issues, instances being offline, or other factors. Investigating the cause of this status is recommended. | +{{}} + +Monitor the **Config Sync Status** column. It can help you ensure that your configurations are consistently applied across all instances in a group. + +## See also + +- [Create and manage data plane keys]({{< relref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) +- [View and edit NGINX configurations]({{< relref "/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md" >}}) diff --git a/content/nginx-one/how-to/nginx-configs/_index.md b/content/nginx-one/how-to/nginx-configs/_index.md index fd5795cf3..b7fa815da 100644 --- a/content/nginx-one/how-to/nginx-configs/_index.md +++ b/content/nginx-one/how-to/nginx-configs/_index.md @@ -1,6 +1,6 @@ --- description: -title: NGINX configs +title: Instances and Configurations weight: 200 url: /nginx-one/how-to/nginx --- diff --git a/content/nginx-one/how-to/nginx-configs/add-file.md b/content/nginx-one/how-to/nginx-configs/add-file.md index c97685e04..9e7bd9838 100644 --- a/content/nginx-one/how-to/nginx-configs/add-file.md +++ b/content/nginx-one/how-to/nginx-configs/add-file.md @@ -6,7 +6,7 @@ tags: - docs title: Add a file in a configuration toc: true -weight: 200 +weight: 400 --- @@ -24,8 +24,8 @@ Before you add files in your configuration, ensure: ## Important considerations -If your instance is a member of a config sync group, changes that you make may be synchronized to other instances in that group. -For more information, see how you can [Manage config sync groups]({{< relref "/nginx-one/how-to/nginx-configs/manage-config-sync-groups.md" >}}). +If your instance is a member of a Config Sync Group, changes that you make may be synchronized to other instances in that group. +For more information, see how you can [Manage Config Sync Groups]({{< relref "/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md" >}}). ## Add a file diff --git a/content/nginx-one/how-to/nginx-configs/add-instance.md b/content/nginx-one/how-to/nginx-configs/add-instance.md new file mode 100644 index 000000000..8584e7881 --- /dev/null +++ b/content/nginx-one/how-to/nginx-configs/add-instance.md @@ -0,0 +1,75 @@ +--- +description: '' +doctypes: +- task +tags: +- docs +title: Add an NGINX instance +toc: true +weight: 100 +--- + +## Overview + +This guide explains how to add an F5 NGINX instance in F5 NGINX One Console. You can add an instance from the NGINX One Console individually, or as part of a [Config Sync Group]({{< relref "/nginx-one/glossary.md" >}}). In either case, you need +to set up a data plane key to connect your instances to NGINX One. + +## Before you start + +Before you add an instance to NGINX One Console, ensure: + +- You have administrator access to NGINX One Console. +- You have configured instances of NGINX that you want to manage through NGINX One Console. +- You have or are ready to configure a data plane key. +- You have or are ready to set up managed certificates. + +{{< note >}}If this is the first time an instance is being added to a Config Sync Group, and you have not yet defined the configuration for that Config Sync Group, that instance provides the template for that group. For more information, see [Configuration management]({{< relref "nginx-one/how-to/config-sync-groups/manage-config-sync-groups#configuration-management" >}}).{{< /note >}} + +## Add an instance + +You can add an instance to NGINX One Console in the following ways: + +- Directly, under **Instances** +- Indirectly, by selecting a Config Sync Group, and selecting **Add Instance to Config Sync Group** + +In either case, NGINX One Console gives you a choice for data plane keys: + +- Create a new key +- Use an existing key + +NGINX One Console takes the option you use, and adds the data plane key to a command that you'd use to register your target instance. You should see the call in the **Add Instance** screen in the console. The command looks like: + +```bash +curl https:///nginx-agent/install | DATA_PLANE_KEY="" sh -s -- -y +``` + +Sign in to the instance that you want to add. Run that command. If needed, the script [installs NGINX Agent]({{< relref "/nginx-one/getting-started#install-nginx-agent" >}}) dependencies and packages. Once the process is complete, you can configure that instance in your NGINX One Console. + +## Managed and Unmanaged Certificates + +If you add an instance with SSL/TLS certificates, those certificates can match an existing managed SSL certificate/CA bundle. + +### If the certificate is already managed + +If you add an instance with a managed certificate, as described in [Add your NGINX instances to NGINX One], these certificates are added to your list of **Managed Certificates**. + +NGINX One Console can manage your instances along with those certificates. + +### If the certificate is not managed + +These certificates appear in the list of **Unmanaged Certificates**. + +To take full advantage of NGINX One, you can convert these to **Managed Certificates**. You can then manage, update, and deploy a certificate to all of your NGINX instances in a Config Sync Group. + +To convert these cerificates, start with the Certificates menu, and select **Unmanaged**. You should see a list of **Unmanaged Certificates or CA Bundles**. Then: + +- Select a certificate +- Select **Convert to Managed** +- In the window that appears, you can now include the same information as shown in the [Add a new certificate](#add-a-new-certificate) section + +Once you've completed the process, NGINX One reassigns this as a managed certificate, and assigns it to the associated instance or Config Sync Group. + +## Add an instance to a Config Sync Group + +When you [Manage Config Sync Group membership]({{< relref "nginx-one/how-to/config-sync-groups/manage-config-sync-groups#manage-config-sync-group-membership" >}}), you can add an existing or new instance to the group of your choice. +That instance inherits the setup of that Config Sync Group. diff --git a/content/nginx-one/how-to/nginx-configs/clean-up-unavailable-instances.md b/content/nginx-one/how-to/nginx-configs/clean-up-unavailable-instances.md new file mode 100644 index 000000000..168f3e501 --- /dev/null +++ b/content/nginx-one/how-to/nginx-configs/clean-up-unavailable-instances.md @@ -0,0 +1,42 @@ +--- +description: '' +docs: +doctypes: +- task +tags: +- docs +title: Clean up unavailable NGINX instances +toc: true +weight: 200 +--- + +## Overview + +This guide explains how to set up automatic cleanup for NGINX instances in NGINX One. The cleanup process removes instances that have been unavailable for a specified duration. By default, this period is 24 hours from the time the NGINX instance was last updated. Administrators can change or disable the cleanup duration in **Settings > Instance Settings**. Events will be generated for NGINX instances that have been automatically cleaned up; you can see these events on the **Overview > Events** page. + +## Before you start + +Before you set up automatic cleanup for NGINX instances, ensure: + +- You have administrator access to NGINX One. +- You understand that this action will delete instances permanently after they are unavailable for the specified duration. + +## Configure instance cleanup + +Follow these steps to set up automatic cleanup for NGINX instances in NGINX One: + +1. On the left menu, select **Instance Settings**. +1. On the **Instance Settings** page, in the **Unavailable Instance Cleanup** section, select **Edit Duration**. +1. Choose the cleanup duration. + - Select one of the predefined durations (None, 1 day, 7 days, 30 days) or set a custom duration. Selecting **None** disables automatic cleanup. + - If you choose **Custom**, enter the duration in hours or days. +1. Select **Save** to apply the changes. + +## Event log details + +When instances are cleaned up automatically, an event log entry is created. You can find these events on the **Overview > Events** page. The event log includes the following details: + +- **Impacted Object ID**: The unique identifier of the NGINX instance that was cleaned up. +- **Type**: The type of event, which will be "Automated Object Cleanup". +- **Timestamp**: The date and time when the instance was cleaned up. +- **Message**: A description indicating that the instance was unavailable for the configured duration before being cleaned up. 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 800e90515..6070f65bb 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 @@ -6,7 +6,7 @@ tags: - docs title: View and edit NGINX configurations toc: true -weight: 100 +weight: 300 --- 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. @@ -23,4 +23,4 @@ To view and edit an NGINX configuration, follow these steps: ## See also -- [Manage config sync groups]({{< relref "/nginx-one/how-to/nginx-configs/manage-config-sync-groups.md" >}}) +- [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/settings/_index.md b/content/nginx-one/how-to/settings/_index.md index e0588c937..cdbbc1636 100644 --- a/content/nginx-one/how-to/settings/_index.md +++ b/content/nginx-one/how-to/settings/_index.md @@ -3,4 +3,5 @@ description: title: Settings weight: 500 url: /nginx-one/how-to/settings +draft: true --- diff --git a/static/nginx-one/api/one.json b/static/nginx-one/api/one.json index bf17698d6..00742de54 100644 --- a/static/nginx-one/api/one.json +++ b/static/nginx-one/api/one.json @@ -134,48 +134,38 @@ } } }, - "post": { + "patch": { + "x-nginx-one-action": "bulk", + "x-nginx-one-entity": "data plane key", "tags": [ "Data Plane Key" ], - "x-nginx-one-action": "create", - "x-nginx-one-entity": "data plane key", - "summary": "Create a data plane key", - "description": "Creates a unique data plane key that you can use to register NGINX instances with NGINX One.\n\n**IMPORTANT**: Save the data plane key somewhere secure for reference. The key is displayed only once and cannot be retrieved again.\n", - "operationId": "createDataPlaneKey", + "summary": "Bulk operation on multiple data plane keys.", + "operationId": "BulkDataPlaneKeys", + "description": "Performs bulk operation on one or more data plane keys, only delete is supported.", "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DataPlaneKeyCreateRequest" - }, - "examples": { - "DataPlaneKeyCreateRequest": { - "$ref": "#/components/examples/DataPlaneKeyRequest" - } + "$ref": "#/components/schemas/DataPlaneKeyBulkRequest" } } } }, "responses": { "200": { - "description": "Successfully created the data plane key.", + "description": "Batch request completed.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DataPlaneKeyResponse" - }, - "examples": { - "DataPlaneKeyResponse": { - "$ref": "#/components/examples/DataPlaneKeyResponse" - } + "$ref": "#/components/schemas/DataPlaneKeyBulkResponse" } } } }, - "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": { @@ -196,38 +186,48 @@ } } }, - "patch": { - "x-nginx-one-action": "bulk", - "x-nginx-one-entity": "data plane key", + "post": { "tags": [ "Data Plane Key" ], - "summary": "Bulk operation on multiple data plane keys.", - "operationId": "BulkDataPlaneKeys", - "description": "Performs bulk operation on one or more data plane keys, only delete is supported.", + "x-nginx-one-action": "create", + "x-nginx-one-entity": "data plane key", + "summary": "Create a data plane key", + "description": "Creates a unique data plane key that you can use to register NGINX instances with NGINX One.\n\n**IMPORTANT**: Save the data plane key somewhere secure for reference. The key is displayed only once and cannot be retrieved again.\n", + "operationId": "createDataPlaneKey", "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DataPlaneKeyBulkRequest" + "$ref": "#/components/schemas/DataPlaneKeyCreateRequest" + }, + "examples": { + "DataPlaneKeyCreateRequest": { + "$ref": "#/components/examples/DataPlaneKeyRequest" + } } } } }, "responses": { "200": { - "description": "Batch request completed.", + "description": "Successfully created the data plane key.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DataPlaneKeyBulkResponse" + "$ref": "#/components/schemas/DataPlaneKeyResponse" + }, + "examples": { + "DataPlaneKeyResponse": { + "$ref": "#/components/examples/DataPlaneKeyResponse" + } } } } }, - "401": { - "description": "Access denied.", + "400": { + "description": "Request cannot be processed due to invalid input or parameters. Verify the request format and provided data.", "content": { "application/json": { "schema": { @@ -250,36 +250,36 @@ } }, "/data-plane-keys/{data_plane_key_id}": { - "get": { + "delete": { "tags": [ "Data Plane Key" ], - "summary": "Retrieve a data plane key", - "description": "Retrieves the details for an existing data plane key.\n", - "operationId": "getDataPlaneKey", + "x-nginx-one-action": "delete", + "x-nginx-one-entity": "data plane key", + "summary": "Delete a data plane key", + "description": "Deletes a data plane key.\n", + "operationId": "deleteDataPlaneKey", "parameters": [ { "$ref": "#/components/parameters/DataPlaneKeyParamObjectID" } ], "responses": { - "200": { - "description": "Successfully retrieved the details of the data plane key.", + "204": { + "description": "Successfully deleted the data plane key." + }, + "404": { + "description": "The data plane key 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/DataPlaneKey" - }, - "examples": { - "DataPlaneKeys": { - "$ref": "#/components/examples/DataPlaneKey" - } + "$ref": "#/components/schemas/Error" } } } }, - "401": { - "description": "Access denied.", + "409": { + "description": "Cannot delete an active data plane key. Revoke the key first, then try deleting it again.", "content": { "application/json": { "schema": { @@ -300,36 +300,36 @@ } } }, - "delete": { + "get": { "tags": [ "Data Plane Key" ], - "x-nginx-one-action": "delete", - "x-nginx-one-entity": "data plane key", - "summary": "Delete a data plane key", - "description": "Deletes a data plane key.\n", - "operationId": "deleteDataPlaneKey", + "summary": "Retrieve a data plane key", + "description": "Retrieves the details for an existing data plane key.\n", + "operationId": "getDataPlaneKey", "parameters": [ { "$ref": "#/components/parameters/DataPlaneKeyParamObjectID" } ], "responses": { - "204": { - "description": "Successfully deleted the data plane key." - }, - "404": { - "description": "The data plane key with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", + "200": { + "description": "Successfully retrieved the details of the data plane key.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Error" + "$ref": "#/components/schemas/DataPlaneKey" + }, + "examples": { + "DataPlaneKeys": { + "$ref": "#/components/examples/DataPlaneKey" + } } } } }, - "409": { - "description": "Cannot delete an active data plane key. Revoke the key first, then try deleting it again.", + "401": { + "description": "Access denied.", "content": { "application/json": { "schema": { @@ -482,56 +482,14 @@ } } }, - "/instances/summary": { - "get": { - "tags": [ - "Instances" - ], - "summary": "Retrieve a summary for all instances", - "description": "Retrieves a comprehensive summary for all NGINX instances, which includes details such as:\n * Certificate status and associations\n * Operating system details\n * Version of the NGINX Agent\n * Overall system status\n", - "operationId": "listSummary", - "responses": { - "200": { - "description": "Successfully retrieved the summary of NGINX instances.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/InstanceSummary" - } - } - } - }, - "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" - } - } - } - } - } - } - }, - "/instances": { + "/certificates": { "get": { + "x-feature-flag": "cert-mgmt", "tags": [ - "Instances" + "Certificates" ], - "summary": "List all instances", - "operationId": "listInstances", - "description": "Returns a list of all NGINX instances, providing details such as:\n * Unique identifiers for each instance\n * Timestamps for key actions (like registration and last report)\n * Information about the NGINX build\n * Version of the NGINX Agent\n", + "summary": "List all SSL certificates", + "description": "Returns a paginated list showing metadata for every SSL certificate.\n", "parameters": [ { "$ref": "#/components/parameters/Paginated" @@ -543,7 +501,7 @@ "$ref": "#/components/parameters/Offset" }, { - "$ref": "#/components/parameters/FilterFieldInstances" + "$ref": "#/components/parameters/FilterFieldCertificates" }, { "$ref": "#/components/parameters/FilterOperands" @@ -555,16 +513,17 @@ "$ref": "#/components/parameters/SortDirection" }, { - "$ref": "#/components/parameters/SortNameInstances" + "$ref": "#/components/parameters/SortNameCertificates" } ], + "operationId": "listCertificates", "responses": { "200": { - "description": "Successfully retrieved the list of instances.", + "description": "Successfully retrieved the list of SSL certificates.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/InstanceListResponse" + "$ref": "#/components/schemas/CertificateListResponse" } } } @@ -591,32 +550,43 @@ } } }, - "patch": { - "x-nginx-one-action": "bulk", - "x-nginx-one-entity": "NGINX instance", + "post": { + "x-nginx-one-action": "create", + "x-nginx-one-entity": "NGINX certificate", + "x-feature-flag": "cert-mgmt", "tags": [ - "Instances" + "Certificates" ], - "summary": "Bulk operation on multiple instances.", - "operationId": "BulkInstances", - "description": "Performs bulk operation on one or more NGINX instances, only delete is supported.", + "summary": "Create an SSL certificate", + "operationId": "createCertificate", + "description": "Creates a new SSL certificate with an optional name. \nYou must supply the certificate's content in base64-encoded PEM format.\nAny warnings will be displayed only upon creation of the certificate object, and\nis not retrievable after it is created.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/InstanceBulkRequest" + "$ref": "#/components/schemas/CertificateRequest" } } } }, "responses": { "200": { - "description": "Batch request completed.", + "description": "Successfully created the SSL certificate.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/InstanceBulkResponse" + "$ref": "#/components/schemas/CertificateResponse" + } + } + } + }, + "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" } } } @@ -644,29 +614,27 @@ } } }, - "/instances/{instanceObjectID}/cves": { - "get": { + "/certificates/{certificateObjectID}": { + "delete": { + "x-nginx-one-action": "delete", + "x-nginx-one-entity": "NGINX certificate", + "x-feature-flag": "cert-mgmt", "tags": [ - "Instances" - ], - "summary": "Retrieve an instance's security advisories (CVEs)", - "description": "Retrieves a list of the security advisories (CVEs) for an NGINX instance.", - "operationId": "listInstanceSecurityAdvisories", - "parameters": [ - { - "$ref": "#/components/parameters/InstanceParamObjectID" - } + "Certificates" ], + "summary": "Delete an SSL certificate", + "operationId": "deleteCertificate", + "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.", "responses": { - "200": { - "description": "Successfully retrieved the list of security advisories (CVEs).", + "204": { + "description": "Successfully deleted the SSL certificate." + }, + "400": { + "description": "Request cannot be processed due to invalid input or parameters. Verify the request format and provided data.", "content": { "application/json": { "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/NginxSecurityAdvisory" - } + "$ref": "#/components/schemas/Error" } } } @@ -682,7 +650,7 @@ } }, "404": { - "description": "The NGINX instance with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", + "description": "The SSL certificate 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": { @@ -702,28 +670,22 @@ } } } - } - }, - "/instances/{instanceObjectID}": { + }, "get": { + "x-feature-flag": "cert-mgmt", "tags": [ - "Instances" - ], - "summary": "Retrieve an instance", - "description": "Retrieves the details for an NGINX instance, including\n* Hostname\n* System status\n* Timestamps of key actions (registration, last reported, etc.)\n* NGINX build information\n* Certificate data\n* Operating system version\n* NGINX Agent version\n* Config Sync Group membership details\n", - "operationId": "getInstance", - "parameters": [ - { - "$ref": "#/components/parameters/InstanceParamObjectID" - } + "Certificates" ], + "summary": "Retrieve an SSL certificate", + "operationId": "getCertificate", + "description": "Retrieves the details for an SSL certificate, including:\n* Object ID that uniquely identifies this certificate object\n* SSL certificate type (managed or unmanaged by NGINX One Console)\n* Certificate type (whether it is a CA bundle or a certificate-key pair)\n* Subject name of the leaf certificate, or the soonest-expiring CA in a bundle\n * This subject name will be the DNS name in the SAN extension of the certificate. If not present, it will be the certificate's common name\n* Status of the certificate (valid, expiring, expired)\n* Validity period, if applicable to multiple certificates\n* Metadata for each public certificate if multiples are provided\n* Private key metadata, if available\n", "responses": { "200": { - "description": "Successfully retrieved the details of the NGINX instance.", + "description": "Successfully retrieved the details of the SSL certificate.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/InstanceDetails" + "$ref": "#/components/schemas/CertificateResponse" } } } @@ -739,7 +701,7 @@ } }, "404": { - "description": "The NGINX instance with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", + "description": "The SSL certificate 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": { @@ -760,36 +722,44 @@ } } }, - "delete": { + "parameters": [ + { + "$ref": "#/components/parameters/CertificateParamObjectID" + } + ], + "patch": { + "x-nginx-one-action": "update", + "x-nginx-one-entity": "NGINX certificate", + "x-feature-flag": "cert-mgmt", "tags": [ - "Instances" + "Certificates" ], - "x-nginx-one-action": "delete", - "x-nginx-one-entity": "NGINX instance", - "summary": "Delete an instance", - "description": "Deletes an NGINX instance. Associations with certificates will be cleaned up.\n", - "operationId": "deleteInstance", - "parameters": [ - { - "$ref": "#/components/parameters/InstanceParamObjectID" + "summary": "Update an SSL certificate", + "operationId": "updateCertificate", + "description": "Updates public certificates, private keys, or both. \nThis endpoint can also be used to update a Certificate Authority (CA) bundle.\n", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CertificateUpdateRequest" + } + } } - ], + }, "responses": { - "204": { - "description": "Successfully deleted the NGINX instance." - }, - "401": { - "description": "Access denied.", + "200": { + "description": "Successfully updated the specified SSL certificate.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Error" + "$ref": "#/components/schemas/CertificateResponse" } } } }, - "404": { - "description": "The NGINX instance with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", + "400": { + "description": "Request cannot be processed due to invalid input or parameters. Verify the request format and provided data.", "content": { "application/json": { "schema": { @@ -798,8 +768,8 @@ } } }, - "500": { - "description": "An unexpected error occurred on the server. Please try the request again later.", + "401": { + "description": "Access denied.", "content": { "application/json": { "schema": { @@ -807,39 +777,9 @@ } } } - } - } - } - }, - "/instances/{instanceObjectID}/config-report": { - "parameters": [ - { - "$ref": "#/components/parameters/InstanceParamObjectID" - } - ], - "get": { - "tags": [ - "Instances" - ], - "summary": "Retrieve an analysis report for an instance's configuration", - "description": "Analyzes the configuration of an NGINX instance and returns a detailed report.\nThe report includes insights, identified issues, and recommendations for optimizing and troubleshooting.\n", - "operationId": "getInstanceConfigReport", - "responses": { - "200": { - "description": "Successfully retrieved the NGINX configuration analysis for the specified instance.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NginxConfigReports" - } - } - } - }, - "204": { - "description": "The requested instance 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 instance with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", + "description": "The SSL certificate 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": { @@ -859,43 +799,53 @@ } } } - }, - "put": { + } + }, + "/certificates/{certificateObjectID}/deployments": { + "get": { + "x-feature-flag": "cert-mgmt", "tags": [ - "Instances" + "Certificates" ], - "x-nginx-one-action": "analyze", - "x-nginx-one-entity": "NGINX instance configuration", - "summary": "Generate an analysis report for the provided configuration", - "description": "Returns an analysis report for the provided NGINX configuration. This report includes insights, identified issues, and recommendations for optimizing and troubleshooting. Note that this operation is for analysis purposes only and does not apply any changes to the configuration. The report is not stored and is provided only in the API response. To publish the configuration, use the `PUT /instances/{instanceObjectID}/config` endpoint.", - "operationId": "analyzeInstanceConfig", - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NginxConfigRequest" - } - } + "summary": "List SSL certificate deployments", + "description": "Returns a paginated list showing all the deployments for a SSL certificate and assigned file path(s).\n", + "parameters": [ + { + "$ref": "#/components/parameters/CertificateParamObjectID" + }, + { + "$ref": "#/components/parameters/Paginated" + }, + { + "$ref": "#/components/parameters/Limit" + }, + { + "$ref": "#/components/parameters/Offset" + }, + { + "$ref": "#/components/parameters/FilterFieldCertificateDeployments" + }, + { + "$ref": "#/components/parameters/FilterOperands" + }, + { + "$ref": "#/components/parameters/FilterValues" + }, + { + "$ref": "#/components/parameters/SortDirection" + }, + { + "$ref": "#/components/parameters/SortNameCertificateDeployments" } - }, + ], + "operationId": "listCertificateDeployments", "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.", + "description": "Successfully retrieved the list of SSL certificate deployments.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Error" + "$ref": "#/components/schemas/CertificateDeploymentListResponse" } } } @@ -911,7 +861,7 @@ } }, "404": { - "description": "The NGINX instance with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", + "description": "The SSL certificate 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": { @@ -931,33 +881,36 @@ } } } - }, - "patch": { + } + }, + "/certificates/parse": { + "post": { + "x-feature-flag": "cert-mgmt", + "x-nginx-one-action": "validate", + "x-nginx-one-entity": "NGINX certificate", "tags": [ - "Instances" + "Certificates" ], - "x-nginx-one-action": "analyze", - "x-nginx-one-entity": "NGINX instance configuration", - "summary": "Generate an analysis report for the provided modified configuration", - "description": "Analyzes the provided partial updates to an existing NGINX configuration and generates a report detailing potential issues along with optimization suggestions. \nThis analysis accounts for additive updates made to `NginxConfig`. To delete files, omit the `file.contents` field. \nThis method compares the provided `config_version` with the current NGINX instance configuration to detect conflicts, which may arise if the `config_version` does not match due to an out-of-band update. \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 /instances/{instanceObjectID}/config` endpoint.\n", - "operationId": "analyzeInstanceConfigWithModify", + "summary": "Parse and validate an SSL certificate", + "operationId": "parseCertificate", + "description": "Parses and validates an SSL certificate. \nIt checks the provided PEM files and verifies that the public certificates follow the correct X.509 format. \nIf the certificate cannot be parsed, an error will be returned. \nOtherwise, as long as the certificate is parsable, a `200 OK` status will be returned even if there are issues \nsuch as mismatched private keys or expired certificates. Details of any issues found will be shown in the \"warnings\" field of the response.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/NginxConfigRequest" + "$ref": "#/components/schemas/CertificateRequest" } } } }, "responses": { "200": { - "description": "Successfully analyzed the provided NGINX configuration.", + "description": "Successfully parsed and validated the SSL certificate.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/NginxConfigReports" + "$ref": "#/components/schemas/CertificateResponse" } } } @@ -982,16 +935,6 @@ } } }, - "404": { - "description": "The NGINX instance 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": { @@ -1005,26 +948,47 @@ } } }, - "/instances/{instanceObjectID}/config": { - "parameters": [ - { - "$ref": "#/components/parameters/InstanceParamObjectID" - } - ], + "/config-sync-groups": { "get": { "tags": [ - "Instances" + "Config Sync Groups" + ], + "summary": "List all config sync groups", + "operationId": "listConfigSyncGroups", + "description": "Returns a list of all NGINX config sync groups, providing details such as:\n * Name of the config sync group\n * List of instance with details\n * Version of the NGINX configuration that's expected to be on all listed instances\n * Status of apply configuration operation \n * Timestamp of last reported action\n", + "parameters": [ + { + "$ref": "#/components/parameters/Paginated" + }, + { + "$ref": "#/components/parameters/Limit" + }, + { + "$ref": "#/components/parameters/Offset" + }, + { + "$ref": "#/components/parameters/FilterFieldConfigSyncGroups" + }, + { + "$ref": "#/components/parameters/FilterOperands" + }, + { + "$ref": "#/components/parameters/FilterValues" + }, + { + "$ref": "#/components/parameters/SortDirection" + }, + { + "$ref": "#/components/parameters/SortNameConfigSyncGroups" + } ], - "summary": "Retrieve an instance's configuration details", - "description": "Returns the configuration details for an NGINX instance, including: \n* Main configuration path\n* Details about configuration files\n* Details about auxiliary files\n* Details about deployed payloads of managed SSL certificates and keys\n* Unique identifiers\n", - "operationId": "getInstanceConfig", "responses": { "200": { - "description": "Successfully retrieved the configuration details for the specified NGINX instance.", + "description": "Successfully retrieved the list of NGINX config sync groups.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/NginxConfig" + "$ref": "#/components/schemas/ConfigSyncGroupListResponse" } } } @@ -1039,16 +1003,6 @@ } } }, - "404": { - "description": "The NGINX instance 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": { @@ -1061,42 +1015,32 @@ } } }, - "put": { + "patch": { + "x-nginx-one-action": "bulk", + "x-nginx-one-entity": "config sync group", "tags": [ - "Instances" + "Config Sync Groups" ], - "x-nginx-one-action": "create", - "x-nginx-one-entity": "NGINX instance configuration", - "summary": "Publish a configuration to an instance", - "description": "Publishes a new or updated NGINX configuration to the specified instance. \nIf no existing configuration is found, a new one is created; otherwise, the current configuration is overwritten. \nBefore publishing, use the `PUT /instances/{instanceObjectID}/config-report` endpoint to generate an analysis report for the provided configuration.\nYou can specify `payloads` in the request to deploy managed certificates and keys to the dataplane. Include file paths\nfor each payload component.\n", - "operationId": "publishInstanceConfig", + "summary": "Bulk operation on multiple config sync groups.", + "operationId": "BulkConfigSyncGroups", + "description": "Performs bulk operation on one or more config sync groups, only delete is supported.", "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/NginxConfigRequest" + "$ref": "#/components/schemas/ConfigSyncGroupBulkRequest" } } } }, "responses": { - "202": { - "description": "The request to publish the configuration has been accepted and is being processed. To check the publication status, make a GET request to /instances/{instanceObjectID}/publications.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PublicationInstance" - } - } - } - }, - "400": { - "description": "Request cannot be processed due to invalid input or parameters. Verify the request format and provided data.", + "200": { + "description": "Batch request completed.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Error" + "$ref": "#/components/schemas/ConfigSyncGroupBulkResponse" } } } @@ -1111,16 +1055,6 @@ } } }, - "404": { - "description": "The NGINX instance 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": { @@ -1133,48 +1067,38 @@ } } }, - "patch": { + "post": { + "x-nginx-one-action": "create", + "x-nginx-one-entity": "NGINX config sync group", "tags": [ - "Instances" + "Config Sync Groups" ], - "x-nginx-one-action": "update", - "x-nginx-one-entity": "NGINX instance configuration", - "summary": "Apply partial updates to an instance's configuration", - "description": "Applies the specified partial updates to an existing NGINX configuration. \nThis endpoint accepts additive updates to `NginxConfig`. \nTo delete files, omit the `file.contents` field. \nThis method compares the provided config_version with the current NGINX instance configuration to detect conflicts, which may arise if the config_version does not match due to an out-of-band update. \nBefore publishing, use the `PATCH /instances/{instanceObjectID}/config-report` endpoint to generate an analysis report for the modified configuration.\n", - "operationId": "publishInstanceConfigWithModify", + "summary": "Create an NGINX config sync group", + "operationId": "createConfigSyncGroup", + "description": "Create NGINX config sync group with a unique name to identify it within the tenant namespace.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/NginxConfigRequest" + "$ref": "#/components/schemas/ConfigSyncGroupCreateRequest" } } } }, "responses": { - "202": { - "description": "The request to publish the configuration has been accepted and is being processed. To check the publication status, make a GET request to /instances/{instanceObjectID}/publications.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PublicationInstance" - } - } - } - }, - "400": { - "description": "Request cannot be processed due to invalid input or parameters. Verify the request format and provided data.", + "200": { + "description": "Successfully created NGINX config sync group", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Error" + "$ref": "#/components/schemas/ConfigSyncGroupCreateResponse" } } } }, "401": { - "description": "Access denied.", + "description": "Access denied", "content": { "application/json": { "schema": { @@ -1183,8 +1107,8 @@ } } }, - "404": { - "description": "The NGINX instance with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", + "409": { + "description": "The NGINX config sync group can't be created because the name is already in use", "content": { "application/json": { "schema": { @@ -1206,35 +1130,22 @@ } } }, - "/instances/{instanceObjectID}/configs": { - "parameters": [ - { - "$ref": "#/components/parameters/InstanceParamObjectID" - } - ], - "get": { + "/config-sync-groups/{configSyncGroupObjectID}": { + "delete": { + "x-nginx-one-action": "delete", + "x-nginx-one-entity": "NGINX config sync group", "tags": [ - "Instances" + "Config Sync Groups" ], - "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 the NGINX One Console for a NGINX instance.", - "operationId": "listInstanceConfigurations", + "summary": "Delete an NGINX config sync group", + "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": { - "200": { - "description": "Successfully retrieved the list of NGINX configurations for the specified NGINX instance.", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/NginxConfigMeta" - } - } - } - } + "204": { + "description": "Successfully deleted the NGINX config sync group" }, "401": { - "description": "Access denied.", + "description": "Access denied", "content": { "application/json": { "schema": { @@ -1244,7 +1155,7 @@ } }, "404": { - "description": "The NGINX instance with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", + "description": "The NGINX config sync group 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": { @@ -1264,37 +1175,27 @@ } } } - } - }, - "/instances/{instanceObjectID}/configs/{instanceConfigurationObjectID}": { - "parameters": [ - { - "$ref": "#/components/parameters/InstanceParamObjectID" - }, - { - "$ref": "#/components/parameters/InstanceConfigurationParamObjectID" - } - ], + }, "get": { "tags": [ - "Instances" + "Config Sync Groups" ], - "summary": "Retrieve an instance's configuration details", - "description": "Returns the configuration details for an NGINX instance, including: \n* Main configuration path\n* Details about configuration files\n* Details about auxiliary files\n* Unique identifiers\n", - "operationId": "getInstanceConfigWithObjectID", + "summary": "Retrieve an NGINX config sync group", + "description": "Retrieve the details for an NGINX config sync group, including:\n* name\n* Instances and details of each instance\n* Timestamp of last reported action\n* NGINX config version on the config sync group\n* Certificate summary referenced by config sync group members\n* NGINX config sync operation status\n* Last config sync group publication operation status\n", + "operationId": "getConfigSyncGroup", "responses": { "200": { - "description": "Successfully retrieved the configuration details for the specified NGINX instance and NGINX configuration.", + "description": "Successfully retrieved the details of the NGINX config sync group.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/NginxConfig" + "$ref": "#/components/schemas/ConfigSyncGroupDetails" } } } }, "401": { - "description": "Access denied.", + "description": "Access denied", "content": { "application/json": { "schema": { @@ -1304,7 +1205,7 @@ } }, "404": { - "description": "The NGINX instance or NGINX configuration with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", + "description": "The NGINX config sync group 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": { @@ -1324,31 +1225,28 @@ } } } - } + }, + "parameters": [ + { + "$ref": "#/components/parameters/ConfigSyncGroupParamObjectID" + } + ] }, - "/instances/{instanceObjectID}/publications": { + "/config-sync-groups/{configSyncGroupObjectID}/config": { "get": { "tags": [ - "Instances" - ], - "summary": "Retrieve the publications for an instance", - "description": "Returns a list of all publications for a NGINX instance.", - "operationId": "listInstancePublications", - "parameters": [ - { - "$ref": "#/components/parameters/InstanceParamObjectID" - } + "Config Sync Groups" ], + "summary": "Retrieve a config sync group's configuration details", + "description": "Returns the configuration details for a NGINX config sync group, including: \n* Main configuration path\n* Details about configuration files\n* Details about auxiliary files\n* Unique identifiers\n", + "operationId": "getConfigSyncGroupConfig", "responses": { "200": { - "description": "Successfully retrieved the list of all publications for the specified NGINX instance.", + "description": "Successfully retrieved the configuration details for the specified NGINX config sync group.", "content": { "application/json": { "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PublicationInstance" - } + "$ref": "#/components/schemas/NginxConfig" } } } @@ -1363,6 +1261,16 @@ } } }, + "404": { + "description": "The NGINX config sync group 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": { @@ -1374,27 +1282,44 @@ } } } - } - }, - "/instances/{instanceObjectID}/publications/{publicationObjectID}": { - "get": { + }, + "parameters": [ + { + "$ref": "#/components/parameters/ConfigSyncGroupParamObjectID" + } + ], + "patch": { "tags": [ - "Instances" + "Config Sync Groups" ], - "summary": "Retrieve a publication for an NGINX instance.", - "description": "Returns a specific publication for an NGINX instance. Only 5 previous entries of Publication are kept for each NGINX instance.", - "operationId": "getInstancePublication", - "parameters": [ - { - "$ref": "#/components/parameters/InstanceParamObjectID" - }, - { - "$ref": "#/components/parameters/PublicationParamObjectID" + "x-nginx-one-action": "update", + "x-nginx-one-entity": "NGINX config sync group configuration", + "summary": "Apply partial updates to config sync group's configuration", + "description": "Applies the specified partial updates to an existing NGINX configuration. Details:\n * This endpoint accepts additive updates to `NginxConfig`. \n * To delete files, omit the `file.contents` field. \n * This method compares the provided config_version with the current NGINX config sync group configuration to detect conflicts, which may arise if the config_version does not match due to an out-of-band update.\n", + "operationId": "patchConfigSyncGroupConfig", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NginxConfigRequest" + } + } } - ], + }, "responses": { "200": { - "description": "Successfully retrieved the specific Publication for the specified NGINX instance.", + "description": "Successfully stored the configuration of the NGINX config sync group", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NginxConfig" + } + } + } + }, + "202": { + "description": "The request to publish the configuration has been accepted and is being processed. To check the publication status, make a GET request to /config-sync-groups/{configSyncGroupObjectID}/publications.", "content": { "application/json": { "schema": { @@ -1403,8 +1328,18 @@ } } }, + "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.", + "description": "Access denied", "content": { "application/json": { "schema": { @@ -1414,7 +1349,7 @@ } }, "404": { - "description": "The NGINX instance or Publication with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", + "description": "The NGINX config sync group 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": { @@ -1434,35 +1369,53 @@ } } } - } - }, - "/config-sync-groups": { - "post": { - "x-nginx-one-action": "create", - "x-nginx-one-entity": "NGINX config sync group", + }, + "put": { "tags": [ "Config Sync Groups" ], - "summary": "Create an NGINX config sync group", - "operationId": "createConfigSyncGroup", - "description": "Create NGINX config sync group with a unique name to identify it within the tenant namespace.\n", + "x-nginx-one-action": "create", + "x-nginx-one-entity": "NGINX config sync group configuration", + "summary": "Publish a configuration to NGINX config sync group", + "description": "Publishes a new or updated NGINX configuration to the specified config sync group. \nIf no existing configuration is found, a new one is created; otherwise, the current configuration is overwritten.\n", + "operationId": "publishConfigSyncGroupConfig", "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ConfigSyncGroupCreateRequest" + "$ref": "#/components/schemas/NginxConfigRequest" } } } }, "responses": { "200": { - "description": "Successfully created NGINX config sync group", + "description": "Successfully stored the configuration of the NGINX config sync group.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ConfigSyncGroupCreateResponse" + "$ref": "#/components/schemas/NginxConfig" + } + } + } + }, + "202": { + "description": "The request to publish the configuration has been accepted and is being processed. To check the publication status, make a GET request to /config-sync-groups/{configSyncGroupObjectID}/publications.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConfigSyncGroupPublication" + } + } + } + }, + "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" } } } @@ -1477,8 +1430,8 @@ } } }, - "409": { - "description": "The NGINX config sync group can't be created because the name is already in use", + "404": { + "description": "The NGINX config sync group 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": { @@ -1498,53 +1451,32 @@ } } } - }, + } + }, + "/config-sync-groups/{configSyncGroupObjectID}/config-report": { "get": { "tags": [ "Config Sync Groups" ], - "summary": "List all config sync groups", - "operationId": "listConfigSyncGroups", - "description": "Returns a list of all NGINX config sync groups, providing details such as:\n * Name of the config sync group\n * List of instance with details\n * Version of the NGINX configuration that's expected to be on all listed instances\n * Status of apply configuration operation \n * Timestamp of last reported action\n", - "parameters": [ - { - "$ref": "#/components/parameters/Paginated" - }, - { - "$ref": "#/components/parameters/Limit" - }, - { - "$ref": "#/components/parameters/Offset" - }, - { - "$ref": "#/components/parameters/FilterFieldConfigSyncGroups" - }, - { - "$ref": "#/components/parameters/FilterOperands" - }, - { - "$ref": "#/components/parameters/FilterValues" - }, - { - "$ref": "#/components/parameters/SortDirection" - }, - { - "$ref": "#/components/parameters/SortNameConfigSyncGroups" - } - ], + "summary": "Retrieve an analysis report for the configuration of an NGINX config sync group", + "description": "Analyzes the configuration of an NGINX config sync group and returns a detailed report.\nThe report includes insights, identified issues, and recommendations for optimizing and troubleshooting.\n", + "operationId": "getConfigSyncGroupConfigReport", "responses": { "200": { - "description": "Successfully retrieved the list of NGINX config sync groups.", + "description": "Successfully retrieved the NGINX configuration analysis for the specified config sync group.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ConfigSyncGroupListResponse" + "$ref": "#/components/schemas/NginxConfigReports" } } } }, - "401": { - "description": "Access denied.", + "204": { + "description": "The requested config sync group 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 config sync group 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": { @@ -1565,38 +1497,63 @@ } } }, + "parameters": [ + { + "$ref": "#/components/parameters/ConfigSyncGroupParamObjectID" + } + ], "patch": { - "x-nginx-one-action": "bulk", - "x-nginx-one-entity": "config sync group", + "x-nginx-one-action": "analyze", + "x-nginx-one-entity": "NGINX config sync group configuration", "tags": [ "Config Sync Groups" ], - "summary": "Bulk operation on multiple config sync groups.", - "operationId": "BulkConfigSyncGroups", - "description": "Performs bulk operation on one or more config sync groups, only delete is supported.", + "summary": "Generate an analysis report for the configuration of the modified NGINX config sync group", + "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. \nThis method compares the provided `config_version` with the current NGINX config sync group's configuration to detect conflicts, which may arise if the `config_version` does not match due to an out-of-band update. \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 /config-sync-groups/{configSyncGroupObjectID}/config` endpoint.\n", + "operationId": "analyzeConfigSyncGroupConfigPatch", "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ConfigSyncGroupBulkRequest" + "$ref": "#/components/schemas/NginxConfigRequest" } } } }, "responses": { "200": { - "description": "Batch request completed.", + "description": "Successfully analyzed the provided NGINX configuration", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ConfigSyncGroupBulkResponse" + "$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.", + "description": "Access denied", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "The NGINX config sync group 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": { @@ -1616,28 +1573,43 @@ } } } - } - }, - "/config-sync-groups/{configSyncGroupObjectID}": { - "parameters": [ - { - "$ref": "#/components/parameters/ConfigSyncGroupParamObjectID" - } - ], - "get": { + }, + "put": { + "x-nginx-one-action": "analyze", + "x-nginx-one-entity": "NGINX config sync group configuration", "tags": [ "Config Sync Groups" ], - "summary": "Retrieve an NGINX config sync group", - "description": "Retrieve the details for an NGINX config sync group, including:\n* name\n* Instances and details of each instance\n* Timestamp of last reported action\n* NGINX config version on the config sync group\n* Certificate summary referenced by config sync group members\n* NGINX config sync operation status\n* Last config sync group publication operation status\n", - "operationId": "getConfigSyncGroup", + "summary": "Generate an analysis report for the configuration of the NGINX config sync group", + "description": "Returns an analysis report for the configuration of the NGINX config sync group. This report includes insights, identified issues, and recommendations for optimizing and troubleshooting. Note that this operation is for analysis purposes only and does not apply any changes to the configuration. The report is not stored and is provided only in the API response. To publish the configuration, use the `PUT /config-sync-groups/{configSyncGroupObjectID}/config` endpoint.", + "operationId": "analyzeConfigSyncGroupConfig", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NginxConfigRequest" + } + } + } + }, "responses": { "200": { - "description": "Successfully retrieved the details of the NGINX config sync group.", + "description": "Successfully analyzed the provided NGINX configuration.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ConfigSyncGroupDetails" + "$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" } } } @@ -1673,19 +1645,26 @@ } } } - }, - "delete": { - "x-nginx-one-action": "delete", - "x-nginx-one-entity": "NGINX config sync group", + } + }, + "/config-sync-groups/{configSyncGroupObjectID}/config/{configSyncGroupConfigurationObjectID}": { + "get": { "tags": [ "Config Sync Groups" ], - "summary": "Delete an NGINX config sync group", - "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", + "summary": "Retrieve details the NGINX config sync group", + "description": "Returns the configuration details for an NGINX config sync group, including: \n* Main configuration path\n* Details about configuration files\n* Details about auxiliary files\n* Unique identifiers\n", + "operationId": "getConfigSyncGroupConfigWithObjectID", "responses": { - "204": { - "description": "Successfully deleted the NGINX config sync group" + "200": { + "description": "Successfully retrieved the configuration details for the specified NGINX config sync group and NGINX configuration.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NginxConfig" + } + } + } }, "401": { "description": "Access denied", @@ -1698,7 +1677,7 @@ } }, "404": { - "description": "The NGINX config sync group with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", + "description": "The NGINX config sync group or NGINX configuration 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": { @@ -1718,34 +1697,40 @@ } } } - } - }, - "/config-sync-groups/{configSyncGroupObjectID}/config": { + }, "parameters": [ { "$ref": "#/components/parameters/ConfigSyncGroupParamObjectID" + }, + { + "$ref": "#/components/parameters/ConfigSyncGroupConfigurationParamObjectID" } - ], + ] + }, + "/config-sync-groups/{configSyncGroupObjectID}/configs": { "get": { "tags": [ "Config Sync Groups" ], - "summary": "Retrieve a config sync group's configuration details", - "description": "Returns the configuration details for a NGINX config sync group, including: \n* Main configuration path\n* Details about configuration files\n* Details about auxiliary files\n* Unique identifiers\n", - "operationId": "getConfigSyncGroupConfig", + "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 the NGINX One Console for a NGINX config sync group.", + "operationId": "listConfigSyncGroupConfigurations", "responses": { "200": { - "description": "Successfully retrieved the configuration details for the specified NGINX config sync group.", + "description": "Successfully retrieved the list of NGINX configurations for the specified NGINX config sync group.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/NginxConfig" + "type": "array", + "items": { + "$ref": "#/components/schemas/NginxConfigMeta" + } } } } }, "401": { - "description": "Access denied.", + "description": "Access denied", "content": { "application/json": { "schema": { @@ -1776,52 +1761,30 @@ } } }, - "put": { + "parameters": [ + { + "$ref": "#/components/parameters/ConfigSyncGroupParamObjectID" + } + ] + }, + "/config-sync-groups/{configSyncGroupObjectID}/publications": { + "get": { "tags": [ "Config Sync Groups" ], - "x-nginx-one-action": "create", - "x-nginx-one-entity": "NGINX config sync group configuration", - "summary": "Publish a configuration to NGINX config sync group", - "description": "Publishes a new or updated NGINX configuration to the specified config sync group. \nIf no existing configuration is found, a new one is created; otherwise, the current configuration is overwritten.\n", - "operationId": "publishConfigSyncGroupConfig", - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NginxConfigRequest" - } - } - } - }, + "summary": "Retrieve the publications for the NGINX config sync group", + "description": "Returns a list of publications for a NGINX config sync group, providing details such as:\n * Current status along with reason(s) including the target instance object, cause and relevant message\n * Configuration version\n", + "operationId": "listConfigSyncGroupPublications", "responses": { "200": { - "description": "Successfully stored the configuration of the NGINX config sync group.", + "description": "Successfully retrieved the list of all publications for the specified NGINX config sync group.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/NginxConfig" - } - } - } - }, - "202": { - "description": "The request to publish the configuration has been accepted and is being processed. To check the publication status, make a GET request to /config-sync-groups/{configSyncGroupObjectID}/publications.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ConfigSyncGroupPublication" - } - } - } - }, - "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" + "type": "array", + "items": { + "$ref": "#/components/schemas/ConfigSyncGroupPublication" + } } } } @@ -1858,52 +1821,27 @@ } } }, - "patch": { + "parameters": [ + { + "$ref": "#/components/parameters/ConfigSyncGroupParamObjectID" + } + ] + }, + "/config-sync-groups/{configSyncGroupObjectID}/publications/{publicationObjectID}": { + "get": { "tags": [ "Config Sync Groups" ], - "x-nginx-one-action": "update", - "x-nginx-one-entity": "NGINX config sync group configuration", - "summary": "Apply partial updates to config sync group's configuration", - "description": "Applies the specified partial updates to an existing NGINX configuration. Details:\n * This endpoint accepts additive updates to `NginxConfig`. \n * To delete files, omit the `file.contents` field. \n * This method compares the provided config_version with the current NGINX config sync group configuration to detect conflicts, which may arise if the config_version does not match due to an out-of-band update.\n", - "operationId": "patchConfigSyncGroupConfig", - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NginxConfigRequest" - } - } - } - }, + "summary": "Retrieve the publications for the NGINX config sync group, providing details such as:\n * Current status along with reason(s) including the target instance object, cause and relevant message\n * Configuration version\n", + "description": "Returns a publication for a NGINX config sync group.", + "operationId": "getConfigSyncGroupPublication", "responses": { "200": { - "description": "Successfully stored the configuration of the NGINX config sync group", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NginxConfig" - } - } - } - }, - "202": { - "description": "The request to publish the configuration has been accepted and is being processed. To check the publication status, make a GET request to /config-sync-groups/{configSyncGroupObjectID}/publications.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PublicationInstance" - } - } - } - }, - "400": { - "description": "Request cannot be processed due to invalid input or parameters. Verify the request format and provided data.", + "description": "Successfully retrieved the publication for the specified NGINX config sync group.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Error" + "$ref": "#/components/schemas/ConfigSyncGroupPublication" } } } @@ -1939,47 +1877,54 @@ } } } - } - }, - "/config-sync-groups/{configSyncGroupObjectID}/configs": { + }, "parameters": [ { "$ref": "#/components/parameters/ConfigSyncGroupParamObjectID" + }, + { + "$ref": "#/components/parameters/PublicationParamObjectID" } - ], + ] + }, + "/cves": { "get": { "tags": [ - "Config Sync Groups" + "CVEs" + ], + "summary": "List of all CVEs affecting the instances", + "operationId": "listNginxCVEs", + "description": "Returns a list of all CVEs that affect at least one instance under the tenant\n", + "parameters": [ + { + "$ref": "#/components/parameters/Paginated" + }, + { + "$ref": "#/components/parameters/Limit" + }, + { + "$ref": "#/components/parameters/Offset" + }, + { + "$ref": "#/components/parameters/SortDirection" + }, + { + "$ref": "#/components/parameters/SortNameCVEs" + } ], - "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 the NGINX One Console for a NGINX config sync group.", - "operationId": "listConfigSyncGroupConfigurations", "responses": { "200": { - "description": "Successfully retrieved the list of NGINX configurations for the specified NGINX config sync group.", + "description": "Successfully retrieved the list of CVEs.", "content": { "application/json": { "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/NginxConfigMeta" - } + "$ref": "#/components/schemas/CVEListResponse" } } } }, "401": { - "description": "Access denied", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "404": { - "description": "The NGINX config sync group with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", + "description": "Access denied.", "content": { "application/json": { "schema": { @@ -2001,35 +1946,32 @@ } } }, - "/config-sync-groups/{configSyncGroupObjectID}/config/{configSyncGroupConfigurationObjectID}": { - "parameters": [ - { - "$ref": "#/components/parameters/ConfigSyncGroupParamObjectID" - }, - { - "$ref": "#/components/parameters/ConfigSyncGroupConfigurationParamObjectID" - } - ], + "/cves/{nginxCVEID}": { "get": { "tags": [ - "Config Sync Groups" + "CVEs" + ], + "summary": "Retrieve NGINX CVE details", + "operationId": "GetNginxCVEDetails", + "description": "Retrieve CVE details\n", + "parameters": [ + { + "$ref": "#/components/parameters/NginxCVEParamID" + } ], - "summary": "Retrieve details the NGINX config sync group", - "description": "Returns the configuration details for an NGINX config sync group, including: \n* Main configuration path\n* Details about configuration files\n* Details about auxiliary files\n* Unique identifiers\n", - "operationId": "getConfigSyncGroupConfigWithObjectID", "responses": { "200": { - "description": "Successfully retrieved the configuration details for the specified NGINX config sync group and NGINX configuration.", + "description": "Successfully retrieved NGINX CVE details.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/NginxConfig" + "$ref": "#/components/schemas/NginxCVEDetailsResponse" } } } }, "401": { - "description": "Access denied", + "description": "Access denied.", "content": { "application/json": { "schema": { @@ -2039,7 +1981,7 @@ } }, "404": { - "description": "The NGINX config sync group or NGINX configuration with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", + "description": "CVE with the specified nginxCVEID was not found. Check that the nginxCVEID provided is correct and corresponds to an existing resource.", "content": { "application/json": { "schema": { @@ -2061,35 +2003,47 @@ } } }, - "/config-sync-groups/{configSyncGroupObjectID}/publications": { - "parameters": [ - { - "$ref": "#/components/parameters/ConfigSyncGroupParamObjectID" - } - ], + "/cves/{nginxCVEID}/impacted_instances": { "get": { "tags": [ - "Config Sync Groups" + "CVEs" + ], + "summary": "Retrieve the instances impacted by a CVE", + "description": "Retrieves a list of the instances impacted by a security advisory.", + "operationId": "listCVEImpactedInstances", + "parameters": [ + { + "$ref": "#/components/parameters/Paginated" + }, + { + "$ref": "#/components/parameters/Limit" + }, + { + "$ref": "#/components/parameters/Offset" + }, + { + "$ref": "#/components/parameters/SortDirection" + }, + { + "$ref": "#/components/parameters/SortNameCVEImpactedInstances" + }, + { + "$ref": "#/components/parameters/NginxCVEParamID" + } ], - "summary": "Retrieve the publications for the NGINX config sync group", - "description": "Returns a list of publications for a NGINX config sync group, providing details such as:\n * Current status along with reason(s) including the target instance object, cause and relevant message\n * Configuration version\n", - "operationId": "listConfigSyncGroupPublications", "responses": { "200": { - "description": "Successfully retrieved the list of all publications for the specified NGINX config sync group.", + "description": "Successfully retrieved the list of instances affected by the CVE", "content": { "application/json": { "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ConfigSyncGroupPublication" - } + "$ref": "#/components/schemas/CVEImpactedInstancesListResponse" } } } }, "401": { - "description": "Access denied", + "description": "Access denied.", "content": { "application/json": { "schema": { @@ -2099,7 +2053,7 @@ } }, "404": { - "description": "The NGINX config sync group with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", + "description": "The CVE with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing CVE.", "content": { "application/json": { "schema": { @@ -2121,35 +2075,47 @@ } } }, - "/config-sync-groups/{configSyncGroupObjectID}/publications/{publicationObjectID}": { - "parameters": [ - { - "$ref": "#/components/parameters/ConfigSyncGroupParamObjectID" - }, - { - "$ref": "#/components/parameters/PublicationParamObjectID" - } - ], + "/events": { "get": { "tags": [ - "Config Sync Groups" + "Events" + ], + "summary": "Retrieve system events.", + "description": "Retrieves a list of the system events.", + "operationId": "listEvents", + "parameters": [ + { + "$ref": "#/components/parameters/Paginated" + }, + { + "$ref": "#/components/parameters/Limit" + }, + { + "$ref": "#/components/parameters/Offset" + }, + { + "$ref": "#/components/parameters/FilterFieldEvents" + }, + { + "$ref": "#/components/parameters/FilterOperands" + }, + { + "$ref": "#/components/parameters/FilterValues" + } ], - "summary": "Retrieve the publications for the NGINX config sync group, providing details such as:\n * Current status along with reason(s) including the target instance object, cause and relevant message\n * Configuration version\n", - "description": "Returns a publication for a NGINX config sync group.", - "operationId": "getConfigSyncGroupPublication", "responses": { "200": { - "description": "Successfully retrieved the publication for the specified NGINX config sync group.", + "description": "Successfully retrieved the list of events.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ConfigSyncGroupPublication" + "$ref": "#/components/schemas/EventsListResponse" } } } }, "401": { - "description": "Access denied", + "description": "Access denied.", "content": { "application/json": { "schema": { @@ -2158,18 +2124,8 @@ } } }, - "404": { - "description": "The NGINX config sync group 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.", + "500": { + "description": "An unexpected error occurred on the server. Please try the request again later.", "content": { "application/json": { "schema": { @@ -2181,35 +2137,42 @@ } } }, - "/config-sync-groups/{configSyncGroupObjectID}/config-report": { - "parameters": [ - { - "$ref": "#/components/parameters/ConfigSyncGroupParamObjectID" - } - ], + "/events/{eventObjectID}": { "get": { "tags": [ - "Config Sync Groups" + "Events" + ], + "operationId": "getEvent", + "summary": "Retrieve specific event.", + "description": "Retrieve a specific event using the event object_id.", + "parameters": [ + { + "$ref": "#/components/parameters/EventParamObjectID" + } ], - "summary": "Retrieve an analysis report for the configuration of an NGINX config sync group", - "description": "Analyzes the configuration of an NGINX config sync group and returns a detailed report.\nThe report includes insights, identified issues, and recommendations for optimizing and troubleshooting.\n", - "operationId": "getConfigSyncGroupConfigReport", "responses": { "200": { - "description": "Successfully retrieved the NGINX configuration analysis for the specified config sync group.", + "description": "Successfully retrieved the details of the event.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/NginxConfigReports" + "$ref": "#/components/schemas/Event" } } } }, - "204": { - "description": "The requested config sync group exists, but analysis of the NGINX configuration is not yet completed. Please retry the request at a later time to retrieve the report." + "401": { + "description": "Access denied.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "404": { - "description": "The NGINX config sync group with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", + "description": "The Event 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": { @@ -2229,59 +2192,55 @@ } } } - }, - "put": { - "x-nginx-one-action": "analyze", - "x-nginx-one-entity": "NGINX config sync group configuration", + } + }, + "/instances": { + "get": { "tags": [ - "Config Sync Groups" + "Instances" ], - "summary": "Generate an analysis report for the configuration of the NGINX config sync group", - "description": "Returns an analysis report for the configuration of the NGINX config sync group. This report includes insights, identified issues, and recommendations for optimizing and troubleshooting. Note that this operation is for analysis purposes only and does not apply any changes to the configuration. The report is not stored and is provided only in the API response. To publish the configuration, use the `PUT /config-sync-groups/{configSyncGroupObjectID}/config` endpoint.", - "operationId": "analyzeConfigSyncGroupConfig", - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NginxConfigRequest" - } - } + "summary": "List all instances", + "operationId": "listInstances", + "description": "Returns a list of all NGINX instances, providing details such as:\n * Unique identifiers for each instance\n * Timestamps for key actions (like registration and last report)\n * Information about the NGINX build\n * Version of the NGINX Agent\n", + "parameters": [ + { + "$ref": "#/components/parameters/Paginated" + }, + { + "$ref": "#/components/parameters/Limit" + }, + { + "$ref": "#/components/parameters/Offset" + }, + { + "$ref": "#/components/parameters/FilterFieldInstances" + }, + { + "$ref": "#/components/parameters/FilterOperands" + }, + { + "$ref": "#/components/parameters/FilterValues" + }, + { + "$ref": "#/components/parameters/SortDirection" + }, + { + "$ref": "#/components/parameters/SortNameInstances" } - }, + ], "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.", + "description": "Successfully retrieved the list of instances.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Error" + "$ref": "#/components/schemas/InstanceListResponse" } } } }, "401": { - "description": "Access denied", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "404": { - "description": "The NGINX config sync group with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", + "description": "Access denied.", "content": { "application/json": { "schema": { @@ -2303,57 +2262,37 @@ } }, "patch": { - "x-nginx-one-action": "analyze", - "x-nginx-one-entity": "NGINX config sync group configuration", + "x-nginx-one-action": "bulk", + "x-nginx-one-entity": "NGINX instance", "tags": [ - "Config Sync Groups" + "Instances" ], - "summary": "Generate an analysis report for the configuration of the modified NGINX config sync group", - "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. \nThis method compares the provided `config_version` with the current NGINX config sync group's configuration to detect conflicts, which may arise if the `config_version` does not match due to an out-of-band update. \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 /config-sync-groups/{configSyncGroupObjectID}/config` endpoint.\n", - "operationId": "analyzeConfigSyncGroupConfigPatch", + "summary": "Bulk operation on multiple instances.", + "operationId": "BulkInstances", + "description": "Performs bulk operation on one or more NGINX instances, only delete is supported.", "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/NginxConfigRequest" + "$ref": "#/components/schemas/InstanceBulkRequest" } } } }, "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.", + "description": "Batch request completed.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Error" + "$ref": "#/components/schemas/InstanceBulkResponse" } } } }, "401": { - "description": "Access denied", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "404": { - "description": "The NGINX config sync group with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", + "description": "Access denied.", "content": { "application/json": { "schema": { @@ -2375,54 +2314,37 @@ } } }, - "/certificates": { - "get": { - "x-feature-flag": "cert-mgmt", + "/instances/{instanceObjectID}": { + "delete": { "tags": [ - "Certificates" + "Instances" ], - "summary": "List all SSL certificates", - "description": "Returns a paginated list showing metadata for every SSL certificate.\n", + "x-nginx-one-action": "delete", + "x-nginx-one-entity": "NGINX instance", + "summary": "Delete an instance", + "description": "Deletes an NGINX instance. Associations with certificates will be cleaned up.\n", + "operationId": "deleteInstance", "parameters": [ { - "$ref": "#/components/parameters/Paginated" - }, - { - "$ref": "#/components/parameters/Limit" - }, - { - "$ref": "#/components/parameters/Offset" - }, - { - "$ref": "#/components/parameters/FilterFieldCertificates" - }, - { - "$ref": "#/components/parameters/FilterOperands" - }, - { - "$ref": "#/components/parameters/FilterValues" - }, - { - "$ref": "#/components/parameters/SortDirection" - }, - { - "$ref": "#/components/parameters/SortNameCertificates" + "$ref": "#/components/parameters/InstanceParamObjectID" } ], - "operationId": "listCertificates", "responses": { - "200": { - "description": "Successfully retrieved the list of SSL certificates.", + "204": { + "description": "Successfully deleted the NGINX instance." + }, + "401": { + "description": "Access denied.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CertificateListResponse" + "$ref": "#/components/schemas/Error" } } } }, - "401": { - "description": "Access denied.", + "404": { + "description": "The NGINX instance 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": { @@ -2443,39 +2365,31 @@ } } }, - "post": { - "x-nginx-one-action": "create", - "x-nginx-one-entity": "NGINX certificate", - "x-feature-flag": "cert-mgmt", + "get": { "tags": [ - "Certificates" + "Instances" ], - "summary": "Create an SSL certificate", - "operationId": "createCertificate", - "description": "Creates a new SSL certificate with an optional name. \nYou must supply the certificate's content in base64-encoded PEM format.\nAny warnings will be displayed only upon creation of the certificate object, and\nis not retrievable after it is created.\n", - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CertificateRequest" - } - } + "summary": "Retrieve an instance", + "description": "Retrieves the details for an NGINX instance, including\n* Hostname\n* System status\n* Timestamps of key actions (registration, last reported, etc.)\n* NGINX build information\n* Certificate data\n* Operating system version\n* NGINX Agent version\n* Config Sync Group membership details\n", + "operationId": "getInstance", + "parameters": [ + { + "$ref": "#/components/parameters/InstanceParamObjectID" } - }, + ], "responses": { "200": { - "description": "Successfully created the SSL certificate.", + "description": "Successfully retrieved the details of the NGINX instance.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CertificateResponse" + "$ref": "#/components/schemas/InstanceDetails" } } } }, - "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": { @@ -2484,8 +2398,8 @@ } } }, - "401": { - "description": "Access denied.", + "404": { + "description": "The NGINX instance 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": { @@ -2505,35 +2419,100 @@ } } } - }, - "patch": { - "x-nginx-one-action": "bulk", - "x-nginx-one-entity": "NGINX certificate", - "x-feature-flag": "cert-api-bulk", - "x-nodoc": true, + } + }, + "/instances/{instanceObjectID}/config": { + "get": { "tags": [ - "Certificates" + "Instances" + ], + "summary": "Retrieve an instance's configuration details", + "description": "Returns the configuration details for an NGINX instance, including: \n* Main configuration path\n* Details about configuration files\n* Details about auxiliary files\n* Details about deployed payloads of managed SSL certificates and keys\n* Unique identifiers\n", + "operationId": "getInstanceConfig", + "responses": { + "200": { + "description": "Successfully retrieved the configuration details for the specified NGINX instance.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NginxConfig" + } + } + } + }, + "401": { + "description": "Access denied.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "The NGINX instance 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/InstanceParamObjectID" + } + ], + "patch": { + "tags": [ + "Instances" ], - "summary": "Bulk operation on multiple managed certificates.", - "operationId": "bulkCertificates", - "description": "Performs bulk operation on one or more managed certificates, only delete is supported.", + "x-nginx-one-action": "update", + "x-nginx-one-entity": "NGINX instance configuration", + "summary": "Apply partial updates to an instance's configuration", + "description": "Applies the specified partial updates to an existing NGINX configuration. \nThis endpoint accepts additive updates to `NginxConfig`. \nTo delete files, omit the `file.contents` field. \nThis method compares the provided config_version with the current NGINX instance configuration to detect conflicts, which may arise if the config_version does not match due to an out-of-band update. \nBefore publishing, use the `PATCH /instances/{instanceObjectID}/config-report` endpoint to generate an analysis report for the modified configuration.\n", + "operationId": "publishInstanceConfigWithModify", "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CertificateBulkRequest" + "$ref": "#/components/schemas/NginxConfigRequest" } } } }, "responses": { - "200": { - "description": "Batch request completed.", + "202": { + "description": "The request to publish the configuration has been accepted and is being processed. To check the publication status, make a GET request to /instances/{instanceObjectID}/publications.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PublicationInstance" + } + } + } + }, + "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/CertificateBulkResponse" + "$ref": "#/components/schemas/Error" } } } @@ -2548,6 +2527,16 @@ } } }, + "404": { + "description": "The NGINX instance 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": { @@ -2559,36 +2548,33 @@ } } } - } - }, - "/certificates/parse": { - "post": { - "x-feature-flag": "cert-mgmt", - "x-nginx-one-action": "validate", - "x-nginx-one-entity": "NGINX certificate", + }, + "put": { "tags": [ - "Certificates" + "Instances" ], - "summary": "Parse and validate an SSL certificate", - "operationId": "parseCertificate", - "description": "Parses and validates an SSL certificate. \nIt checks the provided PEM files and verifies that the public certificates follow the correct X.509 format. \nIf the certificate cannot be parsed, an error will be returned. \nOtherwise, as long as the certificate is parsable, a `200 OK` status will be returned even if there are issues \nsuch as mismatched private keys or expired certificates. Details of any issues found will be shown in the \"warnings\" field of the response.\n", + "x-nginx-one-action": "create", + "x-nginx-one-entity": "NGINX instance configuration", + "summary": "Publish a configuration to an instance", + "description": "Publishes a new or updated NGINX configuration to the specified instance. \nIf no existing configuration is found, a new one is created; otherwise, the current configuration is overwritten. \nBefore publishing, use the `PUT /instances/{instanceObjectID}/config-report` endpoint to generate an analysis report for the provided configuration.\nYou can specify `payloads` in the request to deploy managed certificates and keys to the dataplane. Include file paths\nfor each payload component.\n", + "operationId": "publishInstanceConfig", "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CertificateRequest" + "$ref": "#/components/schemas/NginxConfigRequest" } } } }, "responses": { - "200": { - "description": "Successfully parsed and validated the SSL certificate.", + "202": { + "description": "The request to publish the configuration has been accepted and is being processed. To check the publication status, make a GET request to /instances/{instanceObjectID}/publications.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CertificateResponse" + "$ref": "#/components/schemas/PublicationInstance" } } } @@ -2613,6 +2599,16 @@ } } }, + "404": { + "description": "The NGINX instance 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": { @@ -2626,43 +2622,30 @@ } } }, - "/certificates/{certificateObjectID}": { - "parameters": [ - { - "$ref": "#/components/parameters/CertificateParamObjectID" - } - ], + "/instances/{instanceObjectID}/config-report": { "get": { - "x-feature-flag": "cert-mgmt", "tags": [ - "Certificates" + "Instances" ], - "summary": "Retrieve an SSL certificate", - "operationId": "getCertificate", - "description": "Retrieves the details for an SSL certificate, including:\n* Object ID that uniquely identifies this certificate object\n* SSL certificate type (managed or unmanaged by NGINX One Console)\n* Certificate type (whether it is a CA bundle or a certificate-key pair)\n* Subject name of the leaf certificate, or the soonest-expiring CA in a bundle\n * This subject name will be the DNS name in the SAN extension of the certificate. If not present, it will be the certificate's common name\n* Status of the certificate (valid, expiring, expired)\n* Validity period, if applicable to multiple certificates\n* Metadata for each public certificate if multiples are provided\n* Private key metadata, if available\n", + "summary": "Retrieve an analysis report for an instance's configuration", + "description": "Analyzes the configuration of an NGINX instance and returns a detailed report.\nThe report includes insights, identified issues, and recommendations for optimizing and troubleshooting.\n", + "operationId": "getInstanceConfigReport", "responses": { "200": { - "description": "Successfully retrieved the details of the SSL certificate.", + "description": "Successfully retrieved the NGINX configuration analysis for the specified instance.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CertificateResponse" + "$ref": "#/components/schemas/NginxConfigReports" } } } }, - "401": { - "description": "Access denied.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } + "204": { + "description": "The requested instance 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 SSL certificate with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", + "description": "The NGINX instance 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": { @@ -2683,33 +2666,37 @@ } } }, + "parameters": [ + { + "$ref": "#/components/parameters/InstanceParamObjectID" + } + ], "patch": { - "x-nginx-one-action": "update", - "x-nginx-one-entity": "NGINX certificate", - "x-feature-flag": "cert-mgmt", "tags": [ - "Certificates" + "Instances" ], - "summary": "Update an SSL certificate", - "operationId": "updateCertificate", - "description": "Updates public certificates, private keys, or both. \nThis endpoint can also be used to update a Certificate Authority (CA) bundle.\n", + "x-nginx-one-action": "analyze", + "x-nginx-one-entity": "NGINX instance configuration", + "summary": "Generate an analysis report for the provided modified configuration", + "description": "Analyzes the provided partial updates to an existing NGINX configuration and generates a report detailing potential issues along with optimization suggestions. \nThis analysis accounts for additive updates made to `NginxConfig`. To delete files, omit the `file.contents` field. \nThis method compares the provided `config_version` with the current NGINX instance configuration to detect conflicts, which may arise if the `config_version` does not match due to an out-of-band update. \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 /instances/{instanceObjectID}/config` endpoint.\n", + "operationId": "analyzeInstanceConfigWithModify", "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CertificateUpdateRequest" + "$ref": "#/components/schemas/NginxConfigRequest" } } } }, "responses": { "200": { - "description": "Successfully updated the specified SSL certificate.", + "description": "Successfully analyzed the provided NGINX configuration.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CertificateResponse" + "$ref": "#/components/schemas/NginxConfigReports" } } } @@ -2735,7 +2722,7 @@ } }, "404": { - "description": "The SSL certificate with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", + "description": "The NGINX instance 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": { @@ -2756,19 +2743,35 @@ } } }, - "delete": { - "x-nginx-one-action": "delete", - "x-nginx-one-entity": "NGINX certificate", - "x-feature-flag": "cert-mgmt", + "put": { "tags": [ - "Certificates" + "Instances" ], - "summary": "Delete an SSL certificate", - "operationId": "deleteCertificate", - "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.", + "x-nginx-one-action": "analyze", + "x-nginx-one-entity": "NGINX instance configuration", + "summary": "Generate an analysis report for the provided configuration", + "description": "Returns an analysis report for the provided NGINX configuration. This report includes insights, identified issues, and recommendations for optimizing and troubleshooting. Note that this operation is for analysis purposes only and does not apply any changes to the configuration. The report is not stored and is provided only in the API response. To publish the configuration, use the `PUT /instances/{instanceObjectID}/config` endpoint.", + "operationId": "analyzeInstanceConfig", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/NginxConfigRequest" + } + } + } + }, "responses": { - "204": { - "description": "Successfully deleted the SSL certificate." + "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.", @@ -2791,7 +2794,7 @@ } }, "404": { - "description": "The SSL certificate with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", + "description": "The NGINX instance 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": { @@ -2813,54 +2816,27 @@ } } }, - "/certificates/{certificateObjectID}/deployments": { + "/instances/{instanceObjectID}/configs": { "get": { - "x-feature-flag": "cert-mgmt", "tags": [ - "Certificates" + "Instances" ], - "summary": "List SSL certificate deployments", - "description": "Returns a paginated list showing all the deployments for a SSL certificate and assigned file path(s).\n", - "parameters": [ - { - "$ref": "#/components/parameters/CertificateParamObjectID" - }, - { - "$ref": "#/components/parameters/Paginated" - }, - { - "$ref": "#/components/parameters/Limit" - }, - { - "$ref": "#/components/parameters/Offset" - }, - { - "$ref": "#/components/parameters/FilterFieldCertificateDeployments" - }, - { - "$ref": "#/components/parameters/FilterOperands" - }, - { - "$ref": "#/components/parameters/FilterValues" - }, - { - "$ref": "#/components/parameters/SortDirection" - }, - { - "$ref": "#/components/parameters/SortNameCertificateDeployments" - } - ], - "operationId": "listCertificateDeployments", - "responses": { - "200": { - "description": "Successfully retrieved the list of SSL certificate deployments.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CertificateDeploymentListResponse" - } - } - } + "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 the NGINX One Console for a NGINX instance.", + "operationId": "listInstanceConfigurations", + "responses": { + "200": { + "description": "Successfully retrieved the list of NGINX configurations for the specified NGINX instance.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/NginxConfigMeta" + } + } + } + } }, "401": { "description": "Access denied.", @@ -2873,7 +2849,7 @@ } }, "404": { - "description": "The SSL certificate with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing resource.", + "description": "The NGINX instance 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": { @@ -2893,40 +2869,28 @@ } } } - } + }, + "parameters": [ + { + "$ref": "#/components/parameters/InstanceParamObjectID" + } + ] }, - "/cves": { + "/instances/{instanceObjectID}/configs/{instanceConfigurationObjectID}": { "get": { "tags": [ - "CVEs" - ], - "summary": "List of all CVEs affecting the instances", - "operationId": "listNginxCVEs", - "description": "Returns a list of all CVEs that affect at least one instance under the tenant\n", - "parameters": [ - { - "$ref": "#/components/parameters/Paginated" - }, - { - "$ref": "#/components/parameters/Limit" - }, - { - "$ref": "#/components/parameters/Offset" - }, - { - "$ref": "#/components/parameters/SortDirection" - }, - { - "$ref": "#/components/parameters/SortNameCVEs" - } + "Instances" ], + "summary": "Retrieve an instance's configuration details", + "description": "Returns the configuration details for an NGINX instance, including: \n* Main configuration path\n* Details about configuration files\n* Details about auxiliary files\n* Unique identifiers\n", + "operationId": "getInstanceConfigWithObjectID", "responses": { "200": { - "description": "Successfully retrieved the list of CVEs.", + "description": "Successfully retrieved the configuration details for the specified NGINX instance and NGINX configuration.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CVEListResponse" + "$ref": "#/components/schemas/NginxConfig" } } } @@ -2941,6 +2905,16 @@ } } }, + "404": { + "description": "The NGINX instance or NGINX configuration 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": { @@ -2952,28 +2926,39 @@ } } } - } + }, + "parameters": [ + { + "$ref": "#/components/parameters/InstanceParamObjectID" + }, + { + "$ref": "#/components/parameters/InstanceConfigurationParamObjectID" + } + ] }, - "/cves/{nginxCVEID}": { + "/instances/{instanceObjectID}/cves": { "get": { "tags": [ - "CVEs" + "Instances" ], - "summary": "Retrieve NGINX CVE details", - "operationId": "GetNginxCVEDetails", - "description": "Retrieve CVE details\n", + "summary": "Retrieve an instance's security advisories (CVEs)", + "description": "Retrieves a list of the security advisories (CVEs) for an NGINX instance.", + "operationId": "listInstanceSecurityAdvisories", "parameters": [ { - "$ref": "#/components/parameters/NginxCVEParamID" + "$ref": "#/components/parameters/InstanceParamObjectID" } ], "responses": { "200": { - "description": "Successfully retrieved NGINX CVE details.", + "description": "Successfully retrieved the list of security advisories (CVEs).", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/NginxCVEDetailsResponse" + "type": "array", + "items": { + "$ref": "#/components/schemas/NginxSecurityAdvisory" + } } } } @@ -2989,7 +2974,7 @@ } }, "404": { - "description": "CVE with the specified nginxCVEID was not found. Check that the nginxCVEID provided is correct and corresponds to an existing resource.", + "description": "The NGINX instance 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": { @@ -3011,41 +2996,29 @@ } } }, - "/cves/{nginxCVEID}/impacted_instances": { + "/instances/{instanceObjectID}/publications": { "get": { "tags": [ - "CVEs" + "Instances" ], - "summary": "Retrieve the instances impacted by a CVE", - "description": "Retrieves a list of the instances impacted by a security advisory.", - "operationId": "listCVEImpactedInstances", + "summary": "Retrieve the publications for an instance", + "description": "Returns a list of all publications for a NGINX instance.", + "operationId": "listInstancePublications", "parameters": [ { - "$ref": "#/components/parameters/Paginated" - }, - { - "$ref": "#/components/parameters/Limit" - }, - { - "$ref": "#/components/parameters/Offset" - }, - { - "$ref": "#/components/parameters/SortDirection" - }, - { - "$ref": "#/components/parameters/SortNameCVEImpactedInstances" - }, - { - "$ref": "#/components/parameters/NginxCVEParamID" + "$ref": "#/components/parameters/InstanceParamObjectID" } ], "responses": { "200": { - "description": "Successfully retrieved the list of instances affected by the CVE", + "description": "Successfully retrieved the list of all publications for the specified NGINX instance.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CVEImpactedInstancesListResponse" + "type": "array", + "items": { + "$ref": "#/components/schemas/PublicationInstance" + } } } } @@ -3060,16 +3033,6 @@ } } }, - "404": { - "description": "The CVE with the specified object_id was not found. Check that the object_id provided is correct and corresponds to an existing CVE.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "500": { "description": "An unexpected error occurred on the server. Please try the request again later.", "content": { @@ -3083,41 +3046,29 @@ } } }, - "/events": { + "/instances/{instanceObjectID}/publications/{publicationObjectID}": { "get": { "tags": [ - "Events" + "Instances" ], - "summary": "Retrieve system events.", - "description": "Retrieves a list of the system events.", - "operationId": "listEvents", + "summary": "Retrieve a publication for an NGINX instance.", + "description": "Returns a specific publication for an NGINX instance. Only 5 previous entries of Publication are kept for each NGINX instance.", + "operationId": "getInstancePublication", "parameters": [ { - "$ref": "#/components/parameters/Paginated" - }, - { - "$ref": "#/components/parameters/Limit" - }, - { - "$ref": "#/components/parameters/Offset" - }, - { - "$ref": "#/components/parameters/FilterFieldEvents" - }, - { - "$ref": "#/components/parameters/FilterOperands" + "$ref": "#/components/parameters/InstanceParamObjectID" }, { - "$ref": "#/components/parameters/FilterValues" + "$ref": "#/components/parameters/PublicationParamObjectID" } ], "responses": { "200": { - "description": "Successfully retrieved the list of events.", + "description": "Successfully retrieved the specific Publication for the specified NGINX instance.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/EventsListResponse" + "$ref": "#/components/schemas/PublicationInstance" } } } @@ -3132,6 +3083,16 @@ } } }, + "404": { + "description": "The NGINX instance or Publication 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": { @@ -3145,26 +3106,21 @@ } } }, - "/events/{eventObjectID}": { + "/instances/summary": { "get": { "tags": [ - "Events" - ], - "operationId": "getEvent", - "summary": "Retrieve specific event.", - "description": "Retrieve a specific event using the event object_id.", - "parameters": [ - { - "$ref": "#/components/parameters/EventParamObjectID" - } + "Instances" ], + "summary": "Retrieve a summary for all instances", + "description": "Retrieves a comprehensive summary for all NGINX instances, which includes details such as:\n * Certificate status and associations\n * Operating system details\n * Version of the NGINX Agent\n * Overall system status\n", + "operationId": "listSummary", "responses": { "200": { - "description": "Successfully retrieved the details of the event.", + "description": "Successfully retrieved the summary of NGINX instances.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Event" + "$ref": "#/components/schemas/InstanceSummary" } } } @@ -3179,16 +3135,6 @@ } } }, - "404": { - "description": "The Event 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": { @@ -3573,14 +3519,14 @@ "description": "A globally unique identifier for the data plane key.\n", "required": true }, - "FilterFieldInstances": { + "FilterFieldCertificates": { "name": "filter_fields", "in": "query", - "description": "An array of strings indicating which fields to filter by (for example, `hostname`, `nginx_version`). This parameter works in conjunction with `filter_values` and `filter_ops`.\n", + "description": "Filter options for certificates; used in conjunction with other filter parameters having the same array length.\n", "schema": { "type": "array", "items": { - "$ref": "#/components/schemas/FilterNameInstances" + "$ref": "#/components/schemas/FilterNameCertificates" } } }, @@ -3600,53 +3546,65 @@ ] } }, - "SortNameInstances": { - "name": "sort_instances", + "SortNameCertificates": { + "name": "sort_certificates", "in": "query", - "description": "Sort instances by enumerate value(s). Ordinal position determines primary, secondary, etc.\n", + "description": "Sort certificates by enumerate value(s). Ordinal position determines primary, secondary, etc.\n", "schema": { "type": "array", "items": { "type": "string", "enum": [ - "hostname", - "status", - "last_reported" + "name", + "subject_name", + "not_before", + "not_after" ], "x-enum-varnames": [ - "sort_name_instance_hostname", - "sort_name_instance_status", - "sort_name_instance_last_reported" + "sort_name_certificates_name", + "sort_name_certificates_subject_name", + "sort_name_certificates_not_before", + "sort_name_certificates_not_after" ] } } }, - "InstanceParamObjectID": { - "name": "instanceObjectID", + "CertificateParamObjectID": { + "name": "certificateObjectID", "in": "path", "schema": { - "$ref": "#/components/schemas/InstanceObjectID" + "$ref": "#/components/schemas/CertificateObjectID" }, - "description": "A globally unique identifier for the NGINX instance.\n", + "description": "A globally unique identifier for the certificate.\n", "required": true }, - "InstanceConfigurationParamObjectID": { - "name": "instanceConfigurationObjectID", - "in": "path", + "FilterFieldCertificateDeployments": { + "name": "filter_fields", + "in": "query", + "description": "Filter options for certificate deployments; used in conjunction with other filter parameters having the same array length.\n", "schema": { - "$ref": "#/components/schemas/NginxConfigObjectID" - }, - "description": "A globally unique identifier for the NGINX instance configuration.\n", - "required": true + "type": "array", + "items": { + "$ref": "#/components/schemas/FilterNameCertificateDeployments" + } + } }, - "PublicationParamObjectID": { - "name": "publicationObjectID", - "in": "path", + "SortNameCertificateDeployments": { + "name": "sort_certificate_deployments", + "in": "query", + "description": "Sort certificate deployments by enumerate value(s). Ordinal position determines primary, secondary, etc.\n", "schema": { - "$ref": "#/components/schemas/PublicationObjectID" - }, - "description": "A globally unique identifier for a Publication.\n", - "required": true + "type": "array", + "items": { + "type": "string", + "enum": [ + "name" + ], + "x-enum-varnames": [ + "sort_name_certificate_deployments_name" + ] + } + } }, "FilterFieldConfigSyncGroups": { "name": "filter_fields", @@ -3694,77 +3652,15 @@ "description": "A globally unique identifier for the NGINX config sync group configuration.\n", "required": true }, - "FilterFieldCertificates": { - "name": "filter_fields", - "in": "query", - "description": "Filter options for certificates; used in conjunction with other filter parameters having the same array length.\n", - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/FilterNameCertificates" - } - } - }, - "SortNameCertificates": { - "name": "sort_certificates", - "in": "query", - "description": "Sort certificates by enumerate value(s). Ordinal position determines primary, secondary, etc.\n", - "schema": { - "type": "array", - "items": { - "type": "string", - "enum": [ - "name", - "subject_name", - "not_before", - "not_after" - ], - "x-enum-varnames": [ - "sort_name_certificates_name", - "sort_name_certificates_subject_name", - "sort_name_certificates_not_before", - "sort_name_certificates_not_after" - ] - } - } - }, - "CertificateParamObjectID": { - "name": "certificateObjectID", + "PublicationParamObjectID": { + "name": "publicationObjectID", "in": "path", "schema": { - "$ref": "#/components/schemas/CertificateObjectID" + "$ref": "#/components/schemas/PublicationObjectID" }, - "description": "A globally unique identifier for the certificate.\n", + "description": "A globally unique identifier for a Publication.\n", "required": true }, - "FilterFieldCertificateDeployments": { - "name": "filter_fields", - "in": "query", - "description": "Filter options for certificate deployments; used in conjunction with other filter parameters having the same array length.\n", - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/FilterNameCertificateDeployments" - } - } - }, - "SortNameCertificateDeployments": { - "name": "sort_certificate_deployments", - "in": "query", - "description": "Sort certificate deployments by enumerate value(s). Ordinal position determines primary, secondary, etc.\n", - "schema": { - "type": "array", - "items": { - "type": "string", - "enum": [ - "name" - ], - "x-enum-varnames": [ - "sort_name_certificate_deployments_name" - ] - } - } - }, "SortNameCVEs": { "name": "sort_cves", "in": "query", @@ -3836,6 +3732,56 @@ }, "description": "A globally unique identifier for an event.\n", "required": true + }, + "FilterFieldInstances": { + "name": "filter_fields", + "in": "query", + "description": "An array of strings indicating which fields to filter by (for example, `hostname`, `nginx_version`). This parameter works in conjunction with `filter_values` and `filter_ops`.\n", + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/FilterNameInstances" + } + } + }, + "SortNameInstances": { + "name": "sort_instances", + "in": "query", + "description": "Sort instances by enumerate value(s). Ordinal position determines primary, secondary, etc.\n", + "schema": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "hostname", + "status", + "last_reported" + ], + "x-enum-varnames": [ + "sort_name_instance_hostname", + "sort_name_instance_status", + "sort_name_instance_last_reported" + ] + } + } + }, + "InstanceParamObjectID": { + "name": "instanceObjectID", + "in": "path", + "schema": { + "$ref": "#/components/schemas/InstanceObjectID" + }, + "description": "A globally unique identifier for the NGINX instance.\n", + "required": true + }, + "InstanceConfigurationParamObjectID": { + "name": "instanceConfigurationObjectID", + "in": "path", + "schema": { + "$ref": "#/components/schemas/NginxConfigObjectID" + }, + "description": "A globally unique identifier for the NGINX instance configuration.\n", + "required": true } }, "schemas": { @@ -4180,6 +4126,96 @@ } } }, + "FilterNameCertificates": { + "type": "string", + "description": "Keywords for certificates filters.\nWhen filtering on `management`, only the following `filter_values` are supported:\n * managed\n * unmanaged\nWhen filtering on `type`, only the following `filter_values` are supported:\n * cert_key\n * ca_bundle\n * unknown\nWhen filtering on `status`, only the following `filter_values` are supported:\n * valid\n * expiring\n * expired\n * not_ready\n", + "enum": [ + "name", + "management", + "type", + "subject_name", + "status", + "object_id" + ], + "x-enum-varnames": [ + "filter_name_certificates_name", + "filter_name_certificates_management", + "filter_name_certificates_type", + "filter_name_certificates_subject_name", + "filter_name_certificates_status", + "filter_name_certificates_object_id" + ] + }, + "CertificateObjectID": { + "description": "A globally unique identifier for the certificates.", + "type": "string", + "format": "object_id", + "pattern": "^cert_.*", + "x-go-type": "objects.ID", + "x-go-type-import": { + "name": "objects", + "path": "gitlab.com/f5/nginx/one/saas/control-plane/pkg/collections/objects" + } + }, + "CertificateManagement": { + "type": "string", + "description": "Management type:\n * `managed` - Certificate managed by NGINX One Console.\n * `unmanaged` - Certificate that only exists on a data plane instance, detected from its NGINX configuration.\n", + "enum": [ + "managed", + "unmanaged" + ], + "x-enum-varnames": [ + "certificate_management_managed", + "certificate_management_unmanaged" + ] + }, + "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", + "enum": [ + "ca_bundle", + "cert_key", + "unmanaged" + ], + "x-enum-varnames": [ + "certificate_type_ca_bundle", + "certificate_type_pem_cert_key", + "certificate_type_unmanaged" + ] + }, + "CertificateObjectMetadata": { + "required": [ + "management", + "type" + ], + "properties": { + "name": { + "description": "Name of the certificate, optionally specified upon creation", + "type": "string" + }, + "object_id": { + "$ref": "#/components/schemas/CertificateObjectID" + }, + "management": { + "$ref": "#/components/schemas/CertificateManagement" + }, + "type": { + "$ref": "#/components/schemas/CertificateType" + }, + "certs_count": { + "description": "The number of public certificates under this certificate object.", + "type": "integer", + "format": "int64" + } + }, + "example": { + "name": "example-ca-bundle", + "object_id": "cert_Tet21AeYTHCj7taOwVfzyw", + "management": "managed", + "type": "ca_bundle", + "certs_count": 5 + } + }, "CertificateStatus": { "type": "string", "description": "Status of the certificate:\n * `valid` - The certificate is currently valid and operational.\n * `expiring` - The certificate will expire within the next 30 days. Consider renewing it to maintain uninterrupted service.\n * `expired` - The certificate is no longer valid. Immediate renewal is recommended to ensure secure connections.\n * `not_ready` - The certificate is not ready to be used, based on the start date of its validity period.\n", @@ -4196,229 +4232,817 @@ "certificate_status_not_ready" ] }, - "CertificateSummaryItem": { - "description": "summary information for certificate with certain status.", + "CertificateDisplayMetadata": { + "description": "This represents the essential metadata of a public certificate.", "type": "object", "required": [ + "subject_name", "status", - "count", - "affected_instances" + "not_before", + "not_after" ], "properties": { + "subject_name": { + "type": "string", + "example": "www.example.com", + "description": "DNS name that identifies the certificate. If DNS is not present in the SAN extension, this will be the common name.\n" + }, "status": { "$ref": "#/components/schemas/CertificateStatus" }, - "count": { - "description": "The total number of SSL certificates for each status category.", - "type": "integer" + "not_before": { + "type": "string", + "format": "date-time", + "example": "2023-06-12T09:12:33.001Z", + "description": "The start of the validity period for the certificate." }, - "affected_instances": { - "description": "Indicates the total number of SSL/TLS certificates corresponding to the status provided.", - "type": "integer" + "not_after": { + "type": "string", + "format": "date-time", + "example": "2029-12-25T09:12:33.001Z", + "description": "The end of the validity period for the certificate." } + }, + "example": { + "subject_name": "self_ca_signed", + "status": "valid", + "not_before": "2023-08-10T16:59:15Z", + "not_after": "2024-08-14T16:59:15Z" } }, - "SummaryDisplayCount": { - "description": "The name, the total count, and an optional user-friendly display name of the resource being summarized.", + "CertificateOverviewMetadata": { + "description": "Represents an overview of all the public certificates under a single cert object.\nIf multiple public certificates on the same CA chain, including the leaf certificate and key are provided, \nthis includes `status`, `subject_name`, `not_before` and `not_after` for the leaf certificate.\nIf a CA bundle is provided, the above mentioned certificate metadata is for the Certificate Authority that\nexpires the soonest in the bundle.\n", "type": "object", - "required": [ - "name", - "count" - ], - "properties": { - "name": { - "description": "Identifies the category of data being reported, such as an operating system, NGINX version, or another type.", - "type": "string" - }, - "count": { - "description": "The number of resources matching the given type.", - "type": "integer" + "allOf": [ + { + "$ref": "#/components/schemas/CertificateObjectMetadata" }, - "display": { - "description": "A user-friendly label for the category count, intended for display purposes where a more descriptive or readable format is preferred.", - "type": "string" + { + "$ref": "#/components/schemas/CertificateDisplayMetadata" } + ], + "example": { + "name": "example-ca-bundle", + "object_id": "cert_Tet21AeYTHCj7taOwVfzyw", + "management": "managed", + "type": "ca_bundle", + "subject_name": "self_ca_signed", + "status": "valid", + "not_before": "2023-08-10T16:59:15Z", + "not_after": "2024-08-14T16:59:15Z", + "certs_count": 5 } }, - "OperatingSystemVersionSummary": { - "description": "An array summarizing the operating systems and their versions on the NGINX data plane.", - "type": "array", - "items": { - "$ref": "#/components/schemas/SummaryDisplayCount" - } - }, - "NGINXVersionSummary": { - "description": "An array summarizing the versions of NGINX installed across the NGINX data plane.", - "type": "array", - "items": { - "$ref": "#/components/schemas/SummaryDisplayCount" + "CertificateListResponse": { + "allOf": [ + { + "$ref": "#/components/schemas/PaginationResponse" + }, + { + "type": "object", + "description": "List of SSL certificates.", + "required": [ + "items" + ], + "properties": { + "items": { + "description": "An array of basic metadata for all the SSL certificates in NGINX One Console. \nFor a CA bundle, an overview with metadata on the first Certificate Authority in the bundle will be displayed.\nOtherwise, an overview with metadata on the leaf certificate will be displayed.\n", + "type": "array", + "items": { + "$ref": "#/components/schemas/CertificateOverviewMetadata" + } + } + } + } + ], + "example": { + "total": 10, + "count": 2, + "start_index": 1, + "items_per_page": 100, + "items": [ + { + "name": "example-cert_key", + "object_id": "cert_Tet21AeYTHCj7taOwVfzyw", + "management": "managed", + "type": "cert_key", + "status": "valid", + "subject_name": "www.example.com", + "not_before": "2023-08-10T16:59:15Z", + "not_after": "2024-08-14T16:59:15Z", + "certs_count": 1 + }, + { + "name": "example-ca-bundle", + "object_id": "cert_Tet21AeYTHCj7taOwVfzyw", + "management": "managed", + "type": "ca_bundle", + "subject_name": "self_ca_signed", + "status": "valid", + "not_before": "2023-08-10T16:59:15Z", + "not_after": "2024-08-14T16:59:15Z", + "certs_count": 5 + } + ] } }, - "StatusSummary": { - "description": "An overview of the status for each NGINX instance, indicating availability.", + "CertificateContent": { "type": "object", + "description": "Defines the PEM-formatted certificate content which includes the certificates and corresponding private key, all encoded in base64.\n", "required": [ - "online", - "offline", - "unavailable" + "public_certs" ], "properties": { - "online": { - "description": "The number of NGINX instances reporting as `online`.\nThe NGINX Agent is connected to NGINX One, and the NGINX instance is online.\n", - "type": "integer" - }, - "offline": { - "description": "The number of NGINX instances reporting as `offline`.\nThe NGINX Agent is connected to NGINX One, but the NGINX instance is offline.\n", - "type": "integer" + "public_certs": { + "type": "string", + "format": "base64", + "maxLength": 3145728, + "description": "Base64-encoded PEM-formatted certificate information. \nThe `public_certs` field can include a leaf certificate along with its full chain of trust or a CA bundle. \nFor leaf certificates, the accompanying `private_key` is required to authenticate the certificate's validity. \nCA bundles contain trusted CA certificates and may consist of certificates from different CA chains. A private\nkey should not be included in a CA bundle.\n" }, - "unavailable": { - "description": "The number of NGINX instances reporting as `unavailable`.\nThe NGINX Agent has lost connection to NGINX One, rendering the NGINX instance unavailable.\n", - "type": "integer" + "private_key": { + "type": "string", + "format": "base64", + "maxLength": 3145728, + "description": "Base64-encoded private key string for the leaf certificate, required only for certificate-key pairs to \nverify the certificate's authenticity.\n" } + }, + "example": { + "public_certs": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUUzb3lkdWVPQU5KSGh2TDN5dkpkVHBob2V2NUdPN2dvK0J5WU9PL2w1NHU1TzJQeE1lWCtBakFiNkF4bXEKbGl2SXVodz0KLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQ==" } }, - "CveSeverityType": { - "type": "string", - "description": "Severity ratings:\n * `high` - High severity.\n * `medium` - Moderate severity.\n * `low` - Least severe.\n * `none` - Not severe.\n * `other` - Severity that does not fit the other categories.\n", - "enum": [ - "high", - "medium", - "low", - "none", - "other" - ], - "x-enum-varnames": [ - "cve_severity_type_high", - "cve_severity_type_medium", - "cve_severity_type_low", - "cve_severity_type_none", - "cve_severity_type_other" - ] - }, - "CveSummary": { - "description": "A summary of Common Vulnerabilities and Exposures (CVEs) across the NGINX data plane.", + "CertificateRequest": { "type": "object", + "description": "Request structure for parsing or upserting certificates with an optional private key.\n", "required": [ - "severity", - "count", - "affected_instances" + "content" ], "properties": { - "severity": { - "$ref": "#/components/schemas/CveSeverityType" - }, - "count": { - "description": "The number of CVEs at each severity level.", - "type": "integer" + "name": { + "description": "A name for the certificate, making it identifiable among others.", + "type": "string", + "minLength": 1, + "maxLength": 128 }, - "affected_instances": { - "description": "The number of NGINX instances affected by each CVE.", - "type": "integer" + "content": { + "$ref": "#/components/schemas/CertificateContent" + } + }, + "example": { + "name": "example-ca-bundle", + "content": { + "public_certs": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUUzb3lkdWVPQU5KSGh2TDN5dkpkVHBob2V2NUdPN2dvK0J5WU9PL2w1NHU1TzJQeE1lWCtBakFiNkF4bXEKbGl2SXVodz0KLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQ==", + "private_key": "" } } }, - "RecommendationType": { - "type": "string", - "description": "Types of configuration recommendations:\n * `best_practice` - Suggestions based on established best practices.\n * `security` - Recommendations related to security.\n * `optimization` - Advice for optimizing performance.\n * `other` - Recommendations that do not fit the above categories.\n", - "enum": [ - "best_practice", - "security", - "optimization", - "other" - ], - "x-enum-varnames": [ - "recommendation_type_best_practice", - "recommendation_type_security", - "recommendation_type_optimization", - "recommendation_type_other" - ] - }, - "IssueSummary": { - "description": "A summary of issue details from the configuration analysis report.", + "CertificateMetadata": { + "description": "A comprehensive list of all the metadata for a public certificate.", "type": "object", "required": [ - "type", - "count", - "affected_instances" + "status", + "serial_number", + "signature_algorithm", + "not_before", + "not_after", + "public_key_type", + "thumbprint" ], "properties": { - "type": { - "$ref": "#/components/schemas/RecommendationType" + "status": { + "$ref": "#/components/schemas/CertificateStatus" }, - "count": { - "description": "The number of times this recommendation appears in the configuration analysis report.", - "type": "integer" + "version": { + "type": "integer", + "format": "int64", + "example": 3, + "description": "The version of the certificate, typically 3 for X.509 certificates." }, - "affected_instances": { - "description": "The number of instances affected by this issue.", - "type": "integer" - } - } - }, - "InstanceSummary": { - "description": "A summary of NGINX instances, including certificates, OS versions, NGINX versions, and status details.", + "serial_number": { + "type": "string", + "example": "16469416336579571270", + "description": "A unique identifier for the certificate." + }, + "signature_algorithm": { + "type": "string", + "example": "SHA-256", + "description": "Identifies the algorithm used to sign the certificate." + }, + "issuer": { + "type": "string", + "example": "CN=Example CA, O=Certificate Authority Inc., OU=CA Department, L=City, ST=State, C=Country", + "description": "Identifies the entity who signed and issued the certificate." + }, + "not_before": { + "type": "string", + "format": "date-time", + "example": "2023-06-12T09:12:33.001Z", + "description": "The start of the validity period for the certificate." + }, + "not_after": { + "type": "string", + "format": "date-time", + "example": "2029-12-25T09:12:33.001Z", + "description": "The end of the validity period for the certificate." + }, + "subject": { + "type": "string", + "example": "CN=www.example.com, O=Example Inc., OU=IT Department, L=City, ST=State, C=Country", + "description": "Identifies the primary entity to which the certificate is issued. Typically, it contains information\nsuch as the Common Name (CN), Organization (O), Organizational Unit (OU), Country (C), etc.\n" + }, + "subject_alternative_name": { + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "DNS:www.example.com", + "DNS:example.com", + "email:info@example.com" + ], + "description": "Defines additional identifies bound to the subject of the certificate. \nFor example, the DNS name is used to add additional domain names to a certificate.\n" + }, + "public_key_type": { + "type": "string", + "example": "RSA (2048 Bits)", + "description": "Identifies the encryption algorithm used to create the public key for the certificate." + }, + "common_name": { + "type": "string", + "example": "www.example.com", + "description": "The Common Name (CN) for the certificate, used when DNS name is not present in the SAN extension.\n" + }, + "authority_key_identifier": { + "type": "string", + "example": "2B D0 69 47 94 76 09 FE F4 6B 8D 2E 40 A6 F7 47 4D 7F 08 5E", + "description": "The identifier of the signing authority for the certificate." + }, + "subject_key_identifier": { + "type": "string", + "example": "31 EA 76 A9 23 74 A5 DF D4 FD EE A0 C1 A6 9E C6 11 0E 11 EC", + "description": "A hash value of the SSL certificate that can be used to identify certificates that \ncontain a particular public key.\n" + }, + "thumbprint_algorithm": { + "type": "string", + "example": "SHA-1", + "description": "Defines the algorithm used to hash the certificate." + }, + "thumbprint": { + "type": "string", + "example": "E6 A7 87 96 E0 C7 A3 E5 43 78 35 CA 16 78 5B 48 5A A9 DD C4 5C CD 0A 65 AA 89 33 E3 C3 D0 89 71", + "description": "A hash to ensure that the certificate has not been modified." + } + }, + "example": { + "status": "valid", + "version": 3, + "serial_number": "71283929", + "signature_algorithm": "SHA256-RSA", + "issuer": "C=US, ST=WA, L=Seattle, O=F5 Networks, OU=nginx.test, CN=eg3bsriq_cert_bundle_CA", + "not_before": "2023-02-10T16:59:15Z", + "not_after": "2024-08-14T16:59:15Z", + "subject": "C=US, ST=WA, L=Seattle, O=F5 Networks, OU=nginx.test, CN=self_ca_signed", + "subject_alternative_name": [], + "public_key_type": "RSA (2048 bit)", + "common_name": "self_ca_signed", + "authority_key_identifier": "3A:79:E0:3E:61:CD:94:29:1D:BB:45:37:0B:E9:78:E9:2F:40:67:CA", + "subject_key_identifier": "93:35:2B:75:09:B9:FF:01:1B:63:F1:0E:50:71:9C:4E:B4:E2:02:BA", + "thumbprint_algorithm": "SHA-256", + "thumbprint": "C1:EB:E8:CE:35:77:63:75:D3:C0:E7:97:5F:02:8C:D3:D8:C4:12:34:40:45:D3:98:67:39:BE:8A:33:CE:1F:B2" + } + }, + "PrivateKeyMetadata": { + "type": "object", + "description": "Metadata for a private key.", + "properties": { + "key_size": { + "description": "Size of the private key in bits.", + "type": "integer", + "format": "int64" + }, + "encryption_algorithm": { + "description": "The encryption algorithm used for the private key.", + "type": "string" + } + }, + "example": { + "key_size": 512, + "encryption_algorithm": "RSA" + } + }, + "CertificateResponse": { + "type": "object", + "description": "Response structure containing details of the created, updated or retrieved SSL certificate. In general, \nthe response should contain:\n * an overview of all the public certificates\n * `warnings` whether any issue is found after parsing the certificates and key\n * `certs`\n * `key_metadata` if key provided in the request body\n * timestamps that represent when this cert object was created or modified\n", + "allOf": [ + { + "$ref": "#/components/schemas/CertificateOverviewMetadata" + }, + { + "type": "object", + "properties": { + "warnings": { + "type": "string", + "description": "Warnings indicate whether there are any issues with the stored cert object. Empty when no issues were found.\n" + }, + "certs": { + "description": "An array of metadata for all the public certificates under the cert object.", + "type": "array", + "items": { + "$ref": "#/components/schemas/CertificateMetadata" + } + }, + "key": { + "$ref": "#/components/schemas/PrivateKeyMetadata" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "The date and time when the SSL certificate was created." + }, + "modified_at": { + "type": "string", + "format": "date-time", + "description": "The date and time when the SSL certificate was last modified." + } + } + } + ], + "example": { + "name": "example-cert_key", + "object_id": "cert_Tet21AeYTHCj7taOwVfzyw", + "management": "managed", + "type": "cert_key", + "status": "valid", + "subject_name": "www.example.com", + "not_before": "2023-08-10T16:59:15Z", + "not_after": "2024-08-14T16:59:15Z", + "warnings": "The provided private key does not match the certificate's signing key.", + "certs_count": 1, + "certs": [ + { + "status": "valid", + "version": 3, + "serial_number": "71283929", + "signature_algorithm": "SHA256-RSA", + "issuer": "C=US, ST=WA, L=Seattle, O=F5 Networks, OU=nginx.test, CN=eg3bsriq_cert_A", + "not_before": "2023-02-10T16:59:15Z", + "not_after": "2024-08-14T16:59:15Z", + "subject": "C=US, ST=WA, L=Seattle, O=F5 Networks, OU=nginx.test, CN=eg3bsriq_cert_B", + "subject_alternative_name": [], + "public_key_type": "RSA (2048 bit)", + "common_name": "eg3bsriq_cert_B", + "authority_key_identifier": "3A:79:E0:3E:61:CD:94:29:1D:BB:45:37:0B:E9:78:E9:2F:40:67:CA", + "subject_key_identifier": "93:35:2B:75:09:B9:FF:01:1B:63:F1:0E:50:71:9C:4E:B4:E2:02:BA", + "thumbprint_algorithm": "SHA-256", + "thumbprint": "C1:EB:E8:CE:35:77:63:75:D3:C0:E7:97:5F:02:8C:D3:D8:C4:12:34:40:45:D3:98:67:39:BE:8A:33:CE:1F:B2" + } + ], + "key": { + "key_size": 512, + "encryption_algorithm": "RSA" + }, + "modified_at": "2023-11-01T00:00:00Z", + "created_at": "2023-10-01T00:00:00Z" + } + }, + "CertificateUpdateContent": { + "type": "object", + "description": "Defines the PEM-formatted certificate content which includes the certificates and corresponding private key, all encoded in base64.\n", + "properties": { + "public_certs": { + "type": "string", + "format": "base64", + "maxLength": 3145728, + "description": "Base64-encoded PEM-formatted certificate information. \nThis is used for updating an existing certificate object. The schema is the same as `CertificateContent`,\nthe only difference is that both `public_certs` and `private_key` fields are optional. There are three use\ncases for this schema:\n* the below update can be done on either a Cert Key Pair or a CA Bundle:\n * when only `public_certs` is populated, update the public certificates on a certificate object. \n The updated public certificates will be validated against the existing private key.\n* the below update can be done only on a Cert Key Pair:\n * when only `private_key` is populated, update only the private key on a certificate object. \n The updated private key will be validated against the existing public certificates.\n * when both `public_certs` and `private_key` fields are populated, update both of them on a certificate \n object.\n" + }, + "private_key": { + "type": "string", + "format": "base64", + "maxLength": 3145728, + "description": "Base64-encoded private key string for the leaf certificate, required only for certificate-key pairs to \nverify the certificate's authenticity.\n" + } + }, + "example": { + "private_key": "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFM295ZHVlT0FOSkhodkwzeXZKZFRwaG9ldjVHTzdnbytCeVlPTy9sNTR1NU8yUHhNZVgrQWpBYjZBeG1xCmxpdkl1aHc9Ci0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0t" + } + }, + "CertificateUpdateRequest": { + "type": "object", + "description": "Request structure for updating a certificate object. If key provided, it will be validated against the \nexisting leaf certificate stored under the certificate object.\n* Update for an unmanaged certificate object:\n * This converts the unmanaged certificate object to managed.\n * `public_certs` should always be provided during the conversion.\n * When key is provided, this certificate object is converted to a managed Cert Key Pair. Otherwise, it is\n converted to a managed CA Bundle.\n", + "properties": { + "name": { + "description": "A name for the certificate, making it identifiable among others.", + "type": "string", + "minLength": 1, + "maxLength": 128 + }, + "content": { + "$ref": "#/components/schemas/CertificateUpdateContent" + } + }, + "example": { + "name": "example-cert-object", + "content": { + "public_certs": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUUzb3lkdWVPQU5KSGh2TDN5dkpkVHBob2V2NUdPN2dvK0J5WU9PL2w1NHU1TzJQeE1lWCtBakFiNkF4bXEKbGl2SXVodz0KLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQ==" + } + } + }, + "FilterNameCertificateDeployments": { + "type": "string", + "description": "Keywords for certificate deployment filters.\nWhen filtering on `association_type`, only the following `filter_values` are supported:\n * instance\n * config_sync_group\nWhen filtering on `deployment_status`, only the following `filter_values` are supported:\n * latest\n * stale\n", + "enum": [ + "name", + "association_type", + "deployment_status" + ], + "x-enum-varnames": [ + "filter_name_certificate_deployments_name", + "filter_name_certificate_deployments_association_type", + "filter_name_certificate_deployments_deployment_status" + ] + }, + "CertificateAssociationType": { + "type": "string", + "description": "Certificate association type:\n * `instance` - This certificate deployment is for an instance.\n * `config_sync_group` - This certificate deployment is for a config sync group.\n", + "enum": [ + "instance", + "config_sync_group" + ], + "x-enum-varnames": [ + "certificate_association_type_instance", + "certificate_association_type_config_sync_group" + ] + }, + "CertificateDeploymentStatus": { + "type": "string", + "description": "Certificate deployment status:\n * `latest` - This certificate deployment is up to date with the latest certificates and key.\n * `stale` - This certificate deployment is outdated and needs to deploy the latest certificates and key.\n * `unmanaged` - This certificate deployment is unmanaged by NGINX One Console.\n", + "enum": [ + "latest", + "stale", + "unmanaged" + ], + "x-enum-varnames": [ + "certificate_deployment_status_latest", + "certificate_deployment_status_stale", + "certificate_deployment_status_unmanaged" + ] + }, + "CertificateDeployment": { + "type": "object", + "description": "Response structure containing certificate deployment details for an SSL certificate, which include\n * `association_type` represents type of the object affected by this certificate deployment, which is either\n an instance or config sync group\n * `object_id` represents the object ID for the associated instance or config sync group\n * `name` for either the host name of an instance or the name of a config sync group\n * `deployment_status`:\n * `latest`: deployment is up to date with the latest updated certificate and key contents\n * `stale`: deployment for either certificates or key is outdated, requires a redeployment with the latest contents\n * `cert_paths` represents the file paths used for deploying public certificates of this certificate object\n * `key_paths` represents the file paths used for deploying the private key of this certificate object, if a\n private key is present\n", + "required": [ + "association_type", + "object_id", + "name", + "deployment_status" + ], + "properties": { + "association_type": { + "$ref": "#/components/schemas/CertificateAssociationType" + }, + "object_id": { + "$ref": "#/components/schemas/ObjectID" + }, + "name": { + "type": "string", + "description": "The host name of an instance or the name of a config sync group." + }, + "deployment_status": { + "$ref": "#/components/schemas/CertificateDeploymentStatus" + }, + "cert_paths": { + "description": "Deployment file paths for public certificates.", + "type": "array", + "items": { + "type": "string" + } + }, + "key_paths": { + "description": "Deployment file paths for the private key.", + "type": "array", + "items": { + "type": "string" + } + } + }, + "example": { + "association_type": "instance", + "name": "instance-host-name", + "object_id": "inst_-uvR3F2TQGm18jnl7bpaGw", + "deployment_status": "latest", + "cert_paths": [ + "/etc/nginx/example.crt", + "/etc/nginx/certs/cert.crt" + ], + "key_paths": [ + "/etc/nginx/example.key" + ] + } + }, + "CertificateDeploymentListResponse": { + "allOf": [ + { + "$ref": "#/components/schemas/PaginationResponse" + }, + { + "type": "object", + "description": "List of certificate deployments for a SSL certificate.", + "required": [ + "items" + ], + "properties": { + "items": { + "description": "An array of certificate deployments for an SSL certificate. If this certificate object represents a \nCA bundle, there will be only public certificate file paths in the certificate deployment details.\n", + "type": "array", + "items": { + "$ref": "#/components/schemas/CertificateDeployment" + } + } + } + } + ], + "example": { + "total": 10, + "count": 2, + "start_index": 1, + "items_per_page": 100, + "items": [ + { + "association_type": "instance", + "name": "instance-host-name", + "object_id": "inst_-uvR3F2TQGm18jnl7bpaGw", + "deployment_status": "latest", + "cert_paths": [ + "/etc/nginx/example.crt", + "/etc/nginx/certs/cert.crt" + ], + "key_paths": [ + "/etc/nginx/example.key" + ] + }, + { + "association_type": "config_sync_group", + "name": "group1", + "object_id": "csg_vfr5Oqv-AhxGzyqTXW-Ubw", + "deployment_status": "stale", + "cert_paths": [ + "/etc/nginx/cert.crt" + ], + "key_paths": [ + "/etc/nginx/server.key" + ] + } + ] + } + }, + "FilterNameConfigSyncGroups": { + "type": "string", + "description": "Keywords for config sync groups filters.\nWhen filtering on `config_status`, only the following `filter_values` are supported:\n * in_sync\n * out_of_sync\n * sync_in_progress\n * unknown\n", + "enum": [ + "name", + "config_status", + "object_id" + ], + "x-enum-varnames": [ + "filter_name_config_sync_group_name", + "filter_name_config_sync_group_config_status", + "filter_name_config_sync_group_object_id" + ] + }, + "configSyncGroupObjectID": { + "description": "A globally unique identifier for the NGINX config sync group.", + "type": "string", + "format": "object_id", + "pattern": "^csg_.*", + "x-go-type": "objects.ID", + "x-go-type-import": { + "name": "objects", + "path": "gitlab.com/f5/nginx/one/saas/control-plane/pkg/collections/objects" + } + }, + "ConfigSyncStatus": { + "type": "string", + "description": "The current config sync status of the NGINX config sync group, with the following possible values:\n* `unknown` - The status cannot be determined at this moment.\n* `in_sync` - All Nginx instances in config sync group have same config as indicated by config_version.\n* `out_of_sync` - Some Nginx instances in config sync group have config different than indicated by config_version.\n* `sync_in_progress` - The operation of applying config_version to all Nginx instances in config sync group is in progress.\n", + "enum": [ + "unknown", + "in_sync", + "out_of_sync", + "sync_in_progress" + ], + "x-enum-varnames": [ + "nginx_config_sync_group_config_status_unknown", + "nginx_config_sync_group_config_status_in_sync", + "nginx_config_sync_group_config_status_out_of_sync", + "nginx_config_sync_group_config_status_in_progress" + ] + }, + "CertificateInstanceSummary": { + "description": "A breakdown and tally of certificates, detailing the total count, number of expired certificates, certificates nearing expiration, and those that are valid.", "type": "object", + "required": [ + "total", + "expired", + "expiring", + "valid", + "not_ready" + ], "properties": { - "certs": { - "description": "An array detailing each certificate's status across all NGINX instances.", - "type": "array", - "items": { - "$ref": "#/components/schemas/CertificateSummaryItem" - } + "total": { + "description": "Total count of certificates across the NGINX data plane.", + "type": "integer" }, - "os": { - "$ref": "#/components/schemas/OperatingSystemVersionSummary" + "expired": { + "description": "The number of certificates that have expired and are no longer valid.", + "type": "integer" }, - "nginx_versions": { - "$ref": "#/components/schemas/NGINXVersionSummary" + "expiring": { + "description": "The number of certificates due to expire in the next 30 days.", + "type": "integer" }, - "statuses": { - "$ref": "#/components/schemas/StatusSummary" + "valid": { + "description": "The number of certificates that are valid and in good standing.", + "type": "integer" }, - "cves": { - "description": "An array summarizing identified Common Vulnerabilities and Exposures (CVEs) across the NGINX data plane.", - "type": "array", - "items": { - "$ref": "#/components/schemas/CveSummary" - } + "not_ready": { + "description": "The number of certificates that are not ready to be used.", + "type": "integer" + } + } + }, + "ListConfigSyncGroupObject": { + "type": "object", + "description": "Summary information of the NGINX config sync group.", + "required": [ + "object_id", + "name", + "instances_count", + "config_status" + ], + "properties": { + "object_id": { + "$ref": "#/components/schemas/configSyncGroupObjectID" }, - "recommendations": { - "description": "An array summarizing the suggestions from the configuration analysis report.", - "type": "array", - "items": { - "$ref": "#/components/schemas/IssueSummary" + "name": { + "description": "Name of the Nginx config sync group.", + "type": "string" + }, + "instances_count": { + "description": "Number of instances in the Nginx config sync group.", + "type": "integer" + }, + "config_status": { + "$ref": "#/components/schemas/ConfigSyncStatus" + }, + "cert_summary": { + "$ref": "#/components/schemas/CertificateInstanceSummary" + } + } + }, + "ConfigSyncGroupListResponse": { + "allOf": [ + { + "$ref": "#/components/schemas/PaginationResponse" + }, + { + "type": "object", + "description": "List of Nginx config sync groups.", + "required": [ + "items" + ], + "properties": { + "items": { + "description": "An array of Config Sync Group objects.", + "type": "array", + "items": { + "$ref": "#/components/schemas/ListConfigSyncGroupObject" + } + } } } + ], + "example": { + "total": 10, + "count": 1, + "start_index": 1, + "items_per_page": 100, + "items": [ + { + "object_id": "csg_-uvR3F2TQGm18jnl7bpaGw", + "name": "test-config-sync-group", + "config_status": "in_sync", + "instances_count": 1 + } + ] } }, - "FilterNameInstances": { - "type": "string", - "description": "Keywords for instance filters.\n\nWhen filtering on `instance_status`, only the following `filter_values` are supported:\n * online\n * offline\n * unavailable\n * unknown\nWhen filtering base on `cert_status`, only the following `filter_values` are supported:\n * valid\n * expiring\n * expired\n * not_ready\n", - "enum": [ - "hostname", - "nginx_version", - "os_version", - "instance_status", - "cert_status", - "cve_severity", - "config_recommendation", - "key_object_id", - "system_id", + "ConfigSyncGroupCreateRequest": { + "description": "Body to create a Nginx config sync group.", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "A name to uniquely identify the Nginx config sync group in a given tenant namespace.", + "minLength": 1, + "maxLength": 256 + } + }, + "example": { + "name": "my-nginx-config-sync-group" + } + }, + "ConfigSyncGroupCreateResponse": { + "description": "Response to a create Nginx config sync group request.", + "required": [ + "object_id", + "name" + ], + "properties": { + "object_id": { + "$ref": "#/components/schemas/configSyncGroupObjectID" + }, + "name": { + "description": "Name of the Nginx config sync group.", + "type": "string" + } + }, + "example": { + "name": "my-nginx-config-sync-group", + "object_id": "csg_Tet21AeYTHCj7taOwVfzyw" + } + }, + "ConfigSyncGroupBulkRequestData": { + "type": "object", + "description": "Part of bulk operation on a config sync group, only `delete` is supported.", + "required": [ + "action", "object_id" ], - "x-enum-varnames": [ - "filter_name_instances_hostname", - "filter_name_instances_nginx_version", - "filter_name_instances_os_version", - "filter_name_instances_instance_status", - "filter_name_instances_cert_status", - "filter_name_instances_cve_severity", - "filter_name_instances_config_recommendation", - "filter_name_instances_key_object_id", - "filter_name_instances_system_id", - "filter_name_instances_object_id" + "properties": { + "object_id": { + "$ref": "#/components/schemas/configSyncGroupObjectID" + }, + "action": { + "$ref": "#/components/schemas/BulkRequestAction" + } + }, + "example": { + "object_id": "csg_-uvR3F2TQGm18jnl7bpaGw", + "action": "delete" + } + }, + "ConfigSyncGroupBulkRequest": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ConfigSyncGroupBulkRequestData" + }, + "minItems": 1, + "maxItems": 50, + "example": [ + { + "object_id": "csg_-uvR3F2TQGm18jnl7bpaGw", + "action": "delete" + }, + { + "object_id": "csg_PL0c1XodRemmzVEjiXSsTg", + "action": "delete" + } ] }, + "ConfigSyncGroupBulkResponse": { + "description": "The config sync group bulk outcome.", + "type": "array", + "items": { + "$ref": "#/components/schemas/BulkRequestObjectStatus" + } + }, + "ConfigSyncGroupMeta": { + "type": "object", + "description": "Meta information of the NGINX config sync group including:\n* NGINX config sync group object ID\n* unique name of the config sync group in the tenant namespace\n* last publication timestamp\n", + "required": [ + "object_id", + "name" + ], + "properties": { + "object_id": { + "$ref": "#/components/schemas/configSyncGroupObjectID" + }, + "name": { + "description": "Name of the Nginx config sync group.", + "type": "string" + }, + "last_publication": { + "description": "The date and time of the most recent config sync group publication.", + "type": "string", + "format": "date-time" + } + }, + "example": { + "object_id": "csg_-uvR3F2TQGm18jnl7bpaGw", + "name": "test-config-sync-group", + "last_publication": "2023-12-06T22:37:24.120114Z" + } + }, "InstanceObjectID": { "description": "A globally unique identifier for the NGINX instance.", "type": "string", @@ -4451,38 +5075,23 @@ } } }, - "CertificateInstanceSummary": { - "description": "A breakdown and tally of certificates, detailing the total count, number of expired certificates, certificates nearing expiration, and those that are valid.", - "type": "object", - "required": [ - "total", - "expired", - "expiring", - "valid", - "not_ready" + "CveSeverityType": { + "type": "string", + "description": "Severity ratings:\n * `high` - High severity.\n * `medium` - Moderate severity.\n * `low` - Least severe.\n * `none` - Not severe.\n * `other` - Severity that does not fit the other categories.\n", + "enum": [ + "high", + "medium", + "low", + "none", + "other" ], - "properties": { - "total": { - "description": "Total count of certificates across the NGINX data plane.", - "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_ready": { - "description": "The number of certificates that are not ready to be used.", - "type": "integer" - } - } + "x-enum-varnames": [ + "cve_severity_type_high", + "cve_severity_type_medium", + "cve_severity_type_low", + "cve_severity_type_none", + "cve_severity_type_other" + ] }, "CveDetails": { "description": "CVEs details, including the type and count.\n", @@ -4501,6 +5110,22 @@ } } }, + "RecommendationType": { + "type": "string", + "description": "Types of configuration recommendations:\n * `best_practice` - Suggestions based on established best practices.\n * `security` - Recommendations related to security.\n * `optimization` - Advice for optimizing performance.\n * `other` - Recommendations that do not fit the above categories.\n", + "enum": [ + "best_practice", + "security", + "optimization", + "other" + ], + "x-enum-varnames": [ + "recommendation_type_best_practice", + "recommendation_type_security", + "recommendation_type_optimization", + "recommendation_type_other" + ] + }, "IssueDetails": { "description": "Issue details, including the type and count.\n", "type": "object", @@ -4532,227 +5157,111 @@ ], "properties": { "object_id": { - "$ref": "#/components/schemas/InstanceObjectID" - }, - "hostname": { - "description": "The name of the host system where the NGINX instance is running.", - "type": "string" - }, - "system_id": { - "description": "The unique identifier assigned to the host system by the NGINX Agent.", - "type": "string" - }, - "nginx_id": { - "description": "The unique identifier for the NGINX process on the host system, assigned by the NGINX Agent.", - "type": "string" - }, - "agent_version": { - "description": "The version of the NGINX Agent.", - "type": "string" - }, - "key_object_id": { - "$ref": "#/components/schemas/DataPlaneKeyObjectID" - }, - "nginx_build": { - "$ref": "#/components/schemas/NginxBuild" - }, - "os_version": { - "description": "The operating system's name and its and version or codename.\n", - "type": "string", - "example": "ubuntu_jammy" - }, - "registered_at": { - "description": "The date and time when the NGINX instance first registered with NGINX One.", - "type": "string", - "format": "date-time" - }, - "last_reported": { - "description": "The date and time of the most recent report received from the NGINX Agent.", - "type": "string", - "format": "date-time" - }, - "status": { - "type": "string", - "description": "The current operational status of the NGINX instance, with the following possible values:\n* `unknown` - The status of the NGINX instance cannot be determined at this moment.\n* `unavailable` - The NGINX Agent has lost connection to NGINX One, rendering the NGINX instance unavailable.\n* `offline` - The NGINX Agent is connected to NGINX One, but the NGINX instance is offline.\n* `online` - The NGINX Agent is connected to NGINX One, and the NGINX instance is online.\n", - "enum": [ - "unknown", - "unavailable", - "offline", - "online" - ] - }, - "cert_summary": { - "$ref": "#/components/schemas/CertificateInstanceSummary" - }, - "cve_severity": { - "type": "array", - "description": "An array summarizing identified Common Vulnerabilities and Exposures (CVEs) across the NGINX data plane.", - "items": { - "$ref": "#/components/schemas/CveDetails" - } - }, - "recommendations": { - "type": "array", - "description": "An array summarizing the suggestions from the configuration analysis report.", - "items": { - "$ref": "#/components/schemas/IssueDetails" - } - } - } - }, - "InstanceListResponse": { - "allOf": [ - { - "$ref": "#/components/schemas/PaginationResponse" - }, - { - "type": "object", - "description": "List of data plane instances.", - "required": [ - "items" - ], - "properties": { - "items": { - "description": "An array of Instance objects.", - "type": "array", - "items": { - "$ref": "#/components/schemas/Instance" - } - } - } - } - ], - "example": { - "total": 10, - "count": 1, - "start_index": 1, - "items_per_page": 100, - "items": [ - { - "agent_version": "v2.30.3", - "hostname": "4d116619f106", - "key": "key_Tet21AeYTHCj7taOwVfzyw", - "last_reported": "2023-12-06T22:37:24.120114Z", - "nginx_build": { - "conf_path": "/etc/nginx/nginx.conf", - "version": "1.25.3" - }, - "nginx_id": "b636d4376dea15405589692d3c5d3869ff3a9b26b0e7bb4bb1aa7e658ace1437", - "registered_at": "2023-12-06T22:37:24.120114Z", - "status": "unknown", - "system_id": "b2c0b6a8-8b6a-3a8f-a541-17d8899c119a", - "object_id": "inst_-uvR3F2TQGm18jnl7bpaGw" - } - ] - } - }, - "InstanceBulkRequestData": { - "type": "object", - "description": "Part of bulk operation on a NGINX instance, only `delete` is supported.", - "required": [ - "action" - ], - "properties": { - "object_id": { - "$ref": "#/components/schemas/InstanceObjectID" - }, - "action": { - "$ref": "#/components/schemas/BulkRequestAction" - } - }, - "example": { - "object_id": "inst_-uvR3F2TQGm18jnl7bpaGw", - "action": "delete" - } - }, - "InstanceBulkRequest": { - "type": "array", - "items": { - "$ref": "#/components/schemas/InstanceBulkRequestData" - }, - "maxItems": 50, - "example": [ - { - "object_id": "inst_-uvR3F2TQGm18jnl7bpaGw", - "action": "delete" - }, - { - "object_id": "inst_PL0c1XodRemmzVEjiXSsTg", - "action": "delete" - } - ] - }, - "InstanceBulkResponse": { - "description": "The NGINX instance bulk outcome.", - "type": "array", - "items": { - "$ref": "#/components/schemas/BulkRequestObjectStatus" - } - }, - "NginxSecurityAdvisory": { - "type": "object", - "description": "Details about a specific NGINX security advisory, including its severity, a link to more information, and a brief description.", - "required": [ - "id", - "severity", - "advisory", - "info" - ], - "properties": { - "id": { - "description": "The security advisory's unique identifier.", + "$ref": "#/components/schemas/InstanceObjectID" + }, + "hostname": { + "description": "The name of the host system where the NGINX instance is running.", "type": "string" }, - "severity": { - "$ref": "#/components/schemas/CveSeverityType" + "system_id": { + "description": "The unique identifier assigned to the host system by the NGINX Agent.", + "type": "string" }, - "advisory": { - "description": "The URL to detailed information about the security advisory.", + "nginx_id": { + "description": "The unique identifier for the NGINX process on the host system, assigned by the NGINX Agent.", "type": "string" }, - "info": { - "description": "A brief description of security advisory.", + "agent_version": { + "description": "The version of the NGINX Agent.", "type": "string" + }, + "key_object_id": { + "$ref": "#/components/schemas/DataPlaneKeyObjectID" + }, + "nginx_build": { + "$ref": "#/components/schemas/NginxBuild" + }, + "os_version": { + "description": "The operating system's name and its and version or codename.\n", + "type": "string", + "example": "ubuntu_jammy" + }, + "registered_at": { + "description": "The date and time when the NGINX instance first registered with NGINX One.", + "type": "string", + "format": "date-time" + }, + "last_reported": { + "description": "The date and time of the most recent report received from the NGINX Agent.", + "type": "string", + "format": "date-time" + }, + "status": { + "type": "string", + "description": "The current operational status of the NGINX instance, with the following possible values:\n* `unknown` - The status of the NGINX instance cannot be determined at this moment.\n* `unavailable` - The NGINX Agent has lost connection to NGINX One, rendering the NGINX instance unavailable.\n* `offline` - The NGINX Agent is connected to NGINX One, but the NGINX instance is offline.\n* `online` - The NGINX Agent is connected to NGINX One, and the NGINX instance is online.\n", + "enum": [ + "unknown", + "unavailable", + "offline", + "online" + ] + }, + "cert_summary": { + "$ref": "#/components/schemas/CertificateInstanceSummary" + }, + "cve_severity": { + "type": "array", + "description": "An array summarizing identified Common Vulnerabilities and Exposures (CVEs) across the NGINX data plane.", + "items": { + "$ref": "#/components/schemas/CveDetails" + } + }, + "recommendations": { + "type": "array", + "description": "An array summarizing the suggestions from the configuration analysis report.", + "items": { + "$ref": "#/components/schemas/IssueDetails" + } } } }, - "CertificateObjectID": { - "description": "A globally unique identifier for the certificates.", - "type": "string", - "format": "object_id", - "pattern": "^cert_.*", - "x-go-type": "objects.ID", - "x-go-type-import": { - "name": "objects", - "path": "gitlab.com/f5/nginx/one/saas/control-plane/pkg/collections/objects" - } - }, - "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", - "enum": [ - "ca_bundle", - "cert_key", - "unmanaged" - ], - "x-enum-varnames": [ - "certificate_type_ca_bundle", - "certificate_type_pem_cert_key", - "certificate_type_unmanaged" + "ConfigSyncGroupInstance": { + "allOf": [ + { + "$ref": "#/components/schemas/Instance" + }, + { + "type": "object", + "required": [ + "config_status", + "config_version" + ], + "properties": { + "config_status": { + "$ref": "#/components/schemas/ConfigSyncStatus" + }, + "config_version": { + "description": "A computed hash of current config on the config sync group.", + "type": "string" + } + } + } ] }, - "CertificateDeploymentStatus": { + "ConfigSyncGroupPublicationStatus": { "type": "string", - "description": "Certificate deployment status:\n * `latest` - This certificate deployment is up to date with the latest certificates and key.\n * `stale` - This certificate deployment is outdated and needs to deploy the latest certificates and key.\n * `unmanaged` - This certificate deployment is unmanaged by NGINX One Console.\n", + "description": "The status on the last publication issued on this config sync group:\n* `pending` - The publication request has been accepted and is currently processing.\n* `failed` - The publication attempt failed.\n* `succeeded` - The publication was successful.\n* `partially_succeeded` - The publication attempt had one or more failures.\n", "enum": [ - "latest", - "stale", - "unmanaged" + "pending", + "failed", + "succeeded", + "partially_succeeded" ], "x-enum-varnames": [ - "certificate_deployment_status_latest", - "certificate_deployment_status_stale", - "certificate_deployment_status_unmanaged" + "publication_config_sync_group_status_pending", + "publication_config_sync_group_status_failed", + "publication_config_sync_group_status_succeeded", + "publication_config_sync_group_status_partially_succeeded" ] }, "CertAssociation": { @@ -4824,144 +5333,67 @@ } } }, - "OperatingSystem": { - "description": "Release details for the operating system.", - "type": "object", - "required": [ - "name", - "id", - "codename", - "version", - "version_id" - ], - "properties": { - "name": { - "description": "The official name of the operating system release.", - "type": "string" - }, - "id": { - "description": "The distinctive identifier for the operating system release.", - "type": "string" - }, - "codename": { - "description": "The codename assigned to the operating system release.", - "type": "string" - }, - "version": { - "description": "The version label for the operating system, which may include the name and version number or codename.", - "type": "string" - }, - "version_id": { - "description": "The specific version number of the operating system release.", - "type": "string" - } - }, - "example": { - "name": "Ubuntu", - "id": "ubuntu", - "codename": "bionic", - "version": "18.04.5 LTS (Bionic Beaver)", - "version_id": "18.04" - } - }, - "configSyncGroupObjectID": { - "description": "A globally unique identifier for the NGINX config sync group.", - "type": "string", - "format": "object_id", - "pattern": "^csg_.*", - "x-go-type": "objects.ID", - "x-go-type-import": { - "name": "objects", - "path": "gitlab.com/f5/nginx/one/saas/control-plane/pkg/collections/objects" - } - }, - "ConfigSyncGroupMeta": { - "type": "object", - "description": "Meta information of the NGINX config sync group including:\n* NGINX config sync group object ID\n* unique name of the config sync group in the tenant namespace\n* last publication timestamp\n", - "required": [ - "object_id", - "name" - ], - "properties": { - "object_id": { - "$ref": "#/components/schemas/configSyncGroupObjectID" - }, - "name": { - "description": "Name of the Nginx config sync group.", - "type": "string" - }, - "last_publication": { - "description": "The date and time of the most recent config sync group publication.", - "type": "string", - "format": "date-time" - } - }, - "example": { - "object_id": "csg_-uvR3F2TQGm18jnl7bpaGw", - "name": "test-config-sync-group", - "last_publication": "2023-12-06T22:37:24.120114Z" - } - }, - "ConfigSyncStatus": { - "type": "string", - "description": "The current config sync status of the NGINX config sync group, with the following possible values:\n* `unknown` - The status cannot be determined at this moment.\n* `in_sync` - All Nginx instances in config sync group have same config as indicated by config_version.\n* `out_of_sync` - Some Nginx instances in config sync group have config different than indicated by config_version.\n* `sync_in_progress` - The operation of applying config_version to all Nginx instances in config sync group is in progress.\n", - "enum": [ - "unknown", - "in_sync", - "out_of_sync", - "sync_in_progress" - ], - "x-enum-varnames": [ - "nginx_config_sync_group_config_status_unknown", - "nginx_config_sync_group_config_status_in_sync", - "nginx_config_sync_group_config_status_out_of_sync", - "nginx_config_sync_group_config_status_in_progress" - ] - }, - "ConfigSyncGroupInstanceMeta": { + "ConfigSyncGroup": { "allOf": [ { "$ref": "#/components/schemas/ConfigSyncGroupMeta" }, { "type": "object", - "description": "Additional details on instance in the NGINX config sync group including:\n* config sync status\n", + "description": "Additional information of the NGINX config sync group including:\n* config sync status\n* config checksum\n* instances\n* last known publication status\n* certs associated with this config sync group\n", "properties": { - "instance_config_status": { + "config_status": { "$ref": "#/components/schemas/ConfigSyncStatus" - } - } - } - ] - }, - "InstanceDetails": { - "type": "object", - "description": "Detailed information about an NGINX instance.", - "allOf": [ - { - "$ref": "#/components/schemas/Instance" - }, - { - "type": "object", - "properties": { + }, + "config_version": { + "description": "A computed hash of current config on the config sync group.", + "type": "string" + }, + "instances": { + "description": "An array of Instance objects.", + "type": "array", + "items": { + "$ref": "#/components/schemas/ConfigSyncGroupInstance" + } + }, + "last_publication_status": { + "$ref": "#/components/schemas/ConfigSyncGroupPublicationStatus" + }, "certs": { - "description": "An array detailing each certificate's information, including its friendly name, unique identifier, applicable file system paths, subject name, and validity dates. \nIt provides insights into the operational status of each certificate, such as whether it's currently valid, nearing expiration, is not ready to be used, or has already expired.\nThe deployment status indicates whether the latest certs and key managed by NGINX One Console are deployed onto this data plane instance.\n", + "description": "An array detailing each certificate's information, including its friendly name, unique identifier, applicable file system paths, subject name, and validity dates. \nIt provides insights into the operational status of each certificate, such as whether it's currently valid, nearing expiration, is not ready to be used, or has already expired.\nThe deployment status indicates whether the latest certs and key managed by NGINX One Console are deployed onto the data plane instances that are part of this config sync group.\n", "type": "array", "items": { "$ref": "#/components/schemas/CertAssociation" } - }, - "os": { - "$ref": "#/components/schemas/OperatingSystem" - }, - "config_sync_group": { - "$ref": "#/components/schemas/ConfigSyncGroupInstanceMeta" } } } ], "example": { - "agent_version": "v2.30.3", + "object_id": "csg_-uvR3F2TQGm18jnl7bpaGw", + "name": "test-config-sync-group", + "last_reported": "2023-12-06T22:37:24.120114Z", + "config_status": "in_sync", + "config_version": "uvR3F2TQGm18jnl7bpaGw", + "instances": [ + { + "object_id": "inst_-uvR3F2TQGm18jnl7bpaGw", + "hostname": "816e3c194d59", + "system_id": "6066aad2-211e-3718-be5d-fcc01ffc5cc8", + "agent_version": "v2.33.0", + "registered_at": "2024-05-16T18:26:40.556048Z", + "last_reported": "2023-12-06T22:37:24.120114Z", + "status": "unavailable", + "nginx_build": { + "conf_path": "/etc/nginx/nginx.conf", + "version": "1.25.3" + }, + "os_version": "Ubuntu 22.04", + "nginx_id": "b636d4376dea15405589692d3c5d3869ff3a9b26b0e7bb4bb1aa7e658ace1437", + "config_status": "in_sync", + "config_version": "abc123def456" + } + ], "certs": [ { "subject_name": "test.com", @@ -4976,98 +5408,31 @@ "deployment_status": "latest", "object_id": "cert_Tet21AeYTHCj7taOwVfzyw" } - ], - "hostname": "4d116619f106", - "key": "key_wN3IhLCmR3qmwybG_6ptEg", - "last_reported": "2023-12-06T22:37:24.120114Z", - "nginx_build": { - "conf_path": "/etc/nginx/nginx.conf", - "version": "1.25.3" - }, - "nginx_id": "b636d4376dea15405589692d3c5d3869ff3a9b26b0e7bb4bb1aa7e658ace1437", - "os": { - "codename": "jammy", - "id": "ubuntu", - "name": "Ubuntu", - "version": "22.04.3 LTS (Jammy Jellyfish)", - "version_id": "22.04" - }, - "registered_at": "2023-12-06T22:37:24.120114Z", - "status": "unknown", - "system_id": "b2c0b6a8-8b6a-3a8f-a541-17d8899c119a", - "object_id": "inst_-uvR3F2TQGm18jnl7bpaGw" - } - }, - "NginxConfigProblem": { - "type": "object", - "description": "Representation of a problem found during NGINX configuration analysis.", - "properties": { - "directive": { - "description": "Directive in the NGINX configuration where the issue is identified.", - "type": "string" - }, - "file": { - "description": "File where the issue is detected.", - "type": "string" - }, - "line": { - "description": "Line number in the configuration where the issue is found.", - "type": "integer" - } + ] } }, - "NginxConfigReport": { + "ConfigSyncGroupDetails": { "type": "object", - "description": "An analysis of the NGINX configuration, highlighting issues and their severity, and offering recommendations.", - "properties": { - "rule": { - "description": "The name of the configuration rule that was violated.", - "type": "string" - }, - "info": { - "description": "A detailed description of the issue.", - "type": "string" - }, - "severity": { - "description": "The severity level of the issue.", - "type": "string" - }, - "category": { - "description": "Classification category of the issue.", - "type": "string" - }, - "documentation": { - "description": "Links to documentation that can assist in resolving the identified issue.", - "type": "array", - "items": { - "type": "string" - } - }, - "where": { - "description": "Specific locations in the configuration where issues were detected.", - "type": "array", - "items": { - "$ref": "#/components/schemas/NginxConfigProblem" - } + "description": "Detailed information of the NGINX config sync group.", + "allOf": [ + { + "$ref": "#/components/schemas/ConfigSyncGroup" } - } - }, - "NginxConfigReports": { - "type": "array", - "items": { - "$ref": "#/components/schemas/NginxConfigReport" - } + ] }, - "FileDataRequest": { + "FileData": { "type": "object", - "description": "Details about a file, name, and content.", + "description": "Details about a file, including its path, content, size, and last modified time.", "required": [ - "name" + "name", + "contents", + "size", + "mtime" ], "properties": { "name": { "type": "string", - "description": "The file's relative path to the parent directory, absolute path also accepted.", + "description": "The file's relative path to the parent directory.", "minLength": 1, "maxLength": 4096 }, @@ -5076,12 +5441,21 @@ "format": "byte", "description": "The base64-encoded contents of the file.", "maxLength": 3145728 + }, + "size": { + "type": "integer", + "description": "The size of the file, in bytes." + }, + "mtime": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the last modification made to the file." } } }, - "DirectoryRequestWithFileContent": { + "DirectoryWithFileContent": { "type": "object", - "description": "Represents a directory and its contents, detailing the directory's full path, and the files within it.", + "description": "Represents a directory and its contents, detailing the directory's full path, assigned permissions, last modified time, and the files within it.", "required": [ "name", "files" @@ -5089,19 +5463,27 @@ "properties": { "name": { "type": "string", - "minLength": 1, "description": "The complete path of the directory." }, + "permissions": { + "type": "string", + "description": "The permissions for the directory." + }, + "mtime": { + "type": "string", + "description": "The date and time when the directory was last modified.", + "format": "date-time" + }, "files": { "type": "array", "description": "The list of files in the directory.", "items": { - "$ref": "#/components/schemas/FileDataRequest" + "$ref": "#/components/schemas/FileData" } } } }, - "NginxConfigObjectRequest": { + "NginxConfigObject": { "type": "object", "description": "Details of an NGINX configuration, the main configuration path, and the configuration directories.\n", "required": [ @@ -5124,16 +5506,61 @@ "type": "array", "description": "An array of directories containing NGINX configuration files.", "items": { - "$ref": "#/components/schemas/DirectoryRequestWithFileContent" + "$ref": "#/components/schemas/DirectoryWithFileContent" } }, "aux": { "type": "array", - "description": "An array of auxiliary directory contents related to the NGINX configuration. When auxiliary contents are\nprovided, they become the authoritative source of non-NGINX configuration content. Please ensure the\nprovided contents are complete, missing files that are referenced in the NGINX configuration can cause\nNGINX reload failure. When not provided, the previous known auxiliary contents will be used as part of\npublish.\n", + "description": "An array of auxiliary directory contents related to the NGINX configuration.", "items": { - "$ref": "#/components/schemas/DirectoryRequestWithFileContent" + "$ref": "#/components/schemas/DirectoryWithFileContent" } } + }, + "example": { + "aux": [], + "conf_path": "/etc/nginx/nginx.conf", + "configs": [ + { + "files": [ + { + "contents": "Cm1hcCAkdXJpICRtYXBwZWRfc2VydmljZSB7CiAgICBkZWZhdWx0IFVOTUFUQ0hFRDsKICAgICJ+Xi9hcGkvdjEvbmFtZXNwYWNlcy9cdysvaW5zdGFuY2VzIiAgICAgICAgaW5zdGFuY2VzLXN2YzsKICAgICJ+Xi9hcGkvdjEvbmFtZXNwYWNlcy9cdysvZGF0YS1wbGFuZS1rZXlzIiAga2V5cy1zdmM7CiAgICAifl4vYXBpL3YxL25hbWVzcGFjZXMvXHcrL21vbml0b3IiICAgICAgICAgIG1vbml0b3Itc3ZjOwp9Cgp1cHN0cmVhbSBpbnN0YW5jZXMtc3ZjIHsKICAgIHNlcnZlciBpbnN0YW5jZXMtc3ZjOjgwODA7Cn0KCnVwc3RyZWFtIGtleXMtc3ZjIHsKICAgIHNlcnZlciBrZXlzLXN2Yzo4MDkwOwp9Cgp1cHN0cmVhbSBkYXRhcGxhbmUtY3RybCB7CiAgICBzZXJ2ZXIgZGF0YXBsYW5lLWN0cmw6ODA4MDsKfQoKdXBzdHJlYW0gbW9uaXRvci1zdmMgewogICAgc2VydmVyIG1vbml0b3Itc3ZjOjgwODA7Cn0KCnVwc3RyZWFtIG1ldHJpY3MtaW5nZXN0IHsKICAgIHNlcnZlciBtZXRyaWNzLWluZ2VzdDo4MDgwOwp9CgpzZXJ2ZXIgewogICAgbGlzdGVuIDg4ODg7CiAgICBzZXJ2ZXJfbmFtZSBfOwogICAgaHR0cDIgb247CgogICAgcHJveHlfcGFzc19yZXF1ZXN0X2hlYWRlcnMgb247CiAgICByZXdyaXRlICJeL2FwaS8obmdpbngvb25lfHYxKS8oLiopJCIgIi9hcGkvdjEvJDIiIGJyZWFrOwogICAgbG9jYXRpb24gL2FwaS92MS8gewogICAgICAgIGlmICgkbWFwcGVkX3NlcnZpY2UgPSAiVU5NQVRDSEVEIikgewogICAgICAgICAgICByZXR1cm4gNDA0ICd7ImVycm9yOiAiTm90IGZvdW5kIn0nOwogICAgICAgIH0KICAgICAgICBwcm94eV9wYXNzX2hlYWRlciBYLVZvbHRlcnJhLUFwaWd3LVRlbmFudDsKICAgICAgICBwcm94eV9wYXNzIGh0dHA6Ly8kbWFwcGVkX3NlcnZpY2U7CiAgICB9CgogICAgIyBnUlBDIHNlcnZpY2UgZm9yIGRhdGFwbGFuZS1jdHJsCiAgICBsb2NhdGlvbiAvZjUubmdpbnguYWdlbnQuc2RrLkNvbW1hbmRlciB7CiAgICAgICAgZ3JwY19zb2NrZXRfa2VlcGFsaXZlIG9uOwogICAgICAgIGdycGNfcmVhZF90aW1lb3V0IDVtOwogICAgICAgIGdycGNfc2VuZF90aW1lb3V0IDVtOwogICAgICAgIGNsaWVudF9ib2R5X3RpbWVvdXQgMTBtOwogICAgICAgIGdycGNfcGFzcyBncnBjOi8vZGF0YXBsYW5lLWN0cmw7CiAgICB9CgogICAgIyBnUlBDIHNlcnZpY2UgZm9yIG1ldHJpY3MgaW5nZXN0aW9uCiAgICBsb2NhdGlvbiAvZjUubmdpbnguYWdlbnQuc2RrLk1ldHJpY3NTZXJ2aWNlIHsKICAgICAgICBncnBjX3NvY2tldF9rZWVwYWxpdmUgb247CiAgICAgICAgZ3JwY19yZWFkX3RpbWVvdXQgNW07CiAgICAgICAgZ3JwY19zZW5kX3RpbWVvdXQgNW07CiAgICAgICAgY2xpZW50X2JvZHlfdGltZW91dCAxMG07CiAgICAgICAgY2xpZW50X21heF9ib2R5X3NpemUgMDsKICAgICAgICBncnBjX3Bhc3MgZ3JwYzovL21ldHJpY3MtaW5nZXN0OwogICAgfQp9CgojIHByb3h5IHRvIHRoZSBtYW5hZ2VtZW50IHNlcnZlcnMKc2VydmVyIHsKICAgIGxpc3RlbiAxNTAwMDsKICAgIHNlcnZlcl9uYW1lIF87CiAgICAjIHVzZSBkb2NrZXIgRE5TCiAgICByZXNvbHZlciAxMjcuMC4wLjExIHZhbGlkPTMwczsKCiAgICAjIG1hdGNoIC88c2VydmljZT4vPG1nbXQgZW5kcG9pbnQ+CiAgICBsb2NhdGlvbiB+Xi8oW14vXSspLyguKykkIHsKICAgICAgICBwcm94eV9wYXNzIGh0dHA6Ly8kMToxNTAwMC8kMjsKICAgIH0KCiAgICBsb2NhdGlvbiAvIHsKICAgICAgICBhZGRfaGVhZGVyICJDb250ZW50LVR5cGUiICJ0ZXh0L2h0bWwiOwogICAgICAgIHJldHVybiAyMDAgIjxwPkFjY2VzcyB0aGUgbWFuYWdlbWVudCBzZXJ2ZXIgb2YgYW55IHNlcnZpY2Ugd2l0aCBVUkxzIGxpa2UgPGNvZGU+aHR0cDovL2xvY2FsaG9zdDoxNTAwMC8mbHQ7U0VSVklDRV9OQU1FJmd0Oy9tZXRyaWNzPC9jb2RlPjwvcD4iOwogICAgfQp9Cg==", + "mtime": "1970-01-01T00:00:00Z", + "name": "default.conf", + "size": 1942 + } + ], + "name": "/etc/nginx/conf.d" + }, + { + "files": [ + { + "contents": "CnVzZXIgIG5naW54Owp3b3JrZXJfcHJvY2Vzc2VzICBhdXRvOwoKZXJyb3JfbG9nICAvdmFyL2xvZy9uZ2lueC9lcnJvci5sb2cgbm90aWNlOwpwaWQgICAgICAgIC92YXIvcnVuL25naW54LnBpZDsKCgpldmVudHMgewogICAgd29ya2VyX2Nvbm5lY3Rpb25zICAxMDI0Owp9CgoKaHR0cCB7CiAgICBpbmNsdWRlICAgICAgIC9ldGMvbmdpbngvbWltZS50eXBlczsKICAgIGRlZmF1bHRfdHlwZSAgYXBwbGljYXRpb24vb2N0ZXQtc3RyZWFtOwoKICAgIGxvZ19mb3JtYXQgIG1haW4gICckcmVtb3RlX2FkZHIgLSAkcmVtb3RlX3VzZXIgWyR0aW1lX2xvY2FsXSAiJHJlcXVlc3QiICcKICAgICAgICAgICAgICAgICAgICAgICckc3RhdHVzICRib2R5X2J5dGVzX3NlbnQgIiRodHRwX3JlZmVyZXIiICcKICAgICAgICAgICAgICAgICAgICAgICciJGh0dHBfdXNlcl9hZ2VudCIgIiRodHRwX3hfZm9yd2FyZGVkX2ZvciInOwoKICAgIGFjY2Vzc19sb2cgIC92YXIvbG9nL25naW54L2FjY2Vzcy5sb2cgIG1haW47CgogICAgc2VuZGZpbGUgICAgICAgIG9uOwogICAgI3RjcF9ub3B1c2ggICAgIG9uOwoKICAgIGtlZXBhbGl2ZV90aW1lb3V0ICA2NTsKCiAgICAjZ3ppcCAgb247CgogICAgaW5jbHVkZSAvZXRjL25naW54L2NvbmYuZC8qLmNvbmY7Cn0K", + "mtime": "1970-01-01T00:00:00Z", + "name": "nginx.conf", + "size": 648 + }, + { + "contents": "CnR5cGVzIHsKICAgIHRleHQvaHRtbCAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBodG1sIGh0bSBzaHRtbDsKICAgIHRleHQvY3NzICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBjc3M7CiAgICB0ZXh0L3htbCAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgeG1sOwogICAgaW1hZ2UvZ2lmICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIGdpZjsKICAgIGltYWdlL2pwZWcgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBqcGVnIGpwZzsKICAgIGFwcGxpY2F0aW9uL2phdmFzY3JpcHQgICAgICAgICAgICAgICAgICAgICAgICAgICBqczsKICAgIGFwcGxpY2F0aW9uL2F0b20reG1sICAgICAgICAgICAgICAgICAgICAgICAgICAgICBhdG9tOwogICAgYXBwbGljYXRpb24vcnNzK3htbCAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIHJzczsKCiAgICB0ZXh0L21hdGhtbCAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgbW1sOwogICAgdGV4dC9wbGFpbiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIHR4dDsKICAgIHRleHQvdm5kLnN1bi5qMm1lLmFwcC1kZXNjcmlwdG9yICAgICAgICAgICAgICAgICBqYWQ7CiAgICB0ZXh0L3ZuZC53YXAud21sICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgd21sOwogICAgdGV4dC94LWNvbXBvbmVudCAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIGh0YzsKCiAgICBpbWFnZS9hdmlmICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgYXZpZjsKICAgIGltYWdlL3BuZyAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBwbmc7CiAgICBpbWFnZS9zdmcreG1sICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgc3ZnIHN2Z3o7CiAgICBpbWFnZS90aWZmICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgdGlmIHRpZmY7CiAgICBpbWFnZS92bmQud2FwLndibXAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgd2JtcDsKICAgIGltYWdlL3dlYnAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICB3ZWJwOwogICAgaW1hZ2UveC1pY29uICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIGljbzsKICAgIGltYWdlL3gtam5nICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBqbmc7CiAgICBpbWFnZS94LW1zLWJtcCAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgYm1wOwoKICAgIGZvbnQvd29mZiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICB3b2ZmOwogICAgZm9udC93b2ZmMiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIHdvZmYyOwoKICAgIGFwcGxpY2F0aW9uL2phdmEtYXJjaGl2ZSAgICAgICAgICAgICAgICAgICAgICAgICBqYXIgd2FyIGVhcjsKICAgIGFwcGxpY2F0aW9uL2pzb24gICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBqc29uOwogICAgYXBwbGljYXRpb24vbWFjLWJpbmhleDQwICAgICAgICAgICAgICAgICAgICAgICAgIGhxeDsKICAgIGFwcGxpY2F0aW9uL21zd29yZCAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBkb2M7CiAgICBhcHBsaWNhdGlvbi9wZGYgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgcGRmOwogICAgYXBwbGljYXRpb24vcG9zdHNjcmlwdCAgICAgICAgICAgICAgICAgICAgICAgICAgIHBzIGVwcyBhaTsKICAgIGFwcGxpY2F0aW9uL3J0ZiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBydGY7CiAgICBhcHBsaWNhdGlvbi92bmQuYXBwbGUubXBlZ3VybCAgICAgICAgICAgICAgICAgICAgbTN1ODsKICAgIGFwcGxpY2F0aW9uL3ZuZC5nb29nbGUtZWFydGgua21sK3htbCAgICAgICAgICAgICBrbWw7CiAgICBhcHBsaWNhdGlvbi92bmQuZ29vZ2xlLWVhcnRoLmtteiAgICAgICAgICAgICAgICAga216OwogICAgYXBwbGljYXRpb24vdm5kLm1zLWV4Y2VsICAgICAgICAgICAgICAgICAgICAgICAgIHhsczsKICAgIGFwcGxpY2F0aW9uL3ZuZC5tcy1mb250b2JqZWN0ICAgICAgICAgICAgICAgICAgICBlb3Q7CiAgICBhcHBsaWNhdGlvbi92bmQubXMtcG93ZXJwb2ludCAgICAgICAgICAgICAgICAgICAgcHB0OwogICAgYXBwbGljYXRpb24vdm5kLm9hc2lzLm9wZW5kb2N1bWVudC5ncmFwaGljcyAgICAgIG9kZzsKICAgIGFwcGxpY2F0aW9uL3ZuZC5vYXNpcy5vcGVuZG9jdW1lbnQucHJlc2VudGF0aW9uICBvZHA7CiAgICBhcHBsaWNhdGlvbi92bmQub2FzaXMub3BlbmRvY3VtZW50LnNwcmVhZHNoZWV0ICAgb2RzOwogICAgYXBwbGljYXRpb24vdm5kLm9hc2lzLm9wZW5kb2N1bWVudC50ZXh0ICAgICAgICAgIG9kdDsKICAgIGFwcGxpY2F0aW9uL3ZuZC5vcGVueG1sZm9ybWF0cy1vZmZpY2Vkb2N1bWVudC5wcmVzZW50YXRpb25tbC5wcmVzZW50YXRpb24KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBwcHR4OwogICAgYXBwbGljYXRpb24vdm5kLm9wZW54bWxmb3JtYXRzLW9mZmljZWRvY3VtZW50LnNwcmVhZHNoZWV0bWwuc2hlZXQKICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICB4bHN4OwogICAgYXBwbGljYXRpb24vdm5kLm9wZW54bWxmb3JtYXRzLW9mZmljZWRvY3VtZW50LndvcmRwcm9jZXNzaW5nbWwuZG9jdW1lbnQKICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBkb2N4OwogICAgYXBwbGljYXRpb24vdm5kLndhcC53bWxjICAgICAgICAgICAgICAgICAgICAgICAgIHdtbGM7CiAgICBhcHBsaWNhdGlvbi93YXNtICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgd2FzbTsKICAgIGFwcGxpY2F0aW9uL3gtN3otY29tcHJlc3NlZCAgICAgICAgICAgICAgICAgICAgICA3ejsKICAgIGFwcGxpY2F0aW9uL3gtY29jb2EgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBjY287CiAgICBhcHBsaWNhdGlvbi94LWphdmEtYXJjaGl2ZS1kaWZmICAgICAgICAgICAgICAgICAgamFyZGlmZjsKICAgIGFwcGxpY2F0aW9uL3gtamF2YS1qbmxwLWZpbGUgICAgICAgICAgICAgICAgICAgICBqbmxwOwogICAgYXBwbGljYXRpb24veC1tYWtlc2VsZiAgICAgICAgICAgICAgICAgICAgICAgICAgIHJ1bjsKICAgIGFwcGxpY2F0aW9uL3gtcGVybCAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBwbCBwbTsKICAgIGFwcGxpY2F0aW9uL3gtcGlsb3QgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBwcmMgcGRiOwogICAgYXBwbGljYXRpb24veC1yYXItY29tcHJlc3NlZCAgICAgICAgICAgICAgICAgICAgIHJhcjsKICAgIGFwcGxpY2F0aW9uL3gtcmVkaGF0LXBhY2thZ2UtbWFuYWdlciAgICAgICAgICAgICBycG07CiAgICBhcHBsaWNhdGlvbi94LXNlYSAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgc2VhOwogICAgYXBwbGljYXRpb24veC1zaG9ja3dhdmUtZmxhc2ggICAgICAgICAgICAgICAgICAgIHN3ZjsKICAgIGFwcGxpY2F0aW9uL3gtc3R1ZmZpdCAgICAgICAgICAgICAgICAgICAgICAgICAgICBzaXQ7CiAgICBhcHBsaWNhdGlvbi94LXRjbCAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgdGNsIHRrOwogICAgYXBwbGljYXRpb24veC14NTA5LWNhLWNlcnQgICAgICAgICAgICAgICAgICAgICAgIGRlciBwZW0gY3J0OwogICAgYXBwbGljYXRpb24veC14cGluc3RhbGwgICAgICAgICAgICAgICAgICAgICAgICAgIHhwaTsKICAgIGFwcGxpY2F0aW9uL3hodG1sK3htbCAgICAgICAgICAgICAgICAgICAgICAgICAgICB4aHRtbDsKICAgIGFwcGxpY2F0aW9uL3hzcGYreG1sICAgICAgICAgICAgICAgICAgICAgICAgICAgICB4c3BmOwogICAgYXBwbGljYXRpb24vemlwICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIHppcDsKCiAgICBhcHBsaWNhdGlvbi9vY3RldC1zdHJlYW0gICAgICAgICAgICAgICAgICAgICAgICAgYmluIGV4ZSBkbGw7CiAgICBhcHBsaWNhdGlvbi9vY3RldC1zdHJlYW0gICAgICAgICAgICAgICAgICAgICAgICAgZGViOwogICAgYXBwbGljYXRpb24vb2N0ZXQtc3RyZWFtICAgICAgICAgICAgICAgICAgICAgICAgIGRtZzsKICAgIGFwcGxpY2F0aW9uL29jdGV0LXN0cmVhbSAgICAgICAgICAgICAgICAgICAgICAgICBpc28gaW1nOwogICAgYXBwbGljYXRpb24vb2N0ZXQtc3RyZWFtICAgICAgICAgICAgICAgICAgICAgICAgIG1zaSBtc3AgbXNtOwoKICAgIGF1ZGlvL21pZGkgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBtaWQgbWlkaSBrYXI7CiAgICBhdWRpby9tcGVnICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgbXAzOwogICAgYXVkaW8vb2dnICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIG9nZzsKICAgIGF1ZGlvL3gtbTRhICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBtNGE7CiAgICBhdWRpby94LXJlYWxhdWRpbyAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgcmE7CgogICAgdmlkZW8vM2dwcCAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDNncHAgM2dwOwogICAgdmlkZW8vbXAydCAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIHRzOwogICAgdmlkZW8vbXA0ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIG1wNDsKICAgIHZpZGVvL21wZWcgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBtcGVnIG1wZzsKICAgIHZpZGVvL3F1aWNrdGltZSAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBtb3Y7CiAgICB2aWRlby93ZWJtICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgd2VibTsKICAgIHZpZGVvL3gtZmx2ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBmbHY7CiAgICB2aWRlby94LW00diAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgbTR2OwogICAgdmlkZW8veC1tbmcgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIG1uZzsKICAgIHZpZGVvL3gtbXMtYXNmICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBhc3ggYXNmOwogICAgdmlkZW8veC1tcy13bXYgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIHdtdjsKICAgIHZpZGVvL3gtbXN2aWRlbyAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBhdmk7Cn0K", + "mtime": "1970-01-01T00:00:00Z", + "name": "mime.types", + "size": 5349 + } + ], + "name": "/etc/nginx" + } + ] + } + }, + "NginxConfigObjectID": { + "description": "A globally unique identifier for the NGINX Config object.", + "type": "string", + "format": "object_id", + "pattern": "^nc_.*", + "x-go-type": "objects.ID", + "x-go-type-import": { + "name": "objects", + "path": "gitlab.com/f5/nginx/one/saas/control-plane/pkg/collections/objects" } }, "NginxConfigPayload": { @@ -5216,14 +5643,21 @@ } ] }, - "NginxConfigRequest": { + "NginxConfig": { + "description": "Details of an NGINX configuration, including its unique identifier, the main configuration path, the \nconfiguration directories, and the NGINX configuration payloads that indicate where managed SSL certificates\nand keys were deployed to on the data plane instance.\n", "allOf": [ { - "$ref": "#/components/schemas/NginxConfigObjectRequest" + "$ref": "#/components/schemas/NginxConfigObject" }, { "type": "object", + "required": [ + "object_id" + ], "properties": { + "object_id": { + "$ref": "#/components/schemas/NginxConfigObjectID" + }, "payloads": { "$ref": "#/components/schemas/NginxConfigPayloads" } @@ -5231,19 +5665,16 @@ } ] }, - "FileData": { + "FileDataRequest": { "type": "object", - "description": "Details about a file, including its path, content, size, and last modified time.", + "description": "Details about a file, name, and content.", "required": [ - "name", - "contents", - "size", - "mtime" + "name" ], "properties": { "name": { "type": "string", - "description": "The file's relative path to the parent directory.", + "description": "The file's relative path to the parent directory, absolute path also accepted.", "minLength": 1, "maxLength": 4096 }, @@ -5252,21 +5683,12 @@ "format": "byte", "description": "The base64-encoded contents of the file.", "maxLength": 3145728 - }, - "size": { - "type": "integer", - "description": "The size of the file, in bytes." - }, - "mtime": { - "type": "string", - "format": "date-time", - "description": "Timestamp of the last modification made to the file." } } }, - "DirectoryWithFileContent": { + "DirectoryRequestWithFileContent": { "type": "object", - "description": "Represents a directory and its contents, detailing the directory's full path, assigned permissions, last modified time, and the files within it.", + "description": "Represents a directory and its contents, detailing the directory's full path, and the files within it.", "required": [ "name", "files" @@ -5274,27 +5696,19 @@ "properties": { "name": { "type": "string", + "minLength": 1, "description": "The complete path of the directory." }, - "permissions": { - "type": "string", - "description": "The permissions for the directory." - }, - "mtime": { - "type": "string", - "description": "The date and time when the directory was last modified.", - "format": "date-time" - }, "files": { "type": "array", "description": "The list of files in the directory.", "items": { - "$ref": "#/components/schemas/FileData" + "$ref": "#/components/schemas/FileDataRequest" } } } }, - "NginxConfigObject": { + "NginxConfigObjectRequest": { "type": "object", "description": "Details of an NGINX configuration, the main configuration path, and the configuration directories.\n", "required": [ @@ -5317,78 +5731,26 @@ "type": "array", "description": "An array of directories containing NGINX configuration files.", "items": { - "$ref": "#/components/schemas/DirectoryWithFileContent" + "$ref": "#/components/schemas/DirectoryRequestWithFileContent" } }, "aux": { "type": "array", - "description": "An array of auxiliary directory contents related to the NGINX configuration.", + "description": "An array of auxiliary directory contents related to the NGINX configuration. When auxiliary contents are\nprovided, they become the authoritative source of non-NGINX configuration content. Please ensure the\nprovided contents are complete, missing files that are referenced in the NGINX configuration can cause\nNGINX reload failure. When not provided, the previous known auxiliary contents will be used as part of\npublish.\n", "items": { - "$ref": "#/components/schemas/DirectoryWithFileContent" + "$ref": "#/components/schemas/DirectoryRequestWithFileContent" } } - }, - "example": { - "aux": [], - "conf_path": "/etc/nginx/nginx.conf", - "configs": [ - { - "files": [ - { - "contents": "Cm1hcCAkdXJpICRtYXBwZWRfc2VydmljZSB7CiAgICBkZWZhdWx0IFVOTUFUQ0hFRDsKICAgICJ+Xi9hcGkvdjEvbmFtZXNwYWNlcy9cdysvaW5zdGFuY2VzIiAgICAgICAgaW5zdGFuY2VzLXN2YzsKICAgICJ+Xi9hcGkvdjEvbmFtZXNwYWNlcy9cdysvZGF0YS1wbGFuZS1rZXlzIiAga2V5cy1zdmM7CiAgICAifl4vYXBpL3YxL25hbWVzcGFjZXMvXHcrL21vbml0b3IiICAgICAgICAgIG1vbml0b3Itc3ZjOwp9Cgp1cHN0cmVhbSBpbnN0YW5jZXMtc3ZjIHsKICAgIHNlcnZlciBpbnN0YW5jZXMtc3ZjOjgwODA7Cn0KCnVwc3RyZWFtIGtleXMtc3ZjIHsKICAgIHNlcnZlciBrZXlzLXN2Yzo4MDkwOwp9Cgp1cHN0cmVhbSBkYXRhcGxhbmUtY3RybCB7CiAgICBzZXJ2ZXIgZGF0YXBsYW5lLWN0cmw6ODA4MDsKfQoKdXBzdHJlYW0gbW9uaXRvci1zdmMgewogICAgc2VydmVyIG1vbml0b3Itc3ZjOjgwODA7Cn0KCnVwc3RyZWFtIG1ldHJpY3MtaW5nZXN0IHsKICAgIHNlcnZlciBtZXRyaWNzLWluZ2VzdDo4MDgwOwp9CgpzZXJ2ZXIgewogICAgbGlzdGVuIDg4ODg7CiAgICBzZXJ2ZXJfbmFtZSBfOwogICAgaHR0cDIgb247CgogICAgcHJveHlfcGFzc19yZXF1ZXN0X2hlYWRlcnMgb247CiAgICByZXdyaXRlICJeL2FwaS8obmdpbngvb25lfHYxKS8oLiopJCIgIi9hcGkvdjEvJDIiIGJyZWFrOwogICAgbG9jYXRpb24gL2FwaS92MS8gewogICAgICAgIGlmICgkbWFwcGVkX3NlcnZpY2UgPSAiVU5NQVRDSEVEIikgewogICAgICAgICAgICByZXR1cm4gNDA0ICd7ImVycm9yOiAiTm90IGZvdW5kIn0nOwogICAgICAgIH0KICAgICAgICBwcm94eV9wYXNzX2hlYWRlciBYLVZvbHRlcnJhLUFwaWd3LVRlbmFudDsKICAgICAgICBwcm94eV9wYXNzIGh0dHA6Ly8kbWFwcGVkX3NlcnZpY2U7CiAgICB9CgogICAgIyBnUlBDIHNlcnZpY2UgZm9yIGRhdGFwbGFuZS1jdHJsCiAgICBsb2NhdGlvbiAvZjUubmdpbnguYWdlbnQuc2RrLkNvbW1hbmRlciB7CiAgICAgICAgZ3JwY19zb2NrZXRfa2VlcGFsaXZlIG9uOwogICAgICAgIGdycGNfcmVhZF90aW1lb3V0IDVtOwogICAgICAgIGdycGNfc2VuZF90aW1lb3V0IDVtOwogICAgICAgIGNsaWVudF9ib2R5X3RpbWVvdXQgMTBtOwogICAgICAgIGdycGNfcGFzcyBncnBjOi8vZGF0YXBsYW5lLWN0cmw7CiAgICB9CgogICAgIyBnUlBDIHNlcnZpY2UgZm9yIG1ldHJpY3MgaW5nZXN0aW9uCiAgICBsb2NhdGlvbiAvZjUubmdpbnguYWdlbnQuc2RrLk1ldHJpY3NTZXJ2aWNlIHsKICAgICAgICBncnBjX3NvY2tldF9rZWVwYWxpdmUgb247CiAgICAgICAgZ3JwY19yZWFkX3RpbWVvdXQgNW07CiAgICAgICAgZ3JwY19zZW5kX3RpbWVvdXQgNW07CiAgICAgICAgY2xpZW50X2JvZHlfdGltZW91dCAxMG07CiAgICAgICAgY2xpZW50X21heF9ib2R5X3NpemUgMDsKICAgICAgICBncnBjX3Bhc3MgZ3JwYzovL21ldHJpY3MtaW5nZXN0OwogICAgfQp9CgojIHByb3h5IHRvIHRoZSBtYW5hZ2VtZW50IHNlcnZlcnMKc2VydmVyIHsKICAgIGxpc3RlbiAxNTAwMDsKICAgIHNlcnZlcl9uYW1lIF87CiAgICAjIHVzZSBkb2NrZXIgRE5TCiAgICByZXNvbHZlciAxMjcuMC4wLjExIHZhbGlkPTMwczsKCiAgICAjIG1hdGNoIC88c2VydmljZT4vPG1nbXQgZW5kcG9pbnQ+CiAgICBsb2NhdGlvbiB+Xi8oW14vXSspLyguKykkIHsKICAgICAgICBwcm94eV9wYXNzIGh0dHA6Ly8kMToxNTAwMC8kMjsKICAgIH0KCiAgICBsb2NhdGlvbiAvIHsKICAgICAgICBhZGRfaGVhZGVyICJDb250ZW50LVR5cGUiICJ0ZXh0L2h0bWwiOwogICAgICAgIHJldHVybiAyMDAgIjxwPkFjY2VzcyB0aGUgbWFuYWdlbWVudCBzZXJ2ZXIgb2YgYW55IHNlcnZpY2Ugd2l0aCBVUkxzIGxpa2UgPGNvZGU+aHR0cDovL2xvY2FsaG9zdDoxNTAwMC8mbHQ7U0VSVklDRV9OQU1FJmd0Oy9tZXRyaWNzPC9jb2RlPjwvcD4iOwogICAgfQp9Cg==", - "mtime": "1970-01-01T00:00:00Z", - "name": "default.conf", - "size": 1942 - } - ], - "name": "/etc/nginx/conf.d" - }, - { - "files": [ - { - "contents": "CnVzZXIgIG5naW54Owp3b3JrZXJfcHJvY2Vzc2VzICBhdXRvOwoKZXJyb3JfbG9nICAvdmFyL2xvZy9uZ2lueC9lcnJvci5sb2cgbm90aWNlOwpwaWQgICAgICAgIC92YXIvcnVuL25naW54LnBpZDsKCgpldmVudHMgewogICAgd29ya2VyX2Nvbm5lY3Rpb25zICAxMDI0Owp9CgoKaHR0cCB7CiAgICBpbmNsdWRlICAgICAgIC9ldGMvbmdpbngvbWltZS50eXBlczsKICAgIGRlZmF1bHRfdHlwZSAgYXBwbGljYXRpb24vb2N0ZXQtc3RyZWFtOwoKICAgIGxvZ19mb3JtYXQgIG1haW4gICckcmVtb3RlX2FkZHIgLSAkcmVtb3RlX3VzZXIgWyR0aW1lX2xvY2FsXSAiJHJlcXVlc3QiICcKICAgICAgICAgICAgICAgICAgICAgICckc3RhdHVzICRib2R5X2J5dGVzX3NlbnQgIiRodHRwX3JlZmVyZXIiICcKICAgICAgICAgICAgICAgICAgICAgICciJGh0dHBfdXNlcl9hZ2VudCIgIiRodHRwX3hfZm9yd2FyZGVkX2ZvciInOwoKICAgIGFjY2Vzc19sb2cgIC92YXIvbG9nL25naW54L2FjY2Vzcy5sb2cgIG1haW47CgogICAgc2VuZGZpbGUgICAgICAgIG9uOwogICAgI3RjcF9ub3B1c2ggICAgIG9uOwoKICAgIGtlZXBhbGl2ZV90aW1lb3V0ICA2NTsKCiAgICAjZ3ppcCAgb247CgogICAgaW5jbHVkZSAvZXRjL25naW54L2NvbmYuZC8qLmNvbmY7Cn0K", - "mtime": "1970-01-01T00:00:00Z", - "name": "nginx.conf", - "size": 648 - }, - { - "contents": "CnR5cGVzIHsKICAgIHRleHQvaHRtbCAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBodG1sIGh0bSBzaHRtbDsKICAgIHRleHQvY3NzICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBjc3M7CiAgICB0ZXh0L3htbCAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgeG1sOwogICAgaW1hZ2UvZ2lmICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIGdpZjsKICAgIGltYWdlL2pwZWcgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBqcGVnIGpwZzsKICAgIGFwcGxpY2F0aW9uL2phdmFzY3JpcHQgICAgICAgICAgICAgICAgICAgICAgICAgICBqczsKICAgIGFwcGxpY2F0aW9uL2F0b20reG1sICAgICAgICAgICAgICAgICAgICAgICAgICAgICBhdG9tOwogICAgYXBwbGljYXRpb24vcnNzK3htbCAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIHJzczsKCiAgICB0ZXh0L21hdGhtbCAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgbW1sOwogICAgdGV4dC9wbGFpbiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIHR4dDsKICAgIHRleHQvdm5kLnN1bi5qMm1lLmFwcC1kZXNjcmlwdG9yICAgICAgICAgICAgICAgICBqYWQ7CiAgICB0ZXh0L3ZuZC53YXAud21sICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgd21sOwogICAgdGV4dC94LWNvbXBvbmVudCAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIGh0YzsKCiAgICBpbWFnZS9hdmlmICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgYXZpZjsKICAgIGltYWdlL3BuZyAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBwbmc7CiAgICBpbWFnZS9zdmcreG1sICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgc3ZnIHN2Z3o7CiAgICBpbWFnZS90aWZmICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgdGlmIHRpZmY7CiAgICBpbWFnZS92bmQud2FwLndibXAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgd2JtcDsKICAgIGltYWdlL3dlYnAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICB3ZWJwOwogICAgaW1hZ2UveC1pY29uICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIGljbzsKICAgIGltYWdlL3gtam5nICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBqbmc7CiAgICBpbWFnZS94LW1zLWJtcCAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgYm1wOwoKICAgIGZvbnQvd29mZiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICB3b2ZmOwogICAgZm9udC93b2ZmMiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIHdvZmYyOwoKICAgIGFwcGxpY2F0aW9uL2phdmEtYXJjaGl2ZSAgICAgICAgICAgICAgICAgICAgICAgICBqYXIgd2FyIGVhcjsKICAgIGFwcGxpY2F0aW9uL2pzb24gICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBqc29uOwogICAgYXBwbGljYXRpb24vbWFjLWJpbmhleDQwICAgICAgICAgICAgICAgICAgICAgICAgIGhxeDsKICAgIGFwcGxpY2F0aW9uL21zd29yZCAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBkb2M7CiAgICBhcHBsaWNhdGlvbi9wZGYgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgcGRmOwogICAgYXBwbGljYXRpb24vcG9zdHNjcmlwdCAgICAgICAgICAgICAgICAgICAgICAgICAgIHBzIGVwcyBhaTsKICAgIGFwcGxpY2F0aW9uL3J0ZiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBydGY7CiAgICBhcHBsaWNhdGlvbi92bmQuYXBwbGUubXBlZ3VybCAgICAgICAgICAgICAgICAgICAgbTN1ODsKICAgIGFwcGxpY2F0aW9uL3ZuZC5nb29nbGUtZWFydGgua21sK3htbCAgICAgICAgICAgICBrbWw7CiAgICBhcHBsaWNhdGlvbi92bmQuZ29vZ2xlLWVhcnRoLmtteiAgICAgICAgICAgICAgICAga216OwogICAgYXBwbGljYXRpb24vdm5kLm1zLWV4Y2VsICAgICAgICAgICAgICAgICAgICAgICAgIHhsczsKICAgIGFwcGxpY2F0aW9uL3ZuZC5tcy1mb250b2JqZWN0ICAgICAgICAgICAgICAgICAgICBlb3Q7CiAgICBhcHBsaWNhdGlvbi92bmQubXMtcG93ZXJwb2ludCAgICAgICAgICAgICAgICAgICAgcHB0OwogICAgYXBwbGljYXRpb24vdm5kLm9hc2lzLm9wZW5kb2N1bWVudC5ncmFwaGljcyAgICAgIG9kZzsKICAgIGFwcGxpY2F0aW9uL3ZuZC5vYXNpcy5vcGVuZG9jdW1lbnQucHJlc2VudGF0aW9uICBvZHA7CiAgICBhcHBsaWNhdGlvbi92bmQub2FzaXMub3BlbmRvY3VtZW50LnNwcmVhZHNoZWV0ICAgb2RzOwogICAgYXBwbGljYXRpb24vdm5kLm9hc2lzLm9wZW5kb2N1bWVudC50ZXh0ICAgICAgICAgIG9kdDsKICAgIGFwcGxpY2F0aW9uL3ZuZC5vcGVueG1sZm9ybWF0cy1vZmZpY2Vkb2N1bWVudC5wcmVzZW50YXRpb25tbC5wcmVzZW50YXRpb24KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBwcHR4OwogICAgYXBwbGljYXRpb24vdm5kLm9wZW54bWxmb3JtYXRzLW9mZmljZWRvY3VtZW50LnNwcmVhZHNoZWV0bWwuc2hlZXQKICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICB4bHN4OwogICAgYXBwbGljYXRpb24vdm5kLm9wZW54bWxmb3JtYXRzLW9mZmljZWRvY3VtZW50LndvcmRwcm9jZXNzaW5nbWwuZG9jdW1lbnQKICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBkb2N4OwogICAgYXBwbGljYXRpb24vdm5kLndhcC53bWxjICAgICAgICAgICAgICAgICAgICAgICAgIHdtbGM7CiAgICBhcHBsaWNhdGlvbi93YXNtICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgd2FzbTsKICAgIGFwcGxpY2F0aW9uL3gtN3otY29tcHJlc3NlZCAgICAgICAgICAgICAgICAgICAgICA3ejsKICAgIGFwcGxpY2F0aW9uL3gtY29jb2EgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBjY287CiAgICBhcHBsaWNhdGlvbi94LWphdmEtYXJjaGl2ZS1kaWZmICAgICAgICAgICAgICAgICAgamFyZGlmZjsKICAgIGFwcGxpY2F0aW9uL3gtamF2YS1qbmxwLWZpbGUgICAgICAgICAgICAgICAgICAgICBqbmxwOwogICAgYXBwbGljYXRpb24veC1tYWtlc2VsZiAgICAgICAgICAgICAgICAgICAgICAgICAgIHJ1bjsKICAgIGFwcGxpY2F0aW9uL3gtcGVybCAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBwbCBwbTsKICAgIGFwcGxpY2F0aW9uL3gtcGlsb3QgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBwcmMgcGRiOwogICAgYXBwbGljYXRpb24veC1yYXItY29tcHJlc3NlZCAgICAgICAgICAgICAgICAgICAgIHJhcjsKICAgIGFwcGxpY2F0aW9uL3gtcmVkaGF0LXBhY2thZ2UtbWFuYWdlciAgICAgICAgICAgICBycG07CiAgICBhcHBsaWNhdGlvbi94LXNlYSAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgc2VhOwogICAgYXBwbGljYXRpb24veC1zaG9ja3dhdmUtZmxhc2ggICAgICAgICAgICAgICAgICAgIHN3ZjsKICAgIGFwcGxpY2F0aW9uL3gtc3R1ZmZpdCAgICAgICAgICAgICAgICAgICAgICAgICAgICBzaXQ7CiAgICBhcHBsaWNhdGlvbi94LXRjbCAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgdGNsIHRrOwogICAgYXBwbGljYXRpb24veC14NTA5LWNhLWNlcnQgICAgICAgICAgICAgICAgICAgICAgIGRlciBwZW0gY3J0OwogICAgYXBwbGljYXRpb24veC14cGluc3RhbGwgICAgICAgICAgICAgICAgICAgICAgICAgIHhwaTsKICAgIGFwcGxpY2F0aW9uL3hodG1sK3htbCAgICAgICAgICAgICAgICAgICAgICAgICAgICB4aHRtbDsKICAgIGFwcGxpY2F0aW9uL3hzcGYreG1sICAgICAgICAgICAgICAgICAgICAgICAgICAgICB4c3BmOwogICAgYXBwbGljYXRpb24vemlwICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIHppcDsKCiAgICBhcHBsaWNhdGlvbi9vY3RldC1zdHJlYW0gICAgICAgICAgICAgICAgICAgICAgICAgYmluIGV4ZSBkbGw7CiAgICBhcHBsaWNhdGlvbi9vY3RldC1zdHJlYW0gICAgICAgICAgICAgICAgICAgICAgICAgZGViOwogICAgYXBwbGljYXRpb24vb2N0ZXQtc3RyZWFtICAgICAgICAgICAgICAgICAgICAgICAgIGRtZzsKICAgIGFwcGxpY2F0aW9uL29jdGV0LXN0cmVhbSAgICAgICAgICAgICAgICAgICAgICAgICBpc28gaW1nOwogICAgYXBwbGljYXRpb24vb2N0ZXQtc3RyZWFtICAgICAgICAgICAgICAgICAgICAgICAgIG1zaSBtc3AgbXNtOwoKICAgIGF1ZGlvL21pZGkgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBtaWQgbWlkaSBrYXI7CiAgICBhdWRpby9tcGVnICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgbXAzOwogICAgYXVkaW8vb2dnICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIG9nZzsKICAgIGF1ZGlvL3gtbTRhICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBtNGE7CiAgICBhdWRpby94LXJlYWxhdWRpbyAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgcmE7CgogICAgdmlkZW8vM2dwcCAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDNncHAgM2dwOwogICAgdmlkZW8vbXAydCAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIHRzOwogICAgdmlkZW8vbXA0ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIG1wNDsKICAgIHZpZGVvL21wZWcgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBtcGVnIG1wZzsKICAgIHZpZGVvL3F1aWNrdGltZSAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBtb3Y7CiAgICB2aWRlby93ZWJtICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgd2VibTsKICAgIHZpZGVvL3gtZmx2ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBmbHY7CiAgICB2aWRlby94LW00diAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgbTR2OwogICAgdmlkZW8veC1tbmcgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIG1uZzsKICAgIHZpZGVvL3gtbXMtYXNmICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBhc3ggYXNmOwogICAgdmlkZW8veC1tcy13bXYgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIHdtdjsKICAgIHZpZGVvL3gtbXN2aWRlbyAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBhdmk7Cn0K", - "mtime": "1970-01-01T00:00:00Z", - "name": "mime.types", - "size": 5349 - } - ], - "name": "/etc/nginx" - } - ] - } - }, - "NginxConfigObjectID": { - "description": "A globally unique identifier for the NGINX Config object.", - "type": "string", - "format": "object_id", - "pattern": "^nc_.*", - "x-go-type": "objects.ID", - "x-go-type-import": { - "name": "objects", - "path": "gitlab.com/f5/nginx/one/saas/control-plane/pkg/collections/objects" } }, - "NginxConfig": { - "description": "Details of an NGINX configuration, including its unique identifier, the main configuration path, the \nconfiguration directories, and the NGINX configuration payloads that indicate where managed SSL certificates\nand keys were deployed to on the data plane instance.\n", + "NginxConfigRequest": { "allOf": [ { - "$ref": "#/components/schemas/NginxConfigObject" + "$ref": "#/components/schemas/NginxConfigObjectRequest" }, { "type": "object", - "required": [ - "object_id" - ], "properties": { - "object_id": { - "$ref": "#/components/schemas/NginxConfigObjectID" - }, "payloads": { "$ref": "#/components/schemas/NginxConfigPayloads" } @@ -5432,6 +5794,75 @@ } } }, + "ConfigSyncGroupPublicationStatusReason": { + "allOf": [ + { + "$ref": "#/components/schemas/PublicationStatusCause" + }, + { + "type": "object", + "required": [ + "object_id" + ], + "properties": { + "object_id": { + "$ref": "#/components/schemas/InstanceObjectID" + } + } + } + ] + }, + "ConfigSyncGroupPublication": { + "description": "Details of a publication request for the NGINX config sync group.", + "required": [ + "status", + "created_at", + "modified_at" + ], + "properties": { + "object_id": { + "$ref": "#/components/schemas/PublicationObjectID" + }, + "status": { + "$ref": "#/components/schemas/ConfigSyncGroupPublicationStatus" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "The date and time when the publication was created for the instance." + }, + "modified_at": { + "type": "string", + "format": "date-time", + "description": "The date and time when the publication was last modified for the instance." + }, + "status_reasons": { + "description": "Detailed failure reasons on each instance's publication, when 'status' is in 'failed' or 'partially_succeeded'", + "type": "array", + "items": { + "$ref": "#/components/schemas/ConfigSyncGroupPublicationStatusReason" + } + }, + "config_version": { + "type": "string", + "description": "A hash that uniquely identifies the contents of the config object in the publication.\n" + } + }, + "example": { + "config_version": "fc3bb4b50c145b3ca5c5d1342be5ec0718eeb9bb84f8d53c5734b6b8", + "created_at": "2024-05-23T21:57:13.048285Z", + "modified_at": "2024-05-23T21:57:13.048285Z", + "object_id": "pub_UPV8jXFwSgm1vHQJCvLD1w", + "status": "failed", + "status_reasons": [ + { + "cause": "remote", + "message": "Config apply failed (write): error running nginx -t -c /etc/nginx/nginx.conf:\n error running nginx -t -c /etc/nginx/nginx.conf:\nnginx: [emerg] invalid number of arguments in \"worker_processes\" directive in /etc/nginx/nginx.conf:7\nnginx: configuration file /etc/nginx/nginx.conf test failed\n", + "object_id": "inst_QBBobKIAQ_21grAwV83VYw" + } + ] + } + }, "PublicationInstance": { "description": "Details of a publication request for an NGINX instance.", "required": [ @@ -5483,1065 +5914,677 @@ "status": "pending" } }, - "NginxConfigMeta": { + "NginxConfigProblem": { "type": "object", - "description": "Meta data of an NGINX configuration, including its unique identifier, the config_version.\n", - "required": [ - "object_id", - "config_version", - "created_at", - "modified_at" - ], + "description": "Representation of a problem found during NGINX configuration analysis.", "properties": { - "object_id": { - "$ref": "#/components/schemas/NginxConfigObjectID" - }, - "config_version": { - "type": "string", - "description": "A hash that uniquely identifies the contents of the config object.\n" + "directive": { + "description": "Directive in the NGINX configuration where the issue is identified.", + "type": "string" }, - "created_at": { - "type": "string", - "format": "date-time", - "description": "The date and time when the NGINX configuration object was created for the instance." + "file": { + "description": "File where the issue is detected.", + "type": "string" }, - "modified_at": { - "type": "string", - "format": "date-time", - "description": "The date and time when the NGINX configuration object was last modified for the instance." + "line": { + "description": "Line number in the configuration where the issue is found.", + "type": "integer" } - }, - "example": { - "object_id": "nc_AamgWtYSSb6OWGljx3wNDA", - "config_version": "Cm1hcCAkdXJpICRtYXBwZWRfc2V", - "created_at": "2023-08-10T16:59:15Z", - "modified_at": "2023-08-10T16:59:15Z" } }, - "FilterNameConfigSyncGroups": { - "type": "string", - "description": "Keywords for config sync groups filters.\nWhen filtering on `config_status`, only the following `filter_values` are supported:\n * in_sync\n * out_of_sync\n * sync_in_progress\n * unknown\n", - "enum": [ - "name", - "config_status", - "object_id" - ], - "x-enum-varnames": [ - "filter_name_config_sync_group_name", - "filter_name_config_sync_group_config_status", - "filter_name_config_sync_group_object_id" - ] - }, - "ListConfigSyncGroupObject": { + "NginxConfigReport": { "type": "object", - "description": "Summary information of the NGINX config sync group.", - "required": [ - "object_id", - "name", - "instances_count", - "config_status" - ], + "description": "An analysis of the NGINX configuration, highlighting issues and their severity, and offering recommendations.", "properties": { - "object_id": { - "$ref": "#/components/schemas/configSyncGroupObjectID" - }, - "name": { - "description": "Name of the Nginx config sync group.", + "rule": { + "description": "The name of the configuration rule that was violated.", "type": "string" }, - "instances_count": { - "description": "Number of instances in the Nginx config sync group.", - "type": "integer" + "info": { + "description": "A detailed description of the issue.", + "type": "string" }, - "config_status": { - "$ref": "#/components/schemas/ConfigSyncStatus" + "severity": { + "description": "The severity level of the issue.", + "type": "string" }, - "cert_summary": { - "$ref": "#/components/schemas/CertificateInstanceSummary" - } - } - }, - "ConfigSyncGroupListResponse": { - "allOf": [ - { - "$ref": "#/components/schemas/PaginationResponse" + "category": { + "description": "Classification category of the issue.", + "type": "string" }, - { - "type": "object", - "description": "List of Nginx config sync groups.", - "required": [ - "items" - ], - "properties": { - "items": { - "description": "An array of Config Sync Group objects.", - "type": "array", - "items": { - "$ref": "#/components/schemas/ListConfigSyncGroupObject" - } - } - } - } - ], - "example": { - "total": 10, - "count": 1, - "start_index": 1, - "items_per_page": 100, - "items": [ - { - "object_id": "csg_-uvR3F2TQGm18jnl7bpaGw", - "name": "test-config-sync-group", - "config_status": "in_sync", - "instances_count": 1 + "documentation": { + "description": "Links to documentation that can assist in resolving the identified issue.", + "type": "array", + "items": { + "type": "string" } - ] + }, + "where": { + "description": "Specific locations in the configuration where issues were detected.", + "type": "array", + "items": { + "$ref": "#/components/schemas/NginxConfigProblem" + } + } } }, - "ConfigSyncGroupCreateRequest": { - "description": "Body to create a Nginx config sync group.", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "description": "A name to uniquely identify the Nginx config sync group in a given tenant namespace.", - "minLength": 1, - "maxLength": 256 - } - }, - "example": { - "name": "my-nginx-config-sync-group" + "NginxConfigReports": { + "type": "array", + "items": { + "$ref": "#/components/schemas/NginxConfigReport" } }, - "ConfigSyncGroupCreateResponse": { - "description": "Response to a create Nginx config sync group request.", + "NginxConfigMeta": { + "type": "object", + "description": "Meta data of an NGINX configuration, including its unique identifier, the config_version.\n", "required": [ "object_id", - "name" + "config_version", + "created_at", + "modified_at" ], "properties": { "object_id": { - "$ref": "#/components/schemas/configSyncGroupObjectID" + "$ref": "#/components/schemas/NginxConfigObjectID" }, - "name": { - "description": "Name of the Nginx config sync group.", - "type": "string" + "config_version": { + "type": "string", + "description": "A hash that uniquely identifies the contents of the config object.\n" + }, + "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." } }, "example": { - "name": "my-nginx-config-sync-group", - "object_id": "csg_Tet21AeYTHCj7taOwVfzyw" + "object_id": "nc_AamgWtYSSb6OWGljx3wNDA", + "config_version": "Cm1hcCAkdXJpICRtYXBwZWRfc2V", + "created_at": "2023-08-10T16:59:15Z", + "modified_at": "2023-08-10T16:59:15Z" } }, - "ConfigSyncGroupBulkRequestData": { + "NginxCVEObject": { "type": "object", - "description": "Part of bulk operation on a config sync group, only `delete` is supported.", "required": [ - "action", - "object_id" + "id", + "severity", + "info", + "published_at" ], + "description": "Details about a specific NGINX security advisory, including the number of instances impacted by it, its severity, and a brief description.", "properties": { - "object_id": { - "$ref": "#/components/schemas/configSyncGroupObjectID" + "id": { + "description": "The security advisory's unique identifier.", + "type": "string" }, - "action": { - "$ref": "#/components/schemas/BulkRequestAction" - } - }, - "example": { - "object_id": "csg_-uvR3F2TQGm18jnl7bpaGw", - "action": "delete" - } - }, - "ConfigSyncGroupBulkRequest": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ConfigSyncGroupBulkRequestData" - }, - "minItems": 1, - "maxItems": 50, - "example": [ - { - "object_id": "csg_-uvR3F2TQGm18jnl7bpaGw", - "action": "delete" + "severity": { + "$ref": "#/components/schemas/CveSeverityType" }, - { - "object_id": "csg_PL0c1XodRemmzVEjiXSsTg", - "action": "delete" - } - ] - }, - "ConfigSyncGroupBulkResponse": { - "description": "The config sync group bulk outcome.", - "type": "array", - "items": { - "$ref": "#/components/schemas/BulkRequestObjectStatus" - } - }, - "ConfigSyncGroupInstance": { - "allOf": [ - { - "$ref": "#/components/schemas/Instance" + "info": { + "description": "A brief description of security advisory.", + "type": "string" }, - { - "type": "object", - "required": [ - "config_status", - "config_version" - ], - "properties": { - "config_status": { - "$ref": "#/components/schemas/ConfigSyncStatus" - }, - "config_version": { - "description": "A computed hash of current config on the config sync group.", - "type": "string" - } - } - } - ] - }, - "ConfigSyncGroupPublicationStatus": { - "type": "string", - "description": "The status on the last publication issued on this config sync group:\n* `pending` - The publication request has been accepted and is currently processing.\n* `failed` - The publication attempt failed.\n* `succeeded` - The publication was successful.\n* `partially_succeeded` - The publication attempt had one or more failures.\n", - "enum": [ - "pending", - "failed", - "succeeded", - "partially_succeeded" - ], - "x-enum-varnames": [ - "publication_config_sync_group_status_pending", - "publication_config_sync_group_status_failed", - "publication_config_sync_group_status_succeeded", - "publication_config_sync_group_status_partially_succeeded" - ] - }, - "ConfigSyncGroup": { - "allOf": [ - { - "$ref": "#/components/schemas/ConfigSyncGroupMeta" + "instances_impacted": { + "description": "Number of instances impacted by the security advisory", + "type": "integer" }, - { - "type": "object", - "description": "Additional information of the NGINX config sync group including:\n* config sync status\n* config checksum\n* instances\n* last known publication status\n* certs associated with this config sync group\n", - "properties": { - "config_status": { - "$ref": "#/components/schemas/ConfigSyncStatus" - }, - "config_version": { - "description": "A computed hash of current config on the config sync group.", - "type": "string" - }, - "instances": { - "description": "An array of Instance objects.", - "type": "array", - "items": { - "$ref": "#/components/schemas/ConfigSyncGroupInstance" - } - }, - "last_publication_status": { - "$ref": "#/components/schemas/ConfigSyncGroupPublicationStatus" - }, - "certs": { - "description": "An array detailing each certificate's information, including its friendly name, unique identifier, applicable file system paths, subject name, and validity dates. \nIt provides insights into the operational status of each certificate, such as whether it's currently valid, nearing expiration, is not ready to be used, or has already expired.\nThe deployment status indicates whether the latest certs and key managed by NGINX One Console are deployed onto the data plane instances that are part of this config sync group.\n", - "type": "array", - "items": { - "$ref": "#/components/schemas/CertAssociation" - } - } - } + "published_at": { + "description": "The date and time when the cve was published", + "type": "string", + "format": "date-time" } - ], - "example": { - "object_id": "csg_-uvR3F2TQGm18jnl7bpaGw", - "name": "test-config-sync-group", - "last_reported": "2023-12-06T22:37:24.120114Z", - "config_status": "in_sync", - "config_version": "uvR3F2TQGm18jnl7bpaGw", - "instances": [ - { - "object_id": "inst_-uvR3F2TQGm18jnl7bpaGw", - "hostname": "816e3c194d59", - "system_id": "6066aad2-211e-3718-be5d-fcc01ffc5cc8", - "agent_version": "v2.33.0", - "registered_at": "2024-05-16T18:26:40.556048Z", - "last_reported": "2023-12-06T22:37:24.120114Z", - "status": "unavailable", - "nginx_build": { - "conf_path": "/etc/nginx/nginx.conf", - "version": "1.25.3" - }, - "os_version": "Ubuntu 22.04", - "nginx_id": "b636d4376dea15405589692d3c5d3869ff3a9b26b0e7bb4bb1aa7e658ace1437", - "config_status": "in_sync", - "config_version": "abc123def456" - } - ], - "certs": [ - { - "subject_name": "test.com", - "name": "client", - "cert_type": "cert_key", - "not_after": "2024-01-06T00:01:30Z", - "not_before": "2023-12-07T00:01:30Z", - "cert_paths": [ - "/etc/nginx/client.pem" - ], - "cert_status": "expiring", - "deployment_status": "latest", - "object_id": "cert_Tet21AeYTHCj7taOwVfzyw" - } - ] } }, - "ConfigSyncGroupDetails": { - "type": "object", - "description": "Detailed information of the NGINX config sync group.", - "allOf": [ - { - "$ref": "#/components/schemas/ConfigSyncGroup" - } - ] - }, - "ConfigSyncGroupPublicationStatusReason": { + "CVEListResponse": { "allOf": [ { - "$ref": "#/components/schemas/PublicationStatusCause" + "$ref": "#/components/schemas/PaginationResponse" }, { "type": "object", + "description": "List of all CVEs.", "required": [ - "object_id" + "items" ], "properties": { - "object_id": { - "$ref": "#/components/schemas/InstanceObjectID" + "items": { + "description": "An array of CVE objects.", + "type": "array", + "items": { + "$ref": "#/components/schemas/NginxCVEObject" + } } } } ] }, - "ConfigSyncGroupPublication": { - "description": "Details of a publication request for the NGINX config sync group.", + "NginxProduct": { + "type": "string", + "description": "NGINX product :\n * `noss` - NGINX Open Source.\n * `nplus` - NGINX PLUS.\n", + "enum": [ + "noss", + "nplus", + "unknown" + ], + "x-enum-varnames": [ + "nginx_product_noss", + "nginx_product_nplus", + "nginx_product_unknown" + ] + }, + "CveImpactedNginxProduct": { + "type": "object", "required": [ - "status", - "created_at", - "modified_at" + "versions", + "name" ], + "description": "security advisory impacted NGINX product and its version.", "properties": { - "object_id": { - "$ref": "#/components/schemas/PublicationObjectID" - }, - "status": { - "$ref": "#/components/schemas/ConfigSyncGroupPublicationStatus" - }, - "created_at": { - "type": "string", - "format": "date-time", - "description": "The date and time when the publication was created for the instance." - }, - "modified_at": { - "type": "string", - "format": "date-time", - "description": "The date and time when the publication was last modified for the instance." - }, - "status_reasons": { - "description": "Detailed failure reasons on each instance's publication, when 'status' is in 'failed' or 'partially_succeeded'", + "versions": { + "description": "List of impacted NGINX product versions.", "type": "array", "items": { - "$ref": "#/components/schemas/ConfigSyncGroupPublicationStatusReason" + "type": "string" } }, - "config_version": { - "type": "string", - "description": "A hash that uniquely identifies the contents of the config object in the publication.\n" + "name": { + "$ref": "#/components/schemas/NginxProduct" } - }, - "example": { - "config_version": "fc3bb4b50c145b3ca5c5d1342be5ec0718eeb9bb84f8d53c5734b6b8", - "created_at": "2024-05-23T21:57:13.048285Z", - "modified_at": "2024-05-23T21:57:13.048285Z", - "object_id": "pub_UPV8jXFwSgm1vHQJCvLD1w", - "status": "failed", - "status_reasons": [ - { - "cause": "remote", - "message": "Config apply failed (write): error running nginx -t -c /etc/nginx/nginx.conf:\n error running nginx -t -c /etc/nginx/nginx.conf:\nnginx: [emerg] invalid number of arguments in \"worker_processes\" directive in /etc/nginx/nginx.conf:7\nnginx: configuration file /etc/nginx/nginx.conf test failed\n", - "object_id": "inst_QBBobKIAQ_21grAwV83VYw" - } - ] } }, - "FilterNameCertificates": { - "type": "string", - "description": "Keywords for certificates filters.\nWhen filtering on `management`, only the following `filter_values` are supported:\n * managed\n * unmanaged\nWhen filtering on `type`, only the following `filter_values` are supported:\n * cert_key\n * ca_bundle\n * unknown\nWhen filtering on `status`, only the following `filter_values` are supported:\n * valid\n * expiring\n * expired\n * not_ready\n", - "enum": [ - "name", - "management", - "type", - "subject_name", - "status", - "object_id" - ], - "x-enum-varnames": [ - "filter_name_certificates_name", - "filter_name_certificates_management", - "filter_name_certificates_type", - "filter_name_certificates_subject_name", - "filter_name_certificates_status", - "filter_name_certificates_object_id" - ] - }, - "CertificateManagement": { - "type": "string", - "description": "Management type:\n * `managed` - Certificate managed by NGINX One Console.\n * `unmanaged` - Certificate that only exists on a data plane instance, detected from its NGINX configuration.\n", - "enum": [ - "managed", - "unmanaged" - ], - "x-enum-varnames": [ - "certificate_management_managed", - "certificate_management_unmanaged" + "NginxCVEDetailsResponse": { + "allOf": [ + { + "$ref": "#/components/schemas/NginxCVEObject" + }, + { + "type": "object", + "required": [ + "detail", + "impacted_products" + ], + "description": "Details about a specific NGINX security advisory, including its severity, detail,\npublished date and time, description and impacted products.\n", + "properties": { + "impacted_products": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CveImpactedNginxProduct" + } + }, + "detail": { + "description": "the details about security advisory", + "type": "string" + } + }, + "example": { + "detail": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-ID", + "id": "CVE-ID", + "impacted_products": [ + { + "name": "nplus", + "versions": [ + "r1", + "r2" + ] + }, + { + "name": "noss", + "versions": [ + "1.11.1", + "1.20.2", + "1.19.9" + ] + } + ], + "info": "Memory disclosure in the ngx_http_mp4_module", + "published_at": "2022-10-19T00:00:00Z", + "severity": "medium" + } + } ] }, - "CertificateObjectMetadata": { + "NginxProductInfo": { + "type": "object", + "description": "Information about an NGINX product type and its version", "required": [ - "management", - "type" + "name", + "version" ], "properties": { "name": { - "description": "Name of the certificate, optionally specified upon creation", - "type": "string" - }, - "object_id": { - "$ref": "#/components/schemas/CertificateObjectID" - }, - "management": { - "$ref": "#/components/schemas/CertificateManagement" - }, - "type": { - "$ref": "#/components/schemas/CertificateType" + "$ref": "#/components/schemas/NginxProduct" }, - "certs_count": { - "description": "The number of public certificates under this certificate object.", - "type": "integer", - "format": "int64" + "version": { + "description": "version of the Nginx product installed on the instance.", + "type": "string" } - }, - "example": { - "name": "example-ca-bundle", - "object_id": "cert_Tet21AeYTHCj7taOwVfzyw", - "management": "managed", - "type": "ca_bundle", - "certs_count": 5 } }, - "CertificateDisplayMetadata": { - "description": "This represents the essential metadata of a public certificate.", + "CVEImpactedInstance": { "type": "object", + "description": "Summary information about a NGINX instance.", "required": [ - "subject_name", - "status", - "not_before", - "not_after" + "object_id", + "hostname", + "status" ], "properties": { - "subject_name": { - "type": "string", - "example": "www.example.com", - "description": "DNS name that identifies the certificate. If DNS is not present in the SAN extension, this will be the common name.\n" + "object_id": { + "$ref": "#/components/schemas/InstanceObjectID" }, - "status": { - "$ref": "#/components/schemas/CertificateStatus" + "hostname": { + "description": "The name of the host system where the NGINX instance is running.", + "type": "string" }, - "not_before": { - "type": "string", - "format": "date-time", - "example": "2023-06-12T09:12:33.001Z", - "description": "The start of the validity period for the certificate." + "products": { + "description": "List of NGINX products in the instance", + "type": "array", + "items": { + "$ref": "#/components/schemas/NginxProductInfo" + } }, - "not_after": { + "status": { "type": "string", - "format": "date-time", - "example": "2029-12-25T09:12:33.001Z", - "description": "The end of the validity period for the certificate." - } - }, - "example": { - "subject_name": "self_ca_signed", - "status": "valid", - "not_before": "2023-08-10T16:59:15Z", - "not_after": "2024-08-14T16:59:15Z" - } - }, - "CertificateOverviewMetadata": { - "description": "Represents an overview of all the public certificates under a single cert object.\nIf multiple public certificates on the same CA chain, including the leaf certificate and key are provided, \nthis includes `status`, `subject_name`, `not_before` and `not_after` for the leaf certificate.\nIf a CA bundle is provided, the above mentioned certificate metadata is for the Certificate Authority that\nexpires the soonest in the bundle.\n", - "type": "object", - "allOf": [ - { - "$ref": "#/components/schemas/CertificateObjectMetadata" - }, - { - "$ref": "#/components/schemas/CertificateDisplayMetadata" + "description": "The current operational status of the NGINX instance, with the following possible values:\n* `unknown` - The status of the NGINX instance cannot be determined at this moment.\n* `unavailable` - The NGINX Agent has lost connection to NGINX One, rendering the NGINX instance unavailable.\n* `offline` - The NGINX Agent is connected to NGINX One, but the NGINX instance is offline.\n* `online` - The NGINX Agent is connected to NGINX One, and the NGINX instance is online.\n", + "enum": [ + "unknown", + "unavailable", + "offline", + "online" + ] } - ], - "example": { - "name": "example-ca-bundle", - "object_id": "cert_Tet21AeYTHCj7taOwVfzyw", - "management": "managed", - "type": "ca_bundle", - "subject_name": "self_ca_signed", - "status": "valid", - "not_before": "2023-08-10T16:59:15Z", - "not_after": "2024-08-14T16:59:15Z", - "certs_count": 5 } }, - "CertificateListResponse": { + "CVEImpactedInstancesListResponse": { "allOf": [ { "$ref": "#/components/schemas/PaginationResponse" }, { "type": "object", - "description": "List of SSL certificates.", + "description": "List of instances affected by a CVE.", "required": [ "items" ], "properties": { "items": { - "description": "An array of basic metadata for all the SSL certificates in NGINX One Console. \nFor a CA bundle, an overview with metadata on the first Certificate Authority in the bundle will be displayed.\nOtherwise, an overview with metadata on the leaf certificate will be displayed.\n", + "description": "An array of Instance objects.", "type": "array", "items": { - "$ref": "#/components/schemas/CertificateOverviewMetadata" + "$ref": "#/components/schemas/CVEImpactedInstance" } } - } - } - ], - "example": { - "total": 10, - "count": 2, - "start_index": 1, - "items_per_page": 100, - "items": [ - { - "name": "example-cert_key", - "object_id": "cert_Tet21AeYTHCj7taOwVfzyw", - "management": "managed", - "type": "cert_key", - "status": "valid", - "subject_name": "www.example.com", - "not_before": "2023-08-10T16:59:15Z", - "not_after": "2024-08-14T16:59:15Z", - "certs_count": 1 }, - { - "name": "example-ca-bundle", - "object_id": "cert_Tet21AeYTHCj7taOwVfzyw", - "management": "managed", - "type": "ca_bundle", - "subject_name": "self_ca_signed", - "status": "valid", - "not_before": "2023-08-10T16:59:15Z", - "not_after": "2024-08-14T16:59:15Z", - "certs_count": 5 + "example": { + "total": 10, + "count": 1, + "start_index": 1, + "items_per_page": 100, + "items": [ + { + "object_id": "inst_8Iwn7dT7RF-PRLxkSt5EYQ", + "hostname": "4d116619f106", + "products": [ + { + "name": "noss", + "version": "1.18.0" + } + ], + "status": "unknown" + } + ] } - ] - } - }, - "CertificateContent": { - "type": "object", - "description": "Defines the PEM-formatted certificate content which includes the certificates and corresponding private key, all encoded in base64.\n", - "required": [ - "public_certs" - ], - "properties": { - "public_certs": { - "type": "string", - "format": "base64", - "maxLength": 3145728, - "description": "Base64-encoded PEM-formatted certificate information. \nThe `public_certs` field can include a leaf certificate along with its full chain of trust or a CA bundle. \nFor leaf certificates, the accompanying `private_key` is required to authenticate the certificate's validity. \nCA bundles contain trusted CA certificates and may consist of certificates from different CA chains. A private\nkey should not be included in a CA bundle.\n" - }, - "private_key": { - "type": "string", - "format": "base64", - "maxLength": 3145728, - "description": "Base64-encoded private key string for the leaf certificate, required only for certificate-key pairs to \nverify the certificate's authenticity.\n" } - }, - "example": { - "public_certs": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUUzb3lkdWVPQU5KSGh2TDN5dkpkVHBob2V2NUdPN2dvK0J5WU9PL2w1NHU1TzJQeE1lWCtBakFiNkF4bXEKbGl2SXVodz0KLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQ==" - } + ] }, - "CertificateRequest": { - "type": "object", - "description": "Request structure for parsing or upserting certificates with an optional private key.\n", - "required": [ - "content" + "FilterNameEvents": { + "type": "string", + "description": "Keywords for events filters.\n", + "enum": [ + "object_id" ], - "properties": { - "name": { - "description": "A name for the certificate, making it identifiable among others.", - "type": "string", - "minLength": 1, - "maxLength": 128 - }, - "content": { - "$ref": "#/components/schemas/CertificateContent" - } - }, - "example": { - "name": "example-ca-bundle", - "content": { - "public_certs": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUUzb3lkdWVPQU5KSGh2TDN5dkpkVHBob2V2NUdPN2dvK0J5WU9PL2w1NHU1TzJQeE1lWCtBakFiNkF4bXEKbGl2SXVodz0KLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQ==", - "private_key": "" - } + "x-enum-varnames": [ + "filter_name_events_object_id" + ] + }, + "EventObjectID": { + "description": "A globally unique identifier for a NGINX One system event.", + "type": "string", + "format": "object_id", + "pattern": "^event_.*", + "x-go-type": "objects.ID", + "x-go-type-import": { + "name": "objects", + "path": "gitlab.com/f5/nginx/one/saas/control-plane/pkg/collections/objects" } }, - "CertificateMetadata": { - "description": "A comprehensive list of all the metadata for a public certificate.", + "Event": { "type": "object", + "description": "An Event is a system message.", "required": [ - "status", - "serial_number", - "signature_algorithm", - "not_before", - "not_after", - "public_key_type", - "thumbprint" + "type", + "timestamp", + "object_id", + "message" ], "properties": { - "status": { - "$ref": "#/components/schemas/CertificateStatus" - }, - "version": { - "type": "integer", - "format": "int64", - "example": 3, - "description": "The version of the certificate, typically 3 for X.509 certificates." - }, - "serial_number": { - "type": "string", - "example": "16469416336579571270", - "description": "A unique identifier for the certificate." - }, - "signature_algorithm": { - "type": "string", - "example": "SHA-256", - "description": "Identifies the algorithm used to sign the certificate." - }, - "issuer": { - "type": "string", - "example": "CN=Example CA, O=Certificate Authority Inc., OU=CA Department, L=City, ST=State, C=Country", - "description": "Identifies the entity who signed and issued the certificate." - }, - "not_before": { - "type": "string", - "format": "date-time", - "example": "2023-06-12T09:12:33.001Z", - "description": "The start of the validity period for the certificate." - }, - "not_after": { + "timestamp": { + "description": "time of the event", "type": "string", "format": "date-time", - "example": "2029-12-25T09:12:33.001Z", - "description": "The end of the validity period for the certificate." + "example": "2019-08-07T09:57:36.088757764Z" }, - "subject": { + "type": { "type": "string", - "example": "CN=www.example.com, O=Example Inc., OU=IT Department, L=City, ST=State, C=Country", - "description": "Identifies the primary entity to which the certificate is issued. Typically, it contains information\nsuch as the Common Name (CN), Organization (O), Organizational Unit (OU), Country (C), etc.\n" - }, - "subject_alternative_name": { - "type": "array", - "items": { - "type": "string" - }, - "example": [ - "DNS:www.example.com", - "DNS:example.com", - "email:info@example.com" + "description": "type of event, indication for affected object type.", + "enum": [ + "instance_cleanup", + "certificates" ], - "description": "Defines additional identifies bound to the subject of the certificate. \nFor example, the DNS name is used to add additional domain names to a certificate.\n" - }, - "public_key_type": { - "type": "string", - "example": "RSA (2048 Bits)", - "description": "Identifies the encryption algorithm used to create the public key for the certificate." - }, - "common_name": { - "type": "string", - "example": "www.example.com", - "description": "The Common Name (CN) for the certificate, used when DNS name is not present in the SAN extension.\n" + "x-enum-varnames": [ + "event_type_instance_cleanup", + "event_type_certificates" + ] }, - "authority_key_identifier": { - "type": "string", - "example": "2B D0 69 47 94 76 09 FE F4 6B 8D 2E 40 A6 F7 47 4D 7F 08 5E", - "description": "The identifier of the signing authority for the certificate." + "object_id": { + "$ref": "#/components/schemas/EventObjectID" }, - "subject_key_identifier": { - "type": "string", - "example": "31 EA 76 A9 23 74 A5 DF D4 FD EE A0 C1 A6 9E C6 11 0E 11 EC", - "description": "A hash value of the SSL certificate that can be used to identify certificates that \ncontain a particular public key.\n" + "affected_object_id": { + "$ref": "#/components/schemas/ObjectID" }, - "thumbprint_algorithm": { + "hostname": { "type": "string", - "example": "SHA-1", - "description": "Defines the algorithm used to hash the certificate." + "description": "hostname of the affected instance, if any." }, - "thumbprint": { + "message": { "type": "string", - "example": "E6 A7 87 96 E0 C7 A3 E5 43 78 35 CA 16 78 5B 48 5A A9 DD C4 5C CD 0A 65 AA 89 33 E3 C3 D0 89 71", - "description": "A hash to ensure that the certificate has not been modified." + "description": "Details regarding the event.", + "example": "Instance \"demo-1\" deleted by instance cleanup after \"unavailable\" for 25 hours." } }, "example": { - "status": "valid", - "version": 3, - "serial_number": "71283929", - "signature_algorithm": "SHA256-RSA", - "issuer": "C=US, ST=WA, L=Seattle, O=F5 Networks, OU=nginx.test, CN=eg3bsriq_cert_bundle_CA", - "not_before": "2023-02-10T16:59:15Z", - "not_after": "2024-08-14T16:59:15Z", - "subject": "C=US, ST=WA, L=Seattle, O=F5 Networks, OU=nginx.test, CN=self_ca_signed", - "subject_alternative_name": [], - "public_key_type": "RSA (2048 bit)", - "common_name": "self_ca_signed", - "authority_key_identifier": "3A:79:E0:3E:61:CD:94:29:1D:BB:45:37:0B:E9:78:E9:2F:40:67:CA", - "subject_key_identifier": "93:35:2B:75:09:B9:FF:01:1B:63:F1:0E:50:71:9C:4E:B4:E2:02:BA", - "thumbprint_algorithm": "SHA-256", - "thumbprint": "C1:EB:E8:CE:35:77:63:75:D3:C0:E7:97:5F:02:8C:D3:D8:C4:12:34:40:45:D3:98:67:39:BE:8A:33:CE:1F:B2" + "timestamp": "2024-02-04T09:57:36.088757764Z", + "type": "instance_cleanup", + "object_id": "event_-uvR3F2TQGm18jnl7bpaGw", + "affected_object_id": "inst_-uvR3F2TQGm18jnl7bpaGw", + "message": "ip-170.0.1 deleted after age out period of 3 hours, last seen 2023-08-07T09:57:36.088757764Z" } }, - "PrivateKeyMetadata": { - "type": "object", - "description": "Metadata for a private key.", - "properties": { - "key_size": { - "description": "Size of the private key in bits.", - "type": "integer", - "format": "int64" + "EventsListResponse": { + "allOf": [ + { + "$ref": "#/components/schemas/PaginationResponse" }, - "encryption_algorithm": { - "description": "The encryption algorithm used for the private key.", - "type": "string" + { + "type": "object", + "description": "List of Events.", + "required": [ + "items" + ], + "properties": { + "items": { + "description": "An array of Event objects.", + "type": "array", + "items": { + "$ref": "#/components/schemas/Event" + } + } + } } - }, - "example": { - "key_size": 512, - "encryption_algorithm": "RSA" - } + ] }, - "CertificateResponse": { - "type": "object", - "description": "Response structure containing details of the created, updated or retrieved SSL certificate. In general, \nthe response should contain:\n * an overview of all the public certificates\n * `warnings` whether any issue is found after parsing the certificates and key\n * `certs`\n * `key_metadata` if key provided in the request body\n * timestamps that represent when this cert object was created or modified\n", + "FilterNameInstances": { + "type": "string", + "description": "Keywords for instance filters.\n\nWhen filtering on `instance_status`, only the following `filter_values` are supported:\n * online\n * offline\n * unavailable\n * unknown\nWhen filtering base on `cert_status`, only the following `filter_values` are supported:\n * valid\n * expiring\n * expired\n * not_ready\n", + "enum": [ + "hostname", + "nginx_version", + "os_version", + "instance_status", + "cert_status", + "cve_severity", + "config_recommendation", + "key_object_id", + "system_id", + "object_id" + ], + "x-enum-varnames": [ + "filter_name_instances_hostname", + "filter_name_instances_nginx_version", + "filter_name_instances_os_version", + "filter_name_instances_instance_status", + "filter_name_instances_cert_status", + "filter_name_instances_cve_severity", + "filter_name_instances_config_recommendation", + "filter_name_instances_key_object_id", + "filter_name_instances_system_id", + "filter_name_instances_object_id" + ] + }, + "InstanceListResponse": { "allOf": [ { - "$ref": "#/components/schemas/CertificateOverviewMetadata" + "$ref": "#/components/schemas/PaginationResponse" }, { "type": "object", + "description": "List of data plane instances.", + "required": [ + "items" + ], "properties": { - "warnings": { - "type": "string", - "description": "Warnings indicate whether there are any issues with the stored cert object. Empty when no issues were found.\n" - }, - "certs": { - "description": "An array of metadata for all the public certificates under the cert object.", + "items": { + "description": "An array of Instance objects.", "type": "array", "items": { - "$ref": "#/components/schemas/CertificateMetadata" + "$ref": "#/components/schemas/Instance" } - }, - "key": { - "$ref": "#/components/schemas/PrivateKeyMetadata" - }, - "created_at": { - "type": "string", - "format": "date-time", - "description": "The date and time when the SSL certificate was created." - }, - "modified_at": { - "type": "string", - "format": "date-time", - "description": "The date and time when the SSL certificate was last modified." } } } ], "example": { - "name": "example-cert_key", - "object_id": "cert_Tet21AeYTHCj7taOwVfzyw", - "management": "managed", - "type": "cert_key", - "status": "valid", - "subject_name": "www.example.com", - "not_before": "2023-08-10T16:59:15Z", - "not_after": "2024-08-14T16:59:15Z", - "warnings": "The provided private key does not match the certificate's signing key.", - "certs_count": 1, - "certs": [ + "total": 10, + "count": 1, + "start_index": 1, + "items_per_page": 100, + "items": [ { - "status": "valid", - "version": 3, - "serial_number": "71283929", - "signature_algorithm": "SHA256-RSA", - "issuer": "C=US, ST=WA, L=Seattle, O=F5 Networks, OU=nginx.test, CN=eg3bsriq_cert_A", - "not_before": "2023-02-10T16:59:15Z", - "not_after": "2024-08-14T16:59:15Z", - "subject": "C=US, ST=WA, L=Seattle, O=F5 Networks, OU=nginx.test, CN=eg3bsriq_cert_B", - "subject_alternative_name": [], - "public_key_type": "RSA (2048 bit)", - "common_name": "eg3bsriq_cert_B", - "authority_key_identifier": "3A:79:E0:3E:61:CD:94:29:1D:BB:45:37:0B:E9:78:E9:2F:40:67:CA", - "subject_key_identifier": "93:35:2B:75:09:B9:FF:01:1B:63:F1:0E:50:71:9C:4E:B4:E2:02:BA", - "thumbprint_algorithm": "SHA-256", - "thumbprint": "C1:EB:E8:CE:35:77:63:75:D3:C0:E7:97:5F:02:8C:D3:D8:C4:12:34:40:45:D3:98:67:39:BE:8A:33:CE:1F:B2" + "agent_version": "v2.30.3", + "hostname": "4d116619f106", + "key": "key_Tet21AeYTHCj7taOwVfzyw", + "last_reported": "2023-12-06T22:37:24.120114Z", + "nginx_build": { + "conf_path": "/etc/nginx/nginx.conf", + "version": "1.25.3" + }, + "nginx_id": "b636d4376dea15405589692d3c5d3869ff3a9b26b0e7bb4bb1aa7e658ace1437", + "registered_at": "2023-12-06T22:37:24.120114Z", + "status": "unknown", + "system_id": "b2c0b6a8-8b6a-3a8f-a541-17d8899c119a", + "object_id": "inst_-uvR3F2TQGm18jnl7bpaGw" } - ], - "key": { - "key_size": 512, - "encryption_algorithm": "RSA" - }, - "modified_at": "2023-11-01T00:00:00Z", - "created_at": "2023-10-01T00:00:00Z" + ] } }, - "CertificateBulkRequestData": { + "InstanceBulkRequestData": { "type": "object", - "description": "Part of bulk operation on a certificate, only `delete` is supported.", + "description": "Part of bulk operation on a NGINX instance, only `delete` is supported.", "required": [ - "action", - "object_id" + "action" ], "properties": { "object_id": { - "$ref": "#/components/schemas/CertificateObjectID" + "$ref": "#/components/schemas/InstanceObjectID" }, "action": { "$ref": "#/components/schemas/BulkRequestAction" } }, "example": { - "object_id": "cert_-uvR3F2TQGm18jnl7bpaGw", + "object_id": "inst_-uvR3F2TQGm18jnl7bpaGw", "action": "delete" } }, - "CertificateBulkRequest": { + "InstanceBulkRequest": { "type": "array", "items": { - "$ref": "#/components/schemas/CertificateBulkRequestData" + "$ref": "#/components/schemas/InstanceBulkRequestData" }, - "minItems": 1, "maxItems": 50, "example": [ { - "object_id": "cert_-uvR3F2TQGm18jnl7bpaGw", + "object_id": "inst_-uvR3F2TQGm18jnl7bpaGw", "action": "delete" }, { - "object_id": "cert_PL0c1XodRemmzVEjiXSsTg", + "object_id": "inst_PL0c1XodRemmzVEjiXSsTg", "action": "delete" } ] }, - "CertificateBulkResponse": { - "description": "The certificate bulk operation outcome.", + "InstanceBulkResponse": { + "description": "The NGINX instance bulk outcome.", "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", - "properties": { - "public_certs": { - "type": "string", - "format": "base64", - "maxLength": 3145728, - "description": "Base64-encoded PEM-formatted certificate information. \nThis is used for updating an existing certificate object. The schema is the same as `CertificateContent`,\nthe only difference is that both `public_certs` and `private_key` fields are optional. There are three use\ncases for this schema:\n* the below update can be done on either a Cert Key Pair or a CA Bundle:\n * when only `public_certs` is populated, update the public certificates on a certificate object. \n The updated public certificates will be validated against the existing private key.\n* the below update can be done only on a Cert Key Pair:\n * when only `private_key` is populated, update only the private key on a certificate object. \n The updated private key will be validated against the existing public certificates.\n * when both `public_certs` and `private_key` fields are populated, update both of them on a certificate \n object.\n" - }, - "private_key": { - "type": "string", - "format": "base64", - "maxLength": 3145728, - "description": "Base64-encoded private key string for the leaf certificate, required only for certificate-key pairs to \nverify the certificate's authenticity.\n" - } - }, - "example": { - "private_key": "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFM295ZHVlT0FOSkhodkwzeXZKZFRwaG9ldjVHTzdnbytCeVlPTy9sNTR1NU8yUHhNZVgrQWpBYjZBeG1xCmxpdkl1aHc9Ci0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0t" - } - }, - "CertificateUpdateRequest": { - "type": "object", - "description": "Request structure for updating a certificate object. If key provided, it will be validated against the \nexisting leaf certificate stored under the certificate object.\n* Update for an unmanaged certificate object:\n * This converts the unmanaged certificate object to managed.\n * `public_certs` should always be provided during the conversion.\n * When key is provided, this certificate object is converted to a managed Cert Key Pair. Otherwise, it is\n converted to a managed CA Bundle.\n", - "properties": { - "name": { - "description": "A name for the certificate, making it identifiable among others.", - "type": "string", - "minLength": 1, - "maxLength": 128 - }, - "content": { - "$ref": "#/components/schemas/CertificateUpdateContent" - } - }, - "example": { - "name": "example-cert-object", - "content": { - "public_certs": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUUzb3lkdWVPQU5KSGh2TDN5dkpkVHBob2V2NUdPN2dvK0J5WU9PL2w1NHU1TzJQeE1lWCtBakFiNkF4bXEKbGl2SXVodz0KLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQ==" - } - } - }, - "FilterNameCertificateDeployments": { - "type": "string", - "description": "Keywords for certificate deployment filters.\nWhen filtering on `association_type`, only the following `filter_values` are supported:\n * instance\n * config_sync_group\nWhen filtering on `deployment_status`, only the following `filter_values` are supported:\n * latest\n * stale\n", - "enum": [ - "name", - "association_type", - "deployment_status" - ], - "x-enum-varnames": [ - "filter_name_certificate_deployments_name", - "filter_name_certificate_deployments_association_type", - "filter_name_certificate_deployments_deployment_status" - ] - }, - "CertificateAssociationType": { - "type": "string", - "description": "Certificate association type:\n * `instance` - This certificate deployment is for an instance.\n * `config_sync_group` - This certificate deployment is for a config sync group.\n", - "enum": [ - "instance", - "config_sync_group" - ], - "x-enum-varnames": [ - "certificate_association_type_instance", - "certificate_association_type_config_sync_group" - ] - }, - "CertificateDeployment": { + "OperatingSystem": { + "description": "Release details for the operating system.", "type": "object", - "description": "Response structure containing certificate deployment details for an SSL certificate, which include\n * `association_type` represents type of the object affected by this certificate deployment, which is either\n an instance or config sync group\n * `object_id` represents the object ID for the associated instance or config sync group\n * `name` for either the host name of an instance or the name of a config sync group\n * `deployment_status`:\n * `latest`: deployment is up to date with the latest updated certificate and key contents\n * `stale`: deployment for either certificates or key is outdated, requires a redeployment with the latest contents\n * `cert_paths` represents the file paths used for deploying public certificates of this certificate object\n * `key_paths` represents the file paths used for deploying the private key of this certificate object, if a\n private key is present\n", "required": [ - "association_type", - "object_id", "name", - "deployment_status" + "id", + "codename", + "version", + "version_id" ], "properties": { - "association_type": { - "$ref": "#/components/schemas/CertificateAssociationType" - }, - "object_id": { - "$ref": "#/components/schemas/ObjectID" - }, "name": { - "type": "string", - "description": "The host name of an instance or the name of a config sync group." + "description": "The official name of the operating system release.", + "type": "string" }, - "deployment_status": { - "$ref": "#/components/schemas/CertificateDeploymentStatus" + "id": { + "description": "The distinctive identifier for the operating system release.", + "type": "string" }, - "cert_paths": { - "description": "Deployment file paths for public certificates.", - "type": "array", - "items": { - "type": "string" - } + "codename": { + "description": "The codename assigned to the operating system release.", + "type": "string" }, - "key_paths": { - "description": "Deployment file paths for the private key.", - "type": "array", - "items": { - "type": "string" - } + "version": { + "description": "The version label for the operating system, which may include the name and version number or codename.", + "type": "string" + }, + "version_id": { + "description": "The specific version number of the operating system release.", + "type": "string" } }, "example": { - "association_type": "instance", - "name": "instance-host-name", - "object_id": "inst_-uvR3F2TQGm18jnl7bpaGw", - "deployment_status": "latest", - "cert_paths": [ - "/etc/nginx/example.crt", - "/etc/nginx/certs/cert.crt" - ], - "key_paths": [ - "/etc/nginx/example.key" - ] + "name": "Ubuntu", + "id": "ubuntu", + "codename": "bionic", + "version": "18.04.5 LTS (Bionic Beaver)", + "version_id": "18.04" } }, - "CertificateDeploymentListResponse": { + "ConfigSyncGroupInstanceMeta": { "allOf": [ { - "$ref": "#/components/schemas/PaginationResponse" + "$ref": "#/components/schemas/ConfigSyncGroupMeta" }, { "type": "object", - "description": "List of certificate deployments for a SSL certificate.", - "required": [ - "items" - ], + "description": "Additional details on instance in the NGINX config sync group including:\n* config sync status\n", "properties": { - "items": { - "description": "An array of certificate deployments for an SSL certificate. If this certificate object represents a \nCA bundle, there will be only public certificate file paths in the certificate deployment details.\n", + "instance_config_status": { + "$ref": "#/components/schemas/ConfigSyncStatus" + } + } + } + ] + }, + "InstanceDetails": { + "type": "object", + "description": "Detailed information about an NGINX instance.", + "allOf": [ + { + "$ref": "#/components/schemas/Instance" + }, + { + "type": "object", + "properties": { + "certs": { + "description": "An array detailing each certificate's information, including its friendly name, unique identifier, applicable file system paths, subject name, and validity dates. \nIt provides insights into the operational status of each certificate, such as whether it's currently valid, nearing expiration, is not ready to be used, or has already expired.\nThe deployment status indicates whether the latest certs and key managed by NGINX One Console are deployed onto this data plane instance.\n", "type": "array", "items": { - "$ref": "#/components/schemas/CertificateDeployment" + "$ref": "#/components/schemas/CertAssociation" } + }, + "os": { + "$ref": "#/components/schemas/OperatingSystem" + }, + "config_sync_group": { + "$ref": "#/components/schemas/ConfigSyncGroupInstanceMeta" } } } ], "example": { - "total": 10, - "count": 2, - "start_index": 1, - "items_per_page": 100, - "items": [ - { - "association_type": "instance", - "name": "instance-host-name", - "object_id": "inst_-uvR3F2TQGm18jnl7bpaGw", - "deployment_status": "latest", - "cert_paths": [ - "/etc/nginx/example.crt", - "/etc/nginx/certs/cert.crt" - ], - "key_paths": [ - "/etc/nginx/example.key" - ] - }, + "agent_version": "v2.30.3", + "certs": [ { - "association_type": "config_sync_group", - "name": "group1", - "object_id": "csg_vfr5Oqv-AhxGzyqTXW-Ubw", - "deployment_status": "stale", + "subject_name": "test.com", + "name": "client", + "cert_type": "cert_key", + "not_after": "2024-01-06T00:01:30Z", + "not_before": "2023-12-07T00:01:30Z", "cert_paths": [ - "/etc/nginx/cert.crt" + "/etc/nginx/client.pem" ], - "key_paths": [ - "/etc/nginx/server.key" - ] + "cert_status": "expiring", + "deployment_status": "latest", + "object_id": "cert_Tet21AeYTHCj7taOwVfzyw" } - ] + ], + "hostname": "4d116619f106", + "key": "key_wN3IhLCmR3qmwybG_6ptEg", + "last_reported": "2023-12-06T22:37:24.120114Z", + "nginx_build": { + "conf_path": "/etc/nginx/nginx.conf", + "version": "1.25.3" + }, + "nginx_id": "b636d4376dea15405589692d3c5d3869ff3a9b26b0e7bb4bb1aa7e658ace1437", + "os": { + "codename": "jammy", + "id": "ubuntu", + "name": "Ubuntu", + "version": "22.04.3 LTS (Jammy Jellyfish)", + "version_id": "22.04" + }, + "registered_at": "2023-12-06T22:37:24.120114Z", + "status": "unknown", + "system_id": "b2c0b6a8-8b6a-3a8f-a541-17d8899c119a", + "object_id": "inst_-uvR3F2TQGm18jnl7bpaGw" } }, - "NginxCVEObject": { + "NginxSecurityAdvisory": { "type": "object", + "description": "Details about a specific NGINX security advisory, including its severity, a link to more information, and a brief description.", "required": [ "id", "severity", - "info", - "published_at" + "advisory", + "info" ], - "description": "Details about a specific NGINX security advisory, including the number of instances impacted by it, its severity, and a brief description.", "properties": { "id": { "description": "The security advisory's unique identifier.", @@ -6550,318 +6593,176 @@ "severity": { "$ref": "#/components/schemas/CveSeverityType" }, + "advisory": { + "description": "The URL to detailed information about the security advisory.", + "type": "string" + }, "info": { "description": "A brief description of security advisory.", "type": "string" - }, - "instances_impacted": { - "description": "Number of instances impacted by the security advisory", - "type": "integer" - }, - "published_at": { - "description": "The date and time when the cve was published", - "type": "string", - "format": "date-time" } } }, - "CVEListResponse": { - "allOf": [ - { - "$ref": "#/components/schemas/PaginationResponse" - }, - { - "type": "object", - "description": "List of all CVEs.", - "required": [ - "items" - ], - "properties": { - "items": { - "description": "An array of CVE objects.", - "type": "array", - "items": { - "$ref": "#/components/schemas/NginxCVEObject" - } - } - } - } - ] - }, - "NginxProduct": { - "type": "string", - "description": "NGINX product :\n * `noss` - NGINX Open Source.\n * `nplus` - NGINX PLUS.\n", - "enum": [ - "noss", - "nplus", - "unknown" - ], - "x-enum-varnames": [ - "nginx_product_noss", - "nginx_product_nplus", - "nginx_product_unknown" - ] - }, - "CveImpactedNginxProduct": { + "CertificateSummaryItem": { + "description": "summary information for certificate with certain status.", "type": "object", "required": [ - "versions", - "name" + "status", + "count", + "affected_instances" ], - "description": "security advisory impacted NGINX product and its version.", "properties": { - "versions": { - "description": "List of impacted NGINX product versions.", - "type": "array", - "items": { - "type": "string" - } + "status": { + "$ref": "#/components/schemas/CertificateStatus" }, - "name": { - "$ref": "#/components/schemas/NginxProduct" - } - } - }, - "NginxCVEDetailsResponse": { - "allOf": [ - { - "$ref": "#/components/schemas/NginxCVEObject" + "count": { + "description": "The total number of SSL certificates for each status category.", + "type": "integer" }, - { - "type": "object", - "required": [ - "detail", - "impacted_products" - ], - "description": "Details about a specific NGINX security advisory, including its severity, detail,\npublished date and time, description and impacted products.\n", - "properties": { - "impacted_products": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CveImpactedNginxProduct" - } - }, - "detail": { - "description": "the details about security advisory", - "type": "string" - } - }, - "example": { - "detail": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-ID", - "id": "CVE-ID", - "impacted_products": [ - { - "name": "nplus", - "versions": [ - "r1", - "r2" - ] - }, - { - "name": "noss", - "versions": [ - "1.11.1", - "1.20.2", - "1.19.9" - ] - } - ], - "info": "Memory disclosure in the ngx_http_mp4_module", - "published_at": "2022-10-19T00:00:00Z", - "severity": "medium" - } + "affected_instances": { + "description": "Indicates the total number of SSL/TLS certificates corresponding to the status provided.", + "type": "integer" } - ] + } }, - "NginxProductInfo": { + "SummaryDisplayCount": { + "description": "The name, the total count, and an optional user-friendly display name of the resource being summarized.", "type": "object", - "description": "Information about an NGINX product type and its version", "required": [ "name", - "version" + "count" ], "properties": { "name": { - "$ref": "#/components/schemas/NginxProduct" + "description": "Identifies the category of data being reported, such as an operating system, NGINX version, or another type.", + "type": "string" }, - "version": { - "description": "version of the Nginx product installed on the instance.", + "count": { + "description": "The number of resources matching the given type.", + "type": "integer" + }, + "display": { + "description": "A user-friendly label for the category count, intended for display purposes where a more descriptive or readable format is preferred.", "type": "string" } } }, - "CVEImpactedInstance": { + "OperatingSystemVersionSummary": { + "description": "An array summarizing the operating systems and their versions on the NGINX data plane.", + "type": "array", + "items": { + "$ref": "#/components/schemas/SummaryDisplayCount" + } + }, + "NGINXVersionSummary": { + "description": "An array summarizing the versions of NGINX installed across the NGINX data plane.", + "type": "array", + "items": { + "$ref": "#/components/schemas/SummaryDisplayCount" + } + }, + "StatusSummary": { + "description": "An overview of the status for each NGINX instance, indicating availability.", "type": "object", - "description": "Summary information about a NGINX instance.", "required": [ - "object_id", - "hostname", - "status" + "online", + "offline", + "unavailable" ], "properties": { - "object_id": { - "$ref": "#/components/schemas/InstanceObjectID" - }, - "hostname": { - "description": "The name of the host system where the NGINX instance is running.", - "type": "string" + "online": { + "description": "The number of NGINX instances reporting as `online`.\nThe NGINX Agent is connected to NGINX One, and the NGINX instance is online.\n", + "type": "integer" }, - "products": { - "description": "List of NGINX products in the instance", - "type": "array", - "items": { - "$ref": "#/components/schemas/NginxProductInfo" - } + "offline": { + "description": "The number of NGINX instances reporting as `offline`.\nThe NGINX Agent is connected to NGINX One, but the NGINX instance is offline.\n", + "type": "integer" }, - "status": { - "type": "string", - "description": "The current operational status of the NGINX instance, with the following possible values:\n* `unknown` - The status of the NGINX instance cannot be determined at this moment.\n* `unavailable` - The NGINX Agent has lost connection to NGINX One, rendering the NGINX instance unavailable.\n* `offline` - The NGINX Agent is connected to NGINX One, but the NGINX instance is offline.\n* `online` - The NGINX Agent is connected to NGINX One, and the NGINX instance is online.\n", - "enum": [ - "unknown", - "unavailable", - "offline", - "online" - ] + "unavailable": { + "description": "The number of NGINX instances reporting as `unavailable`.\nThe NGINX Agent has lost connection to NGINX One, rendering the NGINX instance unavailable.\n", + "type": "integer" } } }, - "CVEImpactedInstancesListResponse": { - "allOf": [ - { - "$ref": "#/components/schemas/PaginationResponse" + "CveSummary": { + "description": "A summary of Common Vulnerabilities and Exposures (CVEs) across the NGINX data plane.", + "type": "object", + "required": [ + "severity", + "count", + "affected_instances" + ], + "properties": { + "severity": { + "$ref": "#/components/schemas/CveSeverityType" }, - { - "type": "object", - "description": "List of instances affected by a CVE.", - "required": [ - "items" - ], - "properties": { - "items": { - "description": "An array of Instance objects.", - "type": "array", - "items": { - "$ref": "#/components/schemas/CVEImpactedInstance" - } - } - }, - "example": { - "total": 10, - "count": 1, - "start_index": 1, - "items_per_page": 100, - "items": [ - { - "object_id": "inst_8Iwn7dT7RF-PRLxkSt5EYQ", - "hostname": "4d116619f106", - "products": [ - { - "name": "noss", - "version": "1.18.0" - } - ], - "status": "unknown" - } - ] - } + "count": { + "description": "The number of CVEs at each severity level.", + "type": "integer" + }, + "affected_instances": { + "description": "The number of NGINX instances affected by each CVE.", + "type": "integer" } - ] - }, - "FilterNameEvents": { - "type": "string", - "description": "Keywords for events filters.\n", - "enum": [ - "object_id" - ], - "x-enum-varnames": [ - "filter_name_events_object_id" - ] - }, - "EventObjectID": { - "description": "A globally unique identifier for a NGINX One system event.", - "type": "string", - "format": "object_id", - "pattern": "^event_.*", - "x-go-type": "objects.ID", - "x-go-type-import": { - "name": "objects", - "path": "gitlab.com/f5/nginx/one/saas/control-plane/pkg/collections/objects" } }, - "Event": { + "IssueSummary": { + "description": "A summary of issue details from the configuration analysis report.", "type": "object", - "description": "An Event is a system message.", "required": [ "type", - "timestamp", - "object_id", - "message" + "count", + "affected_instances" ], "properties": { - "timestamp": { - "description": "time of the event", - "type": "string", - "format": "date-time", - "example": "2019-08-07T09:57:36.088757764Z" - }, "type": { - "type": "string", - "description": "type of event, indication for affected object type.", - "enum": [ - "instance_cleanup", - "certificates" - ], - "x-enum-varnames": [ - "event_type_instance_cleanup", - "event_type_certificates" - ] - }, - "object_id": { - "$ref": "#/components/schemas/EventObjectID" - }, - "affected_object_id": { - "$ref": "#/components/schemas/ObjectID" + "$ref": "#/components/schemas/RecommendationType" }, - "hostname": { - "type": "string", - "description": "hostname of the affected instance, if any." + "count": { + "description": "The number of times this recommendation appears in the configuration analysis report.", + "type": "integer" }, - "message": { - "type": "string", - "description": "Details regarding the event.", - "example": "Instance \"demo-1\" deleted by instance cleanup after \"unavailable\" for 25 hours." + "affected_instances": { + "description": "The number of instances affected by this issue.", + "type": "integer" } - }, - "example": { - "timestamp": "2024-02-04T09:57:36.088757764Z", - "type": "instance_cleanup", - "object_id": "event_-uvR3F2TQGm18jnl7bpaGw", - "affected_object_id": "inst_-uvR3F2TQGm18jnl7bpaGw", - "message": "ip-170.0.1 deleted after age out period of 3 hours, last seen 2023-08-07T09:57:36.088757764Z" } }, - "EventsListResponse": { - "allOf": [ - { - "$ref": "#/components/schemas/PaginationResponse" + "InstanceSummary": { + "description": "A summary of NGINX instances, including certificates, OS versions, NGINX versions, and status details.", + "type": "object", + "properties": { + "certs": { + "description": "An array detailing each certificate's status across all NGINX instances.", + "type": "array", + "items": { + "$ref": "#/components/schemas/CertificateSummaryItem" + } }, - { - "type": "object", - "description": "List of Events.", - "required": [ - "items" - ], - "properties": { - "items": { - "description": "An array of Event objects.", - "type": "array", - "items": { - "$ref": "#/components/schemas/Event" - } - } + "os": { + "$ref": "#/components/schemas/OperatingSystemVersionSummary" + }, + "nginx_versions": { + "$ref": "#/components/schemas/NGINXVersionSummary" + }, + "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" + } + }, + "recommendations": { + "description": "An array summarizing the suggestions from the configuration analysis report.", + "type": "array", + "items": { + "$ref": "#/components/schemas/IssueSummary" } } - ] + } }, "MetricQueryResultEx": { "type": "object",