Publish NGINX Configs

Learn how to edit and publish NGINX configuration files using NGINX Management Suite Instance Manager.

Overview

With Instance Manager, you can easily edit and publish NGINX configurations to your NGINX and NGINX Plus instances. As you edit your configurations, the NGINX config analyzer will automatically detect and highlight errors, ensuring accuracy and reliability.

Before You Begin

To complete the instructions in this guide, you need the following:

  • Instance Manager is installed, licensed, and running
  • One or more NGINX data plane instances

Publishing to Instances

Publish Config Changes to Instances

To edit an instance’s configuration and publish the changes, follow these steps:

  1. In a web browser, go to the FQDN for your NGINX Management Suite host and log in. Then, select Instance Manager from the Launchpad menu.

  2. On the left menu, select Instances.
  3. Choose the instance from the list that you want to publish a configuration to.
  4. Select Edit Config.
  5. Edit the configuration files to make your desired changes. The config analyzer will let you know if there are any errors.
  6. Select Publish to apply the changes and publish them to the instance.

Publish Configs with Hash Versioning (API Only)

With the Instance Manager REST API, you can add a commit hash to NGINX configurations if you use version control, such as Git. This will allow you to retrieve a configuration with a unique version identifier.

See Also:
You can use tools such as curl or Postman to interact with the Instance Manager REST API. The API URL follows the format https://<NMS_FQDN>/api/[nim|platform]/<API_VERSION> and must include authentication information with each call. For more information about authentication options, please refer to the API Overview.


To add a commit hash to a new or existing config using the REST API, send an HTTP POST or PUT request to the Configs endpoint.

Method Endpoint
POST or PUT /systems/{systems_uid}/instances/{instance_uid}/config

The following table lists the parameters to include when adding version control identifiers to a config:

Field Type Possible Values
Description
 Required Default value
externalID string

Commit hash, 1–150 characters

For example, 521747298a3790fde1710f3aa2d03b55020575aa.

The commit hash.

 No null
externalIdType string git,
other

The type of commit that was used for the config update.

If the externalID isn’t specified, the externalIdType reverts automatically to other.

 No other

JSON request 
{
    "auxFiles": {
        "files": [],
        "rootDir": "/"
    },
    "configFiles": {
        "rootDir": "/etc/nginx",
        "files": [
        {
            "contents": "dXNlciB3d3ctZGF0YTsNCndvcmtlcl9wcm9jZXNzZXMgYXV0bzsNCnBpZCAvcnVuL25naW54LnBpZDsNCmluY2x1ZGUgL2V0Yy9uZ2lueC9tb2R1bGVzLWVuYWJsZWQvKi5jb25mOw0KIA0KZXZlbnRzIHsNCgl3b3JrZXJfY29ubmVjdGlvbnMgNzY4Ow0KCSMgbXVsdGlfYWNjZXB0IG9uOw0KfQ0KDQojIG5ldyBjb25maWcNCmh0dHAgew0KDQoJIyMNCgkjIEJhc2ljIFNldHRpbmdzDQoJIyMNCg0KCXNlbmRmaWxlIG9uOw0KCXRjcF9ub3",
            "name": "/etc/nginx/nginx.conf"
        }
        ]
    },
    "updateTime": "2023-02-22T17:10:02.677Z",
    "externalId": "8acf5aed9d2872b266d2f880cab23a4aa5791d1b",
    "externalIdType": "git"
}

This JSON defines an NGINX configuration. It specifies the root directory for auxiliary and configuration files, as well as a list of configuration files with their contents and name; the file contents are base64 encoded. Additionally, it specifies an external ID and type as version control identifiers, as well as an update time.

Important:
If you edit an NGINX configuration in the Instance Manager web interface or directly on the data plane, the previous hashed commit information will lost: the externalID will revert to null and externalIdType will revert to other automatically. The same result will occur if you don’t specify the externalId when making updates using the REST API.

To view the latest version of a configuration, send an HTTP GET request to the Systems endpoint.

Method Endpoint
GET /systems/{systems_uid}/instances/{instance_uid}

To view a specific configuration with a version-controlled hash, send an HTTP GET request to the Configs endpoint and specify the externalID.

Method Endpoint
GET /systems/{systems_uid}/instances/{instance_uid}/config?externalId=
JSON response 
{
  "build": {
    "nginxPlus": true,
    "release": "nginx-plus-r28",
    "version": "1.23.2"
  },
  "configPath": "/etc/nginx/nginx.conf",
  "configVersion": {
    "instanceGroup": {
      "createTime": "0001-01-01T00:00:00Z",
      "uid": "",
      "versionHash": ""
    },
    "versions": [
      {
        "createTime": "2023-02-28T19:54:58.735Z",
        "externalId": "8acf5aed9d2872b266d2f880cab23a4aa5791d1b",
        "externalIdType": "git",
        "uid": "92a9dbfa-dc6a-5bf9-87dd-19405db0b9c0",
        "versionHash": "c0f7abbd9b9060c75985b943f3ec0cfc7e4b28cbf50c26bfd0b2141bb6c277a3"
      }
    ]
  }
}

Publishing to Instance Groups

Publish Config Changes to Instance Groups

