From a5f43c62679c015cc365b67ce9ef9bf4fdc55094 Mon Sep 17 00:00:00 2001 From: Sylvia Wang Date: Wed, 17 Dec 2025 14:44:34 -0800 Subject: [PATCH 1/7] N1C CSG unmanaged certificates --- .../unmanaged-certificates.md | 112 ++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 content/nginx-one-console/nginx-configs/config-sync-groups/unmanaged-certificates.md diff --git a/content/nginx-one-console/nginx-configs/config-sync-groups/unmanaged-certificates.md b/content/nginx-one-console/nginx-configs/config-sync-groups/unmanaged-certificates.md new file mode 100644 index 000000000..f3a44d416 --- /dev/null +++ b/content/nginx-one-console/nginx-configs/config-sync-groups/unmanaged-certificates.md @@ -0,0 +1,112 @@ +--- +nd-content-type: concept +nd-docs: DOCS-000 +nd-product: NONECO +title: Unmanaged certificates in Config Sync Groups +toc: true +weight: 500 +--- + +## Overview + +Config Sync Groups (CSGs) in NGINX One Console ensure configuration consistency across connected NGINX instances. While managed certificates uploaded through the Console are automatically synchronized and tracked, unmanaged certificates follow a different model that provides visibility without automated management. + +Unmanaged certificates are not uploaded to the NGINX One Console. Instead, they are manually installed on individual instances and referenced directly in NGINX configuration files by their file paths. Although NGINX One does not synchronize unmanaged certificates, it tracks their metadata to help you verify consistency across instances. + +## How unmanaged certificates work in Config Sync Groups + +### Certificate tracking and visibility + +When you use unmanaged certificates in a Config Sync Group: + +- The NGINX Agent collects certificate metadata from each instance +- The Console displays unmanaged certificates based on their file paths and metadata +- Certificate consistency is determined by comparing certificate contents and file paths across instances + +### Consistent certificates + +When all instances in a CSG reference identical certificate files with the same file paths: + +- Their contents and metadata match across all instances +- The CSG displays a single unmanaged certificate entry for that file path + +### Inconsistent certificates + +If certificate contents differ between instances, even when file paths are the same: + +- Each unique certificate appears as a separate unmanaged entry in the Console +- Certificates are identified by their content and associated instance +- The CSG displays separate certificate entries in the configuration + +If certificate file paths differ between instances: + +- CSG publication may fail +- The CSG configuration will be out of sync +- Instances may not receive proper configuration updates + +## Requirements for unmanaged certificates + +To use unmanaged certificates effectively in Config Sync Groups, you must: + +- **Manual installation**: Install certificates manually on each NGINX instance in the CSG +- **Identical file paths**: Ensure that file paths referencing unmanaged certificates are identical across all instances +- **Content consistency**: Maintain identical certificate file contents across all instances to ensure proper tracking +- **User responsibility**: Take full responsibility for certificate distribution, updates, and consistency + +## Important considerations + +### Certificate tracking + +- The NGINX One Console tracks unmanaged certificates by their content and file paths +- When certificates are consistent across all instances, their contents and metadata match, and a single consolidated entry appears in the CSG +- If certificate content differs between instances, multiple unique unmanaged certificates are displayed as separate entries + +### Synchronization limitations + +- **No automated sync**: Unmanaged certificates are not synchronized by the Console +- **Manual updates**: You must manually update certificates on each instance when they expire or need rotation +- **No validation**: The Console does not perform validation or rotation logic for unmanaged certificates + +### Configuration options + +If you don't want metadata tracking for unmanaged certificates, you can configure the NGINX Agent to ignore certificate directories using the `allowed_directories` setting. + +## Best practices + +### Converting to managed certificates + +To maintain consistent visibility and automated management across CSGs, consider converting unmanaged certificates to managed certificates by: + +1. Uploading them through the NGINX One Console +2. Leveraging the managed certificate solution for automated synchronization +3. Taking advantage of centralized certificate management features + +## Troubleshooting + +### Certificate inconsistencies + +If you see multiple entries for what should be the same certificate: + +1. Verify that file paths are identical across all instances +2. Check that certificate file contents match across all instances +3. Ensure certificates were installed correctly on all instances +4. Review NGINX Agent logs for any collection issues + +If CSG publication is failing or configurations are out of sync: + +1. Confirm that all certificate file paths are identical across instances +2. Verify that referenced certificate files exist on all instances +3. Check NGINX configuration syntax for certificate references + +### Visibility issues + +If unmanaged certificates aren't appearing in the Console: + +1. Confirm that the NGINX Agent is running and connected +2. Check that certificate directories are not excluded by `allowed_directories` settings +3. Verify that NGINX configuration files correctly reference the certificate paths + +## Related topics + +- [Manage Config Sync Groups]({{< ref "manage-config-sync-groups.md" >}}) +- [Add a file to a Config Sync Group]({{< ref "add-file-csg.md" >}}) \ No newline at end of file From 97fd1703b3c2efc4372ebe730ef75f2d36187bb0 Mon Sep 17 00:00:00 2001 From: Sylvia Wang Date: Thu, 18 Dec 2025 17:48:31 -0800 Subject: [PATCH 2/7] move csg-unmanaged-certificates doc under certificates section --- .../csg-unmanaged-certificates.md} | 7 +++++-- .../config-sync-groups/manage-config-sync-groups.md | 13 +++++++++++++ 2 files changed, 18 insertions(+), 2 deletions(-) rename content/nginx-one-console/nginx-configs/{config-sync-groups/unmanaged-certificates.md => certificates/csg-unmanaged-certificates.md} (86%) diff --git a/content/nginx-one-console/nginx-configs/config-sync-groups/unmanaged-certificates.md b/content/nginx-one-console/nginx-configs/certificates/csg-unmanaged-certificates.md similarity index 86% rename from content/nginx-one-console/nginx-configs/config-sync-groups/unmanaged-certificates.md rename to content/nginx-one-console/nginx-configs/certificates/csg-unmanaged-certificates.md index f3a44d416..ef0b4c43d 100644 --- a/content/nginx-one-console/nginx-configs/config-sync-groups/unmanaged-certificates.md +++ b/content/nginx-one-console/nginx-configs/certificates/csg-unmanaged-certificates.md @@ -4,14 +4,17 @@ nd-docs: DOCS-000 nd-product: NONECO title: Unmanaged certificates in Config Sync Groups toc: true -weight: 500 +weight: 200 --- ## Overview +Unmanaged certificates are SSL/TLS certificates that you install and manage manually on NGINX instances. Unlike managed certificates that are uploaded and distributed through the NGINX One Console, unmanaged certificates are installed directly on individual instances and referenced by their file paths in NGINX configuration files. You are responsible for distributing, updating, and maintaining these certificates across your infrastructure. + +### Unmanaged certificates in Config Sync Groups Config Sync Groups (CSGs) in NGINX One Console ensure configuration consistency across connected NGINX instances. While managed certificates uploaded through the Console are automatically synchronized and tracked, unmanaged certificates follow a different model that provides visibility without automated management. -Unmanaged certificates are not uploaded to the NGINX One Console. Instead, they are manually installed on individual instances and referenced directly in NGINX configuration files by their file paths. Although NGINX One does not synchronize unmanaged certificates, it tracks their metadata to help you verify consistency across instances. +When you use unmanaged certificates in a CSG, NGINX One Console does not synchronize the certificate files themselves. However, it tracks their metadata to help you verify consistency across instances and understand the state of your certificates. ## How unmanaged certificates work in Config Sync Groups diff --git a/content/nginx-one-console/nginx-configs/config-sync-groups/manage-config-sync-groups.md b/content/nginx-one-console/nginx-configs/config-sync-groups/manage-config-sync-groups.md index d375bafdc..6e4c7caf5 100644 --- a/content/nginx-one-console/nginx-configs/config-sync-groups/manage-config-sync-groups.md +++ b/content/nginx-one-console/nginx-configs/config-sync-groups/manage-config-sync-groups.md @@ -329,6 +329,19 @@ The **Config Sync Status** column on the **Config Sync Groups** page provides in Monitor the **Config Sync Status** column. It can help you ensure that your configurations are consistently applied across all instances in a group. +## Working with unmanaged certificates + +Config Sync Groups can work with both managed and unmanaged certificates. While managed certificates are uploaded through the NGINX One Console and automatically synchronized across instances, unmanaged certificates require manual installation and management. + +When using unmanaged certificates in Config Sync Groups: + +- **Manual distribution**: You must manually install certificates on each instance in the group +- **Consistent file paths**: Certificate file paths must be identical across all instances for proper synchronization +- **Visibility without management**: NGINX One tracks unmanaged certificate metadata to help you verify consistency, but does not synchronize the certificates themselves +- **Status impact**: Inconsistent certificate file paths or missing certificates can affect the Config Sync Group status + +For detailed information about how unmanaged certificates work in Config Sync Groups, including requirements, best practices, and troubleshooting, see [Unmanaged certificates in Config Sync Groups]({{< ref "/nginx-one-console/certificates/csg-unmanaged-certificates.md" >}}). + ## See also - [Create and manage data plane keys]({{< ref "/nginx-one-console/connect-instances/create-manage-data-plane-keys.md" >}}) From e2d7a5a5d3de36285e0349c4314e3daee25782b4 Mon Sep 17 00:00:00 2001 From: Sylvia Wang Date: Thu, 18 Dec 2025 22:50:12 -0800 Subject: [PATCH 3/7] update doc ref for csg unmanaged cert --- .../config-sync-groups/manage-config-sync-groups.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nginx-one-console/nginx-configs/config-sync-groups/manage-config-sync-groups.md b/content/nginx-one-console/nginx-configs/config-sync-groups/manage-config-sync-groups.md index 6e4c7caf5..0be279854 100644 --- a/content/nginx-one-console/nginx-configs/config-sync-groups/manage-config-sync-groups.md +++ b/content/nginx-one-console/nginx-configs/config-sync-groups/manage-config-sync-groups.md @@ -340,7 +340,7 @@ When using unmanaged certificates in Config Sync Groups: - **Visibility without management**: NGINX One tracks unmanaged certificate metadata to help you verify consistency, but does not synchronize the certificates themselves - **Status impact**: Inconsistent certificate file paths or missing certificates can affect the Config Sync Group status -For detailed information about how unmanaged certificates work in Config Sync Groups, including requirements, best practices, and troubleshooting, see [Unmanaged certificates in Config Sync Groups]({{< ref "/nginx-one-console/certificates/csg-unmanaged-certificates.md" >}}). +For detailed information about how unmanaged certificates work in Config Sync Groups, including requirements, best practices, and troubleshooting, see [Unmanaged certificates in Config Sync Groups]({{< ref "/nginx-one-console/nginx-configs/certificates/csg-unmanaged-certificates.md" >}}). ## See also From c6e1d414880cd9e954c12baeb8a4f9f5d8228a75 Mon Sep 17 00:00:00 2001 From: Sylvia Wang <139922338+sylwang@users.noreply.github.com> Date: Wed, 7 Jan 2026 11:23:13 -0800 Subject: [PATCH 4/7] Apply suggestions from code review Co-authored-by: Mike Jang <3287976+mjang@users.noreply.github.com> --- .../csg-unmanaged-certificates.md | 27 ++++++++++++------- .../manage-config-sync-groups.md | 2 +- 2 files changed, 18 insertions(+), 11 deletions(-) diff --git a/content/nginx-one-console/nginx-configs/certificates/csg-unmanaged-certificates.md b/content/nginx-one-console/nginx-configs/certificates/csg-unmanaged-certificates.md index ef0b4c43d..513cd1428 100644 --- a/content/nginx-one-console/nginx-configs/certificates/csg-unmanaged-certificates.md +++ b/content/nginx-one-console/nginx-configs/certificates/csg-unmanaged-certificates.md @@ -9,15 +9,20 @@ weight: 200 ## Overview -Unmanaged certificates are SSL/TLS certificates that you install and manage manually on NGINX instances. Unlike managed certificates that are uploaded and distributed through the NGINX One Console, unmanaged certificates are installed directly on individual instances and referenced by their file paths in NGINX configuration files. You are responsible for distributing, updating, and maintaining these certificates across your infrastructure. +Unmanaged certificates are SSL/TLS certificates that you install and manage manually on NGINX instances. Unlike managed certificates that are uploaded and distributed through the NGINX One Console, unmanaged certificates are installed directly on individual instances and referenced by their file paths in NGINX configuration files. + +You are responsible for distributing, updating, and maintaining these certificates across your infrastructure. ### Unmanaged certificates in Config Sync Groups -Config Sync Groups (CSGs) in NGINX One Console ensure configuration consistency across connected NGINX instances. While managed certificates uploaded through the Console are automatically synchronized and tracked, unmanaged certificates follow a different model that provides visibility without automated management. -When you use unmanaged certificates in a CSG, NGINX One Console does not synchronize the certificate files themselves. However, it tracks their metadata to help you verify consistency across instances and understand the state of your certificates. +Config Sync Groups (CSGs) in NGINX One Console ensure configuration consistency across connected NGINX instances. While managed certificates uploaded through the Console are automatically synchronized and tracked, unmanaged certificates follow a different model. + +When you use unmanaged certificates in a CSG, NGINX One Console provides visibility without automated management. It does not synchronize the certificate files themselves. However, it tracks their metadata to help you verify consistency across instances and understand the state of your certificates. ## How unmanaged certificates work in Config Sync Groups +If you have unmanaged certificates with CSGs, consider the following factors: + ### Certificate tracking and visibility When you use unmanaged certificates in a Config Sync Group: @@ -41,7 +46,7 @@ If certificate contents differ between instances, even when file paths are the s - Certificates are identified by their content and associated instance - The CSG displays separate certificate entries in the configuration -If certificate file paths differ between instances: +If certificates are identical, but their file paths differ by instance: - CSG publication may fail - The CSG configuration will be out of sync @@ -49,7 +54,7 @@ If certificate file paths differ between instances: ## Requirements for unmanaged certificates -To use unmanaged certificates effectively in Config Sync Groups, you must: +To use unmanaged certificates effectively in Config Sync Groups, you must address these issues: - **Manual installation**: Install certificates manually on each NGINX instance in the CSG - **Identical file paths**: Ensure that file paths referencing unmanaged certificates are identical across all instances @@ -58,25 +63,25 @@ To use unmanaged certificates effectively in Config Sync Groups, you must: ## Important considerations +NGINX One Console still helps you track unmanaged certificates: + ### Certificate tracking - The NGINX One Console tracks unmanaged certificates by their content and file paths -- When certificates are consistent across all instances, their contents and metadata match, and a single consolidated entry appears in the CSG +- When certificates are consistent across all instances, their contents and metadata match: as a result, a single consolidated entry appears in the CSG - If certificate content differs between instances, multiple unique unmanaged certificates are displayed as separate entries ### Synchronization limitations - **No automated sync**: Unmanaged certificates are not synchronized by the Console -- **Manual updates**: You must manually update certificates on each instance when they expire or need rotation +- **Manual updates**: Certificates must be manually updated on each instance - **No validation**: The Console does not perform validation or rotation logic for unmanaged certificates ### Configuration options If you don't want metadata tracking for unmanaged certificates, you can configure the NGINX Agent to ignore certificate directories using the `allowed_directories` setting. -## Best practices - -### Converting to managed certificates +## Best practice: Convert to managed certificates To maintain consistent visibility and automated management across CSGs, consider converting unmanaged certificates to managed certificates by: @@ -86,6 +91,8 @@ To maintain consistent visibility and automated management across CSGs, consider ## Troubleshooting +Seemingly minor issues can lead to problems with unmanaged certificates. + ### Certificate inconsistencies If you see multiple entries for what should be the same certificate: diff --git a/content/nginx-one-console/nginx-configs/config-sync-groups/manage-config-sync-groups.md b/content/nginx-one-console/nginx-configs/config-sync-groups/manage-config-sync-groups.md index 0be279854..7aa192ed6 100644 --- a/content/nginx-one-console/nginx-configs/config-sync-groups/manage-config-sync-groups.md +++ b/content/nginx-one-console/nginx-configs/config-sync-groups/manage-config-sync-groups.md @@ -329,7 +329,7 @@ The **Config Sync Status** column on the **Config Sync Groups** page provides in Monitor the **Config Sync Status** column. It can help you ensure that your configurations are consistently applied across all instances in a group. -## Working with unmanaged certificates +## Work with unmanaged certificates Config Sync Groups can work with both managed and unmanaged certificates. While managed certificates are uploaded through the NGINX One Console and automatically synchronized across instances, unmanaged certificates require manual installation and management. From 12ea43f262fbe934647aad3845f6d359dc3aa91d Mon Sep 17 00:00:00 2001 From: Sylvia Wang Date: Wed, 7 Jan 2026 11:58:59 -0800 Subject: [PATCH 5/7] address feedback --- .../csg-unmanaged-certificates.md | 34 +++++++++---------- .../manage-config-sync-groups.md | 2 +- 2 files changed, 18 insertions(+), 18 deletions(-) diff --git a/content/nginx-one-console/nginx-configs/certificates/csg-unmanaged-certificates.md b/content/nginx-one-console/nginx-configs/certificates/csg-unmanaged-certificates.md index 513cd1428..b6bdfb27b 100644 --- a/content/nginx-one-console/nginx-configs/certificates/csg-unmanaged-certificates.md +++ b/content/nginx-one-console/nginx-configs/certificates/csg-unmanaged-certificates.md @@ -46,10 +46,10 @@ If certificate contents differ between instances, even when file paths are the s - Certificates are identified by their content and associated instance - The CSG displays separate certificate entries in the configuration -If certificates are identical, but their file paths differ by instance: +If certificate contents are identical, but their file paths differ by instance: -- CSG publication may fail -- The CSG configuration will be out of sync +- CSG publication may fail if file paths referenced in the NGINX configuration files do not exist on the instance +- The CSG configuration status will be out of sync - Instances may not receive proper configuration updates ## Requirements for unmanaged certificates @@ -75,7 +75,7 @@ NGINX One Console still helps you track unmanaged certificates: - **No automated sync**: Unmanaged certificates are not synchronized by the Console - **Manual updates**: Certificates must be manually updated on each instance -- **No validation**: The Console does not perform validation or rotation logic for unmanaged certificates +- **No validation**: The Console does not perform validation logic for unmanaged certificates ### Configuration options @@ -85,9 +85,9 @@ If you don't want metadata tracking for unmanaged certificates, you can configur To maintain consistent visibility and automated management across CSGs, consider converting unmanaged certificates to managed certificates by: -1. Uploading them through the NGINX One Console -2. Leveraging the managed certificate solution for automated synchronization -3. Taking advantage of centralized certificate management features +- Convering them from unmanaged to managed +- Leveraging the managed certificate solution for automated synchronization +- Taking advantage of centralized certificate management features ## Troubleshooting @@ -97,24 +97,24 @@ Seemingly minor issues can lead to problems with unmanaged certificates. If you see multiple entries for what should be the same certificate: -1. Verify that file paths are identical across all instances -2. Check that certificate file contents match across all instances -3. Ensure certificates were installed correctly on all instances -4. Review NGINX Agent logs for any collection issues +- Verify that file paths are identical across all instances +- Check that certificate file contents match across all instances +- Ensure certificates were installed correctly on all instances +- Review NGINX Agent logs for any collection issues If CSG publication is failing or configurations are out of sync: -1. Confirm that all certificate file paths are identical across instances -2. Verify that referenced certificate files exist on all instances -3. Check NGINX configuration syntax for certificate references +- Confirm that all certificate file paths are identical across instances +- Verify that referenced certificate files exist on all instances +- Check NGINX configuration syntax for certificate references ### Visibility issues If unmanaged certificates aren't appearing in the Console: -1. Confirm that the NGINX Agent is running and connected -2. Check that certificate directories are not excluded by `allowed_directories` settings -3. Verify that NGINX configuration files correctly reference the certificate paths +- Confirm that the NGINX Agent is running and connected +- Check that certificate directories are not excluded by `allowed_directories` settings +- Verify that NGINX configuration files correctly reference the certificate paths ## Related topics diff --git a/content/nginx-one-console/nginx-configs/config-sync-groups/manage-config-sync-groups.md b/content/nginx-one-console/nginx-configs/config-sync-groups/manage-config-sync-groups.md index 7aa192ed6..2d257d9ed 100644 --- a/content/nginx-one-console/nginx-configs/config-sync-groups/manage-config-sync-groups.md +++ b/content/nginx-one-console/nginx-configs/config-sync-groups/manage-config-sync-groups.md @@ -338,7 +338,7 @@ When using unmanaged certificates in Config Sync Groups: - **Manual distribution**: You must manually install certificates on each instance in the group - **Consistent file paths**: Certificate file paths must be identical across all instances for proper synchronization - **Visibility without management**: NGINX One tracks unmanaged certificate metadata to help you verify consistency, but does not synchronize the certificates themselves -- **Status impact**: Inconsistent certificate file paths or missing certificates can affect the Config Sync Group status +- **Status impact**: Inconsistent certificate file paths or missing certificates can affect the Config Sync Group configuration sync status For detailed information about how unmanaged certificates work in Config Sync Groups, including requirements, best practices, and troubleshooting, see [Unmanaged certificates in Config Sync Groups]({{< ref "/nginx-one-console/nginx-configs/certificates/csg-unmanaged-certificates.md" >}}). From dcd2b1b140a7a0eda5a8cd0983cc1c8c3c1afb35 Mon Sep 17 00:00:00 2001 From: Sylvia Wang Date: Tue, 27 Jan 2026 09:58:26 -0800 Subject: [PATCH 6/7] update the changelog to include CSG unmanaged certs --- content/nginx-one-console/changelog.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/content/nginx-one-console/changelog.md b/content/nginx-one-console/changelog.md index 42a62e76d..cf62db98a 100644 --- a/content/nginx-one-console/changelog.md +++ b/content/nginx-one-console/changelog.md @@ -11,6 +11,10 @@ Stay up-to-date with what's new and improved in the F5 NGINX One Console. ## January 27, 2026 +### Config Sync Groups: Support for unmanaged certificates + +Config Sync Groups now support unmanaged certificates. You can reference SSL/TLS certificates managed outside of NGINX One Console in your configuration files while maintaining centralized configuration synchronization across all instances in the group. + ### API behavior change: conf_path is now optional for PUT/PATCH operations - The `conf_path` field is now optional when updating configurations for NGINX instances, Config Sync Groups, and Staged Configs with PUT and PATCH operations. From a4651a78ce8537a51fbaf66ad9860b5e6a696627 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Tue, 27 Jan 2026 10:11:22 -0800 Subject: [PATCH 7/7] Update content/nginx-one-console/nginx-configs/certificates/csg-unmanaged-certificates.md --- .../nginx-configs/certificates/csg-unmanaged-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nginx-one-console/nginx-configs/certificates/csg-unmanaged-certificates.md b/content/nginx-one-console/nginx-configs/certificates/csg-unmanaged-certificates.md index b6bdfb27b..491e345ce 100644 --- a/content/nginx-one-console/nginx-configs/certificates/csg-unmanaged-certificates.md +++ b/content/nginx-one-console/nginx-configs/certificates/csg-unmanaged-certificates.md @@ -85,7 +85,7 @@ If you don't want metadata tracking for unmanaged certificates, you can configur To maintain consistent visibility and automated management across CSGs, consider converting unmanaged certificates to managed certificates by: -- Convering them from unmanaged to managed +- Converting them from unmanaged to managed - Leveraging the managed certificate solution for automated synchronization - Taking advantage of centralized certificate management features