feature: define Staged Configs (#264)

* feature: define Staged Configs

* Add Staged Config API endpoints

Co-authored-by: Jon Torre <[email protected]>

* Update content/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md

Author: mjang

Diff for: content/includes/nginx-one/staged-config-overview.md

@@ -0,0 +1,18 @@
+---
+docs: DOCS-000
+files:
+  - content/nginx-one/how-to/staged-configs/add-staged-config.md
+  - content/nginx-one/how-to/staged-configs/edit-staged-config.md
+---
+
+It takes time to set up NGINX configuration files can take time. Staged Configurations can help. They work like a draft that uses the features of NGINX One Console. The Staged Configuration does not have to be valid.
+You can save your work before you push a configuration to an instance of NGINX.
+
+With Staged Configurations, you can use these features of NGINX One Console:
+
+- Automatic syntax checking
+- Contextual documentation
+- Dynamic analysis of your work in progress
+- Suggestions from our AI assistant
+
+Once you've finished your work and have pushed the changes to an Instance or a Config Sync Group, you can next delete that Staged Configuration.

Diff for: content/nginx-one/changelog.md

@@ -30,6 +30,16 @@ h2 {
 
 Stay up-to-date with what's new and improved in the F5 NGINX One Console.
 
+## March 11, 2025
+
+### Set up Staged Configurations
+
+It allows you to:
+
+- Save Your Progress: Staged Configurations allow you to work on configuration changes without the need for a fully functional setup. You can create these drafts from scratch, an existing Instance, another Staged Configuration, or a Config Sync Group.
+- No Immediate Validation Required: You don't have to immediately address syntax or configuration issues. Your Staged Configuration doesn't have to be valid until you publish it to an Instance or a Config Sync Group.
+- Manage through our API: You can easily manage your Staged Configurations programmatically through our [API]({{< ref "/nginx-one/api/api-reference-guide/#tag/StagedConfigs" >}}).
+
 ## January 20, 2025
 
 ### Manage certificates with Config Sync Groups

Diff for: content/nginx-one/glossary.md

@@ -18,6 +18,7 @@ This glossary defines terms used in the F5 NGINX One Console and F5 Distributed
 | **Data Plane** | The data plane is the part of a network architecture that carries user traffic. It handles tasks like forwarding data packets between devices and managing network communication. In the context of NGINX, the data plane is responsible for tasks such as load balancing, caching, and serving web content. |
 | **Instance** | An instance is an individual system with NGINX installed. You can group the instances of your choice in a Config Sync Group. When you add an instance to NGINX One, you need to use a data plane key. | 
 | **Namespace** | In F5 Distributed Cloud, a namespace groups a tenant’s configuration objects, similar to administrative domains. Every object in a namespace must have a unique name, and each namespace must be unique to its tenant. This setup ensures isolation, preventing cross-referencing of objects between namespaces. |
+| **Staged Configurations** | Also known as **Staged Configs**. Allows you to save "work in progress." You can create it from scratch, an Instance, another Staged Config, or a Config Sync Group. It does _not_ have to be a working configuration until you publish it to an instance or a Config Sync Group. You can even manage your **Staged Configurations** through our [API]({{< ref "/nginx-one/api/api-reference-guide/#tag/StagedConfigs" >}}). |
 | **Tenant** | A tenant in F5 Distributed Cloud is an entity that owns a specific set of configuration and infrastructure. It is fundamental for isolation, meaning a tenant cannot access objects or infrastructure of other tenants. Tenants can be either individual or enterprise, with the latter allowing multiple users with role-based access control (RBAC). |
 {{</bootstrap-table>}}
 

Diff for: content/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md

@@ -1,13 +1,28 @@
 ---
-docs: null
+# We use sentence case and present imperative tone
 title: View and edit NGINX configurations
-toc: true
+# Weights are assigned in increments of 100: determines sorting order
 weight: 300
-type:
-- how-to
+# Creates a table of contents and sidebar, useful for large documents
+toc: true
+# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this
+type: tutorial
+# Intended for internal catalogue and search, case sensitive:
+product: NGINX One
 ---
+<!-- Possible future include, with similar files in config-sync-groups/ and staged-configs/ subdirectories -->
+
+## Overview
+
+This guide explains how to add a **Instances** to your NGINX One Console. 
 
-Once you've registered your NGINX instances with the F5 NGINX One Console, you can view and edit their NGINX configurations on the **Instances** details page.
+## Before you start
+
+Before you add **Instances** to NGINX One Console, ensure:
+
+- You have an NGINX One Console account with staged configuration permissions.```
+
+Once you've registered your NGINX Instances with the F5 NGINX One Console, you can view and edit their NGINX configurations on the **Instances** details page.
 
 To view and edit an NGINX configuration, follow these steps:
 
@@ -19,6 +34,8 @@ To view and edit an NGINX configuration, follow these steps:
 6. When you are satisfied with the changes, select **Next**.
 7. Compare and verify your changes before selecting **Save and Publish** to publish the edited configuration.
 
+Alternatively, you can select **Save Changes As**. In the window that appears, you can set up this instance as a [**Staged Configuration**]({{< relref "/nginx-one/how-to/staged-configs/_index.md" >}}).
+
 ## See also
 
 - [Manage Config Sync Groups]({{< relref "/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md" >}})

Diff for: content/nginx-one/how-to/staged-configs/_index.md

@@ -0,0 +1,6 @@
+---
+description:
+title: Staged Configurations
+weight: 800
+url: /nginx-one/how-to/staged-configs
+---

Diff for: content/nginx-one/how-to/staged-configs/add-staged-config.md

@@ -0,0 +1,88 @@
+---
+# We use sentence case and present imperative tone
+title: Add a Staged Configuration
+# Weights are assigned in increments of 100: determines sorting order
+weight: 100
+# Creates a table of contents and sidebar, useful for large documents
+toc: true
+# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this
+type: tutorial
+# Intended for internal catalogue and search, case sensitive:
+# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit
+product:
+---
+
+## Overview
+
+This guide explains how to add a Staged Configuration to your NGINX One Console. 
+
+{{< include "nginx-one/staged-config-overview.md" >}}
+
+## Before you start
+
+Before you add a Staged Configuration to NGINX One Console, ensure:
+
+- You have an NGINX One Console account with staged configuration permissions.
+
+## Add a Staged Configuration
+
+You can add a Staged Configuration from:
+
+- Empty files
+- An existing Instance
+- An existing Config Sync Group
+- An existing Staged Configuration
+
+To start the process from NGINX One Console, select **Manage > Staged Configruations**. Select **Add Staged Configuration**.
+
+The following sections start from the **Add Staged Configuration** window that appears.
+
+### Start from an empty file
+
+To start a new Staged Configuration:
+
+1. Select **New Configuration**.
+1. Enter a name.
+1. Select **Next**.
+
+   You will see a new Staged Configuration with the default NGINX configuration file, `/etc/nginx/nginx.conf`, in edit mode.
+1. Type or paste content for `/etc/nginx/nginx.conf`.
+1. Select **Add File** to add the configuration, certificate, or other file(s) of your choice. 
+1. When you're done, select **Save**.
+
+### Start from an existing Instance
+
+To start from an existing Instance:
+
+1. Select **Existing Source**.
+1. Enter a name for your new Staged Configuration.
+1. Select **Instance**.
+1. In the Choose Instance menu that appears, select an existing Instance.
+1. Select **Next**. 
+
+NGINX One Console imports the configuration from the existing Instance. You can now edit the configuration. When you're ready to stop and save your work, select Save.
+
+### Start from an existing Config Sync Group
+
+To start from an existing Config Sync Group:
+
+1. Select **Existing Source**.
+1. Select **Config Sync Group**.
+1. In the Choose Config Sync Group menu that appears, select an existing Config Sync Group.
+1. Enter a name for your new Staged Configuration.
+1. Select **Next**. 
+
+NGINX One Console imports the configuration from the existing Config Sync Group. You can now edit the configuration. When you're ready to stop and save your work, select Save.
+
+### Start from an existing Staged Config
+
+To start from an existing Staged Config:
+
+1. Select **Existing Source**.
+1. Select **Staged Configuration**.
+1. In the Choose Staged Configuratiog menu that appears, select an existing Staged Configuration.
+1. Enter a name for your new Staged Configuration.
+1. Select **Next**. 
+
+NGINX One Console imports the configuration from the existing Staged Configuration. You can now edit the configuration. When you're ready to stop and save your work, select Save.
+

Diff for: content/nginx-one/how-to/staged-configs/api-staged-config.md

@@ -0,0 +1,20 @@
+---
+# We use sentence case and present imperative tone
+title: Use the API to manage your Staged Configurations
+# Weights are assigned in increments of 100: determines sorting order
+weight: 300
+# Creates a table of contents and sidebar, useful for large documents
+toc: true
+# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this
+type: tutorial
+# Intended for internal catalogue and search, case sensitive:
+product: NGINX One
+---
+
+You can use F5 NGINX One Console API to manage your Staged Configurations. With our API, you can:
+
+- [Create an NGINX Staged Configuration]({{< relref "/nginx-one/api/api-reference-guide/#operation/createStagedConfig" >}})
+  - The details allow you to add existing configuration files.
+- [Get a list of existing Staged Configruations]({{< relref "/nginx-one/api/api-reference-guide/#operation/listStagedConfigs" >}})
+  - Be sure to record the `object_id` of your target Staged Configuration for your analysis report.
+- [Get an analysis report for an existing Staged Configuration]({{< relref "/nginx-one/api/api-reference-guide/#operation/getStagedConfigReport" >}})

Diff for: content/nginx-one/how-to/staged-configs/edit-staged-config.md

@@ -0,0 +1,38 @@
+---
+# We use sentence case and present imperative tone
+title: View and edit a Staged Configuration
+# Weights are assigned in increments of 100: determines sorting order
+weight: 200
+# Creates a table of contents and sidebar, useful for large documents
+toc: true
+# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this
+type: tutorial
+# Intended for internal catalogue and search, case sensitive:
+product: NGINX One
+---
+
+## Overview
+
+This guide explains how to edit an existing Staged Configuration in your NGINX One Console. 
+
+{{< include "nginx-one/staged-config-overview.md" >}}
+
+## Before you start
+
+Before you edit a Staged Configuration, ensure:
+
+- You have an NGINX One Console account with staged configuration permissions.```
+
+## View and edit a Staged Configuration
+<!-- Possible future include, with similar files in config-sync-groups/, nginx-configs/, and staged-configs/ subdirectories -->
+
+Once you've registered your NGINX Staged Configs with the F5 NGINX One Console, you can view and edit their NGINX configurations on the **Staged Configurations** details page.
+
+To view and edit an NGINX configuration, follow these steps:
+
+1. On the left menu, select **Staged Configurations**.
+1. Select the staged configuration you want to view or modify.
+1. Select **Edit** to make changes to the current configuration.
+1. Make your changes to the configuration files. The configuration analyzer will let you know if there are any errors.
+1. When you are satisfied with the changes, select **Next**.
+1. Compare and verify your changes before selecting **Save** to publish the edited Staged configuration.

Diff for: go.mod

@@ -2,4 +2,4 @@ module github.com/nginxinc/docs
 
 go 1.19
 
-require github.com/nginxinc/nginx-hugo-theme v0.42.1 // indirect
+require github.com/nginxinc/nginx-hugo-theme v0.42.1 // indirect