End of Sale Notice:

F5 NGINX is announcing the End of Sale (EoS) for NGINX Controller API Management Module, effective January 1, 2024.

F5 maintains generous lifecycle policies that allow customers to continue support and receive product updates. Existing NGINX Controller API- Management customers can continue to use the product past the EoS date. License renewals are not available after September 30, 2024.

See our End of Sale announcement for more details.

End of Sale Notice:

F5 NGINX is announcing the End of Sale (EoS) for NGINX Controller Application Delivery Module, effective January 1, 2024.

F5 maintains generous lifecycle policies that allow customers to continue support and receive product updates. Existing NGINX Controller Application Delivery customers can continue to use the product past the EoS date. License renewals are not available after September 30, 2024.

See our End of Sale announcement for more details.

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.

   Important:
   Instances and the instance groups they belong to should specify the same location; however, this requirement is not currently enforced. If different locations are specified, the instance group’s location takes precedence. This is important to remember when assigning locations to workload groups.

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:

• Add an AWS NGINX Instance
• Add an Azure NGINX Instance

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

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 receive an NGINX configuration identical to those instances in the group. Instances in an instance group can be stand-alone or clustered NGINX Plus instances. Instances can also leave the group, with the remaining instances continuing to function as intended.

Important:

Workload affinity with instance groups: Similar to instances, instance groups are associated with a location. If a location is not explicitly specified, the unspecified location is assumed. Instances in an instance group should be configured to use the same location; however, this requirement is not currently enforced.

For the workload affinity feature, the location of the instance group must be specified using the optional locationRef field in the component’s workload group API request. The locations of the instances in the instance group are ignored. The workload affinity feature uses this information and the workload groups to load balance traffic to the correct endpoints.

Important:

Instance groups are supported on the following versions of NGINX Controller:

• NGINX Controller API Management module v3.18 and later
• NGINX Controller Application Delivery module v3.21 and later

Create an Instance Group

To add an instance group, 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 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. (Optional) Select the HA type for the instance group.
9. When ready, review the API Spec and then select Submit to create the instance group.

Edit or Delete an Instance Group

To edit or delete an instance group, 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 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.

Add or Remove Instances from an Instance Group

To add an existing instance to an instance group, take the following steps:

1. Make sure that no gateways are using the instance as a placement. Instances that are referenced by a gateway cannot be added to an instance group.
2. Delete the instance.
3. Add the instance back to NGINX Controller. Run the agent install script (Step 11).

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

• Configure the NGINX Controller Agent
• Set up Metrics Collection
• Create and Manage Locations for your Instances
• Create and Manage Instance Templates
• Add an AWS NGINX Instance
• Add an Azure NGINX Instance
• Add a VSphere NGINX Instance