Trial NGINX Controller with NGINX Plus

Overview

This quick-start tutorial shows you how to get started using NGINX Controller with NGINX Plus.

Important:
In this tutorial, NGINX Controller will install an embedded, self-hosted PostgreSQL database suitable for demo and trial purposes only. These instructions are not meant for production environments, which require you to provide your own PostgreSQL database.

Technical Requirements

Make sure to review the NGINX Controller Technical Specifications Guide for the requirements for your distribution and desired configuration.

Supported Distributions

NGINX Controller and the NGINX Controller Agent support the following distributions and architectures:

Distribution Version Architecture(s) NGINX Controller
(Control Plane)
Controller Agent
(Data Plane)
Notes
Amazon Linux 2 x86_64   v3.0+  
Amazon Linux 2017.09+ x86_64   v3.0+  
CentOS 6.0 (6.5+) i386
x86_64
  v3.0+ • This distribution does not support AVRD.
CentOS 7.0 (7.4+) x86_64 v3.0+ v3.0+  
Debian 8 i386
x86_64
  v3.0+ • This distribution does not support AVRD.
Debian 9 i386
x86_64
v3.0+ v3.0+ • Only the NGINX Controller Agent supports the i386 architecture.
Red Hat Enterprise Linux 6.0 (6.5+) i386
x86_64
  v3.0+  
Red Hat Enterprise Linux 7.0 (7.4+) x86_64 v3.5+ v3.5+ • SELinux may interfere with NGINX Controller installation and operation. If you do enable SELinux, it must use permissive mode. Use of enforcing mode is not supported.
Ubuntu 16.04 LTS i386
x86_64
v3.0+ v3.0+ • Only the NGINX Controller Agent supports the i386 architecture.
Ubuntu 18.04 LTS x86_64 v3.0+ v3.0+  
Ubuntu 20.04 LTS x86_64   v3.11+  

Analytics, Visibility, and Reporting Daemon (AVRD)

NGINX Controller v3.1 and later use an Analytics, Visibility, and Reporting daemon (AVRD) to aggregate and report app-centric metrics, which you can use to track and check the health of your apps. To learn more about these metrics, see the NGINX Metrics Catalog topic.

Hardware Specs

NGINX Controller v3 requires the following minimum hardware specifications:

  • RAM: 8 GB RAM
  • CPU: 8-Core CPU @ 2.40 GHz or similar
  • Disk space: 80 GB free disk space

Supported NGINX Plus Versions

NGINX Controller supports the following NGINX Plus versions:

  • NGINX Plus R22
  • NGINX Plus R21
  • NGINX Plus R20
  • NGINX Plus R19

Sign Up for a Trial License

First, you need to sign up for trial licenses for NGINX Controller and NGINX Plus, if you haven’t already done so. To do this, follow these links and complete the short questionnaires:

Install NGINX Controller

Prerequisites

Before installing NGINX Controller, ensure you have the following prerequisites:

  • Your NGINX Controller trial Association Token. You can find this in the MyF5 Customer Portal.

  • Required Linux utilities: These utilities are required by the installation script. The script will prompt you to install any missing utilities.

    • awk
    • bash (4.0 or later)
    • coreutils: base64, basename, cat, comm, dirname, head, id, mkdir, numfmt, sort, tee
    • curl or wget
    • envsubst (provided by the gettext package)
    • getent
    • grep
    • gunzip (provided by the gzip package)
    • jq (1.5 or later)
    • less
    • openssl
    • sed
    • tar
    • yum-plugin-versionlock on RedHat/CentOS
  • Required utilities to support Docker:

    The following system packages are required for Docker. The NGINX Controller installation script will let you know if any are missing:

    • Debian/Ubuntu: util-linux, coreutils, iproute2, iptables, socat, ebtables, ethtool, conntrack

      sudo apt-get install util-linux coreutils iproute2 iptables socat ebtables ethtool conntrack
      
    • RedHat/CentOS: util-linux, coreutils, iproute2, iptables, socat, ebtables, ethtool, conntrack

      sudo yum install util-linux coreutils iproute2 iptables socat ebtables ethtool conntrack
      

Steps

