Install NGINX Controller Agent

Overview

This page shows how to install, update, and uninstall the NGINX Controller Agent.

You can use the NGINX Controller Agent to monitor your systems with the NGINX Controller.

Objectives

  • Install the NGINX Controller Agent
  • Upgrade the NGINX Controller Agent to a newer version
  • Uninstall the NGINX Controller Agent

Install the NGINX Controller Agent

See Also:
If you want to run the NGINX Controller Agent as a non-root user, follow the alternative instructions in the Install NGINX Controller Agent for Non-root User guide instead of the steps provided in this section.

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 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.
  8. (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.

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

  10. 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.

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.

Uninstall the Analytics, Visibility, and Reporting Daemon (AVRD)

NGINX Controller uses an Analytics, Visibility, and Reporting daemon (AVRD) to aggregate and report app-centric metrics. These metrics can be used to track your apps and monitor their health.

If you want to remove AVRD from your dataplane instances, take the following steps to uninstall AVRD and its supporting modules. You must perform these steps on each of your dataplane instances.

  • Debian/Ubuntu

    sudo apt-get purge avrd avrd-metrics nginx-plus-module-metrics
    
  • RedHat/CentOS

    sudo yum remove avrd avrd-metrics nginx-plus-module-metrics
    

Uninstall the NGINX Controller Agent and 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.

What’s Next


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