NGINX Documentation

Installing the NGINX Controller and Controller Agent

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.

Overview

NGINX Controller is a web application that runs next to your NGINX Plus instances.

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

Before installing the NGINX Controller, review the following general prerequisites. Additionally, review the specific requirements and recommendations for the version of the NGINX Controller that you’re installing, presented below.

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 the 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 the 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 the 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 and database naas. User naas requires 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, 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, dirname, head, id, mkdir, numfmt, sort, tee (all provided by the coreutils package)
  • Docker Community Edition (CE) 17.12.0 or later. For links to OS-specific installation instructions, see the Docker CE installation overview.

Additional Requirements for NGINX Controller 2.8 and Later

NGINX Controller 2.8 introduces Kubernetes as the orchestration tool for the NGINX Controller containers.

The following requirements are specific to NGINX Controller 2.8 and later and are in addition to those noted above:

  • NGINX Controller 2.8 and later supports Kubernetes 1.15.3 (client and server).
    • Tip: We recommend that you install the NGINX Controller on a dedicated node without Kubernetes installed already. The installer for the NGINX Controller will install Kubernetes for you.
  • The installer for the NGINX Controller requires Internet access to download Kubernetes 1.15.3 and perform the installation.
  • 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 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 2.8 and later downloads the following items:

Controller Downloads
Item Source
/bin/kubelet packages.cloud.google.com
/bin/kubeadm packages.cloud.google.com
/bin/kubectl packages.cloud.google.com
Flannel Deployment Configuration raw.githubusercontent.com
docker image coredns k8s.gcr.io
docker image etcd k8s.gcr.io
docker image flannel quay.io
docker image kube-apiserver k8s.gcr.io
docker image kube-controller-manager k8s.gcr.io
docker image kube-proxy k8s.gcr.io
docker image kube-scheduler k8s.gcr.io
docker image k8s.gcr.io/pause k8s.gcr.io

Note: Docker images, configurations, and generated files will be removed during the installation cleanup. However, the tools kubelet, kubeadm, and kubectl will not be uninstalled.

Tip: When you install the NGINX Controller, if you allow the Controller to install Docker for you, the 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.

Additional Requirements for NGINX Controller 2.7 and Earlier

The following requirements are specific to NGINX Controller 2.7 and earlier and are in addition to those noted above:

  • Docker Compose 1.18.0 or later. For OS-specific installation instructions, see the table in the Install Compose section of the Compose overview.

Installing NGINX Controller

To install the 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 the 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
    

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

    • Acceptance of the terms of use (type q to finish reading it, then y to accept).
    • A dedicated platform on which to install the NGINX Controller (type q to stop installing, then y to accept).
    • Database settings (you should configure your own PostgreSQL 9.5 database and add the connection credentials in this step).
    • SMTP settings (used to invite new users via email).
    • Fully qualified domain name (FQDN) - a resolvable domain name for your 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.

    Note: Keep the NGINX Controller instance running.

  4. Log in to the 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 the 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>/account/license. In the “Upload a license” section, select “Choose a file” to add your license file.
  6. Install the Controller Agent on each NGINX Plus instance that you want to manage and monitor.

    1. On the menu bar, select “Graphs”.

    2. On the Systems pane, select “New Instance,” and then follow the instructions in the “Add Instance” window to connect to the NGINX Plus instance and install the Controller Agent package.

      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. You’ll be prompted to install Python if it’s not installed already.

      After the Controller Agent is installed and initialized, it starts sending metrics back to the NGINX Controller, usually within a minute.

    instance

  7. Lastly, if you’re installing NGINX Controller 2.8 or later, make sure to exclude the following Kubernetes packages from package upgrades. NGINX Controller 2.8 and later requires that these packages be held at version 1.15.3, that is, the supported version of Kubernetes:

    • kubeadm
    • kubectl
    • kubelet

    On CentOS or Red Hat Enterprise Linux:

    1. Install yum-plugin-versionlock:

      yum install yum-plugin-versionlock

    2. For each package to exclude, run yum versionlock <package name>.

    On Debian or Ubuntu:

    1. For each package to exclude, run apt-mark hold <package name>.
  8. Cleanup

    Once the NGINX Controller installation has completed, you may safely delete the installer package that you downloaded and extracted.

Documentation

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

docs

Managing the NGINX Controller Process

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

./helper.sh start
./helper.sh stop
./helper.sh restart

Updating the NGINX Controller and Agent Software

