From d708f35601a4105f14212386ab0a975b8ac8e2bb Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Wed, 16 Jul 2025 16:46:11 +0100 Subject: [PATCH 1/3] docs: update N1 config sync steps for v3 --- .../manage-config-sync-groups.md | 80 ++++++++++++++++++- 1 file changed, 79 insertions(+), 1 deletion(-) diff --git a/content/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md b/content/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md index 5db71008b..5b4063b3a 100644 --- a/content/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md +++ b/content/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md @@ -81,7 +81,7 @@ 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/`. +- **NGINX Agent configuration file location**: When you run the NGINX Agent installation script to register an instance with NGINX One, the script creates the `nginx-agent.conf` (or `agent-dynamic.conf` if you are using NGINX Agent 2.x) file, which contains settings for the NGINX Agent, including the specified Config Sync Group. This file is typically located in `/etc/nginx-agent/` on most systems. - **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. @@ -104,6 +104,28 @@ Any instance that joins the group afterwards inherits that configuration. You can add existing NGINX instances that are already registered with NGINX One to a Config Sync Group. +{{< tabs name="Add existing instance to Config Sync Group" >}} + +{{%tab name="NGINX Agent 3.x"%}} + +1. Open a command-line terminal on the NGINX instance. +2. Open the `/etc/nginx-agent/nginx-agent.conf` file in a text editor. +3. Find or create the `labels` section and change the `config_sync_group` label to the name of the new Config Sync Group. + + ``` text + labels: + config_sync_group: + ``` + +4. Restart NGINX Agent: + + ``` shell + sudo systemctl restart nginx-agent + ``` + +{{%/tab%}} +{{%tab name="NGINX Agent 2.x"%}} + 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. @@ -118,6 +140,9 @@ You can add existing NGINX instances that are already registered with NGINX One sudo systemctl restart nginx-agent ``` +{{%/tab%}} +{{< /tabs >}} + ### 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. @@ -185,6 +210,29 @@ For more details on creating and managing data plane keys, see [Create and manag If you need to move an NGINX instance to a different Config Sync Group, follow these steps: +{{< tabs name="Add instance to Config Sync Group" >}} + +{{%tab name="NGINX Agent 3.x"%}} + +1. Open a command-line terminal on the NGINX instance. +2. Open the `/etc/nginx-agent/nginx-agent.conf` file in a text editor. +3. Find the `labels` section and change the `config_sync_group` label to the name of the new Config Sync Group. + + ``` text + labels: + config-sync-group: + ``` + +4. Restart NGINX Agent by running the following command: + + ```shell + sudo systemctl restart nginx-agent + ``` + +{{%/tab%}} +{{%tab name="NGINX Agent 2.x"%}} + + 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. @@ -199,12 +247,38 @@ If you need to move an NGINX instance to a different Config Sync Group, follow t sudo systemctl restart nginx-agent ``` +{{%/tab%}} +{{< /tabs >}} + + 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: + +{{< tabs name="Add instance to Config Sync Group" >}} +{{%tab name="NGINX Agent 3.x"%}} + +1. Open a command-line terminal on the NGINX instance. +2. Open the `/etc/nginx-agent/nginx-agent.conf` file in a text editor. +3. Locate the line that begins with `labels:` section and either remove the `config-sync-group` line or comment it out by adding a `#` at the beginning of the line. + + ```text + labels: + # config-sync-group: + ``` + +4. Restart NGINX Agent: + + ```shell + sudo systemctl restart nginx-agent + ``` + +{{%/tab%}} +{{%tab name="NGINX Agent 2.x"%}} + 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. @@ -219,6 +293,10 @@ If you need to remove an NGINX instance from a Config Sync Group without adding sudo systemctl restart nginx-agent ``` +{{%/tab%}} +{{< /tabs >}} + + 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} From cc246d4fa90ac276023b994f5e77e9a96ed6059f Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Wed, 16 Jul 2025 16:56:50 +0100 Subject: [PATCH 2/3] docs: fix label --- .../config-sync-groups/manage-config-sync-groups.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md b/content/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md index 5b4063b3a..f10d05de3 100644 --- a/content/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md +++ b/content/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md @@ -258,7 +258,7 @@ If you move an instance with certificates from one Config Sync Group to another, If you need to remove an NGINX instance from a Config Sync Group without adding it to another group, follow these steps: -{{< tabs name="Add instance to Config Sync Group" >}} +{{< tabs name="Remove instance from Config Sync Group" >}} {{%tab name="NGINX Agent 3.x"%}} 1. Open a command-line terminal on the NGINX instance. From aaf7304c381a356efa66b265e4408cf15cf2fc01 Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Wed, 16 Jul 2025 17:16:14 +0100 Subject: [PATCH 3/3] docs: fix tabs names --- .../config-sync-groups/manage-config-sync-groups.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md b/content/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md index f10d05de3..3d68f350e 100644 --- a/content/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md +++ b/content/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md @@ -210,7 +210,7 @@ For more details on creating and managing data plane keys, see [Create and manag If you need to move an NGINX instance to a different Config Sync Group, follow these steps: -{{< tabs name="Add instance to Config Sync Group" >}} +{{< tabs name="Move instance to Config Sync Group" >}} {{%tab name="NGINX Agent 3.x"%}} @@ -259,6 +259,7 @@ If you need to remove an NGINX instance from a Config Sync Group without adding {{< tabs name="Remove instance from Config Sync Group" >}} + {{%tab name="NGINX Agent 3.x"%}} 1. Open a command-line terminal on the NGINX instance.