To publish a configuration file to an instance group:

  1. In a web browser, go to the FQDN for your NGINX Management Suite host and log in. Then, select Instance Manager from the Launchpad menu.

  2. On the left menu, select Instance Groups.

  3. Select the instance group you want to publish the configuration to.

  4. To add a new config:

    1. Select Add File.
    2. Add the path and filename of the new file.
    3. Select Create.
    4. On the file editor page, type or paste the contents to use for the file. The config analyzer will let you know if there are any errors.

  5. To update an existing config:

    1. Edit the configuration files to make your desired changes. The config analyzer will let you know if there are any errors.

  6. Select Publish to apply the changes and publish them to the instance.

  7. (Optional) To save the file as a staged config, select Save as, then provide a name for the staged config.

Publish Configs with Hash Versioning (API Only)

With the Instance Manager REST API, you can add a commit hash to NGINX configurations if you use version control, such as Git. This will allow you to retrieve a configuration with a unique version identifier.

See Also:
You can use tools such as curl or Postman to interact with the Instance Manager REST API. The API URL follows the format https://<NMS_FQDN>/api/[nim|platform]/<API_VERSION> and must include authentication information with each call. For more information about authentication options, please refer to the API Overview.


To add a commit hash to a new or existing config using the REST API, send an HTTP POST or PUT request to the Configs endpoint.

Method Endpoint
POST or PUT /instance-groups/{instanceGroupUID}/config

The following table lists the parameters to include when adding version control identifiers to a config:

Field Type Possible Values
Description
 Required Default value
externalID string

Commit hash, 1–150 characters

For example, 521747298a3790fde1710f3aa2d03b55020575aa.

The commit hash.

 No null
externalIdType string git,
other

The type of commit that was used for the config update.

If the externalID isn’t specified, the externalIdType reverts automatically to other.

 No other

JSON request 
{
    "auxFiles": {
        "files": [],
        "rootDir": "/"
    },
    "configFiles": {
        "rootDir": "/etc/nginx",
        "files": [
        {
            "contents": "dXNlciB3d3ctZGF0YTsNCndvcmtlcl9wcm9jZXNzZXMgYXV0bzsNCnBpZCAvcnVuL25naW54LnBpZDsNCmluY2x1ZGUgL2V0Yy9uZ2lueC9tb2R1bGVzLWVuYWJsZWQvKi5jb25mOw0KIA0KZXZlbnRzIHsNCgl3b3JrZXJfY29ubmVjdGlvbnMgNzY4Ow0KCSMgbXVsdGlfYWNjZXB0IG9uOw0KfQ0KDQojIG5ldyBjb25maWcNCmh0dHAgew0KDQoJIyMNCgkjIEJhc2ljIFNldHRpbmdzDQoJIyMNCg0KCXNlbmRmaWxlIG9uOw0KCXRjcF9ub3",
            "name": "/etc/nginx/nginx.conf"
        }
        ]
    },
    "updateTime": "2023-02-22T17:10:02.677Z",
    "externalId": "8acf5aed9d2872b266d2f880cab23a4aa5791d1b",
    "externalIdType": "git"
}

This JSON defines an NGINX configuration. It specifies the root directory for auxiliary and configuration files, as well as a list of configuration files with their contents and name; the file contents are base64 encoded. Additionally, it specifies an external ID and type as version control identifiers, as well as an update time.

Important:
If you edit an NGINX configuration in the Instance Manager web interface or directly on the data plane, the previous hashed commit information will lost: the externalID will revert to null and externalIdType will revert to other automatically. The same result will occur if you don’t specify the externalId when making updates using the REST API.

To view an instance group’s config, send an HTTP GET request to the Instance Groups endpoint.

Method Endpoint
GET /instance-groups/{instanceGroupUID}

To view an instance group’s config with a version-controlled hash, send an HTTP GET request to the Instance Groups endpoint and specify the externalID.

Method Endpoint
GET /instance-groups/{instanceGroupUID}/config?externalId={commit_hash}
JSON response 
{
  "build": {
    "nginxPlus": true,
    "release": "nginx-plus-r28",
    "version": "1.23.2"
  },
  "configPath": "/etc/nginx/nginx.conf",
  "configVersion": {
    "instanceGroup": {
      "createTime": "0001-01-01T00:00:00Z",
      "uid": "",
      "versionHash": ""
    },
    "versions": [
      {
        "createTime": "2023-02-28T19:54:58.735Z",
        "externalId": "8acf5aed9d2872b266d2f880cab23a4aa5791d1b",
        "externalIdType": "git",
        "uid": "92a9dbfa-dc6a-5bf9-87dd-19405db0b9c0",
        "versionHash": "c0f7abbd9b9060c75985b943f3ec0cfc7e4b28cbf50c26bfd0b2141bb6c277a3"
      }
    ]
  }
}

Publishing Staged Configs

See Also:
To learn how to add and make changes to staged configuration files, please refer to the Stage Configuration Files topic.

To publish a staged configuration to an NGINX instance or instance group:

  1. In a web browser, go to the FQDN for your NGINX Management Suite host and log in. Then, select Instance Manager from the Launchpad menu.

  2. On the left menu, select Staged Configs.
  3. From the list of staged configs, select the one you want to publish.
  4. Select Publish to.
  5. Select the NGINX instance or instance group to publish the staged config to.
  6. Select Publish.