NGINX Documentation

NGINX Controller Installation Guide v3

Thank you for purchasing NGINX Controller! This guide will help you download, install, and run the system. The installation will result in a configured, working system ready for you to use to monitor and manage your NGINX Plus instances.

Note: If you want to install NGINX Controller v2, please see the NGINX Controller v2 Installation Guide.

Overview

NGINX Controller is NGINX’s control-plane solution that manages the NGINX data plane. Built on a modular architecture, NGINX Controller enables you to manage the entire lifecycle of NGINX Plus, whether it’s deployed as a load balancer, API gateway, or a proxy in a service mesh environment.

To get started, download and run the installer. The installer will:

  • Perform prerequisite checks on your system and prompt for any missing dependencies.
  • Prompt you to accept the terms of service agreement for NGINX Controller.
  • Ask you for a series of parameters including Database, SMTP, Admin user, and FQDN settings.
  • Place configuration and log files in appropriate file locations on your host system.
  • Add extra repositories to the default package manager like apt or yum and install required packages.
  • Launch NGINX Controller.

Open Source Software Dependencies

NGINX Controller uses a number of open source software packages in the product. You can find information about these dependencies in the NGINX Controller v3 Technical Specifications.

Prerequisites

Important: The NGINX Controller should be deployed on a secure, internal network only. We strongly recommend against exposing the NGINX Controller API to the internet.

Before installing NGINX Controller, review the following prerequisites.

Things you’ll need before installing NGINX Controller:

  • The controller-installer-<version>.tar.gz package, downloaded from the MyF5 Customer Portal;

    Note: If you have a trial subscription for NGINX Controller, use the image that was provided on the trial activation page or in the email. You don’t need to log in to the NGINX Customer Portal.

  • A license file for NGINX Controller, accessible via the MyF5 Customer Portal;

    Note: If you have a trial subscription for NGINX Controller, use the license that was provided on the trial activation page or in the email. You don’t need to log in to the NGINX Customer Portal.

  • A dedicated environment (bare metal, VM, or cloud-hosted instance) on which to install NGINX Controller:

  • PostgreSQL:

    NGINX Controller supports the following versions of PostgreSQL:

    • PostgreSQL 12.3 – works with NGINX Controller 3.9 and later.
    • PostgreSQL 9.5 – works with NGINX Controller 3.0 and later.

    Note: To demo or trial NGINX Controller, you can use an internal database provided by NGINX Controller. Such a deployment is not recommended for production environments. For instructions, see the Try NGINX Controller with NGINX Plus guide.

    • The PostgreSQL database must be accessible from the NGINX Controller server. You can use a DNS-resolvable name or an IP address to connect to the database server (names in /etc/hosts are not allowed).
    • Create the user with the Create DB permission.

    Note: For instructions on how to install PostgreSQL on CentOS 7 and Ubuntu 18.04 for use with NGINX Controller, see the AskF5 KB article K49481224.

    Important: Configure PostgreSQL to allow SSL connections; client certificates should also be used for user authentication. (We strongly discourage disabling SSL for PostgreSQL for security reasons.) See the Secure TCP/IP Connections with SSL topic in the PostgreSQL manual for instructions and details (PostgreSQL 9.5, PostgreSQL 12.3).

  • The following Linux utilities are required by the installation script. 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

    To install the required packages, run the command shown below that is appropriate for your OS.

    • Debian/Ubuntu:

      apt-get install curl jq gettext gawk bash getent grep gzip less openssl sed tar coreutils
      
    • RedHat/CentOS:

      yum install curl jq gettext awk bash getent grep gzip less openssl sed tar coreutils yum-plugin-versionlock
      

    Note: The jq package is available in the EPEL (Extra Packages for Enterprise Linux) repository. If you don’t have access to the jq package, the NGINX Controller installer will provide local RPM files to install.