Take the following steps to install NGINX Controller:

  1. Download the NGINX Controller installer package from the MyF5 Customer Portal.

  2. Extract the installer package files:

    tar xzf controller-installer-<version>.tar.gz
    
  3. Run the installation script:

    cd controller-installer
    ./install.sh -n
    
    Important:
    The -n option creates an internal database for NGINX Controller. Upgrades are not supported for -n installations. For production installations, you’ll need to provide your own PostgreSQL database. See the NGINX Controller Installation Guide for details.

    The installation script walks through a series of steps and prompts for the following input:

    • Analytics database volume type: This determines the type of volume that will be used to store the analytics database. We recommend choosing local for demo and trial purposes.

      See Also:
      Refer to the NGINX Controller Technical Specifications Guide for more information about storage options.
    • EULA: Read the end-user license agreement. Type either y to accept or n to exit.

    • SMTP

      • SMTP Host: Provide the host name or IP address of an SMTP server.

        This is used to send password recovery emails. For trial purposes, if you don’t need to receive these communications, you can enter a value of “example.com” or something similar.

      • SMTP Port: The port of the SMTP server.

      • SMTP Authentication: Select y or n to authenticate when connecting to the SMTP server.

      • Use TLS for SMTP Communication: Select y or n to use SSL for SMTP server connections.

      • Do not reply email address: The sender’s email address. For example, [email protected].

    • Admin

      • First name: The first name for the initial admin user.
      • Last name: The last name for the initial admin user.
      • Email address: The contact email address for the initial admin user.
      • Password: The initial admin’s password. Passwords must be 6-64 characters long and must include letters and digits.
    • FQDN: Fully qualified domain name (FQDN) – a resolvable domain name for the NGINX Controller server. You can use the FQDN to access the NGINX Controller web interface. Additionally, the FQDN is used by Controller Agents when connecting to NGINX Controller.

    • SSL/TLS certificates: Type y to generate and use self-signed certs for running NGINX Controller over HTTPS, or type n to provide your own certs.

      Important:
      If you provide your own SSL/TLS certificates, you’ll need a complete certificate chain file, with the intermediate CA cert appended to the server cert; the server certificate must appear before the chained certificates in the combined file.
  4. Once NGINX Controller is installed, you may safely delete the installer package that you downloaded and extracted.

License NGINX Controller

To add a license to NGINX Controller, take the following steps:

  1. Go to https://<Controller-FQDN>/platform/license and log in.

  2. In the Upload a license section, select an upload option:

    • Upload license file – Locate and select your license file in the file explorer.
    • Paste your Association Token or license file – Paste your customer Association Token or the contents of your NGINX Controller license file. These are available on the MyF5 Customer Portal.
  3. Select Save license.

See Also:
To add a license using the NGINX Controller API, send a PUT request to the /platform/license endpoint. Provide your CAT or NGINX Controller license as a base64-encoded string in the JSON request body.

Install NGINX Plus

Prerequisites

  • Make sure to review the NGINX Plus Technical Specifications Guide for the requirements for your distribution and desired configuration.
  • You’ll need the NGINX Plus certificate and public key files (nginx-repo.crt and nginx-repo.key) that were provided when you signed up for the trial license. If you don’t have these files, you can use the NGINX Controller REST API to download them.

How to Download the NGINX Plus Cert and Key using the NGINX Controller API

The NGINX Controller API uses session cookies to authenticate requests. The session cookie is returned in response to a GET /api/v1/platform/login request. See the Login endpoint in the API Reference documentation for information about session cookie timeouts and invalidation.

Tip:
You can send a GET request to the login endpoint to find the status of the session token.

For example:

  • Login and capture the session cookie:

    curl -c cookie.txt -X POST --url 'https://198.51.100.10/api/v1/platform/login' --header 'Content-Type: application/json' --data '{"credentials": {"type": "BASIC","username": "[email protected]","password": "Towel$123"}}'
    
  • Use the session cookie to authenticate and get the session status:

    curl -b cookie.txt -c cookie.txt -X GET --url 'https://198.51.100.10/api/v1/platform/login'
    

To use the NGINX Controller REST API to download your NGINX Plus certificate and key bundle as a gzip or JSON file, send a GET request to the /platform/licenses/nginx-plus-licenses/controller-provided endpoint.

For example:

curl -b cookie.txt -c cookie.txt -X GET --url 'https://192.0.2.0
/api/v1/platform/licenses/nginx-plus-licenses/controller-provided' --output nginx-plus-certs.gz

Steps

To install NGINX Plus, follow the instructions in the NGINX Plus Installation Guide. See the relevant section for your distribution.

Add an NGINX Plus Instance to NGINX Controller

Take the following steps to add an existing 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 Infrastructure menu, select Instances.

  4. On the Instances Overview page, select Create to add an Instance.

  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 select Create New to create a Location.

    Note:
    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. The -i and -l options for the install.sh script specify 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 3.7 and later.

After a few minutes, the NGINX Instance will appear on the Instances Overview page.


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 and 3.10.