Manage Your NGINX Instances

Use the Instance Overview page to view and manage your NGINX Instances

Overview

The Infrastructure > Instances > Overview page allows you to check the status of all your NGINX instances at a glance.

When the Controller Agent is installed on a new system and the system registers with NGINX Controller, the instance is visible on the Instances overview page.

Objective

  • Add an NGINX instance
  • View the number, location, type, and status of all instances registered with NGINX Controller
  • View monitoring graphs for instances
  • Delete an instance
  • Update the NGINX Controller Agent

Create an Instance

Take the following steps to add an instance to NGINX Controller:

  1. Open the NGINX Controller user interface and log in.

  2. Select the NGINX Controller menu icon, then select Infrastructure.

  3. On the Infrastructure menu, select Instances > Overview.

  4. On the Instances overview page, select Create.

  5. On the Create Instance page, select Add an existing instance.

  6. Add a name for the instance. If you don’t provide a name, the hostname of the instance is used by default.

  7. To add the instance to an existing Instance Group, select an Instance Group from the list. Or to create an Instance Group, select Create New.

  8. To add the instance to an existing Location, select a Location from the list. Or to create a Location, select Create New.

    Important:
    Once set, the Location for an instance cannot be changed. If you need to change or remove the Location for an instance, you must remove the instance from NGINX Controller, and then add it back.
  9. (Optional) By default, registration of NGINX Plus instances is performed over a secure connection. To use self-signed certificates with the Controller Agent, select Allow insecure server connections to NGINX Controller using TLS. For security purposes, we recommend that you secure the Controller Agent with signed certificates when possible.

  10. Use SSH to connect and log in to the NGINX instance that you want to connect to NGINX Controller.

  11. Run the curl or wget command that’s shown in the Installation Instructions section on the NGINX instance to download and install the Controller Agent package. When specified, the -i and -l options for the install.sh script refer to the instance name and Location, respectively.

    Note:

    Make sure you enter the commands to download and run the install.sh script on the NGINX Plus system, and not on the NGINX Controller.

    NGINX Controller 3.6 and earlier require Python 2.6 or 2.7. You’ll be prompted to install Python if it’s not installed already. Python is not required for NGINX Controller v3.7 and later.

After a few minutes, the NGINX instance will appear on the Instances overview page.

Create an Instance Using a Template

An Instance Template defines the parameters to use when creating a data plane instance. Instance Templates are ideal for cloud orchestration and make managing your cloud resources easy and quick.

See Also:

For steps on how to deploy NGINX instances on Amazon Web Services or Microsoft Azure, see the following tutorials:

Take the following steps to create an instance using an Instance Template:

  1. Open the NGINX Controller user interface and log in.
  2. Select the NGINX Controller menu icon, then select Infrastructure.
  3. On the Infrastructure menu, select Instances.
  4. On the Instances overview page, select Create.
  5. Select Create a new instance using a template.
  6. Add a name.
  7. Select a Location in the list, or select Create New to create a location.
  8. Select an Instance Template in the list, or select Create New to create an instance template.
  9. Select Submit.

View or Edit an Instance

Take the following steps to view an instance’s details or to edit an instance:

  1. Open the NGINX Controller user interface and log in.
  2. Select the NGINX Controller menu icon, then select Infrastructure.
  3. On the Infrastructure menu, select Instances > Overview.
  4. To view the configuration details for an instance select the radio button next to the instance name. This opens a side panel where you can see the instance’s status, properties, and resource details.
  5. To view the monitoring graphs for an instance – including bytes in/out and CPU and memory usage – select the instance name link.
  6. To edit an instance, select the radio button next to the instance name, then select the edit (pencil) icon.

Delete an Instance

Take the following steps to uninstall the Controller Agent and delete an instance.