See the Docker and Kubernetes Requirements section for additional package requirements.

  • Containerd.io 1.2.10 and Docker Community Edition (CE) 18.09, if you’re installing Docker yourself. If you don’t have Docker installed, NGINX Controller will install these for you.

    Tip: When you install NGINX Controller, if you allow NGINX Controller to install Docker for you, NGINX Controller sets systemd as the cgroup driver. This is recommended by Kubernetes to help protect against system instability. If you have Docker installed already, the Controller installer will warn you if you should change the cgroup driver to systemd. For background information regarding this recommendation, plus instructions on how to change the cgroup driver, see the Kubernetes doc Container runtimes > Cgroup drivers.

  • Disable swap on the NGINX Controller host; this is required by Kubernetes in order for the kubelet to work properly. Refer to your Linux distribution documentation for specific instructions for disabling swap for your system. For more information about this requirement, see the AskF5 knowledge base article K82655201 and the kubeadm installation guide in the Kubernetes documentation.

  • Enable log rotation for the Docker logs so that the logs don’t consume all the free disk space on the server. For instructions on how to enable Docker log rotation, see the Docker guides How to set up log rotation post installation and JSON File logging driver.

  • Install NGINX Controller on a dedicated node that does not already have Kubernetes configured.

Docker and Kubernetes Requirements

NGINX Controller requires the following versions of Kubernetes (client and server):

  • NGINX Controller 3.0+: requires Kubernetes 1.15.5

The following system packages are required for Kubernetes installation. Installation script will let you know if any of them are missing.

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

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

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

The following packages are included in 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

Note: Docker images, configurations, and generated files will be removed during the installation cleanup. Additionally, the tools kubelet, kubeadm, kubectl, kubernetes-cni and cri-tools will be uninstalled if they were installed by the NGINX Controller installer. However, these tools won’t be removed if they already existed, even if they were updated.

Installing NGINX Controller

Install NGINX Controller on a dedicated node that does not already have Kubernetes configured. NGINX Controller does not support pre-configured Kubernetes implementations at this time. The installer for NGINX Controller will install and configure Kubernetes for you.

To install NGINX Controller, take the following steps:

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

    Note: If you have a trial subscription for NGINX Controller, use the image that was provided on the trial activation page or in the activation email. You don’t need to log in to the NGINX Customer Portal.

  2. Extract the installer package files:

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

    cd controller-installer
    ./install.sh
    

    Note: If an HTTPS proxy is configured for the whole system, you should disable the proxy for the IP address and hostname of the host that you’re running the NGINX Controller install script on. For example, run the command export NO_PROXY=<current_ip>,<current_hostname>.

    Note: For PoC deployments you can use an internal database provided by NGINX Controller. Simply run install script with -n option, like ./install.sh -n. It is not recommended to use this option for production-grade deployments!

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

    • Database settings (you should configure your own PostgreSQL database and add the connection credentials in this step).

    • Volume type for the analytics database. (See the Technical Specifications for NGINX Controller v3 for requirements.)

    • Acceptance of the terms of use (type q to finish reading it, then y to accept).

    • SMTP settings (used for sending password recovery emails).

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

    • Admin email, password, first name, and last name.

    • SSL/TLS certificates for running the web app over HTTPS; the installer can generate self-signed certs if you wish.

      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.

      For more information about certificate chains, see Configuring HTTPS servers in the NGINX documentation.

    Note: The above installation options can be set using CLI flags. Run ./install.sh --help to see the full list of available flags and environment variable names.

    Important: Use environment variables when passing passwords. This prevents the password details from being exposed in the list of running processes on the host.

  4. Log in to NGINX Controller at https://<Controller-FQDN>/login. Use the admin email address and password that you provided during the installation process.

  5. Upload the NGINX Controller license. You can access the license via the MyF5 Customer Portal.

    Note: If you have a trial subscription for NGINX Controller, use the license that was provided on the trial activation page or in the activation email. You don’t need to log in to the NGINX Customer Portal.

    • 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.
  6. Cleanup: Once the NGINX Controller installation has completed, you may safely delete the installer package that you downloaded and extracted.

Documentation

