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 NGINX Controller Installation Guide v2.

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. The full list and the license for each package can be found on the NGINX Controller Technical Specifications page.

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 via the NGINX Customer Portal;

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

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

    Note: If you have a trial subscription for NGINX Controller, use the license that was provided on the trial activation page. 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;

    • The 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.
    • 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 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, envsubst
    • awk, bash (4.0 or later), getent, grep, gunzip, less, openssl, sed, tar
    • base64, basename, cat, dirname, head, id, mkdir, numfmt, sort, tee
  • 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–3.1: requires Kubernetes 1.15.5

The installer for NGINX Controller downloads the following items:

  • /bin/kubelet – v1.15.3
  • /bin/kubeadm – v1.15.5
  • /bin/kubectl – v1.15.5
  • Flannel Deployment Configuration – v1.15.5
  • docker image k8s.gcr.io/coredns – 1.3.1
  • docker image k8s.gcr.io/etcd – 3.3.10
  • docker image quay.io/coreos/flannel – v0.11.0-amd64
  • docker image k8s.gcr.io/kube-apiserver – v1.15.5
  • docker image k8s.gcr.io/kube-controller-manager – v1.15.5
  • docker image k8s.gcr.io/kube-proxy – v1.15.5
  • docker image k8s.gcr.io/kube-scheduler – v1.15.5
  • docker image k8s.gcr.io/pause – 3.1

Note: Docker images, configurations, and generated files will be removed during the installation cleanup. Additionally, the tools kubelet, kubeadm, and kubectl 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 and Docker images 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 procedures:

To install NGINX Controller, take the following steps:

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

    Note: If you have a trial subscription for NGINX Controller, use the image that was provided on the trial activation page. 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 guide Technical Specifications for NGINX Controller 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.

    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. Caution: You should use environment variables to pass passwords to prevent the password details from being exposed on the host in the list of running processes.

    Note: Keep the NGINX Controller instance running.

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

  5. Upload the NGINX Controller license provided by NGINX, Inc. You can access the license at the NGINX Customer Portal.

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

    • To upload the licence, go to https://<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 and can be accessed at https://<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

Important: NGINX Controller v3.0.0 does not contain the update script, due to the lack of backwards compatibility with prior releases. If you wish to upgrade from NGINX Controller v2 to v3, you must perform a fresh installation.

To update the NGINX Controller software, take the steps below. You also need to update the Controller Agent software on each monitored NGINX Plus instance.

  1. Caution: We strongly recommend that you make a backup of the following information 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>
        
  2. Download the installer package from the NGINX Customer Portal.

  3. Extract the installer package files:

    tar xzf controller-installer-<version>.tar.gz
    
  4. 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.

  5. 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.
  6. Restore your backup agent.conf file to /etc/controller-agent/agent.conf.

    cp <temporary location>/agent.conf /etc/controller-agent/
    
  7. Update the Controller Agent on each NGINX Plus instance. For instructions, see the NGINX Controller Agent Installation Guide in the NGINX Controller 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 and update the Controller Agent, see the NGINX Controller Agent Installation Guide in the NGINX Controller documentation.

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.

Manually Download Docker images

NGINX Controller may fail to install when images are not properly loaded from public Docker registries. To pull all images required by Kubernetes and save them into a single file that can be moved to the target host and loaded manually, 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:

    # pull and save Docker images
    # this list is obtained by running the following command.
    # update --kubernetes-version to match the Kubernetes version that's required by your version NGINX Controller
    # kubeadm config images list --kubernetes-version 1.15.5
    # yq -r '.spec.template.spec.containers, .spec.template.spec.initContainers | select( . != null) | .[].image' files/k8s/kube-flannel.yml | sort -u | grep amd64
    images=(
        k8s.gcr.io/kube-proxy:v1.15.5
        k8s.gcr.io/kube-apiserver:v1.15.5
        k8s.gcr.io/kube-controller-manager:v1.15.5
        k8s.gcr.io/kube-scheduler:v1.15.5
        k8s.gcr.io/coredns:1.3.1
        k8s.gcr.io/etcd:3.3.10
        k8s.gcr.io/pause:3.1
        quay.io/coreos/flannel:v0.11.0-amd64
    )
    for i in "${images[@]}"; do
        docker pull "$i"
    done
    docker save "${images[@]}" | gzip > k8s-images.tar.gz
    
  2. Enter the following command to load the Docker images:

    gunzip -c k8s-images.tar.gz | docker load

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 http://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"