Important:
Be sure to uninstall the Controller Agent first, before you delete an instance. If you don’t uninstall the Controller Agent first, the instance may reappear in NGINX Controller after it has been deleted.
  1. On your NGINX Plus instance, stop the Controller Agent service:

    • On Ubuntu/Debian:

      service controller-agent stop
      
    • On CentOS/Red Hat Enterprise Linux:

      systemctl stop controller-agent
      
  2. Run the appropriate command for your distribution to uninstall the Controller Agent:

    • On Ubuntu/Debian:

      apt-get purge nginx-controller-agent
      
    • On CentOS/Red Hat Enterprise Linux:

      yum remove nginx-controller-agent
      

      After the package is removed, you can safely delete the files in /etc/controller-agent/ and /var/log/nginx-controller/.

  3. (Optional) If you use SELinux on CentOS or Red Hat Enterprise Linux, take the following steps to remove the SELinux policy that was created when the Controller Agent was installed:

    1. Revert the installed permissions:

      sudo semodule -r nginx
      
    2. Remove the following files:

      • nginx.te
      • nginx.mod
      • nginx.pp
  4. Delete the NGINX Plus instance from the NGINX Controller user interface:

    1. Open the NGINX Controller user interface and log in.

    2. Select the NGINX Controller menu icon, then select Infrastructure.

    3. On the Infrastructure menu, select Instances > Overview.

    4. On the Instances overview page, select the NGINX Plus instance that you want to delete.

    5. Select the delete icon (trash can).

  5. Delete alerts:

    Note:
    When you delete an instance, any related alerts for that instance are not deleted automatically. You can delete the alerts manually, however.
    1. Open the NGINX Controller user interface and log in.
    2. On the Analytics menu, select Alerts > Alert Rules.
    3. Select the alert rule that you want to delete.
    4. Select the delete (trash can) icon to delete the alert rule.
    5. Select Delete in the pop-up box to confirm that you want to proceed.

Instance Groups

Important:
Instance Groups are supported on the NGINX Controller API Management module beginning with version 3.18-APIM. Instance Groups are not supported on the NGINX Controller Application Delivery module.

An Instance Group is a logically grouped set of instances that can be used as a placement for a Gateway, rather than a single instance. This concept supports the ability to scale horizontally without having to update the Gateway placement. As Instances are added to a Group, they will receive an NGINX configuration that is identical to the other Instances in that Group. Instances added to an Instance Group can either be stand-alone or clustered NGINX Plus instances. Instances can also leave the group, with the remaining instances in the Group continuing to function as intended.

Create an Instance Group

  1. Open the NGINX Controller user interface and log in.
  2. Select the NGINX Controller menu icon, then select Infrastructure.
  3. On the Infrastructure menu, select Instance Groups > Overview.
  4. On the Instance Groups overview page, select Create Instance Group.
  5. Add a name for the instance group.
  6. (Optional) Provide a display name.
  7. (Optional) Provide a description.
  8. When ready, review the API Spec and then select Submit to create the Instance Group.

Edit or Delete an Instance Group

  1. Open the NGINX Controller user interface and log in.
  2. Select the NGINX Controller menu icon, then select Infrastructure.
  3. On the Infrastructure menu, select Instance Groups > Overview.
  4. Select the Instance Group that you want to modify or delete.
  5. To edit the Instance Group, select Edit Config on the Quick Actions menu.
  6. To delete the Instance Group, select Delete Config on the Quick Actions menu.

Update the NGINX Controller Agent

When you update NGINX Controller, you also need to update the NGINX Controller Agent software on each monitored NGINX Plus instance.

To update the NGINX Controller Agent, take the following steps:

  1. Open the NGINX Controller user interface and log in.

  2. Select the NGINX Controller menu icon, then select Infrastructure.

  3. On the Infrastructure menu, select Instances > Overview.

  4. On the Instances overview page, select Create.

  5. Follow the instructions in the Install Instructions pane to connect to the NGINX instance and install the updated Controller Agent package.

    Note:
    NGINX Controller 3.6 and earlier require Python 2.6 or 2.7. You’ll be prompted to install Python if it’s not installed already. Python is not required for NGINX Controller 3.7 and later.

Troubleshooting

If an Instance is in a Failed state, the Controller Agent or NGINX service may not be running.

Take the following steps to troubleshoot the issue:

  1. Open an SSH connection to the failed Instance.

  2. Check the status of the Controller Agent service:

    sudo systemctl status controller-agent.service
    

    If the Controller Agent service isn’t running, you can start the service by running the following command:

    sudo systemctl start controller-agent.service
    
  3. Check the status of the NGINX service:

    sudo systemctl status nginx.service
    

    If the NGINX service isn’t running, you can start the service by running the following command:

    sudo systemctl start nginx.service
    
  4. If neither of these steps resolves the issue, inspect the following log files for errors:

    • /var/log/nginx-controller/agent.log
    • /var/log/nginx/error.log

What’s Next

​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ ​

This documentation applies to the following versions of NGINX Controller: 3.0, 3.1, 3.2, 3.3, 3.3, 3.4, 3.5, 3.6, 3.7, 3.8, 3.9, 3.10, 3.12, 3.13, 3.14, 3.15, 3.16.1, 3.17 and 3.18.