NGINX Documentation

Try NGINX Controller with NGINX Plus

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 internal 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. Upgrades are not supported for -n installations.

Objectives

  • Sign up for trial licenses for NGINX Controller and NGINX Plus
  • Install NGINX Plus
  • Install and license NGINX Controller
  • Add your NGINX Plus instance to NGINX Controller

Technical Requirements

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

NGINX Controller v3 supports the following distributions and architectures:

  • CentOS 7 (x86_64)
  • Debian 9 (x86_64)
  • Red Hat Enterprise Linux 7 (x86_64) - Works with NGINX Controller 3.5 and later
  • Ubuntu 16.04 LTS (x86_64)
  • Ubuntu 18.04 LTS (x86_64)

Minimum hardware requirements:

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

Supported NGINX Plus versions:

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

Sign Up for Trial Licenses

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 Plus

Prerequisites

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

Steps

Take the following steps to install NGINX Plus:

  1. First, make sure to review the NGINX Plus Technical Specifications Guide for the requirements for your distribution and desired configuration.
  2. To install NGINX Plus, follow the instructions in the NGINX Plus Installation Guide. See the relevant section for your distribution.

Install NGINX Controller

Prerequisites

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

  • A license file for NGINX Controller. You can download this from the MyF5 Customer Portal.

  • The installation script requires the following Linux utilities. The script will let you know if any of the utilities are missing.

    • curl or wget, jq (1.5 or later), envsubst (provided by the gettext package)
    • awk, bash (4.0 or later), getent, grep, gunzip (provided by the gzip package), less, openssl, sed, tar
    • base64, basename, cat, comm, dirname, head, id, mkdir, numfmt, sort, tee (all provided by the coreutils package)
    • yum-plugin-versionlock on RedHat/CentOS
  • NGINX Controller requires Kubernetes 1.15.5. The following system packages are required for Kubernetes installation. The installation script will let you know if any of them are missing.

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

    The following packages are included with the NGINX Controller installer:

    • kubelet – v1.15.5
    • kubeadm – v1.15.5
    • kubectl – v1.15.5
    • kubernetes-cni – 0.8.6
    • cri-tools – 1.13.0

Steps

Take the following steps to install NGINX Controller:

Note: The documentation for NGINX Controller, including the NGINX Controller API reference guide, is installed with the product and can be accessed at https://<Controller-FQDN>/docs.
  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 that’s suitable for demos and trial use only. 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 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].

  • FQDN: Fully qualified domain name (FQDN) – a resolvable domain name for the NGINX Controller server, which Controller Agents will use when connecting to NGINX Controller.

  • Organization name: The name of your organization.

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

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

License NGINX Controller

  1. Log in to NGINX Controller at https://<Controller-FQDN>/login. Use the admin email address and password that you provided during the installation process.
  2. Upload the NGINX Controller license:
    • To upload the license, go to https://<Controller-FQDN>/platform/license.
    • In the Upload a license section, select Choose a file to add your license file.

Cleanup

Once NGINX Controller is installed, you may safely delete the installer package that you downloaded and extracted.

Add an NGINX Plus Instance to NGINX Controller

To add your NGINX Plus Instance to NGINX Controller, follow the steps in the Manage Your Instances topic in the NGINX Controller documentation: https://<Controller-FQDN>/infrastructure/instances/manage-instances/.