End of Sale Notice:

F5 NGINX is announcing the End of Sale (EoS) for NGINX Controller API Management Module, effective January 1, 2024.

F5 maintains generous lifecycle policies that allow customers to continue support and receive product updates. Existing NGINX Controller API- Management customers can continue to use the product past the EoS date. License renewals are not available after September 30, 2024.

See our End of Sale announcement for more details.

End of Sale Notice:

F5 NGINX is announcing the End of Sale (EoS) for NGINX Controller Application Delivery Module, effective January 1, 2024.

F5 maintains generous lifecycle policies that allow customers to continue support and receive product updates. Existing NGINX Controller Application Delivery customers can continue to use the product past the EoS date. License renewals are not available after September 30, 2024.

See our End of Sale announcement for more details.

Trial NGINX Controller with App Security

This quick-start tutorial shows you how to get started using F5 NGINX Controller with the Application Security Add-on.

Overview

This quick-start tutorial shows you how to get started using F5 NGINX Controller with the Application Security Add-on (“App Security”). The App Security add-on to the NGINX Controller Application Delivery Module enables a web application firewall (WAF) that you can use to protect your apps.

Take the steps in this guide to deploy NGINX Controller with App Security and deploy NGINX App Protect with NGINX Plus as a data plane instance for use with NGINX Controller.

Caution:
In this tutorial, NGINX Controller will install an embedded, self-hosted PostgreSQL database suitable for demo and trial purposes only. These instructions are not meant for use in production environments.

Note:
If you already have an active NGINX Controller trial and want to add App Security to it, you can start with the Install NGINX App Protect with NGINX Plus section.

Technical Requirements

Be sure to review the NGINX Controller Technical Specifications Guide for additional requirements for your desired distribution and configuration.

Supported Distributions

NGINX Controller with App Security supports the following distributions for deploying NGINX App Protect:

• CentOS 7 (7.4+)
• Red Hat Enterprise Linux 7 (7.4+)
• Debian 9
• Ubuntu 18.04 LTS, Ubuntu 20.04 LTS

Hardware Specs

The following minimum hardware specifications are required for each node running NGINX Controller:

• RAM: 8 GB RAM
• CPU: 8-Core CPU @ 2.40 GHz or similar
• Disk space: 155–255 GB free disk space. 255 GB of free space is recommended if NGINX Controller App Security is enabled. See the Storage Requirements section for a categorized list of the storage requirements.

Supported NGINX Versions

The App Security add-on for the NGINX Controller Application Delivery module is compatible with the versions of NGINX Plus and NGINX App Protect shown in the table below. New releases of NGINX Controller ADC support the last four versions of NGINX Plus at release time.

See Also:
Refer to Using NGINX App Protect with NGINX Controller for installation instructions and additional information.

Sign Up for a Trial License

Note:
If you already have an active NGINX Controller trial instance that you want to add App Security to, you can skip this section.

First, you need to sign up for a trial license for NGINX Controller. The trial includes access to NGINX Plus, the NGINX Controller Application Delivery module, and the Application Security add-on.

1. Go to MyF5 and create a new account.
2. Verify your account and log in to MyF5.
3. On the MyF5 landing page, activate the NGINX Controller free trial.
4. On the MyF5 Trials page, select Launch Your Trial.
5. Download the NGINX Controller package.
6. Make note of your Association Token. You will use this to license your NGINX Controller instance.

Install NGINX Controller Prerequisites

Note:
If you already have an active NGINX Controller trial instance that you want to add App Security to, you can skip this section.

You can use the NGINX Controller helper.sh prereqs command to install the required system packages and Docker CE.

To install all of the NGINX Controller prerequisites for your system at the same time, take the following steps:

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 helper script with the prereqs option:

   cd controller-installer
   ./helper.sh prereqs
   

Note:

After you’ve installed NGINX Controller, you can install any of the prerequisites by running the following command:

/opt/nginx-controller/helper.sh prereqs [base|docker|nfs]

Install NGINX Controller

Note:
If you already have an active NGINX Controller trial instance that you want to add App Security to, you can skip this section.

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.

Important:
Before installing NGINX Controller, you must disable swap on the 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.

Caution:
For RHEL 8 deployments, complete the additional prerequisite steps in the Installing NGINX on RHEL 8 guide before installing NGINX Controller. RHEL 8 support is a beta feature.

To install NGINX Controller, take the following steps:

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
   

4. When prompted to use an embedded config DB, type y.

5. The installation script walks through a series of steps and asks for the following inputs:

   • Config database volume type: Specify the type of volume to use to store the config database: local, NFS, or AWS. We recommend choosing local for demo and trial purposes.

     See Also:
     Refer to the NGINX Controller Technical Specifications Guide for more information about the volume options and requirements.

   • Analytics database volume type: Specify the type of volume to use to store the analytics database: local, NFS, or AWS. We recommend choosing local for demo and trial purposes.

   • 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, donotreply@example.com.

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

   • FQDN: Fully qualified domain name (FQDN) – a resolvable domain name for the NGINX Controller server. You can use the FQDN to access the NGINX Controller web interface. Additionally, the FQDN is used by Controller Agents when connecting to NGINX Controller.

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

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

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

License NGINX Controller

To add a license to NGINX Controller, take the following steps:

1. Go to https://<Controller-FQDN>/platform/license and log in.

