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 9.5:

    For instructions on how to install PostgreSQL 9.5 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 section 17.9 Secure TCP/IP Connections with SSL of the PostgreSQL 9.5 manual for instructions and details.

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

  • The installer for NGINX Controller requires Internet access to download Kubernetes and perform the installation. If you prefer or need to install Kubernetes yourself, see the note about offline installations in the Installing NGINX Controller section for important guidance.

  • 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
  • RedHat/CentOS: util-linux, coreutils, iproute, iptables, socat, ebtables, ethtool, conntrack-tools

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.

Offline Installations: If you prefer or need to install Docker and Kubernetes yourself, then you should install the required packages first, and then allow the NGINX Controller installation script to configure Kubernetes for you.

To manually download these prerequisites, see the steps in the following procedure: Retrieving URLs for All Packages and Dependencies

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

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

    • Database settings (you should configure your own PostgreSQL 9.5 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 to invite new users via email).

    • Fully qualified domain name (FQDN) - a resolvable domain name for your the NGINX Controller server, used to access NGINX Controller in the browser after installation.

    • Admin email, password, organization name, 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 or send to NGINX Support at [email protected] for troubleshooting assistance.

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.

Retrieving URLs for All Packages and Dependencies

NGINX Controller may fail to install packages from public repositories. To retrieve the list of URLs for all required packages and their dependencies, perform the following procedure:

Impact of procedure: Performing the following procedure should not have a negative impact on your system.
  1. Enter the following script for Debian packages - Ubuntu/Debian:

    #!/bin/bash
    
    # run this as (assuming script is saved as $HOME/tmp/k8s-deb.sh):
    # docker run --rm -it -v $HOME/tmp:/src ubuntu:18.04 /src/k8s-deb.sh
    
    KUBE_VERSION=1.15.5
    packages=(
        "kubeadm=${KUBE_VERSION}-00"
        "kubelet=${KUBE_VERSION}-00"
        "kubectl=${KUBE_VERSION}-00"
    )
    apt-get update -qq && apt-get install -qq -y apt-transport-https curl gnupg2 >/dev/null
    curl -s https://packages.cloud.google.com/apt/doc/apt-key.gpg | apt-key add -
    echo "deb https://apt.kubernetes.io/ kubernetes-xenial main" | tee -a /etc/apt/sources.list.d/kubernetes.list >/dev/null
    apt-get update -qq
    
    echo ""
    echo "Fetch the following files:"
    apt-get install --reinstall --print-uris -qq "${packages[@]}" | cut -d"'" -f2
    
    echo ""
    echo "Install packages:"
    echo "dpkg -i *.deb"
    
  2. Enter the following script for RPM Packages - RedHat/CentOS:

    #!/bin/bash
    
    # run this as:
    # docker run --rm -it -v $HOME/tmp:/src centos:7 /src/k8s-rpm.sh
    
    KUBE_VERSION=1.15.5
    packages=(
      "kubeadm-${KUBE_VERSION}-0.x86_64"
      "kubelet-${KUBE_VERSION}-0.x86_64"
      "kubectl-${KUBE_VERSION}-0.x86_64"
    )
    tee -a /etc/yum.repos.d/kubernetes.repo <<EOF 1>/dev/null
    [kubernetes]
    name=Kubernetes
    baseurl=https://packages.cloud.google.com/yum/repos/kubernetes-el7-x86_64
    enabled=1
    gpgcheck=1
    repo_gpgcheck=1
    gpgkey=https://packages.cloud.google.com/yum/doc/yum-key.gpg https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
    EOF
    yum install -y -q yum-utils 2>/dev/null
    
    echo ""
    echo "Fetch the following files:"
    yumdownloader -y -q --resolve --urls "${packages[@]}" 2>/dev/null
    
    echo ""
    echo "Install packages:"
    echo "rpm -i *.rpm"