Configure Instances with Instance Groups

Follow the steps in this guide to create instance groups for instances, which you can manage as a single entity.

Overview

With instance groups, you can logically combine instances as a single entity that shares the same configuration. When you update and publish the shared configuration, it’s pushed to the grouped instances simultaneously.

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

How to Access the Web Interface

This guide contains instructions for completing tasks by using the Instance Manager web interface.

To access the web interface, go to the FQDN for your NGINX Management Suite host and log in. Then, select “Instance Manager” on the Launchpad menu.

How to Access the REST API

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/<API_VERSION>.

Note:
When making API calls by using curl, Postman, or any other tool, you need to provide your authentication information with each call. Refer to the API Overview topic for more information about authentication options.

Create Instance Groups

To create an instance group using the web interface, take the following steps:

  1. Open the NGINX Management Suite web interface and log in.

  2. Select Modules > Instance Manager.

  3. In the left navigation menu, select Instance Groups.

  4. Select Create.

  5. Complete the Create Instance Group form:

    • Name: add a name to use 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.
  6. Select Save.

To create an instance group (for example, nginx-01) using the Instance Manager API, send a POST request similar to the following example to the Instance Groups endpoint:

curl -X 'POST' \
'https:///<NMS_FQDN>/api/platform/v1/instance-groups' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"description": "myInstanceGroup",
"displayName": "This is my instance group",
"name": "nginx-01"
}'
Parameter Type Description
description string A brief description for the instance group.
displayName string A friendly name to show for the instance group.
name string

The name to use for the instance group.

The name cannot include URL encoding, spaces, or any of the following characters: ` “ [] {} ; * / \ ? : = & ~ ^ | # % ! $ <>


Add Instances to Instance Groups

Add Instances to Instance Groups when Installing NGINX Agent

You can add an instance to a new or existing instance group when installing the NGINX Agent by including the --instance-group <name> option.

sudo sh install.sh --instance-group <name>
Option Short Option Value
--instance_group -g The name to use for the instance group. For example, nginx-01.
Important:
If the specified instance group doesn’t already exist, the NGINX Agent installer will create it. When creating the group, the installer will use the current instance’s config file as the config file for the group. Instances added to the group after the group has been created will use this config. As a precaution, if you’re using a script to add instances to an instance group, you should give thought to which instance you run the script on first.

Example

The following example adds an instance to the instance group called nginx-01.

sudo sh install.sh --instance-group nginx-01

Add Instances to a Default Instance Group by Editing agent-dynamic.conf

You can add instances to a default instance group by editing the /etc/nginx-agent/agent-dynamic.conf file on the NGINX Management Suite host (that is, where you installed Instance Manager). Then, when you install the NGINX Agent on an instance, the instance is added to this default group.

Note:
You can override using the default group by using the --instance_group <name> option when installing the NGINX Agent on an instance. Select the Agent Install tab at the top of this section for instructions.
  1. Open the /etc/nginx-agent/agent-dynamic.conf for editing.

  2. Add a value for instance_group: <default name>.

    Example:

    #
    # /etc/nginx-agent/dynamic-agent.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
    
  3. Save the changes and exit the editor.


Interacting with Instance Groups

Publish Configuration File

To publish a configuration file to instances in the instance group, take the following steps:

  1. Open the NGINX Management Suite web interface and log in.
  2. Select Modules > Instance Manager.
  3. In the left navigation menu, select Instance Groups.
  4. On the Instance Groups Overview page, select the instance group’s name in the list, for which you want to add the configuration file.
  5. Select Add File.
  6. Add the path and filename of the new file.
  7. Select Create.
  8. On the file editor page, type or paste the contents to use for the file.
  9. To publish the file to all of the instances in the group, select Publish.
  10. To save the file as a staged config, select Save as, then provide a name for the staged config.

View, Edit, and Delete Instance Groups

To view the list of instance groups, take the following steps:

  1. Open the NGINX Management Suite web interface and log in.
  2. Select Modules > Instance Manager.
  3. In the left navigation menu, select Instance Groups.

To edit the display name or description for an instance group, continue with the following steps:

  1. On the Instance Groups Overview page, locate the instance group you want to update.
  2. Under the Actions column, select the ellipsis icon (…) > Edit.

To delete an instance group, perform the following:

  1. On the Instance Groups Overview page, locate the instance group you want to delete.
  2. Under the Actions column, select the ellipsis icon (…) > Delete.

See Also:
Refer to the NIM and Platform API reference guide at https://<NMS_FQDN>/ui/docs for descriptions of the following endpoints and parameters, along with example requests and responses.

Publish Configuration File

  • To publish a configuration file to instances in the instance group, send a POST request similar to the following example to the Instance Groups endpoint:

    POST /instance-groups/{instGroupUid}/config

    {
    "auxFiles": {
        "files": [
        {
            "contents": "IyBmaWxlIGNvbnRlbnQ=",
            "name": "/etc/nginx/aux/somefile.1"
        }
        ],
        "rootDir": "/etc/nginx/aux"
    },
    "configFiles": {
        "files": [
        {
            "contents": "ZXZlbnRzIHt9Cmh0dHAgeyAgCiAgICBzZXJ2ZXIgeyAgCiAgICAgICAgbGlzdGVuIDgwOyAgCiAgICAgICAgc2VydmVyX25hbWUgXzsKCiAgICAgICAgcmV0dXJuIDIwMCAiSGVsbG8iOyAgCiAgICB9ICAKfQ==",
            "name": "/etc/nginx/nginx.conf"
        }
        ],
        "rootDir": "/etc/nginx"
    },
    "ignoreConflict": true,
    "updateTime": "2022-06-13T21:33:43.453Z",
    "validateConfig": true
    }
    
    Note:
    The aux and config file contents need to be base-64 encoded.

Get List of Instance Groups

  • To get a list of all the instance groups, send a GET request similar to the following example to the Instance Groups endpoint:

    curl -X 'GET' \
    'https://<NMS_FQDN>/api/platform/v1/instance-groups' \
    -H 'accept: application/json'
    

Get List of Instances in Instance Group

  • To get a list of the instances in an instance group, send a GET request similar to the following example to the Instance Groups endpoint:

    curl -X 'GET' \
    'https://<NMS_FQDN>/api/platform/v1/instance-groups/{instanceGroupID}' \
    -H 'accept: application/json'
    

Delete an Instance Group

  • To delete an instance group, send a DELETE request similar to the following example to the Instance Groups endpoint

    curl -X 'DELETE' \
    'https://<NMS_FQDN>/api/platform/v1/instance-groups/{instanceGroupID}' \
    -H 'accept: */*'