To update the NGINX Controller software, download and run the newer installer package. You also need to update the Controller Agent software on each monitored NGINX Plus instance.

  1. Important: We strongly recommend that you make a back up of the following information before updating the Controller:

    • DB: Back up all of the NGINX Controller databases
    • Configuration file: agent.conf (this file is on each NGINX Plus instance)
  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 downloads and starts the updated NGINX Controller software.

  5. If you are logged in to the 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. Update the Controller Agent:

    Note: If you’re updating from Controller Agent 2.1.0 or earlier and you’re using Ubuntu 18.04(bionic), run the following command before starting the update:

    curl -fs -k http://<controller-server-FQDN>/packages-repository/nginx-signing.key | sudo apt-key add - && sudo apt-get --allow-releaseinfo-change update
    

    Follow the same instructions above–see step 6 in the Installing NGINX Controller section–to install the Controller Agent on each NGINX Plus instance.

  7. Restore your agent.conf file over the file in /etc/controller-agent/agent.conf.

Uninstalling

To uninstall the NGINX Controller, run the uninstall script:

/opt/nginx-controller/uninstall.sh

In NGINX 2.8 and later, to uninstall the NGINX Controller along with Kubernetes (if installed), run the uninstall script with the --yes-delete-k8s option:

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

Troubleshooting

If the NGINX Controller isn’t working how you expect, try the following troubleshooting steps to help identify the problem. Additionally, if you’re installing the NGINX Controller 2.8 or later, review the specific troubleshooting steps for those versions, presented below.

  • Check the configuration files in /opt/nginx-controller:
    • certs/ (for the web app to run over HTTPS)
    • docker-compose.yml (this file is available only if you’re running Controller 2.7 or earlier)
  • View the log files:
    • If you’re running NGINX Controller 2.7 or earlier, the log files for the Controller components are in /var/log/nginx-controller/.
    • If you’re running NGINX Controller 2.8 or later, you can find the nginx-controller-install.log and nginx-controller-update.log files in /var/log/nginx-controller/. Additionally, if the Controller encounters an issue when installing or updating, the pod logs are extracted automatically to /var/log/nginx-controller/failure/.
  • Run the sudo docker ps command to view the Docker containers.

Additional Troubleshooting for NGINX Controller 2.8 and Later

The following troubleshooting steps are specific to NGINX Controller 2.8 and later and are in addition to those noted above.

Note: NGINX Controller 2.8 introduces Kubernetes as the orchestration tool for the NGINX Controller containers. In Kubernetes, containers are organized into a higher-level structure called a pod. See the following sections for instructions on how to check the status of the Controller’s pods and how to view the pod logs.

View the Installation and Update Logs

For Controller 2.8 and later, you can find the install and update log files in /var/log/nginx-controller/.

Additionally, if the Controller encounters an issue when installing or updating, the Controller’s pods’ logs, pods’ details, node resources, and event resources are extracted automatically to /var/log/nginx-controller/failure/.

Note: You can view the unextracted Controller pod logs at any time by following the instructions in the View the Pod Logs section below.

Database Failed to Initialize

The NGINX Controller might not initialize the database if there’s an issue with the database or if the Controller cannot connect to the database.

To investigate problems with initializing the database, you can check the logs for the job:

  1. Open a secure shell (SSH) connection to the NGINX Controller and log in as an administrator.

  2. Run the kubectl command to view the logs:

    kubectl -n nginx-controller logs -l app=controller-init --all-containers

  3. Search the logs for error messages.

Check the Status of the Controller’s Pods

To check the status of the Controller’s pods:

  1. Open a secure shell (SSH) connection to the NGINX Controller and log in as an administrator.

  2. To see if all the pods are running, run the kubectl get pods command:

    kubectl -n nginx-controller get pods -l org=f5.com

  3. To see the details of a single pod, run the kubectl describe pod command :

    kubectl -n nginx-controller describe pod <pod name>

View the Pod Logs

If all the pods are running, you can search the pod logs for error messages.

  1. Open a secure shell (SSH) connection to the NGINX Controller and log in as an administrator.

  2. To view and follow the logs, run the kubectl log command (press CTRL+C to stop):

    kubectl -n nginx-controller logs --all-containers --max-log-requests=11 --tail 100 -f -l org=f5.com

    Tip: To limit the log output, pipe the results of the preceding command to grep.

The logs contain the following information:

  • Time formatted as RFC3339
  • Log level: INFO, WARNING, ERROR
  • Logger name: access, body, error, request, default
  • App name: coreapi, apimgmt, receiver, appregistry, queue
  • Other details, such as correlation-id (also called action-id), source filename and line number, and a message