The documentation for NGINX Controller is installed with the product, where it can be accessed at https://<Controller-FQDN>/docs.

Managing the NGINX Controller Process

To start, stop, restart, and check the status of the NGINX Controller process, use the helper.sh script found at /opt/nginx-controller/:

./helper.sh controller start
./helper.sh controller stop
./helper.sh controller restart
./helper.sh controller status

Updating NGINX Controller

To update the NGINX Controller software, take the steps below. When complete, you must also update the Controller Agent software on each monitored NGINX Plus instance.

Caution: We strongly recommend that you make a backup of the following information before proceeding, to avoid potential data and/or configuration loss:

  • DB: Back up all of the NGINX Controller databases

  • Agent Configuration file: agent.conf

    • This file is present on each NGINX Plus instance.

    • To create a backup, copy the file from its current location to a new location.

      cp /etc/controller-agent/agent.conf <temporary location>
      
  1. Download the installer package from the MyF5 Customer Portal.

  2. Extract the installer package files:

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

    cd controller-installer
    ./update.sh
    

    Note: The update script requires you to confirm that you’ve backed up the NGINX Controller database.

    Once you’ve confirmed that you’ve backed up the database, the update script starts the updated NGINX Controller software.

  4. If you are logged in to NGINX Controller using a web browser, sign out and log in again.

    • To sign out, select your username in the upper right-hand corner, and then select “Sign Out”. For optimal performance, also flush your browser cache.
  5. Restore your backup agent.conf file to /etc/controller-agent/agent.conf.

    cp <temporary location>/agent.conf /etc/controller-agent/
    
  6. Update the Controller Agent on each NGINX Plus instance. For instructions, see the NGINX Controller Agent Installation Guide in the NGINX Controller onboard documentation.

Installing the Controller Agent

Install the Controller Agent on each NGINX Plus instance that you want to manage and monitor. Also, after you upgrade NGINX Controller, you should update the Controller Agent to the latest version.

For instructions on how to install, update, and configure the Controller Agent, see the documentation that’s installed with NGINX Controller by going to https://<Controller-FQDN>/docs/infrastructure/agent in your web browser.

Uninstalling NGINX Controller

To uninstall NGINX Controller, run the uninstall script:

/opt/nginx-controller/uninstall.sh

To uninstall both NGINX Controller and Kubernetes, run the uninstall script with the --yes-delete-k8s option:

/opt/nginx-controller/uninstall.sh --yes-delete-k8s

Troubleshooting

If NGINX Controller isn’t working how you expect, see the knowledge base article K03263142 for installation troubleshooting procedures.

Create a Support Package

You can create a support package for NGINX Controller that you can use to diagnose issues.

Note: You will need to provide a support package if you open a ticket with NGINX Support via the MyF5 Customer Portal.

To create a support package:

  1. Log in to the command line of the NGINX Controller system.

  2. Run the helper.sh utility with the supportpkg option:

    /opt/nginx-controller/helper.sh supportpkg

    The support package is saved to:

    /var/tmp/supportpkg-<timestamp>.tar.gz

    For example:

    /var/tmp/supportpkg-20200127T063000PST.tar.gz

  3. Run the following command from the machine that you want to download the support package to:

    # scp <username>@<controller-host-ip>:/var/tmp/supportpkg-<timestamp>.tar.gz /local/path

Contents of the Support Package

The support package is a tarball that includes NGINX Controller configuration information, logs, and system command output. Sensitive information, including certificate keys, is not included in the support package.

The support package includes information from the following sources:

  • /database – Directory containing PostgreSQL dump files from the system and common database, and queries for specific information, such as licensing and table sizes. Sensitive information is masked.
  • /k8s – Directory containing Kubernetes resource information and logs for the kube-system and nginx-controller namespaces.
  • /logs – Directory containing NGINX Controller install and uninstall logs.
  • /os – Directory containing Host information such as output from the top, ps, and iptables utilities, each written to a separate file.
  • version.txt – File containing the current running version of NGINX Controller.