Working with Instance Groups

Learn how to use NGINX Management Suite Instance Manager to create instance groups, which you can use to manage multiple NGINX instances as a single entity.

Overview

You can easily manage multiple NGINX instances as a single entity by creating an instance group in Instance Manager and adding NGINX instances to it.

Before You Begin

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

• An installed version of Instance Manager
• One or more NGINX data plane instances

Create Instance Groups

To create 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 navigation menu, select Instance Groups.

3. Select Create.

4. On the Create Instance Group form, complete the necessary fields:

   • Name: add a name for the instance group.
   • Display Name: add a friendly name to show for the instance group.
   • (Optional) Description: add a brief description for the instance group.

5. Select Save.

Note:
When an Instance Group is initially created via the UI/API, its NGINX config will be empty. Adding an Instance to the Instance Group will populated the Instance Group NGINX nginx with the first member’s NGINX config.

Add Instances to Instance Groups

You can assign NGINX instances to instance groups in the following ways:

• (Preferred) Edit the agent-dynamic.conf file on an NGINX instance and specify the instance group.
• Alternatively, when installing the NGINX Agent, you can specify the instance group as a command-line option.

• agent-dynamic.conf
• Command-Line Option

Update Instance Groups

To edit the display name or description for 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. Locate the instance group you want to update. Select the Actions menu (represented by an ellipsis, ...), then select Edit.

Delete Instance Groups

To delete an instance group in the web interface, perform the following:

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. Locate the instance group you want to delete. Select the Actions menu (represented by an ellipsis, ...), then select Delete.

If the instance group you deleted was specified in the agent-dynamic.conf file of an instance, you’ll need to remove the reference. Otherwise, upon restarting the NGINX Agent, the instance group will be recreated.

1. Open a secure shell (SSH) connection to the NGINX instance and log in.

2. Open the /var/lib/nginx-agent/agent-dynamic.conf for editing.

3. Locate and remove or comment out the instance_group: <group name> setting, similar to the following example:

   Example:

   #
   # /var/lib/nginx-agent/agent-dynamic.conf
   #
   # Dynamic configuration file for NGINX Agent.
   #
   # The purpose of this file is to track agent configuration
   # values that can be dynamically changed via the API and the agent install script.
   # You may edit this file, but API calls that modify the tags on this system will
   # overwrite the tag values in this file.
   #
   # The agent configuration values that API calls can modify are as follows:
   #    - tags
   #
   # The agent configuration values that the agent install script can modify are as follows:
   #    - instance_group
   
   # instance_group: default
   

4. Save the changes and exit the editor.

5. Restart the NGINX Agent:

   sudo systemctl restart nginx-agent
   

Permission for Instance Groups

See Set Up RBAC, for detail information on setting up role-based access control (RBAC) for Instance Groups.

Note:
Members of Instance Group automatically inherit role-based access control (RBAC) permissions from their parent.

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.

• POST
• GET

{
    "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"
}

{
  "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"
      }
    ]
  }
}

Additional Information Regarding Instance Groups

When updating Instance Group NGINX config using the UI or API, only the currently “online” members of Instance Group will be affected. Newly registered Instance or reconnected Instance should get NGINX config updated automatically to the last “successful” published NGINX config.

A NGINX config update to Instance Group is considered “successful” with one of the following conditions:

• Instance Group does not have a member Instance online
• Any Instance Group member reported “successful” to the NGINX config update

Note:
Check the Instance details page for the last NGINX config publish status.

Common Usage of Instance Groups

Instance Groups can be used for the following workflows:

• Preset NGINX config for new Instances, i.e. containerized Instances
• Group permissions for a set of Instances that share the same NGINX config