2. In the Upload a license section, select an upload option:

   • Upload license file – Locate and select your license file in the file explorer.
   • Paste your Association Token or license file – Paste your customer Association Token or the contents of your NGINX Controller license file. These are available on the MyF5 Customer Portal.

3. Select Save license.

See Also:
To add a license using the NGINX Controller REST API, send a PUT request to the /platform/license endpoint. Provide your CAT or NGINX Controller license as a base64-encoded string in the JSON request body.

Install NGINX App Protect with NGINX Plus

NGINX App Protect is the security data plane for NGINX Controller App Security. Your NGINX App Protect installation will include NGINX Plus.

Important:

If you are adding App Security to an existing NGINX Controller trial, we recommend that you take the steps in this section to deploy a new NGINX App Protect instance, rather than adding the App Protect module to an existing NGINX Plus instance.

NGINX Controller App Security is supported for use with a limited subset of the OS distributions that are supported by the NGINX Controller Agent and NGINX Plus. If you are planning to add NGINX App Protect to an existing NGINX Plus instance, be sure to check the Supported Distributions section above to verify that your NGINX Plus instance supports NGINX App Protect.

Prerequisites

• Be sure to review the NGINX Plus Technical Specifications for the requirements for your distribution and desired configuration.
• You’ll need the NGINX Plus certificate and public key files (nginx-repo.crt and nginx-repo.key) when installing NGINX App Protect. If you don’t have these files, you can use the NGINX Controller REST API to download them.

Download the NGINX App Protect Cert and Key

Take the steps below to download the cert and key files by using the NGINX Controller REST API.

The NGINX Controller API uses session cookies to authenticate requests. The session cookie is returned in response to a GET /api/v1/platform/login request. See the Login endpoint in the NGINX Controller API Reference documentation for information about session cookie timeouts and invalidation.

Tip:
You can send a GET request to the login endpoint to find the status of the session token.

For example:

• Login and capture the session cookie:

  curl -c cookie.txt -X POST --url 'https://198.51.100.10/api/v1/platform/login' --header 'Content-Type: application/json' --data '{"credentials": {"type": "BASIC","username": "arthur@arthurdent.net","password": "Towel$123"}}'
  

• Use the session cookie to authenticate and get the session status:

  curl -b cookie.txt -c cookie.txt -X GET --url 'https://198.51.100.10/api/v1/platform/login'
  

To use the NGINX Controller REST API to download your NGINX Plus certificate and key bundle as a gzip or JSON file, send a GET request to the /platform/licenses/nginx-plus-licenses/controller-provided endpoint.

For example:

• Download JSON file:

  curl -b cookie.txt -c cookie.txt --header 'Content-Type: application/json' -X GET --url 'https://192.0.2.0/api/v1/platform/licenses/nginx-plus-licenses/controller-provided'  --output nginx-plus-certs.json
  

• Download GZIP file:

  curl -b cookie.txt -c cookie.txt -X GET --url 'https://192.0.2.0/api/v1/platform/licenses/nginx-plus-licenses/controller-provided' --output nginx-plus-certs.gz
  

Note:
If you are using a self-signed certificate you will need to add -k (allow insecure connections) to your curl command to be able to download your NGINX Plus certificate and key bundle.

Once you have downloaded your certificate and key bundle you will need to expand the .gz file to get your certificate and key pair.

For example:

gunzip nginx-plus-certs.gz

Deploy NGINX App Protect

Add the NGINX App Protect Instance to NGINX Controller

Take the following steps to add an instance to NGINX Controller:

1. Open the NGINX Controller user interface and log in.

2. Select the NGINX Controller menu icon, then select Infrastructure.

3. On the Infrastructure menu, select Instances > Overview.

4. On the Instances overview page, select Create.

5. On the Create Instance page, select Add an existing instance.

6. Add a name for the instance. If you don’t provide a name, the hostname of the instance is used by default.

7. To add the instance to an existing Instance Group, select an Instance Group from the list. Or to create an Instance Group, select Create New.

8. To add the instance to an existing Location, select a Location from the list. Or to create a Location, select Create New.

   Important:
   Once set, the Location for an instance cannot be changed. If you need to change or remove the Location for an instance, you must remove the instance from NGINX Controller, and then add it back.

   Important:
   Instances and the instance groups they belong to should specify the same location; however, this requirement is not currently enforced. If different locations are specified, the instance group’s location takes precedence. This is important to remember when assigning locations to workload groups.

9. (Optional) By default, registration of NGINX Plus instances is performed over a secure connection. To use self-signed certificates with the Controller Agent, select Allow insecure server connections to NGINX Controller using TLS. For security purposes, we recommend that you secure the Controller Agent with signed certificates when possible.

10. Use SSH to connect and log in to the NGINX instance that you want to connect to NGINX Controller.

11. Run the curl or wget command that’s shown in the Installation Instructions section on the NGINX instance to download and install the Controller Agent package. When specified, the -i and -l options for the install.sh script refer to the instance name and Location, respectively.

    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.

    NGINX Controller 3.6 and earlier require Python 2.6 or 2.7. You’ll be prompted to install Python if it’s not installed already. Python is not required for NGINX Controller v3.7 and later.

After a few minutes, the NGINX instance will appear on the Instances overview page.

What’s Next

You should now be ready to start your NGINX Controller with App Security trial. Refer to the following topics to get started:

• Configure the NGINX Controller Agent
• Set Up Metrics Collection
• Forward Metrics Data to an External Service
• Set up NGINX Controller Services