From 388bd08ed28782fe4e600cd543d654437d912c3b Mon Sep 17 00:00:00 2001 From: Nick Chen <139289811+nginx-nickc@users.noreply.github.com> Date: Tue, 9 Sep 2025 14:09:54 -0700 Subject: [PATCH 1/8] docs: added guide for working with NGINX Configs --- content/nginx-one/api/nginx_configuration.md | 128 +++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 content/nginx-one/api/nginx_configuration.md diff --git a/content/nginx-one/api/nginx_configuration.md b/content/nginx-one/api/nginx_configuration.md new file mode 100644 index 000000000..02d1be2b6 --- /dev/null +++ b/content/nginx-one/api/nginx_configuration.md @@ -0,0 +1,128 @@ +--- +description: '' +nd-docs: DOCS-1063 +title: Working with NGINX Configs +toc: true +weight: 10 +type: +- how-to +--- + +In this guide, we'll show you how to use API requests to update NGINX Configs for Instances or Config Sync Groups in the F5 NGINX One Console. + +## Getting ready + +Before you begin, make sure you can properly authenticate your API requests with either an API Token or API Certificate, following the instructions in the [Authentication]({{}}) guide. Ensure you have registered or created your NGINX Instance or Config Sync Group in the F5 NGINX One Console, follow the instructions in the [Manage your NGINX instances]({{}}) guide. + +{{< call-out "note" >}} +The workflows for managing NGINX Configs for Instances and Config Sync Groups in the F5 NGINX One Console are quite similar. This guide focuses on the steps for updating NGINX Configs for Instances. If you're working with Config Sync Groups, you'll follow a similar process but will need to update the API endpoints appropriately. +{{< /call-out>}} + +## Getting the current NGINX Config + +You can retrieve the current NGINX Config for an Instance or Config Sync Group using a `GET` request. This is useful for making updates based on the existing configuration. + +Use the following curl command to retrieve the current NGINX Config for a specific Instance. Replace ``, ``, ``, and `` with your actual values. + + ```shell + curl -X GET "https://.console.ves.volterra.io/api/nginx/one/namespaces//instances//config" \ + -H "Authorization: APIToken " -o current_config.json + ``` + - ``: Your tenant name for organization plans. + - ``: The namespace your Instance belongs to. + - ``: The object_id of the NGINX Instance you want to retrieve the NGINX Config for. + - ``: Your API Token. + +{{< call-out "note" >}} +To update the NGINX Config for a Config Sync Group, replace `instances` with `config-sync-groups` and use the object_id of the Config Sync Group in the URL. +{{< /call-out>}} + + The response will include the current NGINX Config in JSON format. This response is saved to a file (e.g., `current_config.json`) for editing. + +## Updating the NGINX Config + +You can modify the NGINX Config using either `PUT` or `PATCH` requests. The `PUT` method replaces the entire NGINX Config, while the `PATCH` method allows you to update specific fields without affecting the rest of the configuration. + +1. **Update the NGINX Config for an Instance using `PUT`**: + + When using the `PUT` method, ensure that your request body includes all necessary contents, as it will overwrite the existing configuration. + The following example demonstrates how to update the NGINX Config for a specific Instance using `PUT`. Replace ``, ``, ``, and `` with your actual values. The request body should contain the complete NGINX Config in JSON format. + ```shell + curl -X PUT "https://.console.ves.volterra.io/api/nginx/one/namespaces//instances//config" \ + -H "Authorization : APIToken " \ + -H "Content-Type: application/json" \ + -d @updated_config.json + ``` + - ``: Your tenant name for organization plans. + - ``: The namespace your Instance belongs to. + - ``: The object_id of the NGINX Instance you want to update the NGINX Config for. + - ``: Your API Token. + +2. **Update the NGINX Config for an Instance using `PATCH`**: + + When using the `PATCH` method, you only need to include the files you want to update in your request body. + The following example demonstrates how to update the NGINX Config for a specific Instance using `PATCH`. Replace ``, ``, ``, and `` with your actual values. The request body should contain only the fields you want to update in JSON format. + ```shell + curl -X PATCH "https://.console.ves.volterra.io/api/nginx/one/namespaces//instances//config" \ + -H "Authorization : APIToken " \ + -H "Content-Type: application/json" \ + -d @partial_update_config.json + ``` + - ``: Your tenant name for organization plans. + - ``: The namespace your Instance belongs to. + - ``: The object_id of the NGINX Instance you want to update the NGINX Config for. + - ``: Your API Token. + + With `PATCH`, you can update specific parts of the NGINX Config without needing to resend the entire configuration. The following file `contents` disposition is observed: + - Leave out file `contents` to remove the file from the NGINX Config. + - Include file `contents` to add or update the file in the NGINX Config. File `contents` must be base64 encoded. File `contents` can be an empty string to create an empty file. + - `config_version` should be included to ensure you're updating the correct version of the configuration. You can get the current `config_version` from the response of the `GET` request. + For example, to update only the `nginx.conf` file in the NGINX Config, your `partial_update_config.json` might look like this: + ```json + { + "conf_path": "/etc/nginx/nginx.conf", + "config_version": "", + "configs": { + "/etc/nginx": { + "files": [{ + "path": "nginx.conf", + "contents": "" + }] + } + } + } + ``` + To remove a file, simply omit the `contents` field for that file in your `PATCH` request body, your `partial_update_config.json` might look like this: + ```json + { + "conf_path": "/etc/nginx/nginx.conf", + "config_version": "", + "configs": { + "/etc/nginx/conf.d": { + "files": [{ + "path": "default.conf" + }] + } + } + } + ``` + Multiple updates can be made in a single `PATCH` request. For example, to update `nginx.conf` and remove `default.conf`, your `partial_update_config.json` might look like this: + ```json + { + "conf_path": "/etc/nginx/nginx.conf", + "config_version": "", + "configs": { + "/etc/nginx": { + "files": [{ + "path": "nginx.conf", + "contents": "" + }] + }, + "/etc/nginx/conf.d": { + "files": [{ + "path": "default.conf" + }] + } + } + } + ``` \ No newline at end of file From eaf53bf36930d3c97078933b24843683d32cf6b5 Mon Sep 17 00:00:00 2001 From: Nick Chen <139289811+nginx-nickc@users.noreply.github.com> Date: Wed, 10 Sep 2025 13:55:44 -0700 Subject: [PATCH 2/8] Update nginx_configuration.md --- content/nginx-one/api/nginx_configuration.md | 87 ++++++++++++-------- 1 file changed, 53 insertions(+), 34 deletions(-) diff --git a/content/nginx-one/api/nginx_configuration.md b/content/nginx-one/api/nginx_configuration.md index 02d1be2b6..09576ac86 100644 --- a/content/nginx-one/api/nginx_configuration.md +++ b/content/nginx-one/api/nginx_configuration.md @@ -12,15 +12,15 @@ In this guide, we'll show you how to use API requests to update NGINX Configs fo ## Getting ready -Before you begin, make sure you can properly authenticate your API requests with either an API Token or API Certificate, following the instructions in the [Authentication]({{}}) guide. Ensure you have registered or created your NGINX Instance or Config Sync Group in the F5 NGINX One Console, follow the instructions in the [Manage your NGINX instances]({{}}) guide. +Before you begin, make sure you can properly authenticate your API requests with either an API Token or API Certificate, following the instructions in the [Authentication]({{}}) guide. Ensure you have registered or created your NGINX Instance, Config Sync Group, or Staged Config in the F5 NGINX One Console, follow the instructions in the [Manage your NGINX instances]({{}}) guide. {{< call-out "note" >}} -The workflows for managing NGINX Configs for Instances and Config Sync Groups in the F5 NGINX One Console are quite similar. This guide focuses on the steps for updating NGINX Configs for Instances. If you're working with Config Sync Groups, you'll follow a similar process but will need to update the API endpoints appropriately. +The workflows for managing NGINX Configs for Instances, Config Sync Groups, and Staged Configs in the F5 NGINX One Console are quite similar. This guide focuses on the steps for updating NGINX Configs for Instances. If you're working with Config Sync Groups, you'll follow a similar process but will need to update the API endpoints appropriately. {{< /call-out>}} ## Getting the current NGINX Config -You can retrieve the current NGINX Config for an Instance or Config Sync Group using a `GET` request. This is useful for making updates based on the existing configuration. +You can retrieve the current NGINX Config for an Instance, Config Sync Group, or Staged Config using a `GET` request. This is useful for making updates based on the existing configuration. Use the following curl command to retrieve the current NGINX Config for a specific Instance. Replace ``, ``, ``, and `` with your actual values. @@ -34,7 +34,7 @@ Use the following curl command to retrieve the current NGINX Config for a specif - ``: Your API Token. {{< call-out "note" >}} -To update the NGINX Config for a Config Sync Group, replace `instances` with `config-sync-groups` and use the object_id of the Config Sync Group in the URL. +To update the NGINX Config for a Config Sync Group, replace `instances` with `config-sync-groups` or `staged-configs` and use the object_id of the Config Sync Group or Staged Config in the URL. {{< /call-out>}} The response will include the current NGINX Config in JSON format. This response is saved to a file (e.g., `current_config.json`) for editing. @@ -77,52 +77,71 @@ You can modify the NGINX Config using either `PUT` or `PATCH` requests. The `PUT - Leave out file `contents` to remove the file from the NGINX Config. - Include file `contents` to add or update the file in the NGINX Config. File `contents` must be base64 encoded. File `contents` can be an empty string to create an empty file. - `config_version` should be included to ensure you're updating the correct version of the configuration. You can get the current `config_version` from the response of the `GET` request. - For example, to update only the `nginx.conf` file in the NGINX Config, your `partial_update_config.json` might look like this: + For example, to update only the `/etc/nginx/nginx.conf` file in the NGINX Config, your `partial_update_config.json` might look like this: ```json { "conf_path": "/etc/nginx/nginx.conf", - "config_version": "", - "configs": { - "/etc/nginx": { - "files": [{ - "path": "nginx.conf", - "contents": "" - }] + "config_version": "", + "configs": [ + { + "name": "/etc/nginx", + "files": [ + { + "name": "nginx.conf", + "contents": "" + } + ] } - } + ] } ``` - To remove a file, simply omit the `contents` field for that file in your `PATCH` request body, your `partial_update_config.json` might look like this: + {{< call-out "note" >}} + To encode files in base64, you can use the following command in a Unix-like terminal: + ```shell + base64 /path/to/your/file + ``` + Replace `/path/to/your/file` with the actual path to the file you want to encode. + {{< /call-out>}} + To remove a file, simply omit the `contents` field for that file in your `PATCH` request body, your `partial_update_config.json` might look like this to remove `/etc/nginx/conf.d/default.conf` from the NGINX Config: ```json { "conf_path": "/etc/nginx/nginx.conf", - "config_version": "", - "configs": { - "/etc/nginx/conf.d": { - "files": [{ - "path": "default.conf" - }] + "config_version": "", + "configs": [ + { + "name": "/etc/nginx/conf.d", + "files": [ + { + "name": "default.conf" + } + ] } - } + ] } ``` - Multiple updates can be made in a single `PATCH` request. For example, to update `nginx.conf` and remove `default.conf`, your `partial_update_config.json` might look like this: + Multiple updates can be made in a single `PATCH` request. For example, to update `/etc/nginx/nginx.conf` and remove `/etc/nginx/conf.d/default.conf`, your `partial_update_config.json` might look like this: ```json { "conf_path": "/etc/nginx/nginx.conf", - "config_version": "", - "configs": { - "/etc/nginx": { - "files": [{ - "path": "nginx.conf", - "contents": "" - }] + "config_version": "", + "configs": [ + { + "name": "/etc/nginx/conf.d", + "files": [ + { + "name": "default.conf" + } + ] }, - "/etc/nginx/conf.d": { - "files": [{ - "path": "default.conf" - }] + { + "name": "/etc/nginx", + "files": [ + { + "name": "nginx.conf", + "contents": "" + } + ] } - } + ] } ``` \ No newline at end of file From 6e612b638c2626dd60d114336b440977a499a96d Mon Sep 17 00:00:00 2001 From: Nick Chen <139289811+nginx-nickc@users.noreply.github.com> Date: Wed, 10 Sep 2025 14:44:13 -0700 Subject: [PATCH 3/8] docs: format --- content/nginx-one/api/nginx_configuration.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/nginx-one/api/nginx_configuration.md b/content/nginx-one/api/nginx_configuration.md index 09576ac86..4dab51cbf 100644 --- a/content/nginx-one/api/nginx_configuration.md +++ b/content/nginx-one/api/nginx_configuration.md @@ -34,7 +34,7 @@ Use the following curl command to retrieve the current NGINX Config for a specif - ``: Your API Token. {{< call-out "note" >}} -To update the NGINX Config for a Config Sync Group, replace `instances` with `config-sync-groups` or `staged-configs` and use the object_id of the Config Sync Group or Staged Config in the URL. +To update the NGINX Config for a Config Sync Group or Staged Config, replace `instances` with `config-sync-groups` or `staged-configs` and use the object_id of the Config Sync Group or Staged Config in the URL. {{< /call-out>}} The response will include the current NGINX Config in JSON format. This response is saved to a file (e.g., `current_config.json`) for editing. @@ -77,6 +77,7 @@ You can modify the NGINX Config using either `PUT` or `PATCH` requests. The `PUT - Leave out file `contents` to remove the file from the NGINX Config. - Include file `contents` to add or update the file in the NGINX Config. File `contents` must be base64 encoded. File `contents` can be an empty string to create an empty file. - `config_version` should be included to ensure you're updating the correct version of the configuration. You can get the current `config_version` from the response of the `GET` request. + For example, to update only the `/etc/nginx/nginx.conf` file in the NGINX Config, your `partial_update_config.json` might look like this: ```json { From 271644e10dbe166d460337f3602681fd397de1fa Mon Sep 17 00:00:00 2001 From: Nick Chen <139289811+nginx-nickc@users.noreply.github.com> Date: Wed, 10 Sep 2025 15:43:39 -0700 Subject: [PATCH 4/8] Update nginx_configuration.md --- content/nginx-one/api/nginx_configuration.md | 100 ++++++++++--------- 1 file changed, 52 insertions(+), 48 deletions(-) diff --git a/content/nginx-one/api/nginx_configuration.md b/content/nginx-one/api/nginx_configuration.md index 4dab51cbf..1c2ff0bdf 100644 --- a/content/nginx-one/api/nginx_configuration.md +++ b/content/nginx-one/api/nginx_configuration.md @@ -23,7 +23,6 @@ The workflows for managing NGINX Configs for Instances, Config Sync Groups, and You can retrieve the current NGINX Config for an Instance, Config Sync Group, or Staged Config using a `GET` request. This is useful for making updates based on the existing configuration. Use the following curl command to retrieve the current NGINX Config for a specific Instance. Replace ``, ``, ``, and `` with your actual values. - ```shell curl -X GET "https://.console.ves.volterra.io/api/nginx/one/namespaces//instances//config" \ -H "Authorization: APIToken " -o current_config.json @@ -39,47 +38,57 @@ To update the NGINX Config for a Config Sync Group or Staged Config, replace `in The response will include the current NGINX Config in JSON format. This response is saved to a file (e.g., `current_config.json`) for editing. -## Updating the NGINX Config - You can modify the NGINX Config using either `PUT` or `PATCH` requests. The `PUT` method replaces the entire NGINX Config, while the `PATCH` method allows you to update specific fields without affecting the rest of the configuration. -1. **Update the NGINX Config for an Instance using `PUT`**: +## How to base64 encode a file for JSON request - When using the `PUT` method, ensure that your request body includes all necessary contents, as it will overwrite the existing configuration. - The following example demonstrates how to update the NGINX Config for a specific Instance using `PUT`. Replace ``, ``, ``, and `` with your actual values. The request body should contain the complete NGINX Config in JSON format. - ```shell - curl -X PUT "https://.console.ves.volterra.io/api/nginx/one/namespaces//instances//config" \ - -H "Authorization : APIToken " \ - -H "Content-Type: application/json" \ - -d @updated_config.json - ``` - - ``: Your tenant name for organization plans. - - ``: The namespace your Instance belongs to. - - ``: The object_id of the NGINX Instance you want to update the NGINX Config for. - - ``: Your API Token. - -2. **Update the NGINX Config for an Instance using `PATCH`**: - - When using the `PATCH` method, you only need to include the files you want to update in your request body. - The following example demonstrates how to update the NGINX Config for a specific Instance using `PATCH`. Replace ``, ``, ``, and `` with your actual values. The request body should contain only the fields you want to update in JSON format. - ```shell +When updating the NGINX Config, file `contents` must be base64 encoded. You can use the following command to base64 encode a file: + +```shell +base64 -w 0 -i +``` +This command reads the file at `` and outputs its base64 encoded content in a single line (due to the `-w 0` option). You can then copy this encoded string and include it in your JSON request body. On some systems the `-w` option may not be available, in which case you can use: +```shell +base64 -i | tr -d '\n' +``` + +## Update the NGINX Config for an Instance using `PUT` + +When using the `PUT` method, ensure that your request body includes all necessary contents, as it will overwrite the existing configuration. +The following example demonstrates how to update the NGINX Config for a specific Instance using `PUT`. Replace ``, ``, ``, and `` with your actual values. The request body should contain the complete NGINX Config in JSON format. + ```shell + curl -X PUT "https://.console.ves.volterra.io/api/nginx/one/namespaces//instances//config" \ + -H "Authorization : APIToken " \ + -H "Content-Type: application/json" \ + -d @updated_config.json + ``` + - ``: Your tenant name for organization plans. + - ``: The namespace your Instance belongs to. + - ``: The object_id of the NGINX Instance you want to update the NGINX Config for. + - ``: Your API Token. + +## Update the NGINX Config for an Instance using `PATCH` + +When using the `PATCH` method, you only need to include the files you want to update in your request body. +The following example demonstrates how to update the NGINX Config for a specific Instance using `PATCH`. Replace ``, ``, ``, and `` with your actual values. The request body should contain only the fields you want to update in JSON format. + ```shell curl -X PATCH "https://.console.ves.volterra.io/api/nginx/one/namespaces//instances//config" \ -H "Authorization : APIToken " \ -H "Content-Type: application/json" \ -d @partial_update_config.json - ``` - - ``: Your tenant name for organization plans. - - ``: The namespace your Instance belongs to. - - ``: The object_id of the NGINX Instance you want to update the NGINX Config for. - - ``: Your API Token. - - With `PATCH`, you can update specific parts of the NGINX Config without needing to resend the entire configuration. The following file `contents` disposition is observed: - - Leave out file `contents` to remove the file from the NGINX Config. - - Include file `contents` to add or update the file in the NGINX Config. File `contents` must be base64 encoded. File `contents` can be an empty string to create an empty file. - - `config_version` should be included to ensure you're updating the correct version of the configuration. You can get the current `config_version` from the response of the `GET` request. - - For example, to update only the `/etc/nginx/nginx.conf` file in the NGINX Config, your `partial_update_config.json` might look like this: - ```json + ``` + - ``: Your tenant name for organization plans. + - ``: The namespace your Instance belongs to. + - ``: The object_id of the NGINX Instance you want to update the NGINX Config for. + - ``: Your API Token. + +With `PATCH`, you can update specific parts of the NGINX Config without needing to resend the entire configuration. The following file `contents` disposition is observed: + - Leave out file `contents` to remove the file from the NGINX Config. + - Include file `contents` to add or update the file in the NGINX Config. File `contents` must be base64 encoded. File `contents` can be an empty string to create an empty file. + - `config_version` should be included to ensure you're updating the correct version of the configuration. You can get the current `config_version` from the response of the `GET` request. + +For example, to update only the `/etc/nginx/nginx.conf` file in the NGINX Config, your `partial_update_config.json` might look like this: + ```json { "conf_path": "/etc/nginx/nginx.conf", "config_version": "", @@ -95,16 +104,9 @@ You can modify the NGINX Config using either `PUT` or `PATCH` requests. The `PUT } ] } - ``` - {{< call-out "note" >}} - To encode files in base64, you can use the following command in a Unix-like terminal: - ```shell - base64 /path/to/your/file ``` - Replace `/path/to/your/file` with the actual path to the file you want to encode. - {{< /call-out>}} - To remove a file, simply omit the `contents` field for that file in your `PATCH` request body, your `partial_update_config.json` might look like this to remove `/etc/nginx/conf.d/default.conf` from the NGINX Config: - ```json +To remove a file, simply omit the `contents` field for that file in your `PATCH` request body, your `partial_update_config.json` might look like this to remove `/etc/nginx/conf.d/default.conf` from the NGINX Config: + ```json { "conf_path": "/etc/nginx/nginx.conf", "config_version": "", @@ -119,9 +121,11 @@ You can modify the NGINX Config using either `PUT` or `PATCH` requests. The `PUT } ] } - ``` - Multiple updates can be made in a single `PATCH` request. For example, to update `/etc/nginx/nginx.conf` and remove `/etc/nginx/conf.d/default.conf`, your `partial_update_config.json` might look like this: - ```json + ``` +## Set up multiple updates with PATCH + +Multiple updates can be made in a single `PATCH` request. For example, to update `/etc/nginx/nginx.conf` and remove `/etc/nginx/conf.d/default.conf`, your `partial_update_config.json` might look like this: + ```json { "conf_path": "/etc/nginx/nginx.conf", "config_version": "", @@ -145,4 +149,4 @@ You can modify the NGINX Config using either `PUT` or `PATCH` requests. The `PUT } ] } - ``` \ No newline at end of file + ``` \ No newline at end of file From 431908f43d1b66f5429ee329be2dbb7f8fd444d4 Mon Sep 17 00:00:00 2001 From: nginx-nickc <139289811+nginx-nickc@users.noreply.github.com> Date: Thu, 11 Sep 2025 09:00:45 -0700 Subject: [PATCH 5/8] Apply suggestions from code review Co-authored-by: Mike Jang <3287976+mjang@users.noreply.github.com> --- content/nginx-one/api/nginx_configuration.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/content/nginx-one/api/nginx_configuration.md b/content/nginx-one/api/nginx_configuration.md index 1c2ff0bdf..f040b59bc 100644 --- a/content/nginx-one/api/nginx_configuration.md +++ b/content/nginx-one/api/nginx_configuration.md @@ -1,16 +1,16 @@ --- description: '' -nd-docs: DOCS-1063 -title: Working with NGINX Configs +nd-docs: DOCS-000 +title: Manage NGINX configurations with API requests toc: true -weight: 10 +weight: 100 type: - how-to --- -In this guide, we'll show you how to use API requests to update NGINX Configs for Instances or Config Sync Groups in the F5 NGINX One Console. +In this guide, we'll show you how to use API requests to update NGINX Configurations for Instances or Config Sync Groups in the F5 NGINX One Console. -## Getting ready +## Get ready Before you begin, make sure you can properly authenticate your API requests with either an API Token or API Certificate, following the instructions in the [Authentication]({{}}) guide. Ensure you have registered or created your NGINX Instance, Config Sync Group, or Staged Config in the F5 NGINX One Console, follow the instructions in the [Manage your NGINX instances]({{}}) guide. @@ -18,15 +18,16 @@ Before you begin, make sure you can properly authenticate your API requests with The workflows for managing NGINX Configs for Instances, Config Sync Groups, and Staged Configs in the F5 NGINX One Console are quite similar. This guide focuses on the steps for updating NGINX Configs for Instances. If you're working with Config Sync Groups, you'll follow a similar process but will need to update the API endpoints appropriately. {{< /call-out>}} -## Getting the current NGINX Config +## Get the current NGINX configuration You can retrieve the current NGINX Config for an Instance, Config Sync Group, or Staged Config using a `GET` request. This is useful for making updates based on the existing configuration. -Use the following curl command to retrieve the current NGINX Config for a specific Instance. Replace ``, ``, ``, and `` with your actual values. +Use the following `curl` command to retrieve the current NGINX configuration for a specific Instance. Replace ``, ``, ``, and `` with your actual values. ```shell curl -X GET "https://.console.ves.volterra.io/api/nginx/one/namespaces//instances//config" \ -H "Authorization: APIToken " -o current_config.json ``` + - ``: Your tenant name for organization plans. - ``: The namespace your Instance belongs to. - ``: The object_id of the NGINX Instance you want to retrieve the NGINX Config for. @@ -36,9 +37,9 @@ Use the following curl command to retrieve the current NGINX Config for a specif To update the NGINX Config for a Config Sync Group or Staged Config, replace `instances` with `config-sync-groups` or `staged-configs` and use the object_id of the Config Sync Group or Staged Config in the URL. {{< /call-out>}} - The response will include the current NGINX Config in JSON format. This response is saved to a file (e.g., `current_config.json`) for editing. + The response will include the current NGINX configuration in JSON format. This response is saved to a file (with a name like `current_config.json`) for editing. -You can modify the NGINX Config using either `PUT` or `PATCH` requests. The `PUT` method replaces the entire NGINX Config, while the `PATCH` method allows you to update specific fields without affecting the rest of the configuration. +You can modify the NGINX configuration using either `PUT` or `PATCH` requests. The `PUT` method replaces the entire NGINX configuration, while the `PATCH` method allows you to update specific fields without affecting the rest of the configuration. ## How to base64 encode a file for JSON request From 323bcff356c1d0bba6aa04be16005e8b62e6172c Mon Sep 17 00:00:00 2001 From: Nick Chen <139289811+nginx-nickc@users.noreply.github.com> Date: Thu, 11 Sep 2025 09:10:39 -0700 Subject: [PATCH 6/8] Update nginx_configuration.md --- content/nginx-one/api/nginx_configuration.md | 36 ++++++++++++-------- 1 file changed, 22 insertions(+), 14 deletions(-) diff --git a/content/nginx-one/api/nginx_configuration.md b/content/nginx-one/api/nginx_configuration.md index f040b59bc..c66306689 100644 --- a/content/nginx-one/api/nginx_configuration.md +++ b/content/nginx-one/api/nginx_configuration.md @@ -12,7 +12,7 @@ In this guide, we'll show you how to use API requests to update NGINX Configurat ## Get ready -Before you begin, make sure you can properly authenticate your API requests with either an API Token or API Certificate, following the instructions in the [Authentication]({{}}) guide. Ensure you have registered or created your NGINX Instance, Config Sync Group, or Staged Config in the F5 NGINX One Console, follow the instructions in the [Manage your NGINX instances]({{}}) guide. +Before you begin, make sure you can properly authenticate your API requests with either an API Token or API Certificate, following the instructions in the [Authentication]({{}}) guide. To ensure you have registered or created your NGINX Instance, Config Sync Group, or Staged Config in the F5 NGINX One Console, follow the instructions in the [Manage your NGINX instances]({{}}) guide. {{< call-out "note" >}} The workflows for managing NGINX Configs for Instances, Config Sync Groups, and Staged Configs in the F5 NGINX One Console are quite similar. This guide focuses on the steps for updating NGINX Configs for Instances. If you're working with Config Sync Groups, you'll follow a similar process but will need to update the API endpoints appropriately. @@ -20,9 +20,10 @@ The workflows for managing NGINX Configs for Instances, Config Sync Groups, and ## Get the current NGINX configuration -You can retrieve the current NGINX Config for an Instance, Config Sync Group, or Staged Config using a `GET` request. This is useful for making updates based on the existing configuration. +You can retrieve the current NGINX configuration for an Instance, Config Sync Group, or Staged Config using a `GET` request. This is useful for making updates based on the existing configuration. Use the following `curl` command to retrieve the current NGINX configuration for a specific Instance. Replace ``, ``, ``, and `` with your actual values. + ```shell curl -X GET "https://.console.ves.volterra.io/api/nginx/one/namespaces//instances//config" \ -H "Authorization: APIToken " -o current_config.json @@ -30,11 +31,11 @@ Use the following `curl` command to retrieve the current NGINX configuration for - ``: Your tenant name for organization plans. - ``: The namespace your Instance belongs to. - - ``: The object_id of the NGINX Instance you want to retrieve the NGINX Config for. + - ``: The object_id of the NGINX Instance you want to retrieve the NGINX configuration for. - ``: Your API Token. {{< call-out "note" >}} -To update the NGINX Config for a Config Sync Group or Staged Config, replace `instances` with `config-sync-groups` or `staged-configs` and use the object_id of the Config Sync Group or Staged Config in the URL. +To update the NGINX configuration for a Config Sync Group or Staged Config, replace `instances` with `config-sync-groups` or `staged-configs` and use the object_id of the Config Sync Group or Staged Config in the URL. {{< /call-out>}} The response will include the current NGINX configuration in JSON format. This response is saved to a file (with a name like `current_config.json`) for editing. @@ -48,42 +49,47 @@ When updating the NGINX Config, file `contents` must be base64 encoded. You can ```shell base64 -w 0 -i ``` + This command reads the file at `` and outputs its base64 encoded content in a single line (due to the `-w 0` option). You can then copy this encoded string and include it in your JSON request body. On some systems the `-w` option may not be available, in which case you can use: + ```shell base64 -i | tr -d '\n' ``` -## Update the NGINX Config for an Instance using `PUT` +## Update the NGINX configuration for an Instance using `PUT` When using the `PUT` method, ensure that your request body includes all necessary contents, as it will overwrite the existing configuration. -The following example demonstrates how to update the NGINX Config for a specific Instance using `PUT`. Replace ``, ``, ``, and `` with your actual values. The request body should contain the complete NGINX Config in JSON format. +The following example demonstrates how to update the NGINX configuration for a specific Instance using `PUT`. Replace ``, ``, ``, and `` with your actual values. The request body should contain the complete NGINX configuration in JSON format. + ```shell curl -X PUT "https://.console.ves.volterra.io/api/nginx/one/namespaces//instances//config" \ -H "Authorization : APIToken " \ -H "Content-Type: application/json" \ -d @updated_config.json ``` + - ``: Your tenant name for organization plans. - ``: The namespace your Instance belongs to. - - ``: The object_id of the NGINX Instance you want to update the NGINX Config for. + - ``: The object_id of the NGINX Instance you want to update the NGINX configuration for. - ``: Your API Token. -## Update the NGINX Config for an Instance using `PATCH` +## Update the NGINX configuration for an Instance using `PATCH` When using the `PATCH` method, you only need to include the files you want to update in your request body. -The following example demonstrates how to update the NGINX Config for a specific Instance using `PATCH`. Replace ``, ``, ``, and `` with your actual values. The request body should contain only the fields you want to update in JSON format. +The following example demonstrates how to update the NGINX configuration for a specific Instance using `PATCH`. Replace ``, ``, ``, and `` with your actual values. The request body should contain only the fields you want to update in JSON format. ```shell curl -X PATCH "https://.console.ves.volterra.io/api/nginx/one/namespaces//instances//config" \ -H "Authorization : APIToken " \ -H "Content-Type: application/json" \ -d @partial_update_config.json ``` + - ``: Your tenant name for organization plans. - ``: The namespace your Instance belongs to. - - ``: The object_id of the NGINX Instance you want to update the NGINX Config for. + - ``: The object_id of the NGINX Instance you want to update the NGINX configuration for. - ``: Your API Token. -With `PATCH`, you can update specific parts of the NGINX Config without needing to resend the entire configuration. The following file `contents` disposition is observed: +With `PATCH`, you can update specific parts of the NGINX Instance configuration without needing to resend the entire configuration. The following file `contents` disposition is observed: - Leave out file `contents` to remove the file from the NGINX Config. - Include file `contents` to add or update the file in the NGINX Config. File `contents` must be base64 encoded. File `contents` can be an empty string to create an empty file. - `config_version` should be included to ensure you're updating the correct version of the configuration. You can get the current `config_version` from the response of the `GET` request. @@ -106,7 +112,8 @@ For example, to update only the `/etc/nginx/nginx.conf` file in the NGINX Config ] } ``` -To remove a file, simply omit the `contents` field for that file in your `PATCH` request body, your `partial_update_config.json` might look like this to remove `/etc/nginx/conf.d/default.conf` from the NGINX Config: + +To remove a file, omit the `contents` field for that file in your `PATCH` request body, your `partial_update_config.json` might look like this to remove `/etc/nginx/conf.d/default.conf` from the NGINX Instance configuration: ```json { "conf_path": "/etc/nginx/nginx.conf", @@ -123,9 +130,10 @@ To remove a file, simply omit the `contents` field for that file in your `PATCH` ] } ``` -## Set up multiple updates with PATCH -Multiple updates can be made in a single `PATCH` request. For example, to update `/etc/nginx/nginx.conf` and remove `/etc/nginx/conf.d/default.conf`, your `partial_update_config.json` might look like this: +## Set up multiple updates with `PATCH` + +You can make multiple updates can be made in a single `PATCH` request. For example, to update `/etc/nginx/nginx.conf` and remove `/etc/nginx/conf.d/default.conf`, your `partial_update_config.json` might look like this: ```json { "conf_path": "/etc/nginx/nginx.conf", From 8161c44326b50f32167e31609ed2daabc78b4efb Mon Sep 17 00:00:00 2001 From: Nick Chen <139289811+nginx-nickc@users.noreply.github.com> Date: Thu, 11 Sep 2025 10:42:36 -0700 Subject: [PATCH 7/8] Update nginx_configuration.md --- content/nginx-one/api/nginx_configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nginx-one/api/nginx_configuration.md b/content/nginx-one/api/nginx_configuration.md index c66306689..21cc88413 100644 --- a/content/nginx-one/api/nginx_configuration.md +++ b/content/nginx-one/api/nginx_configuration.md @@ -8,7 +8,7 @@ type: - how-to --- -In this guide, we'll show you how to use API requests to update NGINX Configurations for Instances or Config Sync Groups in the F5 NGINX One Console. +In this guide, we'll show you how to use API requests to update NGINX Configurations for Instances, Config Sync Groups, or Staged Configs in the F5 NGINX One Console. ## Get ready From 32cd460f332aeb1037ffbbca1f415d22c358b469 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Thu, 11 Sep 2025 11:52:51 -0700 Subject: [PATCH 8/8] Apply suggestion from @mjang --- content/nginx-one/api/nginx_configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nginx-one/api/nginx_configuration.md b/content/nginx-one/api/nginx_configuration.md index 21cc88413..166210be3 100644 --- a/content/nginx-one/api/nginx_configuration.md +++ b/content/nginx-one/api/nginx_configuration.md @@ -10,7 +10,7 @@ type: In this guide, we'll show you how to use API requests to update NGINX Configurations for Instances, Config Sync Groups, or Staged Configs in the F5 NGINX One Console. -## Get ready +## Before you begin Before you begin, make sure you can properly authenticate your API requests with either an API Token or API Certificate, following the instructions in the [Authentication]({{}}) guide. To ensure you have registered or created your NGINX Instance, Config Sync Group, or Staged Config in the F5 NGINX One Console, follow the instructions in the [Manage your NGINX instances]({{}}) guide.