diff --git a/content/controller/_index.md b/content/controller/_index.md deleted file mode 100644 index de4760e6f..000000000 --- a/content/controller/_index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -description: "NGINX Controller provides application delivery and API - management for modern app teams." -title: F5 NGINX Controller -weight: 2100 -cascade: - logo: "NGINX-Controller-product-icon-RGB.svg" - noindex: true - nd-banner: - enabled: true - type: deprecation - md: _banners/eos-cltr.md -url: /nginx-controller/ ---- - diff --git a/content/controller/admin-guides/_index.md b/content/controller/admin-guides/_index.md deleted file mode 100644 index 7c7510467..000000000 --- a/content/controller/admin-guides/_index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -description: Learn how to install and manage NGINX Controller and NGINX Controller - Agent. -title: Admin Guides -weight: 100 -url: /nginx-controller/admin-guides/ ---- - diff --git a/content/controller/admin-guides/backup-restore/_index.md b/content/controller/admin-guides/backup-restore/_index.md deleted file mode 100644 index 542b76cb3..000000000 --- a/content/controller/admin-guides/backup-restore/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -description: Learn how to back up and restore NGINX Controller. -title: Back Up & Restore -weight: 300 -url: /nginx-controller/admin-guides/backup-restore/ ---- - diff --git a/content/controller/admin-guides/backup-restore/backup-restore-cluster-config.md b/content/controller/admin-guides/backup-restore/backup-restore-cluster-config.md deleted file mode 100644 index 146217e3b..000000000 --- a/content/controller/admin-guides/backup-restore/backup-restore-cluster-config.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -description: Learn how to back up your F5 NGINX Controller cluster configuration and - encryption keys. -nd-docs: DOCS-247 -title: Back Up & Restore Cluster Config and Encryption Keys -toc: true -weight: 97 -type: -- how-to ---- - -## Overview - -After installing F5 NGINX Controller, you should back up the cluster config and encryption keys. You'll need these if you ever need to restore the NGINX config database on top of a new NGINX Controller installation. - -- To back up the NGINX Controller cluster configuration and encryption keys: - - ```bash - /opt/nginx-controller/helper.sh cluster-config save - ``` - - The file is saved to `/opt/nginx-controller/cluster-config.tgz`. - -- To restore the cluster's config and encryption keys, take the following steps: - - ```bash - /opt/nginx-controller/helper.sh cluster-config load - ``` - -{{< versions "3.12" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/admin-guides/backup-restore/backup-restore-embedded-config-db.md b/content/controller/admin-guides/backup-restore/backup-restore-embedded-config-db.md deleted file mode 100644 index f1e211f4b..000000000 --- a/content/controller/admin-guides/backup-restore/backup-restore-embedded-config-db.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -description: Learn how to back up and restore the embedded F5 NGINX Controller config - database. -nd-docs: DOCS-248 -title: Back Up & Restore an Embedded Config Database -toc: true -weight: 98 -type: -- tutorial ---- - -## Overview - -Follow the steps in this guide to back up and restore an internal F5 NGINX Controller config database. Use this guide if you selected the option to use an embedded config database when you installed NGINX Controller. Embedded config means that NGINX Controller is using an internal database to store configuration data. - -## Automated Backups of Embedded Config Database - -NGINX Controller automatically takes a snapshot of the embedded config database every 60 minutes and saves the backups on the config DB volume. The backup file location varies depending on the volume chosen at setup: - -- **Local**: The backup files are located in `/opt/nginx-controller/postgres_data/` with the following naming scheme: `backup_.tar`. - -- **NFS**: The backup files are located in the path on the NFS server host that was specified during installation and have the following naming scheme: `backup_.tar`. - -These automated config backups do not include backups of metrics data, which must be backed up separately; refer to [Backup & Restore the Metrics Database]({{< ref "/controller/admin-guides/backup-restore/backup-restore-metrics-db.md" >}}) for those instructions. - -{{< call-out "tip" >}} -As a best practice, we recommend that you make scheduled backups of the entire config DB volume and keep the backups off-site for safekeeping. -{{< /call-out >}} - -  - ---- - -## Restore Embedded Config Database - -This section explains how to restore the embedded config database from the latest backup file or a specific, timestamped file. - -{{< call-out "important" >}}If you restore the config database on top of a new installation of NGINX Controller, make sure to follow the steps to [restore your NGINX config and encryption keys]({{< ref "/controller/admin-guides/backup-restore/backup-restore-cluster-config.md" >}}) afterward. {{< /call-out >}} - -- To restore the embedded NGINX Controller config database **from the latest automated backup**, run the following command: - - ```bash - /opt/nginx-controller/helper.sh backup restore - ``` - -- To restore the embedded config database from **a specific backup file**: - - ```bash - /opt/nginx-controller/helper.sh backup restore - ``` - - - If you installed the embedded config database on a **local volume**, the backup files are located in `/opt/nginx-controller/postgres_data/`. - - - If you installed the embedded config database on an **NFS volume**, follow the steps in [(NFS) Copy Config Database Backup to Local Volume for Restoration]({{< ref "/controller/admin-guides/backup-restore/backup-restore-embedded-config-db.md#nfs-copy-config-database-backup-to-local-volume-for-restoration" >}}) to download the backup file to your local volume, and then use the `helper.sh` script to restore from it. - -  - -### (NFS) Copy Config Database Backup to Local Volume for Restoration - - - -To restore the embedded config database from a specific backup file, the file needs to be on your local volume. - -Take the following steps to copy an embedded config database backup file from an NFS volume to your local volume for restoration: - -1. Log on to the node where PostgreSQL is installed as a user with sudo privileges. - -1. Change to the `/opt/nginx-controller` directory: - - ``` bash - cd /opt/nginx-controller - ``` - -1. Create a local backup directory to copy the backup file to: - - ``` bash - mkdir local_backups - ``` - -1. Get the NFS volume details: - - ``` bash - mount | grep nfs - ``` - - The output looks similar to the following: - - ``` bash - : on type nfs4 (mount options...) - ``` - - For example: - - ``` bash - 192.0.2.1:/mnt/nfs_share/nfs_postgresql on /var/lib/kubelet/pods/1ce4e221-d6d6-434f-9e73-bc81c879530e/volumes/kubernetes.io~nfs/controller-postgres type nfs4 (mount options ...) - ``` - -1. Record the `:` details corresponding to the `nfs_postgresql` volume, namely the volume mounted on the Kubernetes `controller-postgres` container. - - For example: - - ``` bash - 192.0.2.1:/mnt/nfs_share/nfs_postgresql - ``` - -1. Create a parent directory to mount the NFS path to: - - ``` bash - sudo mkdir -p /mnt/local_pgdata - ``` - -1. Mount the NFS path: - - ``` bash - sudo mount : /mnt/local_pgdata - ``` - - For example: - - ``` bash - sudo mount 192.0.2.1:/mnt/nfs_share/nfs_postgresql /mnt/local_pgdata - ``` - -1. View the list of the available backup files. The files have the following naming scheme: `backup_.tar`. - - ```bash - ls /mnt/local_pgdata/ - ``` - -1. Copy the backup file from which you want to restore to the `local_backups/` directory: - - ``` bash - sudo cp /mnt/local_pgdata/backup_.tar local_backups/ - ``` - -1. Use the NGINX Controller `helper.sh` script to restore the backup file: - - ``` bash - /opt/nginx-controller/helper.sh backup restore local_backups/backup_.tar - ``` - -1. After the backup has been restored, you can unmount the NFS path and delete the backup file in the `local_backups` directory: - - ``` bash - sudo umount /mnt/local_pgdata - rm -i local_backups/backup_.tar - ``` - - - - -  - ---- - -## What's Next - -- [Backup & Restore the Metrics Database]({{< ref "/controller/admin-guides/backup-restore/backup-restore-metrics-db.md" >}}) - -{{< versions "3.12" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/admin-guides/backup-restore/backup-restore-external-config-db.md b/content/controller/admin-guides/backup-restore/backup-restore-external-config-db.md deleted file mode 100644 index 8ff44f638..000000000 --- a/content/controller/admin-guides/backup-restore/backup-restore-external-config-db.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -description: Learn how to back up and restore the external F5 NGINX Controller config - database. -nd-docs: DOCS-249 -title: Back Up & Restore an External Config Database -toc: true -weight: 99 -type: -- tutorial ---- - -## Overview - -Follow the steps in this guide to back up and restore an external F5 NGINX Controller config database. Use this guide if you selected the option to use an external PostgreSQL config database when you installed NGINX Controller. External config means that you set up NGINX Controller to store configuration data in your own Postgres database. - -## Before You Begin - -To backup and restore the external config database, you'll need the following: - -- Login credentials for your NGINX Controller PostgreSQL database -- A connection to your NGINX Controller PostgreSQL database -- [psql](https://www.postgresql.org/docs/9.5/app-psql.html) and [pg_dump](https://www.postgresql.org/docs/9.5/app-pgdump.html) installed on the server where you'll be performing the backup or restore - -### Set the PostgreSQL Environment Variables - -1. Log in to the NGINX Controller host using SSH. -2. Set the following environment variables using the credentials for your NGINX Controller PostgreSQL database: - - ``` bash - export PGHOST= - export PGPORT=5432 - export PGUSER= - export PGPASSWORD= - ``` - - {{< call-out "note" >}} -If you've configured PostgreSQL to use SSL, ensure that you've placed your certs in `~/.postgresql`. For more information, see [Client Certificates](https://www.postgresql.org/docs/9.5/libpq-ssl.html#LIBPQ-SSL-CLIENTCERT) in the PostgreSQL documentation. - {{< /call-out >}} - -  - ---- - -## Back Up External Config Database - -Take the following steps to back up the external NGINX Controller config database: - -1. Stop NGINX Controller: - - ``` bash - /opt/nginx-controller/helper.sh controller stop - ``` - -1. Run the following script to back up the NGINX Controller database. The backup files are saved in a directory that looks like `pgbackup_`. - - ``` bash - DATE=$(date +"%Y%m%d%H%M") - mkdir ~/pgbackup_${DATE} - - for db in common data system vault; do - pg_dump -w -E utf8 ${db} -F c -f ~/pgbackup_${DATE}/${db}-${DATE}.backup - done - ``` - -1. Start NGINX Controller: - - ``` bash - /opt/nginx-controller/helper.sh controller start - ``` - - -  - ---- - -## Restore External Config Database - -{{< call-out "important" >}}If you restore the config database on top of a new installation of NGINX Controller, make sure to follow the steps to [restore your NGINX config and encryption keys]({{< ref "/controller/admin-guides/backup-restore/backup-restore-cluster-config.md" >}}) afterward. {{< /call-out >}} - -To restore the external NGINX Controller config database: - -1. Stop NGINX Controller: - - ``` bash - /opt/nginx-controller/helper.sh controller stop - ``` - -1. Locate the backup directory and save the name as a local environment variable. The name of the backup directory follows the format `pgbackup_`. - - ``` bash - BACKUP_PATH=~/pgbackup_ - ``` - -1. Run the restore script: - - ``` bash - for backup_file in "$BACKUP_PATH"/*.backup; do - db="$(basename "$backup_file" | cut -d '-' -f 1)" - pg_restore -c -C -d "$db" "$backup_file" - done - ``` - -1. Start NGINX Controller: - - ``` bash - /opt/nginx-controller/helper.sh controller start - ``` - - -  - ---- - -## What's Next - -- [Backup & Restore the Metrics Database]({{< ref "/controller/admin-guides/backup-restore/backup-restore-metrics-db.md" >}}) - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/admin-guides/backup-restore/backup-restore-metrics-db.md b/content/controller/admin-guides/backup-restore/backup-restore-metrics-db.md deleted file mode 100644 index bd372ded2..000000000 --- a/content/controller/admin-guides/backup-restore/backup-restore-metrics-db.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -description: Learn how to back up and restore the F5 NGINX Controller analytics database. -nd-docs: DOCS-250 -title: Back Up & Restore the Analytics Database -toc: true -weight: 100 -type: -- how-to ---- - -## Overview - -This guide explains how to back up and restore the F5 NGINX Controller analytics database. Backing up and restoring the analytics data lets you preserve the history of graphs. Backing up this information is optional. - -## Back Up the Analytics Database - -Make a backup copy of the metrics database following the steps for your volume type: - -- **Local**: Make a back up copy of the metrics data that's located in `/opt/nginx-controller/clickhouse_data` by default, or on the volume that you specified when installing NGINX Controller. - -- **NFS**: Make a backup copy of all of the data in the NFS path or make a copy of the ClickHouse binary data. Refer to the official ClickHouse documentation on [Data Backup](https://clickhouse.tech/docs/en/operations/backup/). - -- **EBS**: For AWS, refer to the [Amazon EBS snapshots](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSSnapshots.html) documentation to create a volume snapshot. - -## Restore the Analytics Database - -Restore the backup copy of the metrics database following the steps for your volume type: - -- **Local**: Copy the data you backed up to `/opt/nginx-controller/clickhouse_data`. - -- **NFS**: Copy the ClickHouse binary data in the NFS path. Refer to the official ClickHouse documentation on [Data Backup](https://clickhouse.tech/docs/en/operations/backup/). - -- **EBS**: For AWS, refer to the [Amazon EBS snapshots](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSSnapshots.html) documentation to restore a volume snapshot. - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/admin-guides/config-agent/_index.md b/content/controller/admin-guides/config-agent/_index.md deleted file mode 100644 index 5d32cc45c..000000000 --- a/content/controller/admin-guides/config-agent/_index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -description: Learn how to configure and manage the interaction between the F5 NGINX - Plus data plane and NGINX Controller. -title: Configure NGINX Controller Agent -weight: 200 -url: /nginx-controller/admin-guides/config-agent/ ---- - diff --git a/content/controller/admin-guides/config-agent/about-controller-agent.md b/content/controller/admin-guides/config-agent/about-controller-agent.md deleted file mode 100644 index e5efa82c0..000000000 --- a/content/controller/admin-guides/config-agent/about-controller-agent.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -description: Learn about the NGINX Controller Agent. -nd-docs: DOCS-508 -title: Get to Know the F5 NGINX Controller Agent -toc: true -weight: 100 -type: -- concept ---- - -## Overview - -The F5 NGINX Controller Agent is a compact application written in Golang. NGINX Controller uses the Controller Agent to manage and monitor each NGINX Plus instance that the Agent is installed on. Once installed, the NGINX Controller Agent collects metrics and metadata and sends them securely to NGINX Controller for storage and visualization. - -## How NGINX Controller Agent Works - -You need to [install the NGINX Controller Agent]({{< ref "/controller/admin-guides/install/install-nginx-controller-agent.md" >}}) on all of the hosts you'd like to monitor. - -Once installed, the NGINX Controller Agent automatically starts to report metrics. You should see the real-time metrics data in the NGINX Controller user interface after about one minute. - -There's no need to manually add or configure anything in the NGINX Controller user interface after installing the Agent. When the Agent is started, the metrics and the metadata are automatically reported to NGINX Controller and are visualized in the user interface. You can, however, [configure the NGINX Controller Agent]({{< ref "/controller/admin-guides/config-agent/configure-the-agent.md" >}}) to customize how it collects and reports metrics. - -All communications between the NGINX Controller Agent and the backend are done securely over SSL/TLS. All traffic is always initiated by the NGINX Controller Agent. The backend system doesn't set up any connections back to the NGINX Controller Agent. - -## Detecting and Monitoring NGINX Instances - -The NGINX Controller Agent attempts to detect and monitor all unique NGINX process instances running on a host and collects a separate set of metrics and metadata for each. The Agent uses the following qualifications to identify unique NGINX instances: - -- A unique control process and its workers, started with an **absolute path** to a distinct NGINX binary. -- A control process running with a default config path, or with a custom path set in the command-line parameters. - -{{< call-out "caution" >}}You should not make manual changes to the `nginx.conf` file on NGINX Plus instances that are managed by NGINX Controller. Manually updating the `nginx.conf` file on managed instances may adversely affect system performance. In most cases, NGINX Controller will revert or overwrite manual updates made to `nginx.conf`.{{< /call-out >}} - -
- -## Supported Systems - -NGINX Controller, the NGINX Controller Agent, and the NGINX Controller Application Security Add-on support the following distributions and architectures. - -{{< call-out "note" >}}Refer to the [NGINX Plus Technical Specifications](https://docs.nginx.com/nginx/technical-specs/) guide for the distributions that NGINX Plus supports.{{< /call-out>}} - -{{< bootstrap-table "table table-striped table-bordered" >}} - -|Distribution
and Version|NGINX Controller
(Control Plane)|Agent
(Data Plane)|ADC App. Sec.
(Data Plane)|APIM Adv. Sec.
(Data Plane)|Notes| -|--- |--- |--- |--- |--- |--- | -|Amazon Linux
2
(x86_64)| Not supported|v3.0+ |Not supported|Not supported| | -|Amazon Linux
2017.09+
(x86_64)| Not supported |v3.0+|Not supported |Not supported| | -|CentOS
6.5+
(x86_64)| Not supported |v3.0+| Not supported |Not supported| • CentOS 6.5 and later versions in the CentOS 6 family are partially supported.
• This distribution does not support AVRD.| -|CentOS
7.4+
(x86_64)|v3.0+|v3.0+ | v3.12+ |v3.19+| • CentOS 7.4 and later versions in the CentOS 7 family are supported.| -|Debian
8
(x86_64)| Not supported |v3.0–3.21|Not supported|Not supported|• This distribution does not support AVRD.| -|Debian
9
(x86_64)|v3.0+|v3.0–3.21 | v3.12+ |v3.19+ | | -|Debian
10
(x86_64)| Not supported |v3.17+ | v3.17+ |v3.19+| See the [NGINX Plus Admin Guide](https://docs.nginx.com/nginx/) for requirements for Debian 10. | -|Red Hat Enterprise Linux
6.5+| Not supported |v3.0+| Not supported | Not supported| • RHEL 6.5 and later versions in the RHEL 6 family are partially supported.| -|Red Hat Enterprise Linux
7.4+
(x86_64)|v3.5+|v3.5+ | v3.12+|v3.19+| • RHEL 7.4 and later versions in the RHEL 7 family are supported.
• SELinux may interfere with NGINX Controller installation and operation. If you do enable SELinux, it must use permissive mode. Use of enforcing mode is not supported. | -|Red Hat Enterprise Linux
8.0+
(x86_64)|v3.22+|v3.22+ | v3.22+| Not supported | • RHEL 8.0 and later versions in the RHEL 8 family are supported.
• SELinux may interfere with NGINX Controller installation and operation. If you do enable SELinux, it must use permissive mode. Use of enforcing mode is not supported. | -|Ubuntu
18.04 LTS
(x86_64)|v3.0+|v3.0+ |v3.13+|v3.19+| | -|Ubuntu
20.04 LTS
(x86_64)|v3.20+|v3.12+|v3.16.1+|v3.19+| | - -{{< /bootstrap-table >}} - - - - -#### Analytics, Visibility, and Reporting Daemon (AVRD) - -NGINX Controller v3.1 and later use an Analytics, Visibility, and Reporting daemon (AVRD) to aggregate and report app-centric metrics, which you can use to track and check the health of your apps. To learn more about these metrics, see the [NGINX Metrics Catalog]({{< ref "/controller/analytics/catalogs/metrics.md" >}}) topic. - -{{< call-out "note" >}} -See the [NGINX Controller Technical Specifications]({{< ref "/controller/admin-guides/install/nginx-controller-tech-specs.md" >}}) for the complete list of system requirements for NGINX Controller and the NGINX Controller Agent. -{{< /call-out>}} - -## Supported Python Versions - -NGINX Controller and the NGINX Controller Agent versions 3.6 and earlier require Python 2.6 or 2.7. Python is not needed for NGINX Controller or the NGINX Controller Agent versions 3.7 and later. - -## What's Next - -- [Install the NGINX Controller Agent]({{< ref "/controller/admin-guides/install/install-nginx-controller-agent.md" >}}) -- [Customize how the NGINX Controller Agent collects metrics]({{< ref "/controller/admin-guides/config-agent/configure-the-agent.md" >}}) - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/admin-guides/config-agent/configure-metrics-collection.md b/content/controller/admin-guides/config-agent/configure-metrics-collection.md deleted file mode 100644 index c88443035..000000000 --- a/content/controller/admin-guides/config-agent/configure-metrics-collection.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -description: Contains instructions for setting up the F5 NGINX Controller Agent to - collect metrics for NGINX Plus instances. -nd-docs: DOCS-509 -title: Set up Metrics Collection -toc: true -weight: 120 -type: -- how-to ---- - -## Before You Begin - -- Before you can set up metrics collection, you first need to [install and start the F5 NGINX Controller Agent]({{< ref "/controller/admin-guides/install/install-nginx-controller-agent.md" >}}), so that the Agent can start pushing aggregated data to NGINX Controller. - -## Objectives - -Follow the steps in this guide to configure how metrics are collected and monitored. - -## Configuring NGINX for Metrics Collection - -In order to monitor an NGINX Plus instance, the NGINX Controller Agent needs to find the relevant NGINX control process and determine its key characteristics. - -The Agent is able to automatically find all relevant NGINX configuration files, parse them, extract their logical structure, and send the associated JSON data to the Controller Server for further analysis and reporting. - -### SSL Certificate Parsing and Analysis - -To parse SSL certificate metadata, the NGINX Controller Agent uses standard `openssl(1)` functions. SSL certificates are parsed and analyzed only when the corresponding [settings]({{< ref "/controller/admin-guides/config-agent/configure-the-agent.md#default-agent-settings" >}}) are turned on. SSL certificate analysis is *on* by default. - -To enable or disable analyzing SSL certs: - -1. Open the NGINX Controller user interface and log in. -2. Select the NGINX Controller menu icon, then select **Platform**. -3. On the **Platform** menu, select **Agent**. -4. On the **Default agent settings** page, select or clear the **Analyze SSL certificates** box. - -### Metrics from `/api` - -NGINX Controller uses the `/api` location on the NGINX Plus instance to collect metrics. - -When you push a configuration to an NGINX Plus instance, NGINX Controller automatically enables the `/api` location for that instance. - -{{< call-out "note" >}} -The `/api` location settings that NGINX Controller creates will override any settings that you have previously defined. -{{< /call-out >}} - -If you use NGINX Controller solely to monitor your NGINX Plus instances, you may need to enable the `/api` location on your instances manually. -Refer to the [Configuring the API](https://docs.nginx.com/nginx/admin-guide/monitoring/live-activity-monitoring/#configuring-the-api) section of the NGINX Plus Admin Guide for instructions. - -For more information about the metrics list, refer to [Overview: Metrics and Metadata]({{< ref "/controller/analytics/metrics/overview-metrics-metadata.md" >}}). - -### Metrics from `access.log` and `error.log` - -The NGINX Controller Agent collects NGINX metrics from the [access.log](http://nginx.org/en/docs/http/ngx_http_log_module.html) and the [error.log](http://nginx.org/en/docs/ngx_core_module.html#error_log) by default. - -You don't have to specifically point the Agent to either the NGINX configuration or the NGINX log files. The Agent should detect their location automatically. However, **you do need to make sure that the Agent can read the log files**. - -To do so, verify that either the `nginx` user or the [user defined in the NGINX config](https://nginx.org/en/docs/ngx_core_module.html#user) -- such as `www-data` -- can read the log files. In addition, make sure that the log files are being written normally. - -The Agent will try to detect the [log format](https://nginx.org/en/docs/http/ngx_http_log_module.html#log_format) for a particular log, so that it can parse the log correctly and extract relevant metrics data. - -#### Enable Custom `access.log` Metrics - -Some metrics included in the [NGINX Metrics reference]({{< ref "/controller/analytics/catalogs/metrics.md" >}}) are not available unless the corresponding variables are included in a custom [access.log](https://nginx.org/en/docs/http/ngx_http_log_module.html) format in the NGINX config. - -{{< call-out "note" >}} - -- Read [Configuring Logging](https://docs.nginx.com/nginx/admin-guide/monitoring/logging/#setting-up-the-access-log) in the NGINX Admin Guide. -- View the complete list of [NGINX log variables](https://nginx.org/en/docs/varindex.html). - -{{< /call-out>}}. - -Take the steps in this section to enable the NGINX Controller Agent to collect metrics from custom `access.log` variables. - -1. Add a new [access.log](https://nginx.org/en/docs/http/ngx_http_log_module.html) format to the NGINX configuration (or modify an existing one). - -2. Add the desired [NGINX variables](https://nginx.org/en/docs/varindex.html) to the log format. For example: - - ```nginx - log_format main_ext '$remote_addr - $remote_user [$time_local] "$request" ' - '$status $body_bytes_sent "$http_referer" ' - '"$http_user_agent" "$http_x_forwarded_for" ' - '"$host" sn="$server_name" ' - 'rt=$request_time ' - 'ua="$upstream_addr" us="$upstream_status" ' - 'ut="$upstream_response_time" ul="$upstream_response_length" ' - 'cs=$upstream_cache_status' ; - ``` - -3. Use the extended log format in your access log configuration: - - ```nginx - access_log /var/log/nginx/access.log main_ext; - ``` - - {{< call-out "note" >}} -By default, the Controller Agent processes all access logs that it finds in your log directory. If you define a new log file with the extended log format that contains entries that are already being logged to another access log, your metrics might be counted twice. Refer to the [Agent configuration]({{< ref "/controller/admin-guides/config-agent/configure-the-agent.md" >}}) guide to learn how to exclude specific log files from processing. - {{< /call-out >}} - -4. Set the [error.log](https://nginx.org/en/docs/ngx_core_module.html#error_log) log level to `warn`. - - ```nginx - error_log /var/log/nginx/error.log warn; - ``` - -5. [Reload](https://nginx.org/en/docs/control.html) your NGINX configuration: - - ```bash - service nginx reload - ``` - -When the Controller Agent discovers these metrics, the NGINX Controller **Analytics Dashboards Overview** will automatically update with a predefined set of graphs. -You can also use these metrics to build more specific set of [custom Dashboards]({{< ref "/controller/analytics/dashboards/custom-dashboards.md" >}}). - -### Collect Metrics from Syslog - -If you set up the Controller Agent to [use Syslog]({{< ref "/controller/admin-guides/config-agent/configure-the-agent.md#logging-to-syslog" >}}), you need to set up the Controller Agent to collect metrics from Syslog. - -Take the steps below to enable metrics collection from Syslog: - -1. Edit the NGINX configuration file. - - 1. Specify the `syslog` listener address as the first parameter to the [access.log](https://nginx.org/en/docs/http/ngx_http_log_module.html) directive. - 2. Include the `controller` tag and your preferred log format: - - ```nginx - access_log syslog:server=127.0.0.1:12000,tag=controller,severity=info main_ext; - ``` - -2. Reload NGINX: - - ```bash - service nginx reload - ``` - - For more information, see [Controlling NGINX](https://nginx.org/en/docs/control.html). - -{{< call-out "note" >}} -To send the NGINX logs to both the existing logging facility and the NGINX Controller Agent, include a separate [access.log](https://nginx.org/en/docs/http/ngx_http_log_module.html) directive for each destination. -{{< /call-out >}} - - -## What's Next - -- [Overview: NGINX Metrics and Metadata]({{< ref "/controller/analytics/metrics/overview-metrics-metadata.md" >}}) -- [What to check if the Controller Agent isn't reporting metrics]({{< ref "/controller/support/troubleshooting-controller.md#troubleshooting-metrics" >}}) - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/admin-guides/config-agent/configure-the-agent.md b/content/controller/admin-guides/config-agent/configure-the-agent.md deleted file mode 100644 index 9963d0e80..000000000 --- a/content/controller/admin-guides/config-agent/configure-the-agent.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -description: Customize the F5 NGINX Controller Agent configuration. -nd-docs: DOCS-510 -title: Configure the NGINX Controller Agent -toc: true -weight: 110 -type: -- tutorial ---- - -## Overview - -Follow the steps in this guide to customize the F5 NGINX Controller Agent configuration. - -## Default Agent Settings - -To access the **Default Agent Settings** page: - -1. Open the NGINX Controller user interface and log in. -2. Select the NGINX Controller menu icon, then select **Platform**. -3. On the **Platform** menu, select **Agent**. - -On the **Default Agent Settings** page, you can set the following default settings for the NGINX Controller Agent: - -- **NGINX configuration file analysis**. This setting is enabled by default. -- **Periodic NGINX configuration syntax checking with "nginx -t"**. This setting is disabled by default. -- **Analyzing SSL certs**. This setting is enabled by default. - -## Enable /api Location - -NGINX Controller uses the `/api` location on the NGINX Plus instance to collect metrics. - -When you push a configuration to an NGINX Plus instance, NGINX Controller automatically enables the `/api` location for that instance. - -{{< call-out "note" >}} -The `/api` location settings that NGINX Controller creates will override any settings that you have previously defined. -{{< /call-out >}} - -If you use NGINX Controller solely to monitor your NGINX Plus instances, you may need to enable the `/api` location on your instances manually. -Refer to the [Configuring the API](https://docs.nginx.com/nginx/admin-guide/monitoring/live-activity-monitoring/#configuring-the-api) section of the NGINX Plus Admin Guide for instructions. - -## Controller Agent Configuration File - -The configuration file for the NGINX Controller Agent is located at `/etc/controller-agent/agent.conf`. This configuration file is a text-based file. - -## Change the API Key - -When you first [install the NGINX Controller Agent]({{< ref "/controller/admin-guides/install/install-nginx-controller-agent.md" >}}), your API key is written to the `agent.conf` file automatically. If you ever need to change the API key, you can edit the following section in `agent.conf` accordingly: - -``` nginx -[credentials] -api_key = YOUR_API_KEY -``` - -## Change the Hostname and UUID - -To create unique objects for monitoring, the NGINX Controller Agent must be able to extract a valid hostname from the system. The hostname is also used as one of the components for generating a unique identifier. Essentially, the hostname and the UUID (universally unique identifier) unambiguously identify a particular instance of the NGINX Controller Agent to NGINX Controller. If the hostname or the UUID are changed, the NGINX Controller Agent and the server will register a new object for monitoring. - -The NGINX Controller Agent tries its best to determine the correct hostname. If the Agent cannot determine the hostname, you can set the hostname in the `agent.conf` file. Check for the following section, and provide the desired hostname here: - -``` nginx -[credentials] -.. -hostname = myhostname1 -``` - -The hostname should be real. The NGINX Controller Agent won't start unless a valid hostname is defined. The following *are not* valid hostnames: - -- localhost -- localhost.localdomain -- localhost6.localdomain6 -- ip6-localhost - -{{< call-out "note" >}} - -You can use the above method to replace the system's hostname with an arbitrary alias. Keep in mind that if you redefine the hostname for a live object, the existing object will be marked as failed in the NGINX Controller user interface. Redefining the hostname in the NGINX Controller Agent's configuration creates a new UUID and a new system for monitoring. - -Alternatively, you can define an alias for the host in the NGINX Controller user interface. Go to the **Graphs** page, select the system that you want to update, and click the gear icon. - -{{< /call-out >}} - -## Preserving the UUID across OS upgrades - -The UUID is generated based on a combination of the hostname and underlying OS functions. An upgrade to the OS may lead to a new UUID and cause previously registered agents to be offline. - -If your use case requires that the UUID persist across upgrades, you can set the `store_uuid` option in `agent.conf`: - -``` nginx -[credentials] -... -store_uuid = True -``` - -After restarting the Controller Agent -- `service controller-agent restart` -- the UUID will be persisted to `agent.conf` and used for future instance detection. - -## Set the Path to the NGINX Configuration File - -The NGINX Controller Agent detects the NGINX configuration file automatically. You shouldn't need to point the NGINX Controller Agent to the `nginx.conf` file explicitly. - -{{< call-out "caution" >}}You should not make manual changes to the `nginx.conf` file on NGINX Plus instances that are managed by NGINX Controller. Manually updating the `nginx.conf` file on managed instances may adversely affect system performance. In most cases, NGINX Controller will revert or overwrite manual updates made to `nginx.conf`.{{< /call-out >}} - -If, for some reason, the NGINX Controller Agent cannot find the NGINX configuration, you can use the following option in `/etc/controller-agent/agent.conf` to point to the configuration file: - -``` nginx -[nginx] -configfile = /etc/nginx/nginx.conf -``` - -{{< call-out "note" >}} We recommend using this option only as a workaround if needed. If you do need to add the path to the NGINX config file, we ask that you [contact NGINX Support]({{< ref "/controller/support/contact-support.md" >}}) so they can help troubleshoot the issue.{{< /call-out >}} - -## Set Host Tags - -You can define arbitrary tags on a "per-host" basis. Tags can be configured in the Controller user interface on the **Graphs** page, or set in the `/etc/controller-agent/agent.conf` file: - -``` nginx -[credentials] -tags = foo bar foo:bar -``` - -{{< call-out "note" >}} Any changes to instance Tags made in the Controller user interface will overwrite the values stored in `agent.conf`.{{< /call-out >}} - -You can use tags to build custom graphs, configure alerts, and filter the systems on the **Graphs** page in the Controller user interface. - -## Logging to Syslog - -{{< call-out "note" >}} -[NGINX Admin Guide - Logging to Syslog](https://docs.nginx.com/nginx/admin-guide/monitoring/logging/#logging-to-syslog) -{{< /call-out>}} - -The NGINX Controller Agent can collect NGINX log files using `syslog`. This could be useful when you don't keep the NGINX logs on disk, or when monitoring a container environment such as Docker with NGINX Controller. - -To configure the NGINX Controller Agent to send logs to `syslog`: - -1. Add the following to the `/etc/controller-agent/agent.conf` file: - - ``` nginx - [listeners] - keys = syslog-default - - [listener_syslog-default] - address = 127.0.0.1:12000 - ``` - -2. Restart the NGINX Controller Agent. This will reload the configuration, and the Agent will start listening on the specified IP address and port: - - ``` nginx - # service controller-agent restart - ``` - - {{< call-out "important" >}} -Make sure you [add the `syslog` settings to your NGINX configuration file]({{< ref "/controller/admin-guides/config-agent/configure-metrics-collection.md#collect-metrics-from-syslog" >}}) as well. - {{< /call-out >}} - -## Exclude Certain NGINX Log Files - -By default, the NGINX Controller Agent tries to find and watch all `access.log` files described in the NGINX configuration. If there are multiple log files where the same request is logged, the metrics may be counted more than once. - -To exclude specific NGINX log files from the metrics collection, add lines similar to the following to `/etc/controller-agent/agent.conf`: - -``` nginx -[nginx] -exclude_logs=/var/log/nginx/app1/*,access-app1-*.log,sender1-*.log -``` - -## Set Up a Proxy - -If your system is in a DMZ environment without direct access to NGINX Controller, the only way for the NGINX Controller Agent to report collected metrics to NGINX Controller is through a proxy. - -The NGINX Controller Agent will use the usual environment variables common on Linux systems (for example, `https_proxy` or `HTTP_PROXY`). However, you can also define HTTPS proxy manually in `agent.conf`. This can be done as follows: - -``` nginx -[proxies] -https = https://10.20.30.40:3030 -.. -``` - -## Controller Agent Logfile - -The NGINX Controller Agent maintains its log file in `/var/log/nginx-controller/agent.log`. - -Upon installation, the NGINX Controller Agent's log rotation schedule is added to `/etc/logrotate.d/controller-agent`. - -The normal level of logging for the NGINX Controller Agent is `INFO`. If you ever need to debug the NGINX Controller Agent, change the level to `DEBUG` as described below. - -{{< call-out "caution" >}} -The size of the NGINX Controller Agent's log file can proliferate in `DEBUG` mode. You should use `DEBUG` mode only for troubleshooting purposes. -{{< /call-out >}} - -### Change the Agent Log Level - -To change the log level for the NGINX Controller Agent: - -1. Edit the `[loggers]` section of the NGINX Controller Agent configuration file -- `/etc/controller-agent/agent.conf`. -1. Set the `level` to one of the following: - - - error - - info - - debug - - trace - - ```plaintext - [loggers] - level = DEBUG - ... - ``` - -1. [Restart the NGINX Controller Agent]({{< ref "/controller/admin-guides/install/agent-restart.md#Starting-and-Stopping-the-Agent" >}}) to make the changes take effect. - -## What's Next - -- [Set up Metrics Collection]({{< ref "/controller/admin-guides/config-agent/configure-metrics-collection.md" >}}) - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/admin-guides/config-agent/use-agent-with-docker.md b/content/controller/admin-guides/config-agent/use-agent-with-docker.md deleted file mode 100644 index 12a1786b8..000000000 --- a/content/controller/admin-guides/config-agent/use-agent-with-docker.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -description: Learn how to use the F5 NGINX Controller Agent in a Docker environment. -nd-docs: DOCS-511 -title: Use the NGINX Controller Agent with Docker -toc: true -weight: 200 -type: -- reference ---- - -## Before You Begin - -We support running the F5 NGINX Controller Agent in a Docker environment on the following distributions: CentOS, Debian, and Ubuntu. - -We **don't support** containerized instances on RHEL 7 and RHEL 8. - -For optimal performance when using the Controller Agent in a Docker environment, the number of containers shouldn't exceed the number of processors on the container host. - -## Running NGINX Controller Agent in Docker - -When running a containerized instance on an Ubuntu or Debian docker host, you need to enable cgroup swap limit capabilities in order for the NGINX Controller Agent to be able to report swap metrics for instances. See [Docker - Linux post-installation steps](https://docs.docker.com/engine/install/linux-postinstall/#your-kernel-does-not-support-cgroup-swap-limit-capabilities) for details. - -Refer to the [nginxinc/docker-nginx-controller](https://github.com/nginxinc/docker-nginx-controller) repository in GitHub for a set of guidelines that you can use today as we continue to enhance the experience. - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/admin-guides/install/_index.md b/content/controller/admin-guides/install/_index.md deleted file mode 100644 index fbede0eb5..000000000 --- a/content/controller/admin-guides/install/_index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -description: Learn how to install and update F5 NGINX Controller and the NGINX Controller - Agent. -title: Installation -weight: 100 -url: /nginx-controller/admin-guides/install/ ---- - diff --git a/content/controller/admin-guides/install/agent-restart.md b/content/controller/admin-guides/install/agent-restart.md deleted file mode 100644 index acc3e9173..000000000 --- a/content/controller/admin-guides/install/agent-restart.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -description: How to start, stop, and verify the state of the F5 NGINX Controller Agent - service. -nd-docs: DOCS-251 -title: Manage the NGINX Controller Agent Service -toc: true -weight: 210 -type: -- how-to ---- - -## Starting and Stopping the Agent - -To start, stop, and restart the F5 NGINX Controller Agent, run the following commands on the NGINX Plus system where you installed the Agent. - -Start the NGINX Controller Agent: - -```bash -service controller-agent start -``` - -Stop the NGINX Controller Agent: - -```bash -service controller-agent stop -``` - -Restart the NGINX Controller Agent: - -```bash -service controller-agent restart -``` - -## Verify that the Agent Has Started - -To verify that the NGINX Controller Agent has started, run the following command on the NGINX Plus system where you installed the Agent: - -```bash -ps ax | grep -i 'controller\-' -2552 ? S 0:00 controller-agent -``` - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/admin-guides/install/get-n-plus-cert-and-key.md b/content/controller/admin-guides/install/get-n-plus-cert-and-key.md deleted file mode 100644 index 9b980d52f..000000000 --- a/content/controller/admin-guides/install/get-n-plus-cert-and-key.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -description: How to download the F5 NGINX Plus nginx.crt and nginx.key files using - the NGINX Controller API. -nd-docs: DOCS-252 -title: Download the NGINX Plus Cert and Key Bundle -toc: true -weight: 105 -type: -- how-to ---- - -## Overview - -This topic explains how to use the [F5 NGINX Controller REST API](https://docs.nginx.com/nginx-controller/api/ctlr-platform-api/) to download your NGINX Plus `nginx.crt` and `nginx.key` files. You'll need these files if you're [installing NGINX Plus as part of an NGINX Controller trial]({{< ref "/controller/admin-guides/install/try-nginx-controller.md" >}}). - -  - -## Authenticate with the NGINX Controller 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]({{< ref "/controller/api/_index.md" >}}) documentation for information about session cookie timeouts and invalidation. - -{{< call-out "tip" >}} -You can send a GET request to the login endpoint to find the status of the session token. -{{< /call-out >}} - -For example: - -- Login and capture the session cookie: - - ```curl - curl -c cookie.txt -X POST --url 'https:///api/v1/platform/login' --header 'Content-Type: application/json' --data '{"credentials": {"type": "BASIC","username": "","password": ""}}' - ``` - -- Use the session cookie to authenticate and get the session status: - - ```curl - curl -b cookie.txt -c cookie.txt -X GET --url 'https:///api/v1/platform/login' - ``` - - -  - ---- - -## Download the NGINX Plus Certificate and Key Bundle - -To use the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}) 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: - - ```bash - 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: - - ```bash - 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 - ``` - -{{< call-out "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. -{{< /call-out >}} - - -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: - -```bash -gunzip nginx-plus-certs.gz -``` - ---- - -## What's Next - -- [Trial NGINX Controller with NGINX Plus]({{< ref "/controller/admin-guides/install/try-nginx-controller.md" >}}) - -  - -{{< versions "3.10" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/admin-guides/install/install-agent-non-root.md b/content/controller/admin-guides/install/install-agent-non-root.md deleted file mode 100644 index 8c58211cd..000000000 --- a/content/controller/admin-guides/install/install-agent-non-root.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -description: How to install the F5 NGINX Controller Agent to run as a non-root user. -nd-docs: DOCS-253 -title: Install NGINX Controller Agent for Non-root Users -toc: true -weight: 205 -type: -- tutorial ---- - -## Overview - -This document provides the instructions to run F5 NGINX Controller Agent as a non-root user, by making a few adjustments to the deployment process. - -  - ---- - -## Before You Begin - -Before you follow the steps to deploy and run the Controller Agent as a non-root user, [install NGINX Controller]({{< ref "/controller/admin-guides/install/install-nginx-controller" >}}) following the normal installation process. Once you reach the step **Install NGINX Controller Agent** follow the steps in this guide instead. - -  - ---- - -## Install NGINX Controller Agent to Run as a Non-root User - -Take the following steps to add an instance to NGINX Controller: - -1. Open the NGINX Controller user interface and log in. -1. Select the NGINX Controller menu icon, then select **Infrastructure**. -1. On the **Infrastructure** menu, select **Instances** > **Overview**. -1. On the **Instances** overview page, select **Create**. -1. On the **Create Instance** page, select **Add an existing instance**. -1. Add a name for the instance. If you don't provide a name, the hostname of the instance is used by default. -1. To add the instance to an existing Location, select a Location from the list. Or to create a Location, select **Create New**. - - {{< call-out "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]({{< ref "/controller/infrastructure/instances/manage-instances.md#delete-an-instance" >}}), and then add it back. - {{< /call-out >}} - -1. (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. -1. Use SSH to connect and log in to the NGINX instance that you want to connect to NGINX Controller. -1. Copy 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. **You need to modify this command to use a non-root user** -1. Add the parameter `CONTROLLER_USER=''` to the `curl` or `wget` command, substituting the value in the brackets with your desired non-root user. -1. (Optional) Add the parameter `CONTROLLER_GROUP=''` to the `curl` or `wget` command, substituting the value in the brackets with your desired group. If this parameter is not set, a new group with the same name as the user will be created. -1. The `curl` or `wget` command looks similar to this example after applying the required changes: - - ```bash - curl -sS -L https:///install/controller-agent > install.sh && API_KEY='' CONTROLLER_USER='' CONTROLLER_GROUP='' -i -l - ``` - - {{< call-out "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. - -If `CONTROLLER_USER` is not set, during the installation you will see the message `Installing agent to run as root` in red. - -Running agent as non-root changes the nap-syslog port to `5114` in both containerized and non-containerized instances. - - {{< /call-out >}} - -  - -After a few minutes, the NGINX instance will appear on the **Instances** overview page. - -For the NGINX Agent to run properly, NGINX Plus **must** be running as the same user and group as the Agent. To change the user and group NGINX Plus is running as after installing the agent: - -1. Manually edit the `/lib/systemd/system/nginx.service` file and under the `[Service]` block add the lines `User=` and `Group=` replacing the values in brackets with the values chosen during the installation. -1. Run `sudo chown -R : /etc/nginx/ /var/log/nginx/ /var/cache/nginx/` to change the permissions to your non-root user. -1. Ensure the ports NGINX is listening to are all above 1000: Check the NGINX `default.conf` file (usually `/etc/nginx/conf.d/default.conf`) and make sure that the `listen` values are all over `1000`. -1. (CentOS/RHEL) If you're installing the Controller Agent as a non-root user on CentOS or RHEL, make these additional changes: - - - In in the `[Service]` section of `/lib/systemd/system/nginx.service`, set the location for the `PIDfile` to: - - ```nginx - [Service] - PIDFile=/var/tmp/nginx.pid - ``` - - - In `/etc/nginx/nginx.conf`, set the `pid` directive to: - - ```nginx - pid /var/tmp/nginx.pid; - ``` - - -1. Run `sudo systemctl daemon-reload && sudo systemctl restart nginx` to pick up the new configuration. - -  - ---- - -## Verification Steps - -Run `top -u ` for your chosen user. The `/usr/bin/nginx-controller-agent` process will appear in the list of processes. - - -{{< versions "3.16" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/admin-guides/install/install-for-controller.md b/content/controller/admin-guides/install/install-for-controller.md deleted file mode 100644 index 7ddbeda31..000000000 --- a/content/controller/admin-guides/install/install-for-controller.md +++ /dev/null @@ -1,533 +0,0 @@ ---- -description: Take the steps in this guide to deploy F5 WAF for NGINX as a - datapath instance for use with NGINX Controller. -nd-docs: DOCS-645 -title: Using F5 WAF for NGINX with NGINX Controller -toc: true -weight: 500 -type: -- how-to ---- - -**Note:** Refer to the [F5 NGINX Controller Technical Specifications]({{< ref "/controller/admin-guides/install/nginx-controller-tech-specs.md" >}}) guide to find out which distributions are supported for use with NGINX Controller and NGINX Controller Agent. - -## Setup - -Before proceeding, you should review the [Prerequisites]({{< ref "/nap-waf/v4/admin-guide/install#prerequisites" >}}), [Platform Security Considerations]({{< ref "/nap-waf/v4/admin-guide/install#platform-security-considerations" >}}) and [User Permissions]({{< ref "/nap-waf/v4/admin-guide/install#user-permissions" >}}) sections of the F5 WAF for NGINX Admin Guide. - - -## Install F5 WAF for NGINX - -**Note:** If a version of F5 WAF for NGINX prior to 3.6 is required, please contact the NGINX Sales team to assist with this configuration. - -{{}} - -{{%tab name="CentOS 7.4+"%}} - -1. If you already have NGINX packages in your system, back up your configs and logs: - - ```shell - sudo cp -a /etc/nginx /etc/nginx-plus-backup - sudo cp -a /var/log/nginx /var/log/nginx-plus-backup - ``` - -2. Create the `/etc/ssl/nginx/` directory: - - ```shell - sudo mkdir -p /etc/ssl/nginx - ``` - -3. Log in to the [NGINX Customer Portal](https://my.f5.com) and download the following two files: - - ```shell - nginx-repo.key - nginx-repo.crt - ``` - - **See Also:** You can use the [NGINX Controller REST API to download the key and cert files]({{< ref "/controller/admin-guides/install/get-n-plus-cert-and-key" >}}). - -4. Copy the above two files to the CentOS server's `/etc/ssl/nginx/` directory. Use an SCP client or another secure file transfer tool to perform this task. - -5. Install prerequisite packages: - - ```shell - sudo yum install ca-certificates epel-release wget - ``` - -6. Remove any previously downloaded NGINX Plus repository file from /etc/yum.repos.d: - - ```shell - sudo rm /etc/yum.repos.d/nginx-plus-*.repo - ``` - -7. Add NGINX Plus repository by downloading the file nginx-plus-7.4.repo to /etc/yum.repos.d: - - ```shell - sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-7.4.repo - ``` - -8. Add F5 WAF for NGINX repository by downloading the file app-protect-7.repo to /etc/yum.repos.d: - - ```shell - sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/app-protect-7.repo - ``` - -9. If NGINX Plus or F5 WAF for NGINX was previously installed on the system, clean up package manager cache information: - - ```shell - sudo yum clean all - ``` - -10. Install the latest F5 WAF for NGINX package. - - **See Also:** Please refer to [NGINX App Protect Compatibility Matrix]({{< ref "/controller/admin-guides/install/nginx-controller-tech-specs.md#nginx-app-protect-compatibility-matrix" >}}) for specific version compatibility. - - If you wish to install a specific version, please replace `app-protect` with the target version, for example `app-protect-25+3.671.0`: - - ```shell - sudo yum install app-protect - ``` - -11. Check the NGINX binary version to ensure that you have NGINX Plus installed correctly: - - ```shell - sudo nginx -v - ``` - -12. Configure SELinux as appropriate per your organization’s security policies. F5 WAF for NGINX applies the prebuilt SELinux policy module during the installation. If you encounter any issues, check the [Troubleshooting Guide]({{< ref "/nap-waf/v4/troubleshooting-guide/troubleshooting#selinux" >}}). - - **Note:** NGINX Controller has specific [requirements regarding SELinux configuration]({{< ref "/controller/admin-guides/install/nginx-controller-tech-specs.md#supported-distributions" >}}). - -13. Start the NGINX service: - - ```shell - sudo systemctl start nginx - ``` - -14. Start the `bd_agent` service (for Controller ADC Agent 3.20.1 or Controller APIM Agent 3.19.2 only) - - If you plan to use this instance with Controller ADC Agent 3.20.1 or Controller APIM Agent 3.19.2, you need to start the `bd_agent`: - - ```shell - /bin/su -s /bin/bash -c '/opt/app_protect/bin/bd_agent &' nginx - ``` - -15. Verify NGINX Plus and BD processes are running: - - ```shell - ps -ef | grep nginx - ps -ef | grep bd - ``` - - **Note:** If you plan to use this instance with Controller ADC Agent 3.20.1 or Controller APIM Agent 3.19.2, also verify that `bd_agent` is running: - - ```shell - ps -ef | grep bd_agent - ``` - -16. To upgrade your signature package to the latest version and obtain the best protection, refer to [Updating App Protect Attack Signatures]({{< ref "/nap-waf/v4/admin-guide/install#centos--rhel-74--amazon-linux-2">}}). - -{{%/tab%}} - -{{%tab name="Red Hat Enterprise Linux 7.4+"%}} - -1. If you already have NGINX packages in your system, back up your configs and logs: - - ```shell - sudo cp -a /etc/nginx /etc/nginx-plus-backup - sudo cp -a /var/log/nginx /var/log/nginx-plus-backup - ``` - -2. Create the `/etc/ssl/nginx/` directory: - - ```shell - sudo mkdir -p /etc/ssl/nginx - ``` - -3. Log in to the [NGINX Customer Portal](https://my.f5.com) and download the following two files: - - ```shell - nginx-repo.key - nginx-repo.crt - ``` - -4. Copy the above two files to the RHEL server’s `/etc/ssl/nginx/` directory. Use an SCP client or another secure file transfer tool to perform this task. - -5. Install prerequisite packages: - - ```shell - sudo yum install ca-certificates wget - ``` - -6. Remove any previously downloaded NGINX Plus repository file from /etc/yum.repos.d: - - ```shell - sudo rm /etc/yum.repos.d/nginx-plus-*.repo - ``` - -7. Add NGINX Plus repository by downloading the file `nginx-plus-7.4.repo` to `/etc/yum.repos.d`: - - ```shell - sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-7.4.repo - ``` - -8. Add F5 WAF for NGINX repository by downloading the file app-protect-7.repo to /etc/yum.repos.d: - - ```shell - sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/app-protect-7.repo - ``` - -9. Enable Yum repositories to pull App Protect dependencies: - - - Download the file `dependencies.repo` to `/etc/yum.repos.d`: - - ```shell - sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/dependencies.repo - ``` - - - If you have a RHEL subscription: - - ```shell - sudo yum-config-manager --enable rhui-REGION-rhel-server-optional rhui-REGION-rhel-server-releases rhel-7-server-optional-rpms - ``` - - - If you don't have a RHEL subscription, you can pull the dependencies from the CentOS repository. - - Create a new repository, `centos.repo`, in `/etc/yum.repos.d/` with the content: - - ```shell - [centos] - name=CentOS-7 - baseurl=http://ftp.heanet.ie/pub/centos/7/os/x86_64/ - enabled=1 - gpgcheck=1 - gpgkey=http://ftp.heanet.ie/pub/centos/7/os/x86_64/RPM-GPG-KEY-CentOS-7 - ``` - -10. If NGINX Plus or F5 WAF for NGINX was previously installed on the system, clean up package manager cache information: - - ```shell - sudo yum clean all - ``` - -11. Install the latest F5 WAF for NGINX package. - - **See Also:** Please refer to [NGINX App Protect Compatibility Matrix]({{< ref "/controller/admin-guides/install/nginx-controller-tech-specs.md#nginx-app-protect-compatibility-matrix" >}}) for specific version compatibility. - - If you wish to install a specific version, please replace `app-protect` with the target version, for example `app-protect-25+3.671.0`: - - ```shell - sudo yum install app-protect - ``` - -12. Check the NGINX binary version to ensure that you have NGINX Plus installed correctly: - - ```shell - sudo nginx -v - ``` - -13. Configure SELinux as appropriate per your organization’s security policies. F5 WAF for NGINX applies the prebuilt SELinux policy module during the installation. If you encounter any issues, check the [Troubleshooting Guide]({{< ref "/nap-waf/v4/troubleshooting-guide/troubleshooting#selinux" >}}). - - **Note:** NGINX Controller has specific [requirements regarding SELinux configuration]({{< ref "/controller/admin-guides/install/nginx-controller-tech-specs.md#supported-distributions" >}}). - -14. Start the NGINX service: - - ```shell - sudo systemctl start nginx - ``` - -15. Start the `bd_agent` service (for Controller ADC Agent 3.20.1 or Controller APIM Agent 3.19.2 only) - - If you plan to use this instance with Controller ADC Agent 3.20.1 or Controller APIM Agent 3.19.2, you need to start the `bd_agent`: - - ```shell - /bin/su -s /bin/bash -c '/opt/app_protect/bin/bd_agent &' nginx - ``` - -16. Verify NGINX Plus and BD processes are running: - - ```shell - ps -ef | grep nginx - ps -ef | grep bd - ``` - - **Note:** If you plan to use this instance with Controller ADC Agent 3.20.1 or Controller APIM Agent 3.19.2, also verify that `bd_agent` is running: - - ```shell - ps -ef | grep bd_agent - ``` - -17. To upgrade your signature package to the latest version and obtain the best protection, refer to [Updating App Protect Attack Signatures]({{< ref "/nap-waf/v4/admin-guide/install#centos--rhel-74--amazon-linux-2" >}}). - -{{%/tab%}} - -{{%tab name="Debian"%}} - -**Note:** As of NGINX Plus R24, support for Debian 9 is no longer available. As a consequence, F5 WAF for NGINX 3.1 is the final version available for this operating system version. - -1. If you already have NGINX packages in your system, back up your configs and logs: - - ```shell - sudo cp -a /etc/nginx /etc/nginx-plus-backup - sudo cp -a /var/log/nginx /var/log/nginx-plus-backup - ``` - -2. Create the `/etc/ssl/nginx/` directory: - - ```shell - sudo mkdir -p /etc/ssl/nginx - ``` - -3. Log in to the [NGINX Customer Portal](https://my.f5.com) and download the following two files: - - ```shell - nginx-repo.key - nginx-repo.crt - ``` - -4. Copy the above two files to the Debian server’s `/etc/ssl/nginx/` directory. Use an SCP client or another secure file transfer tool to perform this task. - -5. Install apt utils: - - ```shell - sudo apt-get install apt-transport-https lsb-release ca-certificates wget - ``` - -6. Download and add the NGINX signing key: - - ```shell - sudo wget https://cs.nginx.com/static/keys/nginx_signing.key && sudo apt-key add nginx_signing.key - ``` - -7. Remove any previous NGINX Plus repository and apt configuration files: - - ```shell - sudo rm /etc/apt/sources.list.d/nginx-plus.list - sudo rm /etc/apt/apt.conf.d/90nginx - ``` - -8. Add NGINX Plus repository: - - ```shell - printf "deb https://pkgs.nginx.com/plus/debian `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nginx-plus.list - ``` - -9. Add F5 WAF for NGINX repository: - - ```shell - printf "deb https://pkgs.nginx.com/app-protect/debian `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nginx-app-protect.list - ``` - -10. Download the apt configuration to `/etc/apt/apt.conf.d`: - - ```shell - sudo wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90pkgs-nginx - ``` - -11. Update the repository and install the lastest supported F5 WAF for NGINX packages. - - **See Also:** Please refer to [NGINX App Protect Compatibility Matrix]({{< ref "/controller/admin-guides/install/nginx-controller-tech-specs.md#nginx-app-protect-compatibility-matrix" >}}) for specific version compatibility. - - ```shell - sudo apt-get update - sudo apt-get install nginx-plus-module-appprotect - ``` - - To install a specific version based on the NGINX Plus version, for example `r25`, follow these steps: - - ```shell - sudo apt-cache policy app-protect | grep 25+ - 25+3.760.0-1~buster 500 - 25+3.733.0-1~buster 500 - 25+3.671.0-1~buster 500 - - sudo apt-get install nginx-plus-module-appprotect=25+3.671.0-1~buster - ``` - -12. Check the NGINX binary version to ensure that you have NGINX Plus installed correctly: - - ```shell - sudo nginx -v - ``` - -13. Start the NGINX service: - - ```shell - sudo systemctl start nginx - ``` - -14. Start the `bd_agent` service (for Controller ADC Agent 3.20.1 or Controller APIM Agent 3.19.2 only) - - If you plan to use this instance with Controller ADC Agent 3.20.1 or Controller APIM Agent 3.19.2, you need to start the `bd_agent`: - - ```shell - /bin/su -s /bin/bash -c '/opt/app_protect/bin/bd_agent &' nginx - ``` - -15. Verify NGINX Plus and BD processes are running: - - ```shell - ps -ef | grep nginx - ps -ef | grep bd - ``` - - **Note:** If you plan to use this instance with Controller ADC Agent 3.20.1 or Controller APIM Agent 3.19.2, also verify that the `bd_agent` is running: - - ```shell - ps -ef | grep bd_agent - ``` - -16. To upgrade your signature package to the latest version and obtain the best protection, refer to [Updating App Protect Attack Signatures]({{< ref "/nap-waf/v4/admin-guide/install#debian-10" >}}). - -{{%/tab%}} - -{{%tab name="Ubuntu"%}} - -1. If you already have NGINX packages in your system, back up your configs and logs: - - ```shell - sudo cp -a /etc/nginx /etc/nginx-plus-backup - sudo cp -a /var/log/nginx /var/log/nginx-plus-backup - ``` - -2. Create the `/etc/ssl/nginx/` directory: - - ```shell - sudo mkdir -p /etc/ssl/nginx - ``` - -3. Log in to the [NGINX Customer Portal](https://my.f5.com) and download the following two files: - - ```shell - nginx-repo.key - nginx-repo.crt - ``` - -4. Copy the above two files to the Ubuntu server’s `/etc/ssl/nginx/` directory. Use an SCP client or another secure file transfer tool to perform this task. - -5. Install apt utils: - - ```shell - sudo apt-get install apt-transport-https lsb-release ca-certificates wget - ``` - -6. Download and add the NGINX signing key: - - ```shell - sudo wget https://cs.nginx.com/static/keys/nginx_signing.key && sudo apt-key add nginx_signing.key - ``` - -7. Remove any previous NGINX Plus repository and apt configuration files: - - ```shell - sudo rm /etc/apt/sources.list.d/nginx-plus.list - sudo rm /etc/apt/apt.conf.d/90nginx - ``` - -8. Add NGINX Plus repository: - - ```shell - printf "deb https://pkgs.nginx.com/plus/ubuntu `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nginx-plus.list - ``` - -9. Add F5 WAF for NGINX repository: - - ```shell - printf "deb https://pkgs.nginx.com/app-protect/ubuntu `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nginx-app-protect.list - ``` - -10. Download the apt configuration to `/etc/apt/apt.conf.d`: - - ```shell - sudo wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90pkgs-nginx - ``` - -11. Update the repository and install the latest F5 WAF for NGINX package. - - **See Also:** Please refer to [NGINX App Protect Compatibility Matrix]({{< ref "/controller/admin-guides/install/nginx-controller-tech-specs.md#nginx-app-protect-compatibility-matrix" >}}) for specific version compatibility. - - ```shell - sudo apt-get update - sudo apt-get install app-protect - ``` - - To install a specific version based on the NGINX Plus version, for example `r25`, follow these steps: - - ```shell - sudo apt-cache policy app-protect | grep 25+ - 25+3.760.0-1~bionic 500 - 25+3.733.0-1~bionic 500 - 25+3.671.0-1~bionic 500 - - sudo apt-get install app-protect=25+3.671.0-1~bionic - ``` - -12. Check the NGINX binary version to ensure that you have NGINX Plus installed correctly: - - ```shell - sudo nginx -v - ``` - -13. Start the NGINX service: - - ```shell - sudo systemctl start nginx - ``` - -14. Start the `bd_agent` service (for Controller ADC Agent 3.20.1 or Controller APIM Agent 3.19.2 only) - - If you plan to use this instance with Controller Agent 3.20.1, you need to start `bd_agent`: - - ```shell - /bin/su -s /bin/bash -c '/opt/app_protect/bin/bd_agent &' nginx - ``` - -15. Verify NGINX Plus and BD processes are running: - - ```shell - ps -ef | grep nginx - ps -ef | grep bd - ``` - - **Note:** If you plan to use this instance with Controller ADC Agent 3.20.1 or Controller APIM Agent 3.19.2, also verify that `bd_agent` is running: - - ```shell - ps -ef | grep bd_agent - ``` - -16. To upgrade your signature package to the latest version and obtain the best protection, refer to [Updating App Protect Attack Signatures]({{< ref "/nap-waf/v4/admin-guide/install#ubuntu-1804" >}}). - - **Note:** Ubuntu 20.04 activates **AppArmor** by default, but F5 WAF for NGINX will run in unconfined mode after being installed as it is shipped with no AppArmor profile. To benefit from AppArmor access control capabilities for F5 WAF for NGINX, you will have to write your own AppArmor profile for F5 WAF for NGINX executables found in `/opt/app_protect/bin` such that it best suits your environment. - -{{%/tab%}} - -{{%tab name="Amazon Linux 2 LTS"%}} - -Using F5 WAF for NGINX with NGINX Controller isn't supported on Amazon Linux 2 LTS. - -{{%/tab%}} - -{{%tab name="Alpine"%}} - -Using F5 WAF for NGINX with NGINX Controller isn't supported on Alpine. - -{{%/tab%}} -{{}} - -
- -## Add F5 WAF for NGINX to NGINX Controller - -If this NGINX Plus instance is already managed by Controller, [restart the Agent]({{< ref "/controller/admin-guides/install/agent-restart" >}}) after F5 WAF for NGINX is installed. - -Otherwise, complete the tasks in the NGINX Controller [Add an F5 WAF for NGINX Instance]({{< ref "/controller/infrastructure/instances/add-nap-instance.md#add-the-nginx-app-protect-instance" >}}) guide. - -## Use F5 WAF for NGINX with NGINX Controller - -**Note:** When configuring F5 WAF for NGINX as a datapath instance for NGINX Controller, **you should not modify the `nginx.conf` file**. The `nginx.conf` file will be automatically updated when enabling WAF on a Component in NGINX Controller. - -Refer to the following NGINX Controller user guides for further information about how to secure your apps and/or APIs with NGINX Controller: - -- [Learn about App Security for the NGINX Controller App Delivery module]({{< ref "/controller/app-delivery/security/concepts/what-is-waf" >}}) -- [Add Security to your Apps with the NGINX Controller App Delivery module]({{< ref "/controller/app-delivery/security/tutorials/add-app-security-with-waf" >}}) -- [Add Advanced Security (WAF) to your APIs with the NGINX Controller API Management module]({{< ref "/controller/api-management/manage-apis.md#define-the-routing-rules" >}}). diff --git a/content/controller/admin-guides/install/install-nginx-controller-agent.md b/content/controller/admin-guides/install/install-nginx-controller-agent.md deleted file mode 100644 index 65aa4ab54..000000000 --- a/content/controller/admin-guides/install/install-nginx-controller-agent.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -description: How to install, upgrade, and uninstall the F5 Controller Agent. -nd-docs: DOCS-254 -title: Install NGINX Controller Agent -toc: true -weight: 150 -type: -- tutorial ---- - -## Overview - -This page shows how to install, update, and uninstall the F5 NGINX Controller Agent. - -You can use the NGINX Controller Agent to monitor your systems with the NGINX Controller. - -## Objectives - -- Install the NGINX Controller Agent -- Upgrade the NGINX Controller Agent to a newer version -- Uninstall the NGINX Controller Agent - -## Install the NGINX Controller Agent - -{{< call-out "note" >}} If you want to run the NGINX Controller Agent as a non-root user, follow the alternative instructions in the [Install NGINX Controller Agent for Non-root User]({{< ref "/controller/admin-guides/install/install-agent-non-root.md" >}}) guide instead of the steps provided in this section. {{< /call-out>}} - -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]({{< ref "/controller/infrastructure/instances/manage-instances.md#instance-groups" >}}), 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**. - - {{< call-out "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]({{< ref "/controller/infrastructure/instances/manage-instances.md#delete-an-instance" >}}), and then add it back. - {{< /call-out >}} - - {{< call-out "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]({{< ref "/controller/app-delivery/manage-apps.md#workload-groups">}}). - {{< /call-out >}} - -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. - - {{< call-out "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. - - {{< /call-out >}} - -After a few minutes, the NGINX instance will appear on the **Instances** overview page. - - -## Update the NGINX Controller Agent - -When you [update NGINX Controller]({{< ref "/controller/admin-guides/install/install-nginx-controller.md#update-nginx-controller" >}}), you also need to update the NGINX Controller Agent software on each monitored NGINX Plus instance. - -To update the NGINX Controller Agent, take the following steps: - -1. Open the NGINX Controller user interface and log in. -1. Select the NGINX Controller menu icon, then select **Infrastructure**. -1. On the **Infrastructure** menu, select **Instances** > **Overview**. -1. On the **Instances** overview page, select **Create**. -1. Follow the instructions in the **Install Instructions** pane to connect to the NGINX instance and install the updated Controller Agent package. - - {{< call-out "note" >}} - -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 3.7 and later. - - {{< /call-out >}} - - -## Uninstall the Analytics, Visibility, and Reporting Daemon (AVRD) - -NGINX Controller uses an [Analytics, Visibility, and Reporting daemon (AVRD)]({{< ref "/controller/analytics/metrics/overview-metrics-metadata.md" >}}) to aggregate and report app-centric metrics. You can use these metrics to monitor your apps' performance and health. - -To uninstall AVRD and the supporting modules, run the following command on each dataplane instance: - -- Debian/Ubuntu - - ```bash - sudo apt-get purge avrd nginx-plus-module-metrics avrd-libs - ``` - -- RedHat/CentOS - - ```bash - sudo yum remove avrd avrd-metrics nginx-plus-module-metrics - ``` - - -## Uninstall the NGINX Controller Agent and Delete an Instance - -Take the following steps to uninstall the Controller Agent and delete an instance. - -{{< call-out "important" >}}Be sure to uninstall the Controller Agent first, before you delete an instance. If you don't uninstall the Controller Agent first, the instance may reappear in NGINX Controller after it has been deleted.{{< /call-out >}} - -1. On your NGINX Plus instance, stop the Controller Agent service: - - - On Ubuntu/Debian: - - ```bash - service controller-agent stop - ``` - - - On CentOS/Red Hat Enterprise Linux: - - ```bash - systemctl stop controller-agent - ``` - -1. Run the appropriate command for your distribution to uninstall the Controller Agent: - - - On Ubuntu/Debian: - - ``` bash - apt-get purge nginx-controller-agent - ``` - - - On CentOS/Red Hat Enterprise Linux: - - ``` bash - yum remove nginx-controller-agent - ``` - - After the package is removed, you can safely delete the files in `/etc/controller-agent/` and `/var/log/nginx-controller/`. - -1. (Optional) If you use SELinux on CentOS or Red Hat Enterprise Linux, take the following steps to remove the SELinux policy that was created when the Controller Agent was installed: - - 1. Revert the installed permissions: - - ```bash - sudo semodule -r nginx - ``` - - 1. Remove the following files: - - - `nginx.te` - - `nginx.mod` - - `nginx.pp` - -1. Delete the NGINX Plus instance from the NGINX Controller user interface: - - 1. Open the NGINX Controller user interface and log in. - - 1. Select the NGINX Controller menu icon, then select **Infrastructure**. - - 1. On the **Infrastructure** menu, select **Instances** > **Overview**. - - 1. On the **Instances** overview page, select the NGINX Plus instance that you want to delete. - - 1. Select the delete icon (trash can). - -1. Delete alerts: - - {{< call-out "note" >}}When you delete an instance, any related alerts for that instance are not deleted automatically. You can delete the alerts manually, however.{{< /call-out >}} - - 1. Open the NGINX Controller user interface and log in. - 2. On the Analytics menu, select **Alerts > Alert Rules**. - 3. Select the alert rule that you want to delete. - 4. Select the delete (trash can) icon to delete the alert rule. - 5. Select **Delete** in the pop-up box to confirm that you want to proceed. - - -## What's Next - -- [Customize how the NGINX Controller Agent collects metrics]({{< ref "/controller/admin-guides/config-agent/configure-the-agent.md" >}}) -- [Start or Stop the Agent Service]({{< ref "/controller/admin-guides/install/agent-restart.md" >}}) -- [Manage your NGINX Instances]({{< ref "/controller/infrastructure/instances/manage-instances.md" >}}) -- [Manage Locations for your Instances]({{< ref "/controller/infrastructure/locations/manage-locations.md" >}}) - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/admin-guides/install/install-nginx-controller-rhel-8.md b/content/controller/admin-guides/install/install-nginx-controller-rhel-8.md deleted file mode 100644 index 34431a5a2..000000000 --- a/content/controller/admin-guides/install/install-nginx-controller-rhel-8.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -description: This guide explains how to prepare your RHEL 8 system to install F5 NGINX - Controller and the NGINX Controller Agent. -nd-docs: DOCS-342 -title: Install NGINX Controller on RHEL 8 (experimental) -toc: true -weight: 200 -type: -- tutorial ---- - -## Preparing the F5 NGINX Controller Host - -To install NGINX Controller on RHEL 8, you must complete the following steps to allow iptables-based routing for Kubernetes. Failure to complete these steps may cause the installation to hang. - -### Update System Packages - -1. Before completing any other steps, update the packages on your system: - - ```bash - sudo yum -y upgrade - ``` - -### Install and Configure Docker - -Docker isn't available on RedHat 8 by default, so you'll need to add a Docker repository and install the required packages: - -1. Add the Docker repo: - - ```bash - sudo yum config-manager --add-repo=https://download.docker.com/linux/centos/docker-ce.repo - ``` - -1. Install the Docker packages: - - ```bash - sudo yum install docker-ce-3:19.03.15-3.el8 docker-ce-cli-1:19.03.15-3.el8 containerd.io-1.3.9-3.1.el8 - ``` - -1. Set up the Docker daemon: - - ```bash - sudo mkdir -p /etc/docker - - sudo vi /etc/docker/daemon.json - ``` - - Paste the following JSON snippet into `daemon.json`: - - ```json - { - "exec-opts": ["native.cgroupdriver=systemd"], - "log-driver": "json-file", - "log-opts": { - "max-size": "10m", - "max-file": "2" - }, - "storage-driver": "overlay2" - } - ``` - -1. Run the following commands to set up the Docker service: - - ```bash - sudo systemctl start docker.service - - sudo systemctl status docker.service - - sudo systemctl enable docker.service - ``` - -### Install Required Packages and Kernel Modules - -Take the following steps to install the required packages and kernel modules. - -1. Install the traffic control utility: - - ``` bash - sudo yum install iproute-tc - ``` - -1. Run the following commands to ensure the required kernel modules are loaded at startup: - - ```bash - cat <}}). - -## Preparing the Data Plane Host - -1. For the NGINX Controller Agent to work on RHEL 8, you need to install the following package on each data plane host: - - ``` bash - sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm - sudo dnf install -y xerces-c - ``` - -2. Complete the steps in the NGINX Controller Agent Installation guide to [install the NGINX Controller Agent]({{< ref "/controller/admin-guides/install/install-nginx-controller-agent" >}}). - -## Troubleshooting - -You may encounter the following error when installing or updating NGINX Controller on RHEL 8: - -``` text -Status code: 403 for https://cdn.redhat.com/content/dist/rhel8/8/x86_64/appstream/os/repodata/repomd.xml -``` - -In this case, update your subscription manager on each RHEL 8 host as follows: - -```bash -sudo subscription-manager refresh -``` diff --git a/content/controller/admin-guides/install/install-nginx-controller.md b/content/controller/admin-guides/install/install-nginx-controller.md deleted file mode 100644 index 63ad87cb7..000000000 --- a/content/controller/admin-guides/install/install-nginx-controller.md +++ /dev/null @@ -1,664 +0,0 @@ ---- -description: This guide explains how to install and update F5 NGINX Controller. -nd-docs: DOCS-255 -title: Install NGINX Controller -toc: true -weight: 120 -type: -- tutorial ---- - -## Overview - -F5 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 Technical Specifications]({{< ref "/controller/admin-guides/install/nginx-controller-tech-specs.md" >}}). - -  - ---- - -## Before You Begin - -Before installing NGINX Controller, review the following prerequisites. - -{{< call-out "important" >}} -NGINX Controller should be deployed on a secure, internal network only. We strongly recommend against exposing the NGINX Controller API to the internet. -{{< /call-out >}} - -Things you'll need before installing NGINX Controller: - -- The `controller-installer-.tar.gz` package, downloaded from the [MyF5 Customer Portal](https://my.f5.com/manage/s/downloads); - -- A license file for NGINX Controller, accessible via the [MyF5 Customer Portal](https://account.f5.com/myf5); - -- A dedicated environment (bare metal, VM, or cloud-hosted instance) on which to install NGINX Controller. For the supported Operating Systems and recommended specifications, see the [NGINX Controller Technical Specifications]({{< ref "/controller/admin-guides/install/nginx-controller-tech-specs" >}}) guide; - -  - ---- - -## Install NGINX Controller Prerequisites - -You can use the NGINX Controller `helper.sh prereqs` command to install the required system packages and Docker CE. - - - -| Options | Description | -|----------|-------------| -| `base` | Install the required Linux utilities. | -| `docker` | Install Docker CE. | -| `nfs` | Install NFS system packages. | - -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](https://my.f5.com/manage/s/downloads). - -1. Extract the installer package files: - - ```bash - tar xzf controller-installer-.tar.gz - ``` - -1. Run the helper script with the `prereqs` option: - - ```bash - cd controller-installer - ./helper.sh prereqs - ``` - -{{< call-out "note" >}} -After you've installed NGINX Controller, you can install any of the prerequisites by running the following command: - - ```bash -/opt/nginx-controller/helper.sh prereqs [base|docker|nfs] -``` - -{{< /call-out >}} - -  - ---- - -### Linux Utilities - -The following Linux utilities are required by the installation script. The script will let you know if any of the utilities are missing. - -- `awk` -- `bash` (4.0 or later) -- `conntrack` -- `coreutils`: `base64`, `basename`, `cat`, `comm`, `dirname`, `head`, `id`, `mkdir`, `numfmt`, `sort`, `tee` -- `curl` or `wget` -- `ebtables` -- `envsubst` (provided by the `gettext` package) -- `ethtool` -- `getent` -- `grep` -- `gunzip` (provided by the `gzip` package) -- `iproute` -- `iptables` -- `jq` (1.5 or later) -- `less` -- `openssl` -- `sed` -- `socat` -- `tar` -- `util-linux` -- `yum-plugin-versionlock` on RedHat/CentOS - -  - ---- - -### Docker Requirements - -If you have Internet access, NGINX Controller will install Docker for you as part of the installation process. - -If you prefer to install Docker on the host yourself, install the following: - -- [Docker Community Edition (CE)](https://docs.docker.com/engine/install/) 18.09 -- [Containerd.io](https://containerd.io/) 1.2.10 - -If you are using Ubuntu-20.04 and want to install Docker on your own, choose the following versions instead: - -- [Docker Community Edition (CE)](https://docs.docker.com/engine/install/ubuntu/) 19.03 -- [Containerd.io](https://containerd.io/) 1.2.13 - -{{< call-out "note" >}} -For instructions on installing Docker in offline scenarios on CentOS/RHEL 7, refer to the AskF5 [K84431427](https://support.f5.com/csp/article/K84431427) knowledge base article.{{< /call-out>}} - -{{< call-out "important" >}} You need to enable Docker log rotation to ensure 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 [Configure logging drivers](https://docs.docker.com/config/containers/logging/configure/) and [JSON File logging driver](https://docs.docker.com/config/containers/logging/json-file/).{{< /call-out >}}  - -#### Red Hat Enterprise Linux - -To create container images on Red Hat Enterprise Linux, Red Hat requires you to register and entitle the host computer on which you'll build them. In this case, the host is where you're installing NGINX Controller. Once the host is registered with Red Hat, you can install Docker from the Red Hat Enterprise Linux Extras repository. See the [Red Hat "Getting Started with Containers"](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux_atomic_host/7/html-single/getting_started_with_containers/index#getting_docker_in_rhel_7) guide for instructions. - - -  - ---- - -### Kubernetes Requirements - -NGINX Controller ships with a required version of Kubernetes and will install Kubernetes for you. Be sure to install NGINX Controller on a dedicated node that **does not** already have Kubernetes configured. - -The following table lists the Kubernetes versions that are installed by NGINX Controller: - - -| NGINX Controller | Kubernetes | -|-----------------------|--------------------| -| v3.x | v1.15.5 | - -The [Kubernetes Pod DNS config](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#pod-dns-config) has a limit of six configured DNS search domain names. This is also the [`glibc` limit](https://man7.org/linux/man-pages/man5/resolv.conf.5.html). - -In NGINX Controller, Core-DNS creates three search domains that are determined at run-time and not in `/etc/resolv.conf`: - -- `.svc.cluster.local` -- `svc.cluster.local` -- `cluster.local ` - -In general, changing the settings in NGINX Controller's underlying Kubernetes cluster is not recommended. However, if you do change the cluster's Pod config to allow additional search domains, **you should not add more than three domains**. - - -  - ---- - -### PostgreSQL (Optional) - -When installing NGINX Controller, you can choose to have NGINX Controller install and manage a self-hosted -- also known as "embedded" -- [PostgreSQL](https://www.postgresql.org/) config database for you; this is the recommended implementation. If you choose to use the embedded, self-hosted config database, you can skip this section. - -Alternatively, you can install your own PostgreSQL database for the config database, which you manage; this is sometimes referred to as an "external config database" because it is externally managed by you. Continue reading if you're providing your own PostgreSQL database. - -Refer to the AskF5 KB article [K49481224](https://support.f5.com/csp/article/K49481224) for instructions on how to install PostgreSQL on CentOS 7 and Ubuntu 18.04 for use with NGINX Controller. - -- NGINX Controller supports the following versions of PostgreSQL: - - - PostgreSQL 12.x -- works with NGINX Controller 3.9 and later. - - PostgreSQL 9.5 -- works with NGINX Controller 3.0 and later. - -- 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. -- 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.** Consult the *Secure TCP/IP Connections with SSL* topic in the PostgreSQL manual for instructions and details: - - - [PostgreSQL 9.5](https://www.postgresql.org/docs/9.5/ssl-tcp.html) - - [PostgreSQL 12.x](https://www.postgresql.org/docs/12/ssl-tcp.html) - -- When installed on external NFS or EFS volumes, the config database should support a throughput of 2 MiB/s or greater. - - -  - ---- - -## Install 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. - -{{< call-out "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](https://support.f5.com/csp/article/K82655201) and the [kubeadm installation guide](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/install-kubeadm/#before-you-begin) in the Kubernetes documentation.{{< /call-out >}} - -{{< call-out "caution" >}}**For RHEL 8 deployments**, complete the additional prerequisite steps in the [Installing NGINX on RHEL 8]({{< ref "/controller/admin-guides/install/install-nginx-controller-rhel-8.md" >}}) guide before installing NGINX Controller. RHEL 8 support is a **beta** feature.{{< /call-out >}} - -To install NGINX Controller, take the following steps: - -1. Download the NGINX Controller installer package from the [MyF5 Customer Portal](https://my.f5.com/manage/s/downloads). -1. Extract the installer package files: - - ```bash - tar xzf controller-installer-.tar.gz - ``` - -1. Run the install script: - - ```bash - cd controller-installer - ./install.sh - ``` - - {{< call-out "important" >}}Installing NGINX Controller as `root` is **not supported** on multi-node clusters. Instead, create a user with `sudo` permission for installing and performing all operations with NGINX Controller. Further, NGINX Controller scripts should also run with this dedicated user; scripts shouldn't be run as `sudo`, `sudo su`, or as the `root` user directly.{{< /call-out >}} - - {{< call-out "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=,`. {{< /call-out >}} - - The installation script walks through a series of steps and asks for the following input: - - - **Config database configuration**. Specify whether to use an embedded, self-hosted PostgreSQL database for the config database, or if you want to provide your own external PostgreSQL database. If you choose to provide your own database, make sure you've reviewed the [PostgreSQL prerequisites](#postgresql-optional). - - **Config database volume type**: Specify the type of volume to use to store the config database: local, NFS, or AWS. We recommend choosing `local` only for demo and trial purposes. - - {{< call-out "note" >}}Refer to the [NGINX Controller Technical Specifications Guide]({{< ref "/controller/admin-guides/install/nginx-controller-tech-specs.md#local-or-external-storage" >}}) for more information about the volume options and requirements.{{< /call-out>}} - - - **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. The FQDN is used by Controller Agents when connecting to NGINX Controller. - {{< call-out "note" >}}We recommend setting the FQDN to a internal address when possible, to avoid exposing the traffic between the Agent and NGINX Controller. This also reduces the external traffic in cloud environments. {{< /call-out >}} - - **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. - - {{< call-out "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. If the certificate contains a wildcard Common Name (CN=*.example.com) it must also contain a Subject Alternate Name (SAN=nginx-controller.example.com). {{< /call-out >}} - -1. Log in to the NGINX Controller browser interface by navigating to the DNS, FQDN, or IP address of the NGINX Controller host, for example, `https:///login`. Use the admin email address and password that you provided during the installation process. - -1. Once the NGINX Controller installation has completed, 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:///platform/license` and log in. -1. 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](https://account.f5.com/myf5). - -1. Select **Save license**. - -{{< call-out "note" >}} -To add a license using the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}), 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. -{{< /call-out>}} - - -  - ---- - -## Back Up Cluster Config and Encryption Keys - -After installing NGINX Controller, you should back up the cluster config and encryption keys. You'll need these if you ever need to restore the NGINX config database on top of a new NGINX Controller installation. - -- To back up the NGINX Controller cluster configuration and encryption keys: - - ```bash - /opt/nginx-controller/helper.sh cluster-config save - ``` - - The file is saved to `/opt/nginx-controller/cluster-config.tgz`. - -- To restore the cluster's config and encryption keys, take the following steps: - - ```bash - /opt/nginx-controller/helper.sh cluster-config load - ``` - -  - ---- - -## Manage the NGINX Controller Process - -You can use the `helper.sh` script to start, stop, restart, and check the status of the NGINX Controller process. - -``` bash -/opt/nginx-controller/helper.sh controller start -/opt/nginx-controller/helper.sh controller stop -/opt/nginx-controller/helper.sh controller restart -/opt/nginx-controller/helper.sh controller status -``` - -  - ---- - -## Update 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. - -When updating NGINX Controller on a multi-node cluster, run the `update.sh` script on each node individually -- the order in which you update the nodes doesn't matter. - -{{< call-out "warning" >}} Do not update the nodes in a multi-node cluster in parallel. Doing so may result in race conditions for certain jobs, such as database migrations, and may cause the cluster to become unavailable.{{< /call-out >}} - -{{< call-out "caution" >}} -We strongly recommend that you make a backup of the following information before proceeding, to avoid potential data and/or configuration loss: - -- [Back up the NGINX Controller databases]({{< ref "/controller/admin-guides/backup-restore" >}}). -- Back up the NGINX Controller cluster configuration and encryption keys. These are required if you need to restore the config database on top of a new installation of NGINX Controller. - - ```bash - /opt/nginx-controller/helper.sh cluster-config save - ``` - -- Back up the Controller Agent `agent.conf` file by copying it from its current location to a new location. This file is present on each NGINX Plus instance. - - ```bash - cp /etc/controller-agent/agent.conf - ``` - -{{< /call-out >}} - -1. Download the installer package from the [MyF5 Customer Portal](https://my.f5.com/manage/s/downloads). - -1. Extract the installer package files: - - ```bash - tar xzf controller-installer-.tar.gz - ``` - -1. Before updating, check the NGINX Controller status to confirm the installation is healthy. - - ```bash - ./helper.sh controller status - ``` - - Resolve any degradations before updating. - -1. Run the update script: - - ```bash - cd controller-installer - ./update.sh - ``` - - {{< call-out "note" >}}If you're upgrading from an older version of NGINX Controller and you installed Controller as root user, use `--allow-with-root` flag when running an update script. {{< /call-out >}} - -1. 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. - -{{< call-out "important" >}} After you upgrade NGINX Controller, you also need to [update the NGINX Controller Agent]({{< ref "/controller/admin-guides/install/install-nginx-controller-agent" >}}) to the latest version. {{< /call-out >}} - -  - ---- - -## Uninstall NGINX Controller - -To uninstall NGINX Controller, run the uninstall script: - -```bash -/opt/nginx-controller/uninstall.sh -``` - -  - ---- - -## Install NGINX Controller Agent -{{< call-out "note" >}} If you want to run the NGINX Controller Agent as a non-root user, follow the alternative instructions in the [Install NGINX Controller Agent for Non-root User]({{< ref "/controller/admin-guides/install/install-agent-non-root.md" >}}) guide instead of the steps provided in this section. {{< /call-out>}} - -Install the Controller Agent on each NGINX Plus instance that you want to manage and monitor. - -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]({{< ref "/controller/infrastructure/instances/manage-instances.md#instance-groups" >}}), 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**. - - {{< call-out "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]({{< ref "/controller/infrastructure/instances/manage-instances.md#delete-an-instance" >}}), and then add it back. - {{< /call-out >}} - - {{< call-out "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]({{< ref "/controller/app-delivery/manage-apps.md#workload-groups">}}). - {{< /call-out >}} - -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. - - {{< call-out "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. - - {{< /call-out >}} - -After a few minutes, the NGINX instance will appear on the **Instances** overview page. - - -  - ---- - -## Troubleshooting - -If NGINX Controller isn't working how you expect, see the knowledge base article [K03263142](https://support.f5.com/csp/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. - -{{< call-out "note" >}} -You will need to provide a support package if you open a ticket with NGINX Support via the [MyF5 Customer Portal](https://account.f5.com/myf5). -{{< /call-out >}}  - -```bash -/opt/nginx-controller/helper.sh supportpkg [-o|--output ] [-s|--skip-db-dump] [-t|--timeseries-dump ] -``` - - - -| Options | Description | -|----------|-------------| -| `-o` \| `--output` | Save the support package file to ``. | -| `-s` \| `--skip-db-dump` | Don't include the database dump in the support package. | -| `-t` \| `--timeseries-dump ` | Include the last `` of timeseries data in the support package (default 12 hours). | - -Take the following steps to create a support package: - -1. Open a secure shell (SSH) connection to the NGINX Controller host and log in as an administrator. - -1. Run the `helper.sh` utility with the `supportpkg` option: - - ```bash - /opt/nginx-controller/helper.sh supportpkg - ``` - - The support package is saved to: - - `/var/tmp/supportpkg-.tar.gz` - - For example: - - `/var/tmp/supportpkg-20200127T063000PST.tar.gz` - -1. Run the following command on the machine where you want to download the support package to: - - ``` bash - scp @:/var/tmp/supportpkg-.tar.gz /local/path - ``` - -  - -#### Support Package Details - -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 gathers information from the following locations: - -```md -. -├── database -│   ├── common.dump - full dump of the common database -│   ├── common.dump_stderr - any errors when dumping the database -│   ├── common-apimgmt-api-client-api-keys.txt - contents of apimgmt_api_client_api_keys table from the common database -│   ├── common-apimgmt-api-client-groups.txt - contents of apimgmt_api_client_groups table from the common database -│   ├── common-email-verification.txt - contents of email_verification table from the common database -│   ├── common-oauth-clients.txt - contents of oauth_clients table from the common database -│   ├── common-settings-license.txt - contents of settings_license table from the common database -│   ├── common-settings-nginx-plus.txt - contents of settings_nginx_plus table from the common database -│   ├── common-table-size.txt - list of all tables and their size in the common database -│   ├── data-table-size.txt - list of all tables and their size in the data database -│   ├── postgres-database-size.txt - size of every database -│   ├── postgres-long-running-queries.txt - all queries running longer than 10 seconds -│   ├── system.dump - full dump of the system database -│   ├── system-account-limits.txt - contents of account_limits table from the system database -│   ├── system-accounts.txt - contents of accounts table from the system database -│   ├── system-deleted-accounts.txt - contents of deleted_accounts table from the system database -│   ├── system-deleted-users.txt - contents of deleted_users table from the system database -│   ├── system-users.txt - contents of users table from the system database -│   └── system-table-size.txt - list of all tables and their size in the system database -├── k8s - output of `kubectl cluster-info dump -o yaml` augmented with some extra info -│   ├── apiservices.txt - output of `kubectl get apiservice` -│   ├── kube-system - contents of the kube-system namespace -│   │   ├── coredns-5c98db65d4-6flb9 -│   │   │   ├── desc.txt - pod description -│   │   │   ├── logs.txt - current logs -│   │   │   └── previous-logs.txt - previous logs, if any -│   │   ├── ... -│   │   ├── daemonsets.yaml - list of daemonsets -│   │   ├── deployments.yaml - list of deployments -│   │   ├── events.yaml - all events in this namespace -│   │   ├── namespace.yaml - details of the namespace, including finalizers -│   │   ├── pods.txt - output of `kubectl get pods --show-kind=true -o wide` -│   │   ├── pods.yaml - list of all pods -│   │   ├── replicasets.yaml - list of replicasets -│   │   ├── replication-controllers.yaml - list of replication controllers -│   │   ├── resources.txt - all Kubernetes resources in this namespace -│   │   └── services.yaml - list of services -│   ├── nginx-controller - contents of the nginx-controller namespace -│   │   ├── apigw-8fb64f768-9qwcm -│   │   │   ├── desc.txt - pod description -│   │   │   ├── logs.txt - current logs -│   │   │   └── previous-logs.txt - previous logs, if any -│   │   ├── ... -│   │   ├── daemonsets.yaml - list of daemonsets -│   │   ├── deployments.yaml - list of deployments -│   │   ├── events.yaml - all events in this namespace -│   │   ├── namespace.yaml - details of the namespace, including finalizers -│   │   ├── pods.txt - output of `kubectl get pods --show-kind=true -o wide` -│   │   ├── pods.yaml - list of all pods -│   │   ├── replicasets.yaml - list of replicasets -│   │   ├── replication-controllers.yaml - list of replication controllers -│   │   ├── resources.txt - all Kubernetes resources in this namespace -│   │   ├── services.yaml - list of services -│   ├── nodes.txt - output of `kubectl describe nodes` -│   ├── nodes.yaml - list of nodes -│   ├── resources.txt - all non-namespaced Kubernetes resources (including PersistentVolumes) -│   └── version.yaml - Kubernetes version -├── logs - copy of /var/log/nginx-controller/ -│   └── nginx-controller-install.log -├── os -│   ├── cpuinfo.txt - output of `cat /proc/cpuinfo` -│   ├── df-h.txt - output of `df -h` -│   ├── df-i.txt - output of `df -i` -│   ├── docker-container-ps.txt - output of `docker container ps` -│   ├── docker-images.txt - output of `docker images` -│   ├── docker-info.txt - output of `docker info` -│   ├── docker-stats.txt - output of `docker stats --all --no-stream` -│   ├── docker-version.txt - output of `docker version` -│   ├── du-mcs.txt - output of `du -mcs /opt/nginx-controller/* /var/log /var/lib` -│   ├── env.txt - output of `env` -│   ├── firewall-cmd.txt - output of `firewall-cmd --list-all` -│   ├── free.txt - output of `free -m` -│   ├── hostname-all-fqdns.txt - output of `hostname --all-fqdns` -│   ├── hostname-fqdn.txt - output of `hostname --fqdn` -│   ├── hostname.txt - output of `hostname` -│   ├── hostsfile.txt - output of `cat /etc/hosts` -│   ├── ip-address.txt - output of `ip address` -│   ├── ip-neigh.txt - output of `ip neigh` -│   ├── ip-route.txt - output of `ip route` -│   ├── iptables-filter.txt - output of `iptables -L -n -v` -│   ├── iptables-mangle.txt - output of `iptables -L -n -v -t mangle` -│   ├── iptables-nat.txt - output of `iptables -L -n -v -t nat` -│   ├── iptables-save.txt - output of `iptables-save` -│   ├── journal-kubelet.txt - output of `journalctl -q -u kubelet --no-pager` -│   ├── lspci.txt - output of `lspci -vvv` -│   ├── netstat-nr.txt - output of `netstat -nr` -│   ├── ps-faux.txt - output of `ps faux` -│   ├── pstree.txt - output of `pstree` -│   ├── ps.txt - output of `ps aux --sort=-%mem` -│   ├── resolvconf.txt - output of `cat /etc/resolv.conf` -│   ├── selinux-mode.txt - output of `getenforce` -│   ├── ss-ltunp.txt - output of `ss -ltunp` -│   ├── swapon.txt - output of `swapon -s` -│   ├── sysctl.txt - output of `sysctl -a --ignore` -│   ├── systemd.txt - output of `journalctl -q --utc` -│   ├── top.txt - output of `top -b -o +%CPU -n 3 -d 1 -w512 -c` -│   ├── uname.txt - output of `uname -a` -│   ├── uptime.txt - output of `cat /proc/uptime` -│   └── vmstat.txt - output of `cat /proc/vmstat` -├── timeseries -│ ├── table-sizes.stat - stat table containing controller table sizes -│ ├── events.csv - events table dump in csv -│ ├── events.sql - events table schema -│ ├── metrics_1day.csv - metrics_1day table dump in csv -│ ├── metrics_1day.sql - metrics_1day table schema -│ ├── metrics_1hour.csv - metrics_1hour table dump in csv -│ ├── metrics_1hour.sql - metrics_1hour table schema -│ ├── metrics_5min.csv - metrics_5min table dump in csv -│ ├── metrics_5min.sql - metrics_5min table schema -│ ├── metrics.csv - metrics table dump in csv -│ ├── metrics.sql - metrics table schema -│ ├── system-asynchronous-metrics.stat - shows info about currently executing events or consuming resources -│ ├── system-events.stat - information about the number of events that have occurred in the system -│ ├── system-metrics.stat - system metrics -│ ├── system-parts.stat - information about parts of a table in the MergeTree family -│ ├── system-settings.stat - information about settings that are currently in use -│ └── system-tables.stat - information about all the tables -└── version.txt - Controller version information -``` - - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/admin-guides/install/nginx-controller-tech-specs.md b/content/controller/admin-guides/install/nginx-controller-tech-specs.md deleted file mode 100644 index de963dce1..000000000 --- a/content/controller/admin-guides/install/nginx-controller-tech-specs.md +++ /dev/null @@ -1,425 +0,0 @@ ---- -description: Guidelines and recommendations for configuring F5 NGINX Controller. -nd-docs: DOCS-256 -title: NGINX Controller Tech Specs -toc: true -weight: 100 -type: -- reference ---- - -## Overview - -This guide lists the technical recommendations for F5 NGINX Controller v3 and NGINX Controller Agent. Review this guide before installing or updating NGINX Controller or NGINX Controller Agent. - -## Supported Distributions - -NGINX Controller, the NGINX Controller Agent, and the NGINX Controller Application Security Add-on support the following distributions and architectures. - -{{< call-out "note" >}}Refer to the [NGINX Plus Technical Specifications](https://docs.nginx.com/nginx/technical-specs/) guide for the distributions that NGINX Plus supports.{{< /call-out>}} - -{{< bootstrap-table "table table-striped table-bordered" >}} - -|Distribution
and Version|NGINX Controller
(Control Plane)|Agent
(Data Plane)|ADC App. Sec.
(Data Plane)|APIM Adv. Sec.
(Data Plane)|Notes| -|--- |--- |--- |--- |--- |--- | -|Amazon Linux
2
(x86_64)| Not supported|v3.0+ |Not supported|Not supported| | -|Amazon Linux
2017.09+
(x86_64)| Not supported |v3.0+|Not supported |Not supported| | -|CentOS
6.5+
(x86_64)| Not supported |v3.0+| Not supported |Not supported| • CentOS 6.5 and later versions in the CentOS 6 family are partially supported.
• This distribution does not support AVRD.| -|CentOS
7.4+
(x86_64)|v3.0+|v3.0+ | v3.12+ |v3.19+| • CentOS 7.4 and later versions in the CentOS 7 family are supported.| -|Debian
8
(x86_64)| Not supported |v3.0–3.21|Not supported|Not supported|• This distribution does not support AVRD.| -|Debian
9
(x86_64)|v3.0+|v3.0–3.21 | v3.12+ |v3.19+ | | -|Debian
10
(x86_64)| Not supported |v3.17+ | v3.17+ |v3.19+| See the [NGINX Plus Admin Guide](https://docs.nginx.com/nginx/) for requirements for Debian 10. | -|Red Hat Enterprise Linux
6.5+| Not supported |v3.0+| Not supported | Not supported| • RHEL 6.5 and later versions in the RHEL 6 family are partially supported.| -|Red Hat Enterprise Linux
7.4+
(x86_64)|v3.5+|v3.5+ | v3.12+|v3.19+| • RHEL 7.4 and later versions in the RHEL 7 family are supported.
• SELinux may interfere with NGINX Controller installation and operation. If you do enable SELinux, it must use permissive mode. Use of enforcing mode is not supported. | -|Red Hat Enterprise Linux
8.0+
(x86_64)|v3.22+|v3.22+ | v3.22+| Not supported | • RHEL 8.0 and later versions in the RHEL 8 family are supported.
• SELinux may interfere with NGINX Controller installation and operation. If you do enable SELinux, it must use permissive mode. Use of enforcing mode is not supported. | -|Ubuntu
18.04 LTS
(x86_64)|v3.0+|v3.0+ |v3.13+|v3.19+| | -|Ubuntu
20.04 LTS
(x86_64)|v3.20+|v3.12+|v3.16.1+|v3.19+| | - -{{< /bootstrap-table >}} - - - - -#### Analytics, Visibility, and Reporting Daemon (AVRD) - -NGINX Controller v3.1 and later use an Analytics, Visibility, and Reporting daemon (AVRD) to aggregate and report app-centric metrics, which you can use to track and check the health of your apps. To learn more about these metrics, see the [NGINX Metrics Catalog]({{< ref "/controller/analytics/catalogs/metrics.md" >}}) topic. - - -  - ---- - -## Storage Requirements - -The following table shows the minimum storage requirements we recommend for NGINX Controller. Your final storage requirements may differ depending on your environment, configuration, and the number of instances, apps, and APIs you're managing. Production deployments, for example, will require more storage than trial deployments. Contact your NGINX Controller sales associate if you have questions about sizing for your particular environment. - -We recommend using a local volume for the analytics and config databases for trial deployments, for simplicity's sake so you can get started using NGINX Controller right away. For production environments, we recommend using an external volume for the databases for resiliency. - -{{< bootstrap-table "table table-striped table-bordered" >}} - -| Resource | Path(s) | Minimum Storage | -|-|-|-| -| NGINX Controller | /opt/nginx-controller | 80 GB | -| Analytics database | /opt/nginx-controller/clickhouse_data | • 50 GB
• 150 GB if App Security is enabled | -| Config database | /opt/nginx-controller/postgres_data | 10 GB | -| Logs | • /var/log/nginx-controller
• /var/log/journal
• /var/log/pods
• /var/lib/docker/containers
• /var/lib/kubelet
• /var/lib/kubernetes| 15 GB cumulative | - -{{< /bootstrap-table >}} - - -  - ---- - -## Supported Deployment Environments - -You can deploy NGINX Controller v3 into the following environments: - -- Bare metal -- Public cloud: Amazon Web Services, Google Cloud Platform, Microsoft Azure -- Virtual Machine - -  - ---- - -## NGINX Plus Instances - -NGINX Controller, using the Controller Agent, can monitor and manage up to 100 [NGINX Plus](https://www.f5.com/products/nginx/nginx-plus) instances. When using Controller App Security, NGINX Controller can monitor and manage up to 30 NGINX Plus instances with NGINX App Protect installed. - - -NGINX Controller supports the following [NGINX Plus](https://www.f5.com/products/nginx/nginx-plus) versions: - -{{< bootstrap-table "table table-striped table-bordered" >}} - -| NGINX Plus | NGINX Controller | NGINX Controller ADC | NGINX Controller APIM | -|------------|------------------|----------------------|-----------------------| -| R30 | Not supported | 3.22.9+ | Not supported | -| R29 | Not supported | 3.22.9+ | 3.19.6+ | -| R28 | Not supported | 3.22.6+ | 3.19.6+ | -| R27 | Not supported | 3.22.4+ | 3.19.6+ | -| R26 | Not supported | 3.22.2+ | 3.19.6+ | -| R25 | Not supported | 3.20.1+ | 3.19.2+ | -| R24 | 3.17+ | 3.20+ | 3.18+ | -| R23 | 3.12+ | 3.20.0 - 3.22.2 | 3.18+ | -| R22 | 3.5+ | 3.20.0 - 3.22.1 | 3.18+ | -| R21 | 3.5 - 3.12 | Not supported | Not supported | -| R20 | 3.0 - 3.12 | Not supported | Not supported | -| R19 | 2.6 - 3.5 | Not supported | Not supported | - -{{< /bootstrap-table >}} - - -  - ---- - -## NGINX App Protect Compatibility Matrix - -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. - -{{< call-out "note" >}} -Refer to [Using NGINX App Protect with NGINX Controller]({{< ref "controller/admin-guides/install/install-for-controller.md" >}}) for installation instructions and additional information. -{{< /call-out>}} - -{{< bootstrap-table "table table-striped table-bordered" >}} - -| NGINX Controller version | NGINX App Protect version(s) | NGINX Plus version(s) | -|-------------------------------------|-------------------------------------------------------------------------------------------------|--------------------------------| -| NGINX Controller ADC v3.22.9 | v4.5
v4.3, v4.4
v4.0, v4.1, v4.2
v3.12, v3.11 | R30
R29
R28
R27 | -| NGINX Controller ADC v3.22.8 | v4.0, v4.1
v3.12, v3.11
v3.10.0, v3.9.1, v3.9.0
v3.8, v3.7, v3.6 | R28
R27
R26
R25 | -| NGINX Controller ADC v3.22.7 | v4.0, v4.1
v3.12, v3.11
v3.10.0, v3.9.1, v3.9.0
v3.8, v3.7, v3.6 | R28
R27
R26
R25 | -| NGINX Controller ADC v3.22.6 | v4.0, v4.1
v3.12, v3.11
v3.10.0, v3.9.1, v3.9.0
v3.8, v3.7, v3.6 | R28
R27
R26
R25 | -| NGINX Controller ADC v3.22.5 | v3.12, v3.11
v3.10.0, v3.9.1, v3.9.0
v3.8, v3.7, v3.6
v3.5, v3.4, v3.3, v3.2 | R27
R26
R25
R24 | -| NGINX Controller ADC v3.22.4 | v3.11
v3.10.0, v3.9.1, v3.9.0
v3.8, v3.7, v3.6
v3.5, v3.4, v3.3, v3.2 | R27
R26
R25
R24 | -| NGINX Controller ADC v3.22.3 | v3.10.0, v3.9.1, v3.9.0
v3.8, v3.7, v3.6
v3.5, v3.4, v3.3, v3.2
v3.1, v3.0, v2.3 | R26
R25
R24
R23 | -| NGINX Controller ADC v3.22.2 | v3.9.1, v3.9.0
v3.8, v3.7, v3.6
v3.5, v3.4, v3.3, v3.2
v3.1, v3.0, v2.3 | R26
R25
R24
R23 | -| NGINX Controller ADC v3.22, v3.22.1 | v3.8, v3.7, v3.6
v3.5, v3.4, v3.3, v3.2
v3.1, v3.0, v2.3
v2.1.1 | R25
R24
R23
R22 | -| NGINX Controller ADC v3.21 | v3.6
v3.5, v3.4, v3.3, v3.2
v3.1, v3.0, v2.3
v2.1.1 | R25
R24
R23
R22 | -| NGINX Controller ADC v3.20.1 | v3.6
v3.5, v3.4, v3.3, v3.2
v3.1, v3.0, v2.3
v2.1.1 | R25
R24
R23
R22 | -| NGINX Controller ADC v3.20 | v3.5, v3.4, v3.3, v3.2
v3.1, v3.0, v2.3
v2.1.1 | R24
R23
R22 | -| NGINX Controller APIM v3.19.2 | v3.6
v3.5, v3.4 | R25
R24 | -| NGINX Controller APIM v3.19 | v3.5, v3.4 | R24 | -| NGINX Controller v3.18 | v3.5, v3.2
v3.1, v3.0, v2.3
v2.1.1 | R24
R23
R22 | -| NGINX Controller v3.17 | v3.2
v3.1, v3.0, v2.3
v2.1.1 | R24
R23
R22 | -| NGINX Controller v3.16 | v3.1, v3.0, v2.3
v2.1.1 | R23
R22 | -| NGINX Controller v3.14, v3.15 | v3.0, v2.3
v2.1.1 | R23
R22 | -| NGINX Controller v3.13 | v2.3
v2.1.1 | R23
R22 | -| NGINX Controller v3.12 | v2.1.1 | R22 | - -{{< /bootstrap-table >}} - ---- - -## Supported Browsers - -NGINX Controller works best with the newest and the last prior version of these browsers with JavaScript, cookies, and SSL enabled: - -- [Google Chrome](https://www.google.com/chrome/) -- [Firefox](https://www.mozilla.org/en-US/firefox/new/) -- [Safari](https://support.apple.com/downloads/safari) -- [Internet Explorer](https://support.microsoft.com/en-us/help/17621/internet-explorer-downloads) and [Microsoft Edge](https://www.microsoft.com/en-us/edge) - -{{< call-out "important" >}} -You may need to turn off any ad blockers while using the NGINX Controller user interface. - -In some cases, the NGINX Controller user interface may not display analytics or security events if an ad blocker is enabled. Refer to the AskF5 KB article [K48603454](https://support.f5.com/csp/article/K48903454) to learn more about this issue and how to resolve it. -{{< /call-out >}} - - -  - ---- - -## Hardware Specifications - -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]({{< ref "/controller/admin-guides/install/nginx-controller-tech-specs.md#storage-requirements" >}}) section for a categorized list of the storage requirements. - -The NGINX Controller Agent consumes as little memory and CPU as possible. CPU usage should be under 10%, and RSS memory consumption should be just a few dozen MBs. If you notice the NGINX Controller Agent consuming resources at a higher rate, you should [contact NGINX Support]({{< ref "/controller/support/contact-support.md" >}}) for assistance. - -  - ---- - -## NGINX Controller Database Requirements - -When installing NGINX Controller, you can choose the type of volume to use for the analytics and config databases. The types of volumes that are supported are: - -- [Local Storage](#local-storage) -- [NFS](#nfs) -- [AWS EBS](#aws-ebs) - -We recommend using a local volume for the analytics and config databases for trial deployments, for simplicity's sake so you can get started using NGINX Controller right away. For production environments, we recommend using an external volume for the databases for resiliency. - -  - -### Local Storage - -When using local storage for the analytics and/or config database, we recommend the following specs: - -- 100 IOPS -- 155–255 GB free disk space. 255 GB of free space is recommended if NGINX Controller App Security is enabled. See the [Storage Requirements]({{< ref "/controller/admin-guides/install/nginx-controller-tech-specs.md#storage-requirements" >}}) section for a categorized list of the storage requirements. - -{{< call-out "tip" >}} -To conserve IO and/or disk space, you can use a separate disk for the local storage directory `/opt/nginx-controller/clickhouse_data`. -{{< /call-out >}} - -  - -### NFS - -To use NFS for external storage for the analytics and/or config database, consider the following: - -- Make certain that the NFS version used by the server is supported by the client system where you're installing NGINX Controller. -- If you're using NFS v4 file locking or Network Lock Manager (NLM) on the NFS server, make sure that the client system that's running your NGINX Controller has access to the mount point. -- Install the `nfs-common` (on Ubuntu/Debian) or `nfs-utils` (on CentOS/RedHat) package on all hosts on which NGINX Controller will be installed. -- The `no_root_squash` option must be set for the mount point on the NFS server. If this is not allowed, the owner of the path used for the analytics database must be set to `101:101` and owner of the path for config database must be set to `70:70`. -- The config database should support a throughput of 2 MiB/s or greater. - -  - -### AWS EBS - -{{< call-out "important" >}} -If you plan to run NGINX Controller on AWS EC2 instances, we recommend using NFS shares for the external volumes. Using EBS shares for multi-node clusters is not recommended because of the [EBS Availability Zone limitations](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volumes-multi.html#considerations); for example, the requirement to have EC2 instances and EBS volumes in the same Availability Zone. -{{< /call-out >}} - -If you are installing NGINX Controller on [AWS EC2 instances](https://aws.amazon.com/ec2/getting-started/) and plan to use EBS volumes for the analytics and/or config database, consider the following: - -You will need add an IAM role like that shown below. - -- IAM Role for [Single-Node Installation]({{< ref "/controller/admin-guides/install/install-nginx-controller.md" >}}) - - ```json - { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "autoscaling:DescribeAutoScalingGroups", - "autoscaling:DescribeLaunchConfigurations", - "autoscaling:DescribeTags", - "ec2:DescribeInstances", - "ec2:DescribeRegions", - "ec2:DescribeRouteTables", - "ec2:DescribeSecurityGroups", - "ec2:DescribeSubnets", - "ec2:DescribeVolumes", - "ec2:CreateSecurityGroup", - "ec2:CreateTags", - "ec2:CreateVolume", - "ec2:ModifyInstanceAttribute", - "ec2:ModifyVolume", - "ec2:AttachVolume", - "ec2:AuthorizeSecurityGroupIngress", - "ec2:CreateRoute", - "ec2:DeleteRoute", - "ec2:DeleteSecurityGroup", - "ec2:DeleteVolume", - "ec2:DetachVolume", - "ec2:RevokeSecurityGroupIngress", - "ec2:DescribeVpcs", - "iam:CreateServiceLinkedRole", - "kms:DescribeKey" - ], - "Resource": [ - "*" - ] - } - ] - } - ``` - -- IAM Role for [Multi-Node Installation]({{< ref "/controller/admin-guides/install/resilient-cluster-aws.md" >}}) - - ```json - { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "autoscaling:DescribeAutoScalingGroups", - "autoscaling:DescribeLaunchConfigurations", - "autoscaling:DescribeTags", - "ec2:DescribeInstances", - "ec2:DescribeRegions", - "ec2:DescribeRouteTables", - "ec2:DescribeSecurityGroups", - "ec2:DescribeSubnets", - "ec2:DescribeVolumes", - "ec2:CreateSecurityGroup", - "ec2:CreateTags", - "ec2:CreateVolume", - "ec2:ModifyInstanceAttribute", - "ec2:ModifyVolume", - "ec2:AttachVolume", - "ec2:AuthorizeSecurityGroupIngress", - "ec2:CreateRoute", - "ec2:DeleteRoute", - "ec2:DeleteSecurityGroup", - "ec2:DeleteVolume", - "ec2:DetachVolume", - "ec2:RevokeSecurityGroupIngress", - "ec2:DescribeVpcs", - "elasticloadbalancing:AddTags", - "elasticloadbalancing:AttachLoadBalancerToSubnets", - "elasticloadbalancing:ApplySecurityGroupsToLoadBalancer", - "elasticloadbalancing:CreateLoadBalancer", - "elasticloadbalancing:CreateLoadBalancerPolicy", - "elasticloadbalancing:CreateLoadBalancerListeners", - "elasticloadbalancing:ConfigureHealthCheck", - "elasticloadbalancing:DeleteLoadBalancer", - "elasticloadbalancing:DeleteLoadBalancerListeners", - "elasticloadbalancing:DescribeLoadBalancers", - "elasticloadbalancing:DescribeLoadBalancerAttributes", - "elasticloadbalancing:DetachLoadBalancerFromSubnets", - "elasticloadbalancing:DeregisterInstancesFromLoadBalancer", - "elasticloadbalancing:ModifyLoadBalancerAttributes", - "elasticloadbalancing:RegisterInstancesWithLoadBalancer", - "elasticloadbalancing:SetLoadBalancerPoliciesForBackendServer", - "elasticloadbalancing:AddTags", - "elasticloadbalancing:CreateListener", - "elasticloadbalancing:CreateTargetGroup", - "elasticloadbalancing:DeleteListener", - "elasticloadbalancing:DeleteTargetGroup", - "elasticloadbalancing:DescribeListeners", - "elasticloadbalancing:DescribeLoadBalancerPolicies", - "elasticloadbalancing:DescribeTargetGroups", - "elasticloadbalancing:DescribeTargetHealth", - "elasticloadbalancing:ModifyListener", - "elasticloadbalancing:ModifyTargetGroup", - "elasticloadbalancing:RegisterTargets", - "elasticloadbalancing:DeregisterTargets", - "elasticloadbalancing:SetLoadBalancerPoliciesOfListener", - "iam:CreateServiceLinkedRole", - "kms:DescribeKey" - ], - "Resource": [ - "*" - ] - } - ] - } - ``` - -  - ---- - -## Supported PostgreSQL Versions - -NGINX Controller supports the following versions of PostgreSQL: - -- PostgreSQL 12.x -- works with NGINX Controller 3.9 and later. -- PostgreSQL 9.5 -- works with NGINX Controller 3.0 and later. - -For a system monitoring **100 NGINX Plus instances**, we recommend at least **32 GB of database storage**. Database storage requirements can vary, depending on the number of NGINX Plus instances, components, published API specs, and the churn rate for configuration changes. For monitor-only implementations, the database storage needs are small; for API Management (APIM) and/or App Delivery Controller (ADC) implementations in production, the storage needs are greater. - -{{< call-out "important" >}} -If you use PostgreSQL 12, we recommend disabling [Just-in-Time (JIT)](https://www.postgresql.org/docs/12/jit.html) compilation to improve NGINX Controller's performance. To disable JIT, edit the `postgresql.conf` file and set `jit=off`. -{{< /call-out >}} - - -  - ---- - -## Firewall/IP Settings - -Configure NGINX Controller with the following firewall settings: - -{{< bootstrap-table "table table-striped table-bordered" >}} - -|Port| Used by | Used for| -|---|---|---| -| 5432 TCP | NGINX Controller database | Incoming connections to the NGINX Controller database from the NGINX Controller host. This is the default PostgreSQL port. | -| 443 TCP | • NGINX Controller
• NGINX Controller licensing | • Incoming connections to NGINX Controller from a browser; for example, from an internal network and NGINX Plus instances
• Incoming and outgoing connections used to used to validate the entitlements for your NGINX Controller license | -| 8443 TCP | NGINX Controller | Incoming connections from NGINX Plus instances
You need to **open** port 8443 TCP if you're running **NGINX Controller v3.18.2 or earlier**| -| 8883 TCP | NGINX Controller licensing | Incoming and outgoing connections used to validate the entitlements for your NGINX Controller license
Port 8883 TCP needs to be **opened** only if you're running **NGINX Controller v3.15 or earlier**| - -{{< /bootstrap-table >}} - -If you have a firewall running on the NGINX Controller host, enable NAT (masquerade) and open the following ports. These ports are used for **internal traffic** only and don't need to be open to the outside: - -{{< bootstrap-table "table table-striped table-bordered" >}} - -|Port| Used by | Used for| -|---|---|---| -|2379 TCP
2380 TCP
6443 TCP|NGINX Controller|Incoming requests to the Kubernetes control plane; used for the Kubernetes API server and etcd| -|10250 TCP|NGINX Controller|Incoming requests to the Kubernetes worker node; used for the Kubelet API| -|10251 TCP|NGINX Controller|Incoming requests to the Kubernetes kube-scheduler; used for the pod scheduling| -|10252 TCP|NGINX Controller|Incoming requests to the Kubernetes kube-controller-manager; used for regulating the state of the system| -|8472 UDP|NGINX Controller|Used for pod-to-pod communication in multi-node resilient clusters| - -{{< /bootstrap-table >}} - -For more information about these ports, see the Kubernetes guide [Installing kubeadm](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/install-kubeadm/#check-required-ports). - - -  - ---- - -## Supported Python Versions - -NGINX Controller and the NGINX Controller Agent versions 3.6 and earlier require Python 2.6 or 2.7. Python is not needed for NGINX Controller or the NGINX Controller Agent versions 3.7 and later. - -  - ---- - -## Open-Source Licenses - -The list of open-source packages and their licenses used by NGINX Controller can be found in the downloaded file that is part of the NGINX Controller package. On your NGINX Controller host, see `controller-installer/files/license-controller.md`. - -In addition, see the AskF5 KB article [Third-party software for NGINX Controller controller-datacollection-components](https://support.f5.com/csp/article/K30028643) for third-party software packages that may be used by or distributed with controller-datacollection-components. This information is not included in the `license-controller.md` that's mentioned above. - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/admin-guides/install/resilient-cluster-aws.md b/content/controller/admin-guides/install/resilient-cluster-aws.md deleted file mode 100644 index 839cc8f2e..000000000 --- a/content/controller/admin-guides/install/resilient-cluster-aws.md +++ /dev/null @@ -1,332 +0,0 @@ ---- -description: This guide explains how to deploy F5 NGINX Controller as a multi-node - resilient cluster on AWS. -nd-docs: DOCS-257 -title: Deploy NGINX Controller as a Resilient Cluster on AWS -toc: true -weight: 310 -type: -- tutorial ---- - -## Overview - -Complete the steps in this guide to deploy F5 NGINX Controller as a resilient, three-node cluster on AWS. A multi-node cluster ensures that NGINX Controller stays up even if one of the control-plane hosts becomes unavailable. - -### Failure Tolerance - -To be resilient, a cluster requires three working nodes. That's two nodes for a quorum and one node for failure tolerance. - -If a node fails in a resilient cluster, NGINX Controller automatically redirects traffic to the other working nodes. A multi-node cluster is operational with only two nodes; however, a two-node cluster isn't resilient to further failures. If one of the nodes in a multi-node cluster becomes degraded or fails, you must take action **as soon as possible** to recover or replace the failed node or risk losing resiliency. - -{{< call-out "important" >}}The failover time can take **up to 5 minutes** when a node fails. During this time, NGINX Controller may be unavailable while services are migrated and restarted. Resiliency will be restored once there are **three working nodes** in the cluster. -{{< /call-out >}} - -The following table shows how many nodes are needed for a cluster to have a quorum and what the failure tolerance is: - - - -| Cluster Size | Quorum | Failure Tolerance | -|--------------|--------|-------------------| -| 1 | 1 | 0 | -| 2 | 2 | 0 | -| 3 | 2 | 1 | - -Larger clusters aren't supported. - -  - ---- - -## Before You Begin - -### Implementation Considerations - -Before installing or configuring NGINX Controller as a multi-node cluster, review the following list of considerations to assist with planning: - -- Configuring NGINX Controller as a multi-node cluster on AWS requires **NGINX Controller 3.14 or later**. To upgrade from an earlier version, refer to the [Update NGINX Controller]({{< ref "/controller/admin-guides/install/install-nginx-controller.md#update-nginx-controller" >}}) steps for instructions. -- Data migration is not supported, so it's not possible to implement a multi-node cluster with local volumes without reinstalling NGINX Controller. -- If you plan to run NGINX Controller on AWS EC2 instances, we recommend using NFS shares for the external volumes. Using EBS shares for multi-node clusters is not recommended because of the [EBS Availability Zone limitations](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volumes-multi.html#considerations); for example, the requirement to have EC2 instances and EBS volumes in the same Availability Zone. -- Cluster config changes are orchestrated by a primary control plane node that writes to the external config database. Each NGINX Controller control plane node hosts a set of services (pods) that read and write data. Only the node that hosts the pod that manages the config data writes to the external config database. - - - - -  - ---- - -### Prerequisites - -{{< call-out "important" >}}If you plan to run NGINX Controller on AWS EC2 instances, we recommend you use NFS shares for the external volumes. Using EBS shares for multi-node clusters is not recommended because of the [EBS Availability Zone limitations](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volumes-multi.html#considerations).{{< /call-out >}} - -Things you'll need before installing NGINX Controller as a resilient cluster: - -- Three hosts on which you can install NGINX Controller to create a cluster -- The `controller-installer-.tar.gz` package, which you can get from the [MyF5 Customer Portal](https://my.f5.com/manage/s/downloads). You need to upload and extract this tarball **on each host**. -- A license file for NGINX Controller -- A tool to send API requests, such as Postman or curl -- An external volume for the config database - - When installing NGINX Controller, you can choose to have NGINX Controller install and manage a self-hosted -- also known as "embedded" -- [PostgreSQL](https://www.postgresql.org/) database for you; this is the recommended implementation. Alternatively, you can [install your own PostgreSQL database for the config database]({{< ref "/controller/admin-guides/install/install-nginx-controller.md#postgresql-optional" >}}), which you manage; this is sometimes referred to as an "external config database" because it is externally managed by you. Regardless of whether you use an embedded or an externally managed config database, the config database must be on an external volume for resilient clusters. - -- An external volume for the analytics database - -  - ---- - -## Configure IAM Roles - -{{< call-out "important" >}}If you plan to run NGINX Controller on AWS EC2 instances, we recommend using NFS shares for the external volumes. Using EBS shares for multi-node clusters is not recommended because of the [EBS Availability Zone limitations](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volumes-multi.html#considerations); for example, the requirement to have EC2 instances and EBS volumes in the same Availability Zone.{{< /call-out >}} - -If you are installing NGINX Controller on [AWS EC2 instances](https://aws.amazon.com/ec2/getting-started/) and plan to use EBS volumes for the analytics and/or config database, you will need to add an IAM role like the one shown below. This will also allow the automatic creation of Elastic Load Balancers (ELBs). Additionally, for successful automatic creation of ELBs, all the EC2 instances that are or will be part of the cluster must be tagged with the following key-value pair: - `kubernetes.io/cluster/NGINX-CONTROLLER : owned` - -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "autoscaling:DescribeAutoScalingGroups", - "autoscaling:DescribeLaunchConfigurations", - "autoscaling:DescribeTags", - "ec2:DescribeInstances", - "ec2:DescribeRegions", - "ec2:DescribeRouteTables", - "ec2:DescribeSecurityGroups", - "ec2:DescribeSubnets", - "ec2:DescribeVolumes", - "ec2:CreateSecurityGroup", - "ec2:CreateTags", - "ec2:CreateVolume", - "ec2:ModifyInstanceAttribute", - "ec2:ModifyVolume", - "ec2:AttachVolume", - "ec2:AuthorizeSecurityGroupIngress", - "ec2:CreateRoute", - "ec2:DeleteRoute", - "ec2:DeleteSecurityGroup", - "ec2:DeleteVolume", - "ec2:DetachVolume", - "ec2:RevokeSecurityGroupIngress", - "ec2:DescribeVpcs", - "elasticloadbalancing:AddTags", - "elasticloadbalancing:AttachLoadBalancerToSubnets", - "elasticloadbalancing:ApplySecurityGroupsToLoadBalancer", - "elasticloadbalancing:CreateLoadBalancer", - "elasticloadbalancing:CreateLoadBalancerPolicy", - "elasticloadbalancing:CreateLoadBalancerListeners", - "elasticloadbalancing:ConfigureHealthCheck", - "elasticloadbalancing:DeleteLoadBalancer", - "elasticloadbalancing:DeleteLoadBalancerListeners", - "elasticloadbalancing:DescribeLoadBalancers", - "elasticloadbalancing:DescribeLoadBalancerAttributes", - "elasticloadbalancing:DetachLoadBalancerFromSubnets", - "elasticloadbalancing:DeregisterInstancesFromLoadBalancer", - "elasticloadbalancing:ModifyLoadBalancerAttributes", - "elasticloadbalancing:RegisterInstancesWithLoadBalancer", - "elasticloadbalancing:SetLoadBalancerPoliciesForBackendServer", - "elasticloadbalancing:AddTags", - "elasticloadbalancing:CreateListener", - "elasticloadbalancing:CreateTargetGroup", - "elasticloadbalancing:DeleteListener", - "elasticloadbalancing:DeleteTargetGroup", - "elasticloadbalancing:DescribeListeners", - "elasticloadbalancing:DescribeLoadBalancerPolicies", - "elasticloadbalancing:DescribeTargetGroups", - "elasticloadbalancing:DescribeTargetHealth", - "elasticloadbalancing:ModifyListener", - "elasticloadbalancing:ModifyTargetGroup", - "elasticloadbalancing:RegisterTargets", - "elasticloadbalancing:DeregisterTargets", - "elasticloadbalancing:SetLoadBalancerPoliciesOfListener", - "iam:CreateServiceLinkedRole", - "kms:DescribeKey" - ], - "Resource": [ - "*" - ] - } - ] -} -``` - -  - ---- - -## Install NGINX Controller - -- Complete the steps in the [NGINX Controller Installation Guide]({{< ref "/controller/admin-guides/install/install-nginx-controller.md" >}}) to install NGINX Controller on the first node. - -  - ---- - -## License NGINX Controller - -- Follow the steps to [license NGINX Controller]({{< ref "/controller/platform/licensing-controller.md" >}}). - -  - ---- - -## Add Nodes to the Cluster - -Nodes are additional control-plane hosts that you can add to your cluster to improve uptime resilience. For a resilient cluster, you should have at least three nodes, of which **two nodes must always be operational**. - -{{< call-out "important" >}} -When adding a third node to the cluster for the first time, NGINX Controller may become momentarily unavailable while the cluster is being created. For this reason, we recommend updating NGINX Controller during a planned maintenance window to minimize disruptions. -{{< /call-out >}} - -Take the following steps to add a node to the cluster: - -1. Open the NGINX Controller web interface and log in. -1. Select the NGINX Controller menu icon, then select **Platform**. -1. On the **Platform** menu, select **Cluster**. -1. On the **Cluster** overview page, select **Create Node**. -1. Add a name for the node. -1. (Optional) Add a description. -1. Add the hostname or IP address -- or both -- for the node. -1. Select **Save**. The new node appears in the list of nodes on the **Cluster** overview page with a `Configuring` status. -1. Choose the new node's name in the list, then select **View** (eye icon). A page displays with command-line instructions for adding the node. -1. Copy the `install.sh` command and join-key that are shown. -1. Open an SSH connection to the node that you're adding to the cluster. -1. (Optional) If you're adding a node that was previously deleted, uninstall NGINX Controller from the node if you haven't already, and then continue with the remaining steps in this procedure: - - ```bash - /opt/nginx-controller/uninstall.sh - ``` - -1. Upload and extract the `controller-installer-.tar.gz` tarball. -1. Run the `install.sh` command with the join-key that you copied in the previous step. If you get an error that the join-key has expired, you can get a new one by following the steps in this topic to add a node using the web interface or the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}). - - ```bash - cd controller-installer - ./install.sh --join-key - ``` - -1. After the installation finishes, the node status in the web interface changes to `Configured`. -1. Repeat these steps for each node that you want to add to the cluster. - -{{< call-out "note" >}} -To add nodes to your cluster using the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}), send a POST request to the `/platform/nodes` endpoint. -{{< /call-out>}} - -  - ---- - -## Add Load Balancer Alias to FQDN - -You must add the hostname or IP address for the load balancer as a CNAME or A record for the domain that's used as the Fully Qualified Domain Name (FQDN) for NGINX Controller. - -To get the hostname or IP address for the load balancer using the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}), send a GET request to the `/platform/global` endpoint. - -  - ---- - -## Delete a Node - -There might be situations when you need to delete a node, either temporarily for maintenance or permanently to decommission a node. - -If you need to remove a node temporarily, follow the steps in the [Add Nodes to the Cluster](#add-nodes-to-the-cluster) topic when you are ready to re-add it. Make sure to uninstall NGINX Controller from the node before re-installing NGINX Controller with the new join-key. - -{{< call-out "important" >}} -Deleting nodes can cause NGINX Controller to become momentarily unavailable while the cluster is being updated. For this reason, we recommend updating NGINX Controller during a planned maintenance window to minimize disruptions. When deleting nodes, make sure that **at least two nodes are always operational**. If the cluster has fewer than two working nodes, NGINX Controller may become unresponsive, and you may not be able to add new nodes. -{{< /call-out >}} - -{{< call-out "note" >}} -To delete nodes from your cluster using the [NGINX Controller API Reference]({{< ref "/controller/api/_index.md" >}}), send a DELETE request to the Nodes endpoint. -{{< /call-out>}} - -To delete a node from the cluster using the web interface: - -1. Open the NGINX Controller web interface and log in. -1. Select the NGINX Controller menu icon, then select **Platform**. -1. On the **Platform** menu, select **Cluster**. -1. On the **Cluster** overview page, choose the node you want to delete, then select **Delete** (trash icon). -1. Select **Delete** to confirm. -1. To finish deleting a node from the cluster, uninstall NGINX Controller from the node: - - 1. SSH into the node that you're deleting from the cluster. - 1. Run the NGINX Controller uninstall script: - - ```bash - /opt/nginx-controller/uninstall.sh - ``` - -{{< call-out "note" >}} -To delete nodes from your cluster using the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}), send a DELETE request to the `/platform/nodes` endpoint. -{{< /call-out>}} - -  - ---- - -## Replace a Failed Node - -To be resilient, a cluster requires three working nodes. That's two nodes for a quorum and one node for failure tolerance. - -If one of the nodes in a multi-node cluster becomes degraded or fails, you must take action **as soon as possible** to recover or replace the failed node or risk losing resiliency. - -To replace a failed node: - -1. [Delete the failed node](#delete-a-node). -1. [Add a new node](#add-nodes-to-a-cluster). - -  - ---- - -## Updating a Cluster - -When updating NGINX Controller on a multi-node cluster, run the `update.sh` script on each node individually -- the order in which you update the nodes doesn't matter. - -{{< call-out "warning" >}}Do not update the nodes in a multi-node cluster in parallel. Doing so may result in race conditions for certain jobs, such as database migrations, and may cause the cluster to become unavailable.{{< /call-out >}} - -{{< call-out "important" >}} -Active users will be logged out from NGINX Controller during an update. We recommend updating NGINX Controller during a planned maintenance window to minimize disruptions. -{{< /call-out >}} - -To update your cluster to a newer version of NGINX Controller, take the following steps: - -1. Before updating the cluster, [check each node's status]({{< ref "/controller/platform/manage-cluster.md#view-node-status" >}}) to confirm the nodes are healthy. Resolve any degradations before updating. -1. Download the new installer package from the [MyF5 Customer Portal](https://my.f5.com/manage/s/downloads). - -1. Extract the installer package and save the contents to each node: - - ```bash - tar xzf controller-installer-.tar.gz - ``` - -1. Run the update script on each node -- the order in which you update the nodes doesn't matter: - - ```bash - cd controller-installer - ./update.sh - ``` - -  - -{{< versions "3.14" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/admin-guides/install/resilient-cluster-private-cloud.md b/content/controller/admin-guides/install/resilient-cluster-private-cloud.md deleted file mode 100644 index 5672df653..000000000 --- a/content/controller/admin-guides/install/resilient-cluster-private-cloud.md +++ /dev/null @@ -1,365 +0,0 @@ ---- -description: This guide explains how to deploy F5 NGINX Controller as a multi-node - resilient cluster on a private cloud. -nd-docs: DOCS-258 -title: Deploy NGINX Controller as a Resilient Cluster on a Private Cloud -toc: true -weight: 300 -type: -- tutorial ---- - -## Overview - -Complete the steps in this guide to deploy F5 NGINX Controller as a resilient, three-node cluster on your private cloud. A multi-node cluster ensures that NGINX Controller stays up even if one of the control-plane hosts becomes unavailable. - -The diagram below shows how the different objects in a multi-node NGINX Controller cluster relate to each other. The control nodes communicate with an embedded, self-hosted database that is stored on an external volume. The NGINX Controller Agent -- and NGINX Controller users -- can access the cluster via a load balancer or floating IP address that is associated with NGINX Controller's FQDN. If a node in the cluster becomes unavailable for any reason, traffic is re-routed automatically to an available node. - -{{< img src="/ctlr/img/multi-node-diagram.png" alt="Diagram showing the relationship of objects in a multi-node cluster." width="639" height="689" >}} - - -### Failure Tolerance - -To be resilient, a cluster requires three working nodes. That's two nodes for a quorum and one node for failure tolerance. - -If a node fails in a resilient cluster, NGINX Controller automatically redirects traffic to the other working nodes. A multi-node cluster is operational with only two nodes; however, a two-node cluster isn't resilient to further failures. If one of the nodes in a multi-node cluster becomes degraded or fails, you must take action **as soon as possible** to recover or replace the failed node or risk losing resiliency. - -{{< call-out "important" >}}The failover time can take **up to 5 minutes** when a node fails. During this time, NGINX Controller may be unavailable while services are migrated and restarted. Resiliency will be restored once there are **three working nodes** in the cluster. -{{< /call-out >}} - -The following table shows how many nodes are needed for a cluster to have a quorum and what the failure tolerance is: - - - -| Cluster Size | Quorum | Failure Tolerance | -|--------------|--------|-------------------| -| 1 | 1 | 0 | -| 2 | 2 | 0 | -| 3 | 2 | 1 | - -Larger clusters aren't supported. - -  - ---- - -## Before You Begin - -### Implementation Considerations - -Before installing or configuring NGINX Controller as a multi-node cluster, review the following list of considerations to assist with planning: - -- Configuring NGINX Controller as a multi-node cluster on a private cloud requires **NGINX Controller 3.12 or later**. To upgrade from an earlier version, refer to the [Update NGINX Controller]({{< ref "/controller/admin-guides/install/install-nginx-controller.md#update-nginx-controller" >}}) steps for instructions. -- Data migration is not supported, so it's not possible to implement a multi-node cluster with local volumes without reinstalling NGINX Controller. -- If you plan to run NGINX Controller on AWS EC2 instances, we recommend using NFS shares for the external volumes. Using EBS shares for multi-node clusters is not recommended because of the [EBS Availability Zone limitations](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volumes-multi.html#considerations); for example, the requirement to have EC2 instances and EBS volumes in the same Availability Zone. -- Cluster config changes are orchestrated by a primary control plane node that writes to the external config database. Each NGINX Controller control plane node hosts a set of services (pods) that read and write data. Only the node that hosts the pod that manages the config data writes to the external config database. - -### Prerequisites - -Things you'll need before installing NGINX Controller as a resilient cluster: - -- Three hosts on which you can install NGINX Controller to create a cluster -- The `controller-installer-.tar.gz` package, which you can get from the [MyF5 Customer Portal](https://my.f5.com/manage/s/downloads). You need to upload and extract this tarball **on each host**. -- A license file for NGINX Controller -- A tool to send API requests, such as Postman or curl -- An external volume for the config database - - When installing NGINX Controller, you can choose to have NGINX Controller install and manage a self-hosted -- also known as "embedded" -- [PostgreSQL](https://www.postgresql.org/) database for you; this is the recommended implementation. Alternatively, you can [install your own PostgreSQL database for the config database]({{< ref "/controller/admin-guides/install/install-nginx-controller.md#postgresql-optional" >}}), which you manage; this is sometimes referred to as an "external config database" because it is externally managed by you. Regardless of whether you use an embedded or an externally managed config database, the config database must be on an external volume for resilient clusters. - -- An external volume for the analytics database - -  - ---- - -## Install NGINX Controller - -- Complete the steps in the [NGINX Controller Installation Guide]({{< ref "/controller/admin-guides/install/install-nginx-controller.md" >}}) to install NGINX Controller on the first node. - -  - ---- - -## License NGINX Controller - -- Follow the steps to [license NGINX Controller]({{< ref "/controller/platform/licensing-controller.md" >}}). - -  - ---- - -## Add Nodes to the Cluster - -Nodes are additional control-plane hosts that you can add to your cluster to improve uptime resilience. For a resilient cluster, you should have at least three nodes, of which **two nodes must always be operational**. - -{{< call-out "important" >}} -When adding a third node to the cluster for the first time, NGINX Controller may become momentarily unavailable while the cluster is being created. For this reason, we recommend updating NGINX Controller during a planned maintenance window to minimize disruptions. -{{< /call-out >}} - -Take the following steps to add a node to the cluster: - -1. Open the NGINX Controller web interface and log in. -1. Select the NGINX Controller menu icon, then select **Platform**. -1. On the **Platform** menu, select **Cluster**. -1. On the **Cluster** overview page, select **Create Node**. -1. Add a name for the node. -1. (Optional) Add a description. -1. Add the hostname or IP address -- or both -- for the node. -1. Select **Save**. The new node appears in the list of nodes on the **Cluster** overview page with a `Configuring` status. -1. Choose the new node's name in the list, then select **View** (eye icon). A page displays with command-line instructions for adding the node. -1. Copy the `install.sh` command and join-key that are shown. -1. Open an SSH connection to the node that you're adding to the cluster. -1. (Optional) If you're adding a node that was previously deleted, uninstall NGINX Controller from the node if you haven't already, and then continue with the remaining steps in this procedure: - - ```bash - /opt/nginx-controller/uninstall.sh - ``` - -1. Upload and extract the `controller-installer-.tar.gz` tarball. -1. Run the `install.sh` command with the join-key that you copied in the previous step. If you get an error that the join-key has expired, you can get a new one by following the steps in this topic to add a node using the web interface or the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}). - - ```bash - cd controller-installer - ./install.sh --join-key - ``` - -1. After the installation finishes, the node status in the web interface changes to `Configured`. -1. Repeat these steps for each node that you want to add to the cluster. - -{{< call-out "note" >}} -To add nodes to your cluster using the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}), send a POST request to the `/platform/nodes` endpoint. -{{< /call-out>}} - -  - ---- - -## Set the Floating IP - -**For private cloud deployments**, you must set a floating IP to complete setting up your multi-node resilient cluster. - -A floating IP -- also called a virtual IP -- is a static, routable IPv4 address that improves service resiliency by allowing NGINX Controller to continue to receive traffic if a node becomes unavailable. The floating IP is assigned to one of the cluster nodes, and if the node fails, the floating IP is automatically transferred to another node. The floating IP should not be in any DHCP pool. - -{{< call-out "important" >}} -The floating IP needs to be added as an A record for the domain that's used as the Fully Qualified Domain Name (FQDN) for NGINX Controller. - -NGINX Controller **does not support IPv6** addresses for the floating IP. -{{< /call-out >}} - -Take the following steps to add a floating IP for your private cloud cluster: - -1. Open the NGINX Controller web interface and log in. -1. Select the NGINX Controller menu icon, then select **Platform**. -1. On the **Platform** menu, select **Cluster**. -1. On the **Cluster** overview page, in the **Cluster Configuration** section, select the edit icon (pencil). -1. Select the **Use Floating IP** toggle to turn it on. -1. Add an IP address for the floating IP. -1. Select **Save**. -1. Complete the steps to [update the FQDN](#update-the-fqdn) to use the floating IP. - -{{< call-out "note" >}} -To set a floating IP using the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}), send a PATCH request to the `/platform/global` endpoint. -{{< /call-out>}} -  - ---- - -## Update the FQDN - -The Fully Qualified Domain Name (FQDN) should be a proper domain. The FQDN is used by Controller Agents to access NGINX Controller. It's also used to access the web interface. - -Updating the FQDN for NGINX Controller is a two-step process: - -1. Update the FQDN for NGINX Controller using the web interface or the REST API. -1. Update the Controller Agents to use the new FQDN. - -  - -### Update the FQDN for NGINX Controller - -To change the FQDN for NGINX Controller using the web interface, take the following steps: - -1. Open the NGINX Controller web interface and log in. -1. Select the NGINX Controller menu icon, then select **Platform**. -1. On the **Platform** menu, select **Cluster**. -1. On the Cluster overview page, in the **Cluster Configuration** section, select the edit icon (pencil). -1. In the FQDN box, type the new FQDN that you want to use. If you've [set a floating IP](#set-the-floating-ip), use that value for the FQDN. -1. Select the **Update API Gateway SSL Certificate** toggle. -1. Select an option for updating the API Gateway cert: - - - **Paste**: Paste the cert and key contents in the respective boxes. - - **File**: Browse for and upload the cert and key files. - -1. Select **Save**. The cluster services will restart. During this time, the web interface will be briefly unavailable. -1. Follow the steps to [update the FQDN for Controller Agents](#update-the-fqdn-for-controller-agents). - -{{< call-out "note" >}} -To change the FQDN for NGINX Controller using the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}), send a PATCH request to the `/platform/global` endpoint. -{{< /call-out>}} -  - -### Update the FQDN for Controller Agents - -To update the FQDN for Controller Agents, take the following steps on each instance where the Controller Agent is installed: - -1. Open the `/etc/controller-agent/agent.conf` file for editing. -1. Update the `api_url` value with the new FQDN: - - ```nginx - [cloud] - api_url = https://:8443/1.4 - ``` - -1. Save the changes. -1. Restart the Controller Agent: - - ```bash - sudo service controller-agent restart - ``` - - -  - ---- - -## Update the API Gateway SSL Certificate - -Take the following steps to update the API Gateway SSL certificate: - -1. Open the NGINX Controller web interface and log in. -1. Select the NGINX Controller menu icon, then select **Platform**. -1. On the **Platform** menu, select **Cluster**. -1. On the **Cluster** overview page, in the **Cluster Configuration** section, select the edit icon (pencil). -1. Select the **Update API Gateway SSL Certificate** toggle. -1. Select an option for updating the cert: - - - **Paste**: Paste the cert and key contents in the boxes. - - **File**: Browse for and upload the cert and key files. - -1. Select **Save**. - -{{< call-out "note" >}} -To update the API Gateway SSL certificate and key using the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}), send a PATCH request to the `/platform/global` endpoint. -{{< /call-out>}} - -  - ---- - -## View Node Status - -Take the following steps to view the status for a node: - -{{< call-out "note" >}} -To view a node's status using the [NGINX Controller API Reference]({{< ref "/controller/api/_index.md" >}}), send a GET request to the Nodes endpoint. -{{< /call-out>}} - -1. Open the NGINX Controller web interface and log in. -1. Select the NGINX Controller menu icon, then select **Platform**. -1. On the **Platform** menu, select **Cluster**. -1. On the **Cluster** overview page, choose the node you want to view details for, then select **View** (eye icon). A panel opens and displays the node's current condition, including any errors. If you're adding a node to the cluster, the node status panel shows the command-line instructions to follow to complete setting up the node. - -  - ---- - -## Delete a Node - -There might be situations when you need to delete a node, either temporarily for maintenance or permanently to decommission a node. - -If you need to remove a node temporarily, follow the steps in the [Add Nodes to the Cluster](#add-nodes-to-the-cluster) topic when you are ready to re-add it. Make sure to uninstall NGINX Controller from the node before re-installing NGINX Controller with the new join-key. - -{{< call-out "important" >}} -Deleting nodes can cause NGINX Controller to become momentarily unavailable while the cluster is being updated. For this reason, we recommend updating NGINX Controller during a planned maintenance window to minimize disruptions. When deleting nodes, make sure that **at least two nodes are always operational**. If the cluster has fewer than two working nodes, NGINX Controller may become unresponsive, and you may not be able to add new nodes. -{{< /call-out >}} - -{{< call-out "note" >}} -To delete nodes from your cluster using the [NGINX Controller API Reference]({{< ref "/controller/api/_index.md" >}}), send a DELETE request to the Nodes endpoint. -{{< /call-out>}} - -To delete a node from the cluster using the web interface: - -1. Open the NGINX Controller web interface and log in. -1. Select the NGINX Controller menu icon, then select **Platform**. -1. On the **Platform** menu, select **Cluster**. -1. On the **Cluster** overview page, choose the node you want to delete, then select **Delete** (trash icon). -1. Select **Delete** to confirm. -1. To finish deleting a node from the cluster, uninstall NGINX Controller from the node: - - 1. SSH into the node that you're deleting from the cluster. - 1. Run the NGINX Controller uninstall script: - - ```bash - /opt/nginx-controller/uninstall.sh - ``` - -{{< call-out "note" >}} -To delete nodes from your cluster using the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}), send a DELETE request to the `/platform/nodes` endpoint. -{{< /call-out>}} - -  - ---- - -## Replace a Failed Node - -To be resilient, a cluster requires three working nodes. That's two nodes for a quorum and one node for failure tolerance. - -If one of the nodes in a multi-node cluster becomes degraded or fails, you must take action **as soon as possible** to recover or replace the failed node or risk losing resiliency. - -To replace a failed node: - -1. [Delete the failed node](#delete-a-node). -1. [Add a new node](#add-nodes-to-a-cluster). - -  - ---- - -## Updating a Cluster - -When updating NGINX Controller on a multi-node cluster, run the `update.sh` script on each node individually -- the order in which you update the nodes doesn't matter. - -{{< call-out "warning" >}}Do not update the nodes in a multi-node cluster in parallel. Doing so may result in race conditions for certain jobs, such as database migrations, and may cause the cluster to become unavailable.{{< /call-out >}} - -{{< call-out "important" >}} -Active users will be logged out from NGINX Controller during an update. We recommend updating NGINX Controller during a planned maintenance window to minimize disruptions. -{{< /call-out >}} - -To update your cluster to a newer version of NGINX Controller, take the following steps: - -1. Before updating the cluster, [check each node's status]({{< ref "/controller/platform/manage-cluster.md#view-node-status" >}}) to confirm the nodes are healthy. Resolve any degradations before updating. -1. Download the new installer package from the [MyF5 Customer Portal](https://my.f5.com/manage/s/downloads). - -1. Extract the installer package and save the contents to each node: - - ```bash - tar xzf controller-installer-.tar.gz - ``` - -1. Run the update script on each node -- the order in which you update the nodes doesn't matter: - - ```bash - cd controller-installer - ./update.sh - ``` - -  - -{{< versions "3.12" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/admin-guides/install/try-nginx-controller-app-sec.md b/content/controller/admin-guides/install/try-nginx-controller-app-sec.md deleted file mode 100644 index 7d5bfee52..000000000 --- a/content/controller/admin-guides/install/try-nginx-controller-app-sec.md +++ /dev/null @@ -1,305 +0,0 @@ ---- -description: This quick-start tutorial shows you how to get started using F5 NGINX - Controller with the Application Security Add-on. -nd-docs: DOCS-259 -title: Trial NGINX Controller with App Security -toc: true -weight: 115 -type: -- tutorial ---- - -## 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. - -{{< call-out "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**.{{< /call-out >}} - -{{< call-out "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](#install-nginx-app-protect-with-nginx-plus) section. {{< /call-out >}} - -  - ---- - -## Technical Requirements - -Be sure to review the [NGINX Controller Technical Specifications Guide]({{< ref "/controller/admin-guides/install/nginx-controller-tech-specs.md" >}}) 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]({{< ref "/controller/admin-guides/install/nginx-controller-tech-specs.md#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. - -{{< call-out "note" >}} -Refer to [Using NGINX App Protect with NGINX Controller]({{< ref "controller/admin-guides/install/install-for-controller.md" >}}) for installation instructions and additional information. -{{< /call-out>}} - -{{< bootstrap-table "table table-striped table-bordered" >}} - -| NGINX Controller version | NGINX App Protect version(s) | NGINX Plus version(s) | -|-------------------------------------|-------------------------------------------------------------------------------------------------|--------------------------------| -| NGINX Controller ADC v3.22.9 | v4.5
v4.3, v4.4
v4.0, v4.1, v4.2
v3.12, v3.11 | R30
R29
R28
R27 | -| NGINX Controller ADC v3.22.8 | v4.0, v4.1
v3.12, v3.11
v3.10.0, v3.9.1, v3.9.0
v3.8, v3.7, v3.6 | R28
R27
R26
R25 | -| NGINX Controller ADC v3.22.7 | v4.0, v4.1
v3.12, v3.11
v3.10.0, v3.9.1, v3.9.0
v3.8, v3.7, v3.6 | R28
R27
R26
R25 | -| NGINX Controller ADC v3.22.6 | v4.0, v4.1
v3.12, v3.11
v3.10.0, v3.9.1, v3.9.0
v3.8, v3.7, v3.6 | R28
R27
R26
R25 | -| NGINX Controller ADC v3.22.5 | v3.12, v3.11
v3.10.0, v3.9.1, v3.9.0
v3.8, v3.7, v3.6
v3.5, v3.4, v3.3, v3.2 | R27
R26
R25
R24 | -| NGINX Controller ADC v3.22.4 | v3.11
v3.10.0, v3.9.1, v3.9.0
v3.8, v3.7, v3.6
v3.5, v3.4, v3.3, v3.2 | R27
R26
R25
R24 | -| NGINX Controller ADC v3.22.3 | v3.10.0, v3.9.1, v3.9.0
v3.8, v3.7, v3.6
v3.5, v3.4, v3.3, v3.2
v3.1, v3.0, v2.3 | R26
R25
R24
R23 | -| NGINX Controller ADC v3.22.2 | v3.9.1, v3.9.0
v3.8, v3.7, v3.6
v3.5, v3.4, v3.3, v3.2
v3.1, v3.0, v2.3 | R26
R25
R24
R23 | -| NGINX Controller ADC v3.22, v3.22.1 | v3.8, v3.7, v3.6
v3.5, v3.4, v3.3, v3.2
v3.1, v3.0, v2.3
v2.1.1 | R25
R24
R23
R22 | -| NGINX Controller ADC v3.21 | v3.6
v3.5, v3.4, v3.3, v3.2
v3.1, v3.0, v2.3
v2.1.1 | R25
R24
R23
R22 | -| NGINX Controller ADC v3.20.1 | v3.6
v3.5, v3.4, v3.3, v3.2
v3.1, v3.0, v2.3
v2.1.1 | R25
R24
R23
R22 | -| NGINX Controller ADC v3.20 | v3.5, v3.4, v3.3, v3.2
v3.1, v3.0, v2.3
v2.1.1 | R24
R23
R22 | -| NGINX Controller APIM v3.19.2 | v3.6
v3.5, v3.4 | R25
R24 | -| NGINX Controller APIM v3.19 | v3.5, v3.4 | R24 | -| NGINX Controller v3.18 | v3.5, v3.2
v3.1, v3.0, v2.3
v2.1.1 | R24
R23
R22 | -| NGINX Controller v3.17 | v3.2
v3.1, v3.0, v2.3
v2.1.1 | R24
R23
R22 | -| NGINX Controller v3.16 | v3.1, v3.0, v2.3
v2.1.1 | R23
R22 | -| NGINX Controller v3.14, v3.15 | v3.0, v2.3
v2.1.1 | R23
R22 | -| NGINX Controller v3.13 | v2.3
v2.1.1 | R23
R22 | -| NGINX Controller v3.12 | v2.1.1 | R22 | - -{{< /bootstrap-table >}} - -  - ---- - -## Sign Up for a Trial License - -{{< call-out "note" >}}If you already have an active NGINX Controller trial instance that you want to add App Security to, you can skip this section.{{< /call-out >}} - -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](https://account.f5.com/myf5) and create a new account. -1. Verify your account and log in to MyF5. -1. On the MyF5 landing page, activate the NGINX Controller free trial. -1. On the MyF5 **Trials** page, select Launch Your Trial. -1. Download the NGINX Controller package. -1. Make note of your Association Token. You will use this to [license your NGINX Controller instance]({{< ref "/controller/platform/licensing-controller.md#add-a-license-to-nginx-controller" >}}). - - -  - ---- - -## Install NGINX Controller Prerequisites - -{{< call-out "note" >}}If you already have an active NGINX Controller trial instance that you want to add App Security to, you can skip this section.{{< /call-out >}} - -{{< include "controller/helper-script-prereqs.md" >}} - -  - ---- - -## Install NGINX Controller - -{{< call-out "note" >}}If you already have an active NGINX Controller trial instance that you want to add App Security to, you can skip this section.{{< /call-out >}} - -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. - -{{< call-out "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](https://support.f5.com/csp/article/K82655201) and the [kubeadm installation guide](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/install-kubeadm/#before-you-begin) in the Kubernetes documentation.{{< /call-out >}} - -{{< call-out "caution" >}}**For RHEL 8 deployments**, complete the additional prerequisite steps in the [Installing NGINX on RHEL 8]({{< ref "/controller/admin-guides/install/install-nginx-controller-rhel-8.md" >}}) guide before installing NGINX Controller. RHEL 8 support is a **beta** feature.{{< /call-out >}} - -To install NGINX Controller, take the following steps: - -1. Download the NGINX Controller installer package from the [MyF5 Customer Portal](https://my.f5.com/manage/s/downloads). -1. Extract the installer package files: - - ```bash - tar xzf controller-installer-.tar.gz - ``` - -1. Run the installation script: - - ```bash - cd controller-installer - ./install.sh - ``` - -1. When prompted to use an embedded config DB, type `y`. - -1. 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. - - {{< call-out "note" >}}Refer to the [NGINX Controller Technical Specifications Guide]({{< ref "/controller/admin-guides/install/nginx-controller-tech-specs.md#local-or-external-storage" >}}) for more information about the volume options and requirements.{{< /call-out>}} - - - **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. - - {{< call-out "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. - {{< /call-out >}} - -1. Log in to NGINX Controller at `https:///login`. Use the admin email address and password that you provided during the installation process. - -1. 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:///platform/license` and log in. -1. 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](https://account.f5.com/myf5). - -1. Select **Save license**. - -{{< call-out "note" >}} -To add a license using the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}), 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. -{{< /call-out>}} - - -  - ---- - -## Install NGINX App Protect with NGINX Plus - -[NGINX App Protect](https://www.nginx.com/products/nginx-app-protect/) is the security data plane for NGINX Controller App Security. Your NGINX App Protect installation will include NGINX Plus. - -{{< call-out "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](#supported-distributions) section above to verify that your NGINX Plus instance supports NGINX App Protect. -{{< /call-out >}} - -### Prerequisites - -- Be sure to review the [NGINX Plus Technical Specifications](https://docs.nginx.com/nginx/technical-specs/) 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]({{< ref "/controller/api/_index.md" >}}) 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]({{< ref "/controller/api/_index.md" >}}) documentation for information about session cookie timeouts and invalidation. - -{{< call-out "tip" >}} -You can send a GET request to the login endpoint to find the status of the session token. -{{< /call-out >}} - -For example: - -- Login and capture the session cookie: - - ```curl - curl -c cookie.txt -X POST --url 'https:///api/v1/platform/login' --header 'Content-Type: application/json' --data '{"credentials": {"type": "BASIC","username": "","password": ""}}' - ``` - -- Use the session cookie to authenticate and get the session status: - - ```curl - curl -b cookie.txt -c cookie.txt -X GET --url 'https:///api/v1/platform/login' - ``` - - -
- -To use the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}) 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: - - ```bash - 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: - - ```bash - 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 - ``` - -{{< call-out "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. -{{< /call-out >}} - - -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: - -```bash -gunzip nginx-plus-certs.gz -``` - -### Deploy NGINX App Protect - -
- -Install NGINX App Protect on a host accessible by your NGINX Controller instance by following the appropriate steps for your operating system in the [Using NGINX App Protect with NGINX Controller]({{< ref "controller/admin-guides/install/install-for-controller.md" >}}) guide. - -{{< call-out "note" >}} -If you install NGINX App Protect by using any of the OS-specific install guides, **do not make changes to the `nginx.conf` file**. -The NGINX Controller Agent manages `nginx.conf` settings and will make the appropriate adjustments for you. -{{< /call-out >}} - -
- -  - ---- - -## Add the NGINX App Protect Instance to NGINX Controller - -{{< include "controller/add-existing-instance.md" >}} - -  - ---- - -## 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]({{< ref "/controller/admin-guides/config-agent/configure-the-agent.md" >}}) -- [Set Up Metrics Collection]({{< ref "/controller/admin-guides/config-agent/configure-metrics-collection.md" >}}) -- [Forward Metrics Data to an External Service]({{< ref "/controller/analytics/forwarders/_index.md" >}}) -- [Set up NGINX Controller Services]({{< ref "/controller/services/overview.md" >}}) - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/admin-guides/install/try-nginx-controller.md b/content/controller/admin-guides/install/try-nginx-controller.md deleted file mode 100644 index e77bf343f..000000000 --- a/content/controller/admin-guides/install/try-nginx-controller.md +++ /dev/null @@ -1,279 +0,0 @@ ---- -description: This quick-start tutorial shows you how to get started using F5 NGINX - Controller with NGINX Plus. -nd-docs: DOCS-260 -title: Trial NGINX Controller with NGINX Plus -toc: true -weight: 110 -type: -- tutorial ---- - -## Overview - -This quick-start tutorial shows you how to get started using F5 NGINX Controller with NGINX Plus. - -{{< call-out "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**.{{< /call-out >}} - -{{< call-out "note" >}}If you want to try out NGINX Controller with the Application Security add-on, refer to [Trial NGINX Controller with App Security]({{< ref "/controller/admin-guides/install/try-nginx-controller-app-sec.md" >}}).{{< /call-out>}} - -  - ---- - -## Technical Requirements - -Make sure to review the [NGINX Controller Technical Specifications Guide]({{< ref "/controller/admin-guides/install/nginx-controller-tech-specs.md" >}}) for the requirements for your distribution and desired configuration. - -### Supported Distributions - -NGINX Controller, the NGINX Controller Agent, and the NGINX Controller Application Security Add-on support the following distributions and architectures. - -{{< call-out "note" >}}Refer to the [NGINX Plus Technical Specifications](https://docs.nginx.com/nginx/technical-specs/) guide for the distributions that NGINX Plus supports.{{< /call-out>}} - -{{< bootstrap-table "table table-striped table-bordered" >}} - -|Distribution
and Version|NGINX Controller
(Control Plane)|Agent
(Data Plane)|ADC App. Sec.
(Data Plane)|APIM Adv. Sec.
(Data Plane)|Notes| -|--- |--- |--- |--- |--- |--- | -|Amazon Linux
2
(x86_64)| Not supported|v3.0+ |Not supported|Not supported| | -|Amazon Linux
2017.09+
(x86_64)| Not supported |v3.0+|Not supported |Not supported| | -|CentOS
6.5+
(x86_64)| Not supported |v3.0+| Not supported |Not supported| • CentOS 6.5 and later versions in the CentOS 6 family are partially supported.
• This distribution does not support AVRD.| -|CentOS
7.4+
(x86_64)|v3.0+|v3.0+ | v3.12+ |v3.19+| • CentOS 7.4 and later versions in the CentOS 7 family are supported.| -|Debian
8
(x86_64)| Not supported |v3.0–3.21|Not supported|Not supported|• This distribution does not support AVRD.| -|Debian
9
(x86_64)|v3.0+|v3.0–3.21 | v3.12+ |v3.19+ | | -|Debian
10
(x86_64)| Not supported |v3.17+ | v3.17+ |v3.19+| See the [NGINX Plus Admin Guide](https://docs.nginx.com/nginx/) for requirements for Debian 10. | -|Red Hat Enterprise Linux
6.5+| Not supported |v3.0+| Not supported | Not supported| • RHEL 6.5 and later versions in the RHEL 6 family are partially supported.| -|Red Hat Enterprise Linux
7.4+
(x86_64)|v3.5+|v3.5+ | v3.12+|v3.19+| • RHEL 7.4 and later versions in the RHEL 7 family are supported.
• SELinux may interfere with NGINX Controller installation and operation. If you do enable SELinux, it must use permissive mode. Use of enforcing mode is not supported. | -|Red Hat Enterprise Linux
8.0+
(x86_64)|v3.22+|v3.22+ | v3.22+| Not supported | • RHEL 8.0 and later versions in the RHEL 8 family are supported.
• SELinux may interfere with NGINX Controller installation and operation. If you do enable SELinux, it must use permissive mode. Use of enforcing mode is not supported. | -|Ubuntu
18.04 LTS
(x86_64)|v3.0+|v3.0+ |v3.13+|v3.19+| | -|Ubuntu
20.04 LTS
(x86_64)|v3.20+|v3.12+|v3.16.1+|v3.19+| | - -{{< /bootstrap-table >}} - - - -#### Analytics, Visibility, and Reporting Daemon (AVRD) - -NGINX Controller v3.1 and later use an Analytics, Visibility, and Reporting daemon (AVRD) to aggregate and report app-centric metrics, which you can use to track and check the health of your apps. To learn more about these metrics, see the [NGINX Metrics Catalog]({{< ref "/controller/analytics/catalogs/metrics.md" >}}) topic. - -### 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]({{< ref "/controller/admin-guides/install/nginx-controller-tech-specs.md#storage-requirements" >}}) section for a categorized list of the storage requirements. - -### Supported NGINX Plus Versions - -NGINX Controller supports the following [NGINX Plus](https://www.f5.com/products/nginx/nginx-plus) versions: - -{{< bootstrap-table "table table-striped table-bordered" >}} - -| NGINX Plus | NGINX Controller | NGINX Controller ADC | NGINX Controller APIM | -|------------|------------------|----------------------|-----------------------| -| R30 | Not supported | 3.22.9+ | Not supported | -| R29 | Not supported | 3.22.9+ | 3.19.6+ | -| R28 | Not supported | 3.22.6+ | 3.19.6+ | -| R27 | Not supported | 3.22.4+ | 3.19.6+ | -| R26 | Not supported | 3.22.2+ | 3.19.6+ | -| R25 | Not supported | 3.20.1+ | 3.19.2+ | -| R24 | 3.17+ | 3.20+ | 3.18+ | -| R23 | 3.12+ | 3.20.0 - 3.22.2 | 3.18+ | -| R22 | 3.5+ | 3.20.0 - 3.22.1 | 3.18+ | -| R21 | 3.5 - 3.12 | Not supported | Not supported | -| R20 | 3.0 - 3.12 | Not supported | Not supported | -| R19 | 2.6 - 3.5 | Not supported | Not supported | - -{{< /bootstrap-table >}} - ---- - -## Sign Up for a Trial License - -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](https://account.f5.com/myf5) and create a new account. -1. Verify your account and log in to MyF5. -1. On the MyF5 landing page, activate the NGINX Controller free trial. -1. On the MyF5 **Trials** page, select Launch Your Trial. -1. Download the NGINX Controller package. -1. Make note of your Association Token. You will use this to [license your NGINX Controller instance]({{< ref "/controller/platform/licensing-controller.md#add-a-license-to-nginx-controller" >}}). - -  - ---- - -## Install NGINX Controller Prerequisites - -{{< include "controller/helper-script-prereqs.md" >}} - -  - ---- - -## Install 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. - -{{< call-out "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](https://support.f5.com/csp/article/K82655201) and the [kubeadm installation guide](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/install-kubeadm/#before-you-begin) in the Kubernetes documentation.{{< /call-out >}} - -{{< call-out "caution" >}}**For RHEL 8 deployments**, complete the additional prerequisite steps in the [Installing NGINX on RHEL 8]({{< ref "/controller/admin-guides/install/install-nginx-controller-rhel-8.md" >}}) guide before installing NGINX Controller. RHEL 8 support is a **beta** feature.{{< /call-out >}} - -To install NGINX Controller, take the following steps: - -1. Download the NGINX Controller installer package from the [MyF5 Customer Portal](https://my.f5.com/manage/s/downloads). -1. Extract the installer package files: - - ```bash - tar xzf controller-installer-.tar.gz - ``` - -1. Run the installation script: - - ```bash - cd controller-installer - ./install.sh - ``` - -1. When prompted to use an embedded config DB, type `y`. - -1. 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. - - {{< call-out "note" >}}Refer to the [NGINX Controller Technical Specifications Guide]({{< ref "/controller/admin-guides/install/nginx-controller-tech-specs.md#local-or-external-storage" >}}) for more information about the volume options and requirements.{{< /call-out>}} - - - **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. - - {{< call-out "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. - {{< /call-out >}} - -1. Log in to NGINX Controller at `https:///login`. Use the admin email address and password that you provided during the installation process. - -1. 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:///platform/license` and log in. -1. 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](https://account.f5.com/myf5). - -1. Select **Save license**. - -{{< call-out "note" >}} -To add a license using the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}), 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. -{{< /call-out>}} - - -  - ---- - -## Install NGINX Plus - -### Prerequisites - -- Make sure to review the [NGINX Plus Technical Specifications Guide](https://docs.nginx.com/nginx/technical-specs/) 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`) that were provided when you signed up for the trial license. If you don't have these files, you can use the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}) to download them. - -#### How to Download the NGINX Plus Cert and Key using the NGINX Controller 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]({{< ref "/controller/api/_index.md" >}}) documentation for information about session cookie timeouts and invalidation. - -{{< call-out "tip" >}} -You can send a GET request to the login endpoint to find the status of the session token. -{{< /call-out >}} - -For example: - -- Login and capture the session cookie: - - ```curl - 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@example.net","password": ""}}' - ``` - -- Use the session cookie to authenticate and get the session status: - - ```curl - 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]({{< ref "/controller/api/_index.md" >}}) 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: - - ```bash - 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: - - ```bash - 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 - ``` - -{{< call-out "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. -{{< /call-out >}} - - -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: - -```bash -gunzip nginx-plus-certs.gz -``` - -### Steps - -Take the following steps to install NGINX Plus: - -{{< call-out "important" >}} -You need the NGINX Plus certificate and public key files (`nginx-repo.crt` and `nginx-repo.key`) that were provided when you signed up for the trial license. -{{< /call-out >}} - -1. First, make sure to review the [NGINX Plus Technical Specifications Guide](https://docs.nginx.com/nginx/technical-specs/) for the requirements for your distribution and desired configuration. -2. To install NGINX Plus, follow the instructions in the [NGINX Plus Installation Guide](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/). Refer to the relevant section for your distribution. - -  - ---- - -## Add an NGINX Plus Instance to NGINX Controller - -{{< include "controller/add-existing-instance.md" >}} - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/admin-guides/install/using-helper-script.md b/content/controller/admin-guides/install/using-helper-script.md deleted file mode 100644 index 830602bb7..000000000 --- a/content/controller/admin-guides/install/using-helper-script.md +++ /dev/null @@ -1,448 +0,0 @@ ---- -description: Learn how to update F5 NGINX Controller installation settings and manage - the NGINX Controller service using the helper.sh script. -nd-docs: DOCS-261 -title: Update NGINX Controller Settings with helper.sh -toc: true -weight: 200 -type: -- how-to ---- - -## Overview - -You can use the F5 NGINX Controller `helper.sh` script to update NGINX Controller installation settings and manage the NGINX Controller process. This tutorial shows you how to use `helper.sh` to perform the following tasks: - -- Install the NGINX Controller prerequisites -- View the version of NGINX Controller that's installed and running -- Start, stop, and restart NGINX Controller -- Back up and restore the NGINX Controller config and encryption keys -- Restore the embedded config database -- Get the NGINX Plus repository key and certificate files (deprecated for `helper.sh` in NGINX Controller v3.9) -- Update the SMTP settings -- Update the database settings -- Update or replace the TLS certificates -- Print the NGINX Controller logs -- Create a support package - -## Install NGINX Controller Prerequisites - - - -{{< include "controller/helper-script-prereqs.md" >}} - - - -  - ---- - -## View the Installed NGINX Version - -To see which version of NGINX Controller is installed and running, type the following command: - -``` bash -/opt/nginx-controller/helper.sh version -``` - -The output looks similar to the following: - -``` bash -Installed version: 3.14.0 -Running version: 3.14.0 -``` - -  - ---- - -## Start, Stop, and Restart NGINX Controller - - -You can use the `helper.sh` script to start, stop, restart, and check the status of the NGINX Controller process. - -``` bash -/opt/nginx-controller/helper.sh controller start -/opt/nginx-controller/helper.sh controller stop -/opt/nginx-controller/helper.sh controller restart -/opt/nginx-controller/helper.sh controller status -``` - -  - ---- - -## Back Up and Restore Config and Encryption Keys - - - -After installing NGINX Controller, you should back up the cluster config and encryption keys. You'll need these if you ever need to restore the NGINX config database on top of a new NGINX Controller installation. - -- To back up the NGINX Controller cluster configuration and encryption keys: - - ```bash - /opt/nginx-controller/helper.sh cluster-config save - ``` - - The file is saved to `/opt/nginx-controller/cluster-config.tgz`. - -- To restore the cluster's config and encryption keys, take the following steps: - - ```bash - /opt/nginx-controller/helper.sh cluster-config load - ``` - - - -  - ---- - -## Restore Embedded Config Database - - - -This section explains how to restore the embedded config database from the latest backup file or a specific, timestamped file. - -{{< call-out "important" >}}If you restore the config database on top of a new installation of NGINX Controller, make sure to follow the steps to [restore your NGINX config and encryption keys]({{< ref "/controller/admin-guides/backup-restore/backup-restore-cluster-config.md" >}}) afterward. {{< /call-out >}} - -- To restore the embedded NGINX Controller config database **from the latest automated backup**, run the following command: - - ```bash - /opt/nginx-controller/helper.sh backup restore - ``` - -- To restore the embedded config database from **a specific backup file**: - - ```bash - /opt/nginx-controller/helper.sh backup restore - ``` - - - If you installed the embedded config database on a **local volume**, the backup files are located in `/opt/nginx-controller/postgres_data/`. - - - If you installed the embedded config database on an **NFS volume**, follow the steps in [(NFS) Copy Config Database Backup to Local Volume for Restoration]({{< ref "/controller/admin-guides/backup-restore/backup-restore-embedded-config-db.md#nfs-copy-config-database-backup-to-local-volume-for-restoration" >}}) to download the backup file to your local volume, and then use the `helper.sh` script to restore from it. - -  - - - ---- - -## Get NGINX Plus Repository Key and Certificate - -To install NGINX Plus as a data plane for NGINX Controller, you need to have the NGINX repository key and certificate files. - -{{< deprecated >}}Using the helper.sh script to download your NGINX Plus certificate and key bundle is deprecated in in NGINX Controller v3.9.{{< /deprecated >}} - -{{< call-out "note" >}}If you're running NGINX Controller v3.10+, you can use the REST API to [Download the NGINX Plus Cert and Key Bundle]({{< ref "/controller/admin-guides/install/get-n-plus-cert-and-key.md" >}}). {{< /call-out>}}  - -If you're running NGINX Controller 3.9 or earlier, use the `helper.sh` script to extract the NGINX repository key and certificate files: - -```bash -/opt/nginx-controller/helper.sh repository-cred [-c|--cert ] [-k|--key ] -``` - -{{< call-out "important" >}} - -Make sure that you've [uploaded your license in NGINX Controller]({{< ref "licensing-controller.md" >}}) first before running the `helper.sh repository-cred` command to extract the repository files. - -{{< /call-out >}} - - - -| Options | Description | -|----------|-------------| -| `-c` \| `--cert` | Creates a certificate called ``. The default file name is `nginx-repo.crt` in the current directory.| -| `-k` \| `--key` | Creates a key called ``. The default file name is `nginx-repo.key` in the current directory. | - -  - ---- - -## Update SMTP Settings - -Use the `helper.sh` script to change the SMTP address; port; TLS; sender; and optionally, the username and password. - -``` bash -/opt/nginx-controller/helper.sh configsmtp
[auth] [username] [password] -``` - -For example: - -``` bash -/opt/nginx-controller/helper.sh configsmtp 192.0.2.0 25 false noreply@example.com true user1 -``` - - - -| Options | Description | -|----------|-------------| -| `address` | The host name or IP address of the SMTP server. | -| `port` | The port of the SMTP server. | -| `tls` | `true` or `false`. Set to `true` to require SSL for connections to the SMTP server. | -| `from` | Sender's email address. | -| `auth` | `true` or `false`. Set to `true` to authenticate when connecting to the SMTP server. | -| `username` | The username to use for access to the SMTP server. | -| `password` | The password to use for access to the SMTP server. | - -  - -### Environment Variables - -We strongly recommend that you use environment variables, especially for passwords, to prevent exposing sensitive information in system processes (for example, `ps`, `top`) and the bash history. - -You use these SMTP environment variables with NGINX Controller: - -| Environment Variables | Description | -|----------|-------------| -| `CTR_SMTP_HOST` | The host name or IP address of the SMTP server. | -| `CTR_SMTP_PORT` | The port of the SMTP server.| -| `CTR_SMTP_TLS` | `true` or `false`; Set to `true` to require SSL for connections to the SMTP server. | -| `CTR_SMTP_FROM` | Sender's email address. | -| `CTR_SMTP_AUTH` | `true` or `false`; Set to `true` to authenticate when connecting to the SMTP server. | -| `CTR_SMTP_USER` | The username to use for access to the SMTP server. | -| `CTR_SMTP_PASS` | The password to use for access to the SMTP server. | - -For example: - -``` bash -CTR_SMTP_HOST=192.0.2.0 \ -CTR_SMTP_PORT=25 \ -CTR_SMTP_TLS=false \ -CTR_SMTP_FROM=noreply@nginx.test \ -CTR_SMTP_AUTH=true CTR_SMTP_USER=user1 CTR_SMTP_PASS= \ -/opt/nginx-controller/helper.sh configsmtp -``` - -  - ---- - -## Update Database Settings - -Use the `helper.sh` script to change the external config database address; port; and optionally, the username, password, and certificate authentication. However, if your current installation uses an internal config database, then these settings are read-only and cannot be modified using the `helper.sh` script (password and certificates will be automatically rotated with each Controller update). - -``` bash -/opt/nginx-controller/helper.sh configdb
[username] [password] [ssl] [ca] [cert] [key] -``` - -For example: - -``` bash -/opt/nginx-controller/helper.sh configdb 192.0.2.1 5432 user1 false -``` - - - -| Options | Description | -|----------|-------------| -| `address` | The host name or IP address of config database. | -| `port` | The port of the database. | -| `username` | The username to use for access to the config database. | -| `password` | The password to use for access to the config database. | -| `ssl` | `true` or `false`. Set to 'true' to require SSL for connections to the config database. | -| `ca` | CA certificate file path. | -| `cert` | Certificate file path. | -| `key` | Key file path. | - -  - -### Environment Variables - -We strongly recommend that you use environment variables, especially for passwords, to prevent exposing sensitive information in system processes (for example, `ps`, `top`) and the bash history. - -You can use these database environment variables with NGINX Controller: - -| Environment Variables | Description | -|----------|-------------| -| `CTR_DB_HOST` | The host name or IP address of the config database. | -| `CTR_DB_PORT` | The port of the config database used for incoming connections. | -| `CTR_DB_USER` | The username for the account to use for access to the config database; must be provided with password. | -| `CTR_DB_PASS` | The password for the account to use for access to the config database; must be provided with username. | -| `CTR_DB_ENABLE_SSL` | `true` or `false`; Set to `true` to require SSL for connections to the config database. | -| `CTR_DB_CA` | CA certificate file path. | -| `CTR_DB_CLIENT_CERT` | Certificate file path. | -| `CTR_DB_CLIENT_KEY` | Key file path. | - -For example: - -```bash -CTR_DB_HOST=192.0.2.1 \ -CTR_DB_PORT=5432 \ -CTR_DB_USER=user1 \ -CTR_DB_PASS= \ -CTR_DB_ENABLE_SSL=false \ -/opt/nginx-controller/helper.sh configdb -``` - -  - ---- - -## Update or Replace TLS Certificates - -Use the `helper.sh` script to update or replace the TLS certificates that are used to connect to NGINX Controller. - -``` bash -/opt/nginx-controller/helper.sh configtls -``` - - - -| Options | Description | -|----------|-------------| -| `cert_file` | Certificate file path. | -| `key_file` | Key file path. | - -  - ---- - -## Print NGINX Controller Logs - -To print the NGINX Controller logs, enter the following command: - -``` bash -/opt/nginx-controller/helper.sh logs -``` - -  - ---- - -## Add a Custom Logo - -The NGINX Controller logo in the user interface is replaceable with a custom logo. The requirements being: - -- The logo file is in SVG format. -- The logo is square in shape. - -{{< call-out "note" >}} The above steps modify the logo in the top left corner and in the menu, not the favicon. {{< /call-out >}} - -Follow the steps below to replace the logo: - -1. Connect to the NGINX Controller host using 'ssh'. -1. Transfer the logo file to NGINX Controller using one of the following methods: - 1. Method 1: Download the file using curl after connecting to the host using the command `curl https://example.com/custom-logo.svg`. - 1. Method 2: Upload the logo to the host using SCP: `scp /local/path/custom-logo.svg user@controller-host:/remote/path`. - 1. Method 3: Copy/Paste the logo file. - 1. Copy the logo file to the clipboard before connecting to the host. - 1. After connecting to the host, paste the file. -1. Run `helper.sh setlogo ` ( is the name of the SVG file). -1. Wait for approximately five minutes for the cache to clear and the logo to appear in the user interface. -1. Re-run the `setlogo` command on each NGINX Controller node. This has to be done after an upgrade or reinstallation. - -  - ---- - -## Create a Support Package - -You can create a support package for NGINX Controller that you can use to diagnose issues. - -{{< call-out "note" >}} -You will need to provide a support package if you open a ticket with NGINX Support via the [MyF5 Customer Portal](https://account.f5.com/myf5). -{{< /call-out >}}  - -```bash -/opt/nginx-controller/helper.sh supportpkg [-o|--output ] [-s|--skip-db-dump] [-t|--timeseries-dump ] -``` - - - -| Options | Description | -|----------|-------------| -| `-o` \| `--output` | Save the support package file to ``. | -| `-s` \| `--skip-db-dump` | Don't include the database dump in the support package. | -| `-t` \| `--timeseries-dump ` | Include the last `` of timeseries data in the support package (default 12 hours). | - -Take the following steps to create a support package: - -1. Open a secure shell (SSH) connection to the NGINX Controller host and log in as an administrator. - -1. Run the `helper.sh` utility with the `supportpkg` option: - - ```bash - /opt/nginx-controller/helper.sh supportpkg - ``` - - The support package is saved to: - - `/var/tmp/supportpkg-.tar.gz` - - For example: - - `/var/tmp/supportpkg-20200127T063000PST.tar.gz` - -1. Run the following command on the machine where you want to download the support package to: - - ``` bash - scp @:/var/tmp/supportpkg-.tar.gz /local/path - ``` - -### Support Package Details - -{{< include "controller/helper-script-support-package-details.md" >}} - - - -  - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/analytics/_index.md b/content/controller/analytics/_index.md deleted file mode 100644 index 885c42874..000000000 --- a/content/controller/analytics/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -description: Learn about the F5 NGINX Controller Analytics module. -title: Analytics -weight: 120 -url: /nginx-controller/analytics/ ---- - diff --git a/content/controller/analytics/alerts/_index.md b/content/controller/analytics/alerts/_index.md deleted file mode 100644 index 272f87c87..000000000 --- a/content/controller/analytics/alerts/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -description: Learn about F5 NGINX Controller alerts and notifications. -title: Alerts -weight: 100 -url: /nginx-controller/analytics/alerts/ ---- - diff --git a/content/controller/analytics/alerts/about-alerts.md b/content/controller/analytics/alerts/about-alerts.md deleted file mode 100644 index 60a735d32..000000000 --- a/content/controller/analytics/alerts/about-alerts.md +++ /dev/null @@ -1,224 +0,0 @@ ---- -description: Learn about NGINX Controller Alerts and Notifications. -nd-docs: DOCS-520 -title: About Alerts -toc: true -weight: 100 -type: -- concept ---- - -## Overview - -The F5 NGINX Controller Analytics module lets you configure alerts and notifications, so you can stay informed about your system and app performance. In this topic, you'll learn about [alerts](#alerts), [alert rules](#alert-rules), and [alert notifications](#alert-notifications). - -{{< call-out "note" >}} -Refer to [Manage Alerts]({{< ref "/controller/analytics/alerts/manage-alerts.md" >}}) to learn how to set up alerts. -{{< /call-out>}} - -## Alerts - -An *alert* is generated when the criteria for an alert rule are met. -All alerts contain the following information: - - - -| Name | Description | -|---|---| -| `started_timestamp` | The time at which the alert was triggered.| -| `last_checked_timestamp` | The time at which the last alert check occurred.| -| `started_value` | The value of the alert metric at the time the alert was triggered.| -| `last_checked_value` | The value of the alert metric when it was last checked.| -| `dimensions` | The list of dimension values for which the alert was triggered.| - -## Alert Rules - -An *Alert Rule* defines the conditions that will trigger an alert. NGINX Controller generates names for alert rules automatically. An alert rule consists of the following information: - - - -| Name | Description | -|---|---| -| `name` | A unique identifier for the alert rule.| -| `display name` | A human-friendly name that helps you identify what the alert rule does. | -| `metric` | The [metric]({{< ref "/controller/analytics/catalogs/metrics.md" >}}) that you want to monitor.
{{< call-out "note" >}}An alert rule can monitor one metric.{{< /call-out >}}| -| `operator` | The operator that will be applied to the value of the metric to check if an alert should be triggered. There are two available operators: `le` - less or equal and `ge` - greater or equal.| -| `threshold` | Defines the value that, when exceeded, will trigger an alert.
{{< call-out "tip" >}}You can find the allowed threshold value(s) for each metric in the **unit** field of the metric's entry in the [Metrics Catalogs Reference]({{< ref "/controller/analytics/catalogs/metrics.md" >}}). Select the "Index" button to access the list of all available metrics and jump directly to that item in the catalog.{{< /call-out >}} | -| `period` | Defines the time window in which you want to calculate the aggregated metric value.
- The maximum possible time window is `24h`.
- The minimum possible time window is `2m`.| -| `filter` | Lets you refine the alert rule for a more specific set of metric values, based on dimensions.
If no filter is provided, all collected data will be used when calculating the alert rule status.| -| `group by` | Groups results according to the specified dimension(s). A separate alert will be triggered for each result group. You can provide multiple dimension names as a comma-separated list.
{{< call-out "note" >}}Using a dimension with a high cardinality of values might result in a high volume of alerts.{{< /call-out >}}| -| `notification type` | Defines how you want to receive alert notifications. | -| `email addresses` | A comma-separated list of email addresses that should receive alert notifications.| -| `mute` | Boolean; turns alert notifications on and off. Set to 'on' to mute notifications. | - -If you leave any rule parameter blank, NGINX Controller will take all relevant data for the parameter into account in the alert rule calculation. - -Each Alert Rule has a status that describes the current state of the alert rule. It contains the following information: - - - - - -| Name | Description | -|---|---| -| `alerts count` | The total number of triggered alerts for the Alert Rule since its creation.| -| `status: ok` | The rule has not triggered any alerts, or that all triggered alerts have expired.| -| `status: ongoing` | At least one alert for the alert rule is currently ongoing.| -| `lastCheckedTimestamp` | The time when the alert rule was last checked successfully.| -| `lastStartedTimestamp` | The time when alert rule status has changed from 'ok' to 'ongoing'.| -| `lastExpiredTimestamp` | The time when alert rule status has changed from 'ongoing' to 'ok'.| - -
- -Alert rules work in the following manner: - -1. Incoming metric updates are continuously monitored against the set of alert rules. -2. The most recent metric value is checked against the threshold defined in the alert rule. -3. If the threshold is met, an alert notification is generated and the rule will continue to be monitored. In the [Alerts Status]({{< ref "/controller/analytics/alerts/manage-alerts.md#view-alert-rule-status" >}}) pane, the alert instance's status will be displayed as "ongoing". -4. If subsequent metric updates show that the metric no longer violates the threshold for the configured period, the alert expires. - -## Alert Notifications - -An *Alert notification* is a message either displayed in the NGINX Controller user interface or sent via email. Alert notifications are sent when an alert is triggered or expired, depending on the alert rule criteria. - -- The **Notifications** feed contains information about all changes in the system, including alert changes. To access the Notifications feed, select the bell icon next to the **Account Settings** menu. -- A notification appears in the Notifications feed immediately when an alert is triggered or expires. -- Alert instance emails notify you when a single alert instance starts or expires. - -If you want to stop receiving notifications for an alert rule, but you don't want to delete it, you can [mute the alert rule]({{< ref "/controller/analytics/alerts/manage-alerts.md#mute-or-unmute-an-alert-rule" >}}). -Likewise, if you want to stop receiving emails for an alert rule, but you do want to continue receiving the user interface notifications, [edit the alert rule]({{< ref "/controller/analytics/alerts/manage-alerts.md#edit-an-alert-rule" >}}) and remove your email address. - -{{< call-out "note" >}}If you mute an alert rule while the alert rule status is "ongoing", you will not receive any further alert notifications, including when the alert rule status changes.{{< /call-out >}} - -### Email notifications - -{{< call-out "important" >}} -You must [verify your email address]({{< ref "/controller/analytics/alerts/manage-registered-emails.md" >}}) in order to receive alert notification emails. -{{< /call-out >}} - -When an alert rule's conditions are met, NGINX Controller sends an alert email with the subject "[controller-alert] Alert started: " to all of the email addresses that are specified in the alert rule. - -If multiple alerts are triggered in a single calculation period, NGINX Controller sends a summary email message that contains all of the alerts for the time period. - -When an alert instance expires, NGINX Controller sends a message with subject "[controller-alert] Alert expired: " to all of the email addresses that are specified in the alert rule. - -The notification uses the automatically-generated name that was assigned by the system when the rule was created. - -NGINX Controller sends summary emails once every hour. These emails contain alerts that have been triggered or expired since the last summary email was sent. If no alerts started or expired in that timeframe, then the summary will not be sent. - -### How Many Notifications to Expect - -As an example, let's say that you have three instances configured in the NGINX Controller. You want to monitor all three instances based on the `http.request.count` metric. - -Assuming that traffic is constantly flowing through all three instances, and the threshold is exceeded for all three, the system will return three alerts (one per instance). In this case, you would receive one email, containing three alert notices, and three user interface notifications. - -If the threshold is exceeded for one instance, then you will receive one alert email and one notification in the user interface. - -## How Alerts Work - -NGINX Controller checks the list of configured alert rules every 30 seconds. Then, it queries the [Metrics API]({{< ref "/controller/analytics/metrics/metrics-api.md" >}}) for the data defined in each alert rule. - -The API query uses the following template: - -`?names=()&startTime=now-&endTime=now<&additional-alert-rule-parameters>"` - -where - -- `` is the appropriate [aggregation function]({{< ref "/controller/analytics/metrics/metrics-api.md#aggregations" >}}) for the metric. You can find this information in the [Metrics Catalog Reference]({{< ref "/controller/analytics/catalogs/metrics.md" >}}). - - `AVG` applies to `gauge` metrics. Gauges are averaged over the time period configured in the alert rule. - - `MAX` applies to `counter` metrics. - - `SUM` applies to `incremental` metrics. - -- The `` and `` parameters are read from the alert rule configuration. -- `<&additional-alert-rule-parameters>` e.g. `filter` or `groupBy` parameters read from the alert rule configuration. - -NGINX Controller checks the value returned by the Metrics API against the configured threshold, then takes the appropriate action: - - - -| Conditions | Action | -|---|---| -| - threshold is exceeded
- "ongoing" alert does not exist | Triggers new alert. | -| - threshold is exceeded
- "ongoing" alert exists | Updates existing alert's `last_checked_timestamp` and `last_checked_value`. | -| - threshold *is not* exceeded
- "ongoing" alert exists | Expires alert.| -| - threshold *is not* exceeded
- "ongoing" does not exist | No action.| - -Next, the alert rule status is updated. Each alert rule will be updated with a new `last_checked_timestamp` and new `status`, if applicable. - -Finally, the alert notifications for newly-created or expired alerts will be sent for any rules that are not muted. - -{{< call-out "important" >}} -If the [Metrics API]({{< ref "/controller/analytics/metrics/metrics-api.md" >}}) query does not return any data -- for example, if there was no traffic through the instance and therefore no metric value -- NGINX Controller assumes a value of `0`. In such cases, the threshold will be compared to `0`. -{{< /call-out >}} - -## Alert special cases - -### Alerts for the controller.agent.status metric - -The `controller.agent.status` is a special metric representing the heartbeat of the NGINX Agent running on the instance. -The metric is reported every 1 minute by the NGINX Agent to the NGINX Controller and may only have a value of 1 if the NGINX Agent is healthy. -If the NGINX Agent is unhealthy it is not reporting the heartbeat and effectively no values for the `controller.agent.status` are stored by the NGINX Controller. -Based on this metric it is possible to create an alert rule and receive notifications whenever the total number of heartbeats reported by a certain NGINX Agent in a recent period is below or equal (or above or equal) certain threshold. - -For example, you would like to receive notifications whenever the NGINX Agent availability at any instance is less or equal 70%. -To achieve that: - -1. Create an alert rule for the `controller.agent.status` metric. -2. Set the period to at least 10 minutes (recommended, to avoid flapping conditions). Heartbeats arrive every minute while the alert status is evaluated every 30 seconds. -3. Set the threshold to 7 of the NGINX Agent availability (7 heartbeats received in the last 10 min). -4. Set the operator to below or equal. -5. Break out by the instance dimension to get notified about the NGINX Agent availability per instance. - -## What's Next - -- [Create and Manage Alert Rules]({{< ref "/controller/analytics/alerts/manage-alerts.md" >}}) -- [Manage Registered Emails]({{< ref "/controller/analytics/alerts/manage-registered-emails.md" >}}) -- [NGINX Controller REST API Reference]({{< ref "/controller/api/_index.md" >}}) - -{{< versions "3.13" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/analytics/alerts/manage-alerts.md b/content/controller/analytics/alerts/manage-alerts.md deleted file mode 100644 index 56482ef12..000000000 --- a/content/controller/analytics/alerts/manage-alerts.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -description: Learn how to view, add, mute, and delete Alerts. -nd-docs: DOCS-521 -title: Manage Alerts -toc: true -weight: 200 -type: -- concept ---- - -## Overview - -[Alerts]({{< ref "/controller/analytics/alerts/about-alerts.md" >}}) are notifications about the F5 NGINX Controller system and your applications' performance. - -[Alert rules]({{< ref "/controller/analytics/alerts/about-alerts.md#alert-rules" >}}) let you specify what you want to be alerted about. This includes which metrics you want to monitor; the trigger conditions and threshold to meet; the instance(s) to monitor; and the email address(es) to use for notifications. - -## Add an Alert Rule - -To add an alert rule: - -1. Open the NGINX Controller user interface and log in. -1. On the Analytics menu, select **Alerts > Alert Rules**. -1. Select **Create Alert Rule**. -1. Define your alert rule by providing the following information: - - - Name - - (Optional) Display Name - - Metric - - Condition, Threshold, and Time Period - - Filter - - (Optional) Breakout - - Email Notification Address(es): - - - Select the desired address(es) from the list provided, or - - Select **Manage Email Addresses** to add a new address, then take the steps below: - - 1. Select **Add Email Address**. - 1. Provide the desired email address. - 1. Select the submit (plus sign) icon. - 1. Select **Done** to close the Manage Email Addresses panel. - - {{< call-out "note" >}}You will need to verify the email address before it can begin receiving alerts.{{< /call-out >}} - -1. (Optional) Select **Mute Alert Rule** if you want to create the alert rule but not receive any associated notifications. -1. Select **Create**. - -## View Alerts - -To view all **alerts** that are triggered by alert rules: - -1. Open the NGINX Controller user interface and log in. -1. On the Analytics menu, select **Alerts > Alerts**. - -All alert rules and triggered alerts are displayed on this page. You can use the search bar to filter the alerts that are displayed. - -## Edit an Alert Rule - -To edit an alert: - -1. Open the NGINX Controller user interface and log in. -1. On the Analytics menu, select **Alerts > Alert Rules**. -1. Select the alert rule that you want to edit. -1. Select the edit (pencil) icon for the alert rule. -1. Make the desired changes to the alert rule, then select **Save**. - -{{< call-out "important" >}} -When you edit an alert rule, any ongoing alerts which previously met that rule will expire immediately. - -If the threshold is still exceeded in the new alert rule configuration, new alerts will be triggered. -{{< /call-out >}} - -## Mute or Unmute an Alert Rule - -If you want to stop receiving notifications for an alert rule without deleting it, you can mute it. Likewise, you can unmute alert rules for which you want to resume receiving notifications. - -To mute or unmute an alert: - -1. Open the NGINX Controller user interface and log in. -1. On the Analytics menu, select **Alerts > Alert Rules**. -1. Select the alert rule that you want to mute or unmute. -1. Select the mute (volume) icon to mute or unmute the alert rule. - -## Delete an Alert Rule - -To delete an alert rule: - -1. Open the NGINX Controller user interface and log in. -1. On the Analytics menu, select **Alerts > Alert Rules**. -1. Select the alert rule that you want to delete. -1. Select the delete (trash can) icon to delete the alert rule. -1. Select **Delete** in the pop-up box to confirm that you want to proceed. - -## What's Next - -- Learn more [About Alerts]({{< ref "/controller/analytics/alerts/about-alerts.md" >}}) -- Learn more about [Metrics and Metadata]({{< ref "/controller/analytics/metrics/overview-metrics-metadata.md" >}}) -- Learn more about [Traffic Metrics]({{< ref "/controller/analytics/metrics/overview-traffic-metrics.md" >}}) -- [Manage Registered Emails]({{< ref "/controller/analytics/alerts/manage-registered-emails.md" >}}) - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/analytics/alerts/manage-registered-emails.md b/content/controller/analytics/alerts/manage-registered-emails.md deleted file mode 100644 index e864f4e77..000000000 --- a/content/controller/analytics/alerts/manage-registered-emails.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -description: Learn how to manage the email addresses that receive automatic alert - notifications. -nd-docs: DOCS-522 -title: Manage Registered Email Addresses -toc: true -weight: 310 -type: -- concept ---- - -## Overview - -In order to receive email notifications for [Alerts]({{< ref "/controller/analytics/alerts/about-alerts.md" >}}), you need to provide a valid email address and complete the verification process. - -{{< call-out "important" >}} -You will not receive any alert notifications via email until you verify your email address. Any alert notification emails that were triggered by alert rules prior to the email address being verified will not be re-sent. -{{< /call-out >}} - -## List Registered Email Addresses - -To find the list of registered email addresses: - -1. Open the F5 NGINX Controller user interface and log in. -1. On the **Analytics** menu, select **Alerts**. -1. On the **Alert Rules Overview** page, select **Manage Email Addresses**. -1. All registered email addresses are displayed in the Manage Email Addresses panel. To close the panel, select **Done**. - -{{< call-out "important" >}}The **Manage Email Addresses** button is not displayed if you don't have any Alerts configured. If this is the case, you can add a new email address when you [create an alert rule]({{< ref "/controller/analytics/alerts/manage-alerts.md#add-an-alert-rule" >}}).{{< /call-out >}} - -## Add a New Email Address - -To add a new email address: - -1. Open the NGINX Controller user interface and log in. -1. On the **Analytics** menu, select **Alerts**. -1. On the **Alert Rules Overview** page, select **Manage Email Addresses**. -1. In the **Manage Email Addresses** panel: -1. Select **Add Email Address**. -1. Provide the desired email address. -1. Select the submit (plus sign) icon. -1. Select **Done** to close the Manage Email Addresses panel. -1. Check your email inbox for a message with the subject `[controller-team] Email verification`. -1. Click on the link provided in the email to complete the verification process. - -## Re-send a Verification Email - -To re-send a verification email to a newly-registered email address: - -1. Open the NGINX Controller user interface and log in. -1. On the **Analytics** menu, select **Alerts**. -1. On the **Alert Rules Overview** page, select **Manage Email Addresses**. -1. Select the Resend verification (circular arrows) icon to the right of the email address. -1. Select **Done** to close the Manage Email Addresses panel. - -## Remove a Registered Email Address - -To remove a registered email address: - -1. Open the NGINX Controller user interface and log in. -1. On the **Analytics** menu, select **Alerts**. -1. On the **Alert Rules Overview** page, select **Manage Email Addresses**. -1. On the **Manage Email Addresses** panel, select the Delete email address (trash can) icon to the right of the email address that you want to remove. -1. In the **Delete Email Address** pop-up window, select **Delete** to confirm. -1. Select **Done** to close the Manage Email Addresses panel. - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/analytics/alerts/service-now-notifications.md b/content/controller/analytics/alerts/service-now-notifications.md deleted file mode 100644 index b3c96f2cc..000000000 --- a/content/controller/analytics/alerts/service-now-notifications.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -description: Set up Alerts Integration with ServiceNow. Deprecated in v3.13. -nd-docs: DOCS-523 -title: ServiceNow Alerts Integration -toc: true -weight: 600 -type: -- how-to ---- - -## ServiceNow Alert Integration - -{{< deprecated >}} -**The ServiceNow Alert Integration is deprecated in F5 NGINX Controller v3.13.** -{{< /deprecated >}} - -The ServiceNow integration sends all notifications from NGINX Controller to the Incidents table in your ServiceNow account. Follow the steps below to set up the integration. - -1. Install Python3 on your machine. -2. In your ServiceNow instance, go to **System OAuth > Application Registry** and create a new OAuth API endpoint for external clients. - - Fill out the form and specify a long refresh token lifespan. Consider aligning the token lifespan with the expiry date of your NGINX Controller license. - - {{< call-out "important" >}} The ServiceNow integration will fail once the refresh token expires.{{< /call-out >}} - -3. Select the **Configure ServiceNow** button. In the prompt, provide the requested information for the ServiceNow client and select **Save**. - - - **ServiceNow Instance** - The instance ID for your ServiceNow account. - - **Client ID** - Client ID from ServiceNow (from Step 2). - - **Client Secret** - Client Secret from ServiceNow (from Step 2). - - **Username** - Your ServiceNow username; this is used to generate the access token and will not be stored. - - **Password** - Your ServiceNow password; this is used to generate the access token and will not be stored. - - **Controller host** - The URL of your NGINX Controller instance. - - **Controller email** - The email that you use to log in to Controller. - - **Controller password** - The password that you use to log in to Controller. - - **Controller port** - The port on which NGINX Controller is running; the default is 80. - - **Company name** - The name of your company; this is used to create the ServiceNow transport. -
-4. Watch Controller alerts come through as incidents in ServiceNow. - - Mapping of Controller Alerts to ServiceNow Priority: - - - ('alerts', 'created') → 1 - - ('alerts', 'cleared') → 3 - - ('agent', 'nginx_not_found') → 1 - - ('agent', 'nginx_config_parsing_error') → 1 - - ('ssl_expiration', 'ssl_cert_has_expired') → 1 - - ('ssl_expiration', 'ssl_cert_will_expire') → 2 - - ('agent', 'agent_version_old') → 2 - - ('agent', 'agent_version_obsoleted') → 1 - - ('group_actions', 'group_action_completed') → 3 - -{{< versions "3.0" "3.13" "ctrlvers" >}} - diff --git a/content/controller/analytics/catalogs/_index.md b/content/controller/analytics/catalogs/_index.md deleted file mode 100644 index 6edb79a50..000000000 --- a/content/controller/analytics/catalogs/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -description: Reference information for F5 NGINX Controller Catalogs. -title: Catalogs Reference -weight: 210 -url: /nginx-controller/analytics/catalogs/ ---- - diff --git a/content/controller/analytics/catalogs/dimensions.md b/content/controller/analytics/catalogs/dimensions.md deleted file mode 100644 index 4ed5ea5b4..000000000 --- a/content/controller/analytics/catalogs/dimensions.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -description: Information about all of the Dimensions collected by F5 NGINX Controller - Agent. -nd-docs: DOCS-524 -title: NGINX Controller Dimensions Catalog -toc: false -weight: 20 -type: -- reference ---- - -{{< dimensions path="/static/ctlr/catalogs/dimensions-catalog.json" >}} - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/analytics/catalogs/metrics.md b/content/controller/analytics/catalogs/metrics.md deleted file mode 100644 index ff4c9b25b..000000000 --- a/content/controller/analytics/catalogs/metrics.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -description: Information about all of the Metrics collected by F5 NGINX Controller - Agent. -nd-docs: DOCS-525 -title: NGINX Controller Metrics Catalog -toc: false -weight: 20 -type: -- reference ---- - -{{< metrics path="/static/ctlr/catalogs/metrics-catalog.json" >}} - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/analytics/dashboards/_index.md b/content/controller/analytics/dashboards/_index.md deleted file mode 100644 index 88cfef7a1..000000000 --- a/content/controller/analytics/dashboards/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -description: Learn about F5 NGINX Controller Dashboards. -title: Dashboards -weight: 120 -url: /nginx-controller/analytics/dashboards/ ---- - diff --git a/content/controller/analytics/dashboards/application-health-score.md b/content/controller/analytics/dashboards/application-health-score.md deleted file mode 100644 index 9e27b8b3e..000000000 --- a/content/controller/analytics/dashboards/application-health-score.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -description: View and understand the Application Health Score for your application. -nd-docs: DOCS-526 -title: Understanding the Application Health Score -toc: true -weight: 20 -type: -- concept ---- - -## Overview - -When you log in to the F5 NGINX Controller user interface, you will see the **Analytics Dashboard Overview** page. This page contains an Application Health Score (AHS) that reflects your application's performance. - -The AHS is a customizable [Apdex-like numerical measure](https://www.apdex.org/) that can be used to estimate the quality of experience for your web application. It lets you configure service-level monitoring for your applications. - -You can select any combination of the following three service-level indicators (SLI) to create your AHS: - -- Successful requests (selected by default), -- (Optional) Request time (95th percentile), and -- (Optional) NGINX Controller Agent availability. - -Successful requests are determined according to the total observed average request time (P95) either below the low threshold (100% satisfying) or between the low and high threshold (partially satisfying). - -A simplified formula for AHS is as follows: - -`AHS = (Successful Requests %) * (Timely Requests %) * (Agent Availability %)` - -When you select the Request Time (95th percentile) for inclusion in the AHS, you can set two thresholds for the total observed average request time (P95): - -- Low threshold for satisfying requests. -- High threshold for partially satisfying requests. - -If the average request time (P95) for the selected time period is below the low threshold, this is considered as a "100% satisfying" state of requests. - -If the request time is above the low threshold and below the high threshold, a "satisfaction ratio" is calculated accordingly. -Requests above the high threshold are considered to be "0%", or "unsatisfying". - -For example: If the low threshold is 0.2s and the high threshold is 1s, a request time greater than 1s would be considered unsatisfying and the resulting score would be 0%. - -The algorithm for calculating the AHS is as follows. Here, `T1` represents the low threshold and `T2` represents the high threshold. - -```nginx -successful_req_pct = (nginx.http.request.count - nginx.http.status.5xx) / nginx.http.request.count - -if (nginx.http.request.time.pctl95 < T1) - timely_req_pct = 1 -else - if (nginx.http.request.time.pctl95 < T2) - timely_req_pct = 1 - (nginx.http.request.time.pctl95 - T1) / (T2 - T1) - else - timely_req_pct = 0 - -m1 = successful_req_pct -m2 = timely_req_pct -m3 = agent_up_pct - -app_health_score = m1 * m2 * m3 -``` - -## Customize the Application Health Score - -Take the steps below to customize the Application Health Score (AHS) that displays on the Overview page. - -{{< call-out "note" >}} -By default, the AHS and other metrics on the **Overview** page are calculated for all of the Instances monitored by the Controller Agent. -{{< /call-out >}} - -1. Open the NGINX Controller user interface and log in. -2. On the **Overview** page, select the Settings (gear) icon in the Application Health Score panel. -3. In the **Service Level Monitoring** window, define the following: - - - (Optional) Create a custom name for the monitor (replaces "Application Health Score"). - - (Optional) Select tags to narrow the data source(s) to a specific Instance or set of Instances. - - Select the Service Indicators that you want to include in the score calculation. - - - Successful requests (selected by default). - - Request time (95th percentile): Set a low threshold and a high threshold, in seconds. - - Agent availability. - -4. Select **Save**. - -## What's Next - -- [Overview of metrics and metadata]({{< ref "/controller/analytics/metrics/overview-metrics-metadata.md" >}}) -- [Set up Metrics Collection]({{< ref "/controller/admin-guides/config-agent/configure-metrics-collection.md" >}}) -- [Metrics Catalog Reference]({{< ref "/controller/analytics/catalogs/metrics.md" >}}) -- [Dimensions Catalog Reference]({{< ref "/controller/analytics/catalogs/dimensions.md" >}}) -- [Custom Dashboards]({{< ref "/controller/analytics/dashboards/custom-dashboards.md" >}}) - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/analytics/dashboards/custom-dashboards.md b/content/controller/analytics/dashboards/custom-dashboards.md deleted file mode 100644 index a4cc10730..000000000 --- a/content/controller/analytics/dashboards/custom-dashboards.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -description: Create custom dashboards to view custom graphs. -nd-docs: DOCS-527 -title: Create Custom Dashboards -toc: true -weight: 20 -type: -- how-to ---- - -## Overview - -You can use the F5 NGINX Controller user interface to create your own Dashboards populated with customizable graphs of NGINX and system-level metrics. - -{{< call-out "note" >}} - -- You can add up to 30 Elements to Dashboard. -- Dashboards are accessible by all Users. - -{{< /call-out >}} - -## Before You Begin - -- [Install the NGINX Controller Agent on instances that you want to monitor]({{< ref "/controller/admin-guides/install/install-nginx-controller-agent.md" >}}) -- [Configure Metrics collection on your NGINX instances]({{< ref "/controller/admin-guides/config-agent/configure-metrics-collection.md" >}}) - -## Dashboards - -In NGINX Controller, you can create dashboards to display custom graphs. Some use cases for custom graphs include the following: - -- Checking NGINX performance for a particular application or microservice, for example, based on the URI path -- Displaying metrics per virtual server -- Visualizing the performance of a group of NGINX servers, for example, front-end load-balancers or an NGINX edge caching layer -- Analyzing a detailed breakdown of HTTP status codes per application - -When building a custom graph, metrics can be summed or averaged across NGINX servers. By using metric filters, it is possible to create additional "metric dimensions", for example, reporting the number of POST requests for a specific URI. - - {{< call-out "note" >}} - -The functionality of user-defined dashboards recently changed in NGINX Controller. Some of the functionalities that were present in the -previous version might not be currently present or work differently. Your old dashboards were not migrated to the new version. - - {{< /call-out >}} - -## Create a Custom Dashboard - -To create a custom dashboard: - -1. Open the NGINX Controller user interface and log in. -2. The first page you will see is the **Analytics Overview** page. -3. Select the Dashboards tab to see the **My Dashboards** list page. -4. To create a new dashboard - use **Create** button and provide required information. - -### Add a Dashboard Element - -To add an Element to a Dashboard: - -1. Create a new Dashboard or select the edit icon to edit an existing Dashboard. -2. Select **Add element** button. -3. Provide a title. -4. (Optional) Enter a description of the Element. -5. Select the type of Element to add: - - - **Line chart** displays data for a specific time period - - **Stat** displays the metric's most recent value - -6. Select a metric from the drop-down menu. -7. Select the aggregation method for the selected metric. - {{< call-out "note" >}} -For more information about metrics and supported aggregation methods, see the [Metrics Catalog Reference]({{< ref "/controller/analytics/catalogs/metrics.md" >}}). - {{< /call-out>}} -8. (Optional) Add a filter to refine the data. For example, you can limit the data to a specific App or Environment. -9. (Optional) Select **Add metrics** to add more metrics. - {{< call-out "note" >}} -Additional metrics can only be added to a **Line chart** Element. - {{< /call-out >}} -10. (Optional) Select the **Override Default Time Settings** option to select a time range for the Element. - - - The default time range is the last seven days. - - You can select a new pre-defined time range or select **Custom time range** to define a new time range. - -11. Select **Create** or **Edit** to save your Element settings. - -## Filter Metrics - -You can use the filtering functionality for NGINX metrics. If you select **Add filter**, you can add multiple criteria to define specific "metric dimensions". - -The filter consists of one or more expressions in a form of: - -`dimensionName operator value` - -where: - -- `dimensionName` is a name of the dimension from the dimensions catalog -- `operator` is a comparison rule (equality, likeliness, etc.) -- `value` is a value to which we want compare the dimensions value - -Filters can be used in conjunction using `AND` or `OR` logical operators. There is no possibility of nesting these expressions. - -Filters are used to narrow down the data set presented on the chart/stat. For example, you may not want to display the data for all of your applications, but only for the particular one. - -## Limitations - -- You are not able to add more than 30 elements to the single dashboard. -- All dashboards are accessible for all users. -- Dashboards defined in the old custom dashboards view are not migrated to the new dashboards view. - -## Clone a Custom Dashboard - -To clone an existing dashboard from the Dashboards page, select the **Clone** icon on a dashboard's row, or select **Clone** from the toolbar above the table (you need to select a dashboard first). - -You can also clone a dashboard from the elements view using the **Clone Dashboard** button. This button is not available in "edit" mode, so make sure you finish editing a dashboard before cloning it. - -When you clone a dashboard, the new one will have the same display name as the original dashboard + the current date. For example, if you clone the "My system graphs" dashboard, the cloned dashboard's display name will be something like "My system graphs Aug 24, 2021, 14:37:32". You can change the display name later on the Edit Config page. - -## Predefined Dashboards - -You can find predefined dashboards on the Dashboards page. Predefined dashboards have a special "Read Only" tag, include elements to show the most common metrics, and cover some common cases. The predefined dashboards might be helpful in learning how custom dashboards work. You can clone any of the predefined dashboards and then modify them as needed. - -Predefined dashboards cannot be deleted or modified. - -{{< call-out "note" >}} - -- Predefined dashboards were introduced in NGINX Controller 3.21. -- If you already have custom dashboards, the predefined ones should appear at the end of the list when default sorting is applied. - -{{< /call-out >}} - -## What's Next - -- [Overview Dashboard]({{< ref "/controller/analytics/dashboards/overview-dashboard.md" >}}) -- [Overview of Metrics and Metadata]({{< ref "/controller/analytics/metrics/overview-metrics-metadata.md" >}}) -- [Set up Metrics Collection]({{< ref "/controller/admin-guides/config-agent/configure-metrics-collection.md" >}}) -- [Metrics Catalog Reference]({{< ref "/controller/analytics/catalogs/metrics.md" >}}) -- [Dimensions Catalog Reference]({{< ref "/controller/analytics/catalogs/dimensions.md" >}}) - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/analytics/dashboards/overview-dashboard.md b/content/controller/analytics/dashboards/overview-dashboard.md deleted file mode 100644 index 2693c0f2b..000000000 --- a/content/controller/analytics/dashboards/overview-dashboard.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -description: Learn about the Dashboards that displays cumulative metrics for your - NGINX Instances. -nd-docs: DOCS-528 -title: Analytics Overview -toc: true -weight: 10 -type: -- how-to ---- - -## Overview - -The **Analytics Dashboards** provides an at-a-glance summary of the state of your F5 NGINX infrastructure and your application performance. - -## Before You Begin - -- [Install the NGINX Controller Agent on Instances that you want to monitor]({{< ref "/controller/admin-guides/install/install-nginx-controller-agent.md" >}}) - -## Overview Dashboard - -When you log in to the NGINX Controller user interface, the **Analytics Overview** page displays first by default. Select the Dashboards tab to see the **My Dashboards** list page. On the **Dashboard Overview** page, you can view the key indicators noted below. By default, the graphs display metrics for the last hour. You can select any of the default time periods -- one hour, four hours, one day, two days, or one week -- to get a better idea of your apps' overall health and performance. To view metrics over longer time periods, you can create a [custom dashboard]({{< ref "/controller/analytics/dashboards/custom-dashboards.md" >}}). - -The cumulative [metrics]({{< ref "/controller/analytics/metrics/overview-metrics-metadata.md" >}}) displayed on the **Analytics Overview** page are: - -### System Metrics - -- [Application Health Score]({{< ref "/controller/analytics/dashboards/application-health-score.md" >}}): the health score for your application. -- Average CPU: 100 - AVG of the system.cpu.idle (CPU spent in an idle state) -- Average Memory: AVG of the `system.mem.used` metric - -### Application Metrics - -- Time to First Byte: AVG of the `client.ttfb.latency.max` metric -- Bytes In/s (Bytes In per second): RATE of the `http.request.bytes_rcvd` metric -- Bytes Out/s (Bytes Out per second): RATE of the `http.request.bytes_sent` metric - -- Total Requests: SUM of the `nginx.http.request.count` metric. -- HTTP 5XX Errors: SUM of the `nginx.http.status.5xx` metric. -- HTTP 4XX Errors: SUM of the `nginx.http.status.4xx` metric. -- Request time (P95): AVG of the `nginx.http.request.time.pctl95` metric. - -- Avg Client Response Latency: AVG of the `client.response.latency.max` metric -- Avg Upstream Response Latency: AVG of the `upstream.response.latency.max` metric -- Avg Client Network Latency: AVG of the `client.network.latency.max` metric. - -{{< call-out "note" >}} - -By default, the metrics are calculated for **all** of your Controller Agent-monitored Instances. - -To display metrics for a specific set of hosts (for example, only for "production"), select the gear icon on the Application Health Score panel, then add a tag or tags by which you want to filter the results. - -{{< /call-out >}} - -## What's Next - -- [Overview of metrics and metadata]({{< ref "/controller/analytics/metrics/overview-metrics-metadata.md" >}}) -- [Metrics Catalog Reference]({{< ref "/controller/analytics/catalogs/metrics.md" >}}) -- [Dimensions Catalog Reference]({{< ref "/controller/analytics/catalogs/dimensions.md" >}}) -- [Application Health Score]({{< ref "/controller/analytics/dashboards/application-health-score.md" >}}) -- [Custom Dashboards]({{< ref "/controller/analytics/dashboards/custom-dashboards.md" >}}) - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/analytics/data-explorer/_index.md b/content/controller/analytics/data-explorer/_index.md deleted file mode 100644 index ce3a033f6..000000000 --- a/content/controller/analytics/data-explorer/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -description: Learn about F5 NGINX Controller Data Explorer. -title: Data Explorer -weight: 120 -url: /nginx-controller/analytics/data-explorer/ ---- - diff --git a/content/controller/analytics/data-explorer/how-to-use.md b/content/controller/analytics/data-explorer/how-to-use.md deleted file mode 100644 index bc9471d26..000000000 --- a/content/controller/analytics/data-explorer/how-to-use.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -description: Use the Data Explorer to examine the metrics that F5 NGINX Controller - collects. -nd-docs: DOCS-529 -title: How To Use the Data Explorer -toc: true -weight: 20 -type: -- how-to ---- - -## Overview - -This topic explains how to use the Data Explorer to view the metrics that F5 NGINX Controller collects. - -The Data Explorer lets you perform these following tasks: - -- Easily switch between contexts, metrics, and dimensions -- Specify a time range of interest -- Set the aggregation mode -- Compare results to previous periods -- Export the query that's used to generate the charts as a URL, which you can use outside of NGINX Controller - -  - -## Select the Context - -To get started with the Data Explorer, you need to select the context for the data you want to view. - -1. Open the NGINX Controller user interface and log in. -1. Select the NGINX Controller menu icon, then select **Analytics > Explorer**. -1. On the Data Explorer detail page, select a context area -- **Instances**, **Environments**, **Gateways**, or **Apps** -- for which you want to view data. - -{{< call-out "note" >}} -When you access the Data Explorer from other areas of the browser interface, the context is already defined. So, for example, if you select Data Explorer from within the Instances module (**Infrastructure > Instances > Data Explorer**), the data for your instances is displayed. When you switch between contexts, the metrics options, such as `system.cpu.idle` or `system.load.5`, are updated. -{{< /call-out >}} - -  - -## Select a Resource - -When you [select the context](#select-the-context) for the Data Explorer, a list of related resources is shown. If there aren't any related resources for the selected context, you'll see the message "No Data" on the Data Explorer detail page. - -{{< call-out "note" >}} - -If you don't see a resource in the list, but you expect it to be there, check the [selected metric](#metrics) and the [selected time range](#time-range). When a resource doesn't have the data for the [selected time range](#time-range) it won't be added to the resources list. - -{{< /call-out >}} - -To view data for a resource, select the resource's name from the resource list. - -{{< img src="/ctlr/img/data-explorer_resource.png">}} - -## Metrics - -The [list of metrics]({{< ref "/controller/analytics/catalogs/metrics.md" >}}) is sorted alphabetically, and you can use the search feature to filter the list. As previously mentioned, the list of metrics depends on the context you've selected for the Data Explorer. For example, if you've chosen Instances for the context, then the list of metrics will be for instances. - -{{< img src="/ctlr/img/data-explorer_metric.png">}} - -When the selected metric changes, the **Aggregation** and **Group By** selectors are updated correspondingly (as well as the [list of resources](#select-a-resource) and the [Dimensions panel](#dimensions-panel)). Some metrics have different lists of **Aggregation** and **Group By** values. For example, the `http.response_code` dimension, which is a valid **Group By** value for the `http.request.count` metric, is not available for the `nginx.workers.cpu.user` metric because these items are from different contexts and aren't related to each other. - -## Aggregation Mode - -Use the Aggregation selector -- the Σ symbol with possible values of `AVG`, `MAX`, `MIN`, `RATE`, and `SUM` -- to [aggregate the data]({{< ref "/controller/analytics/metrics/metrics-api.md#aggregations" >}}). The list of possible aggregation values depends on the metrics that's selected. - -{{< img src="/ctlr/img/data-explorer_aggregation.png">}} - -## Group by Dimension - -Use the **Group By** selector to [group the data by a chosen dimension]({{< ref "/controller/analytics/metrics/metrics-api.md#groupby" >}}). - -In the following example image, the data for the `bytes_rcvd` metric is grouped by the dimension `http.request_method`, which displays a data series for the HTTP methods `DELETE`, `GET`, `LINK`, and so on. - -{{< img src="/ctlr/img/data-explorer_group-by.png">}} - -When a **Group By** selection is applied, the chart displays a top-10 data series. For example, let's say you want to check disk usage, so you select the metric `system.disk.total` and `file_path` as the dimension to group by. The chart would then display the top-10 mount points with the highest values. If you have more than 10 mount points, you'll see the top-10 mount points plus an 11th data series that's an aggregation of the rest of the data using the same selection criteria. In other words, you'll see a chart of the 10 most used mount points plus a chart of all the other mount points aggregated into one data series. When a **Group By** dimension is selected, and there are more than 10 dimensions, the 11th data series is named "Other." - -{{< call-out "note" >}} When MIN is selected as the aggregation method, the top-10 series are sorted ascending, lowest-to-highest. For all of the other aggregation methods, the top-10 values are sorted descending, highest-to-lowest. {{< /call-out >}} - -  - -## Time Range - -Use the time range selector above the chart to select the time range you want to examine. You can specify a custom time range if the predefined options aren't what you need. - -The granularity of the data series is based on the selected time range and can vary from 30 seconds to five days to make the chart easier to read. - -When you change the time range, the [list of resources](#select-a-resource) is updated correspondingly and it only includes the resources which have the data for the selected time range. - -## Compare To - -Next to the [time range](#time-range) selector, you'll find the `Compare To` list of options. This list allows you to compare data for the selected time frame with data from an earlier period. For example, you may want to view CPU usage for the last hour and compare the results to the same time from yesterday, last week, or even the previous year. - -{{< img src="/ctlr/img/data-explorer_comparison.png">}} - -{{< call-out "note" >}} - -- When comparison is turned on for a data series, the data have the suffix "Compare" in their names. -- If there is no data available for a comparison period, the comparison data series is not shown. -- When a Group By dimension is applied, data comparisons are made only with the top-10 data series and not with the "Other" series, if there is one. See the [Group By](#group-by) section for a discussion of the top-10 and "Other" series. -{{< /call-out >}} - -  - -## Show Query - -On the Data Explorer details page, you can select the **Show Query** button (eye icon) to view the URL that's used to query the Metrics API to get the data you see in the chart. If you copy the query and use it outside of NGINX Controller, you'll get the same data but in JSON format. - -The query updates whenever the selection options change. The query doesn't include requests for comparison data. - -{{< call-out "note" >}} -For instructions on how to understand the Metrics API response, refer to the topic [Using the Metrics API]({{< ref "/controller/analytics/metrics/metrics-api#understanding-the-metrics-api-response" >}}). -{{< /call-out>}} - -  - -## Dimensions panel - -On the right of the screen there is a panel with the list of dimensions available for the [selected metric](#metrics). - -{{< img src="/ctlr/img/data-explorer_dimensions-drawer.png">}} - -Each dimension is presented as a section in which you can expand and see the values for it. The values are aggregated with the [selected aggregation method](#aggregation-mode) for the [selected time range](#time-range). They depend on the following selected parameters: - -- [context](#select-the-context) -- [resource](#select-a-resource) -- [metric](#metrics) -- [aggregation](#aggregation-mode) -- [time range](#time-range) - -When one of the parameters changes, you'll see the values for expanded dimensions are also updated. - -You can see only top-10 values for each dimension, and based on the [selected aggregation](#aggregation-mode), they are sorted in following ways: - -- When MIN is selected as the aggregation method, the top-10 series are sorted ascending, lowest-to-highest. -- For all of the other aggregation methods, the top-10 values are sorted descending, highest-to-lowest. - -{{< call-out "note" >}} - -- When the selected metric changes, the list of dimensions may change as well, and some of the dimensions you recently explored may disappear from the panel. -- This panel was added in NGINX Controller v3.18. - -{{< /call-out >}} - -  - -{{< versions "3.17" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/analytics/events/_index.md b/content/controller/analytics/events/_index.md deleted file mode 100644 index 5a1be006d..000000000 --- a/content/controller/analytics/events/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -description: View system events and audit logs. -title: Events -weight: 140 -url: /nginx-controller/analytics/events/ ---- - diff --git a/content/controller/analytics/events/view-events.md b/content/controller/analytics/events/view-events.md deleted file mode 100644 index a2baabfbe..000000000 --- a/content/controller/analytics/events/view-events.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -description: View the audit log of system and user actions. -nd-docs: DOCS-530 -title: View Events -toc: true -weight: 20 -type: -- how-to ---- - -## Overview - -The Events page shows a log of the system and user actions for F5 NGINX Controller. The logs are organized by event categories and levels, making it easy to identify and review issues. - -## View Events - -Take the steps below to view NGINX Controller events: - -1. Open the NGINX Controller user interface and log in. -1. On the Analytics menu, select **Events**. -1. To view additional information about a particular event, select the event from the list to open the details pane. - -You can filter the events by typing a keyword in the search box and/or by selecting a time period. You can filter the results further by [Event Categories](#event-categories) or [Event Levels](#event-levels). - -## Event Categories - -You can select from the following Event Categories: - -- Agent Events; -- Agent Status Events; -- Controller Events; -- Audit Events -- a log of all actions performed by NGINX Controller users; -- Forwarder Notifications -- events emitted by [Data Forwarders]({{< ref "/controller/analytics/forwarders/_index.md" >}}) -- Workload Health Events -- events emitted by the Controller Agent when the health of an upstream server changes; - -To view the logs for a specific category, select the category name from the **Event Categories** list. - -## Event Levels - -Event levels sort events according to their information level: Debug, Info, Error, Warning, and Critical. - -To view the logs for a specific level, select the level name from the **Event Levels** list. - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/analytics/forwarders/_index.md b/content/controller/analytics/forwarders/_index.md deleted file mode 100644 index 4fa75a092..000000000 --- a/content/controller/analytics/forwarders/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -description: Learn how to forward data from F5 NGINX Controller to external services. -title: Data Forwarders -weight: 130 -url: /nginx-controller/analytics/forwarders/ ---- - diff --git a/content/controller/analytics/forwarders/forward-analytics-to-datadog.md b/content/controller/analytics/forwarders/forward-analytics-to-datadog.md deleted file mode 100644 index 660e8eeb6..000000000 --- a/content/controller/analytics/forwarders/forward-analytics-to-datadog.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -description: How to forward Analytics data to Datadog. -nd-docs: DOCS-531 -title: Forward Analytics Data to Datadog -toc: true -weight: 100 -type: -- tutorial ---- - -## Overview - -Follow the steps in this guide to set up an F5 NGINX Controller Integration that forwards data to [Datadog](https://www.datadoghq.com/). - -## Before You Begin - -This guide assumes that you are already an active Datadog user. If you haven't already done so, you will need to [install and configure Datadog](https://docs.datadoghq.com/) before you proceed. - -You will also need to [Create an Integration]({{< ref "/controller/platform/integrations/datadog-integration.md" >}}) for your Datadog forwarder. - -## Create a Forwarder - -Take the following steps to create a Forwarder for Datadog: - -1. Open the NGINX Controller user interface and log in. -2. Select the NGINX Controller menu icon, then select **Platform**. -3. On the **Platform** menu, select **Data Forwarders**. -4. On the **Data Forwarders** menu, select the **Create Data Forwarder** quick action. -5. Add a name. -6. (Optional) Add a display name. -7. (Optional) Add a description. -8. Select your **Integration Reference** from the dropdown menu or select **Create New** to create a new Integration. -9. In the **Collector Type** list, select `DATADOG`. -10. In the **Source** list, select the type of data to forward: `metrics` or `events`. -11. In the **Output Format** list, select `DATADOG`. -12. The **Selector** field consists of the following query parameters (optional): - -- `names` (inapplicable for `EVENTS`): The list of metrics names that you want to forward. -- `excluded_names` (inapplicable for `EVENTS`): The list of metric names that you don't want to forward. -- `filter`: The conditions to use to refine the metrics or events data. -- Example usage when selecting metrics: `"names=nginx.*&excluded_names=nginx.upstream.*filter=app='myapp'"` -- Example usage when selecting events: `"filter=type='security violation' AND app='my-app'"` - -13. (Optional) Add additional **Streams** as required using the **Add Stream** button. - -{{< call-out "important" >}} - -Each metric will be prefixed with a common namespace -- such as "nginx-controller" -- before it is sent to Datadog. This prefix is used by Datadog only and is not applied to any of the internal NGINX Controller metrics. Refer to the [metrics catalog]({{< ref "/controller/analytics/catalogs/metrics.md" >}}) for the full list of valid metric names. - -For events, the "nginx-controller" namespace is added to the ["ddsource" key](https://docs.datadoghq.com/api/v1/logs/#send-logs). - -{{< /call-out >}} - -NGINX Controller events are sent to Datadog as logs and NGINX Controller dimensions are sent as tags. The Forwarder converts the dimension data to comply with the Datadog [tags format](https://docs.datadoghq.com/getting_started/tagging/#defining-tags) prior to forwarding it. In some cases, the original dimension value may be transformed to fit the tag requirements. This includes replacing comma characters (`,`) with semicolons (`;`) to ensure that Datadog will properly handle the incoming payload. - -{{< call-out "note" >}} - -See the [NGINX Controller Metrics]({{< ref "/controller/analytics/metrics/_index.md" >}}) docs for more information. - -{{< /call-out>}} - -## Verification - -Soon after you create the Datadog forwarder, you can view the selected metrics in Datadog. - -1. Log into the [Datadog web interface](https://app.datadoghq.com/). -2. On the navigation menu, select **Metrics** > **Summary**. - -## What's Next - -- Refer to [Troubleshooting Forwaders]({{< ref "/controller/support/troubleshooting-forwarders.md" >}}) for tips on resolving common issues. - -{{< versions "3.8" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/analytics/forwarders/forward-analytics-to-otlp.md b/content/controller/analytics/forwarders/forward-analytics-to-otlp.md deleted file mode 100644 index e8dcdd18e..000000000 --- a/content/controller/analytics/forwarders/forward-analytics-to-otlp.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -description: How to forward Analytics Metrics to OpenTelemetry Collector. -nd-docs: DOCS-532 -title: Forward Analytics Metrics to OpenTelemetry Collector -toc: true -weight: 201 -type: -- tutorial ---- - -## Overview - -Follow the steps in this guide to set up an F5 NGINX Controller integration that forwards metrics to OpenTelemetry Collector. - -## Before You Begin - -This guide assumes that you already have a working instance of any OpenTelemetry Collector. - -You will also need to [Create an Integration]({{< ref "/controller/platform/integrations/otlp-integration.md" >}}) for your OpenTelemetry Collector forwarder. - -## Create a Forwarder - -Take the following steps to create a forwarder for OpenTelemetry Collector: - -1. Open the NGINX Controller user interface and log in. -2. Select the NGINX Controller menu icon, then select **Platform**. -3. On the **Platform** menu, select **Data Forwarders**. -4. On the **Data Forwarders** menu, select **Create Data Forwarder**. -5. Add a name. -6. (Optional) Add a display name. -7. (Optional) Add a description. -8. Select your **Integration Reference** from the dropdown list, or select **Create New** to create a new integration. -9. In the **Collector Type** list, select `OTLP_HTTP` or `OTLP_GRPC`. -10. In the **Source** list, select the type of data to forward: `METRICS`. -11. In the **Output Format** list, select `OTLP`. -12. The **Selector** field consists of the following query parameters (optional): - -- `names`: The list of metrics names that you want to forward. -- `excluded_names`: The list of metric names that you don't want to forward. -- `filter`: The conditions to use to refine the metrics data. -- Example usage when selecting metrics: `"names=nginx.*&excluded_names=nginx.upstream.*&filter=app='myapp'"` - -13. (Optional) Select **Add Stream** to add additional streams, as needed. - -{{< call-out "important" >}} - -Each metric is prefixed with a common namespace -- for example, "nginx-controller" -- before it's sent to OpenTelemetry Collector. This prefix is used only by OpenTelemetry Collector and is not applied to any internal NGINX Controller metrics. Refer to the [metrics catalog]({{< ref "/controller/analytics/catalogs/metrics.md" >}}) for the full list of valid metric names. - -We have tested compatability with OTLP collector v0.33.0. We will most likely support versions higher than this, assuming backwards compatability from OTLP. - -{{< /call-out >}} - -{{< call-out "note" >}} - -See the [NGINX Controller Metrics]({{< ref "/controller/analytics/metrics/_index.md" >}}) docs for more information. - -{{< /call-out>}} - -## What's Next - -- Refer to [Troubleshooting Forwaders]({{< ref "/controller/support/troubleshooting-forwarders.md" >}}) for tips on resolving common issues. - -{{< versions "3.16" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/analytics/forwarders/forward-analytics-to-splunk.md b/content/controller/analytics/forwarders/forward-analytics-to-splunk.md deleted file mode 100644 index fc62eccf5..000000000 --- a/content/controller/analytics/forwarders/forward-analytics-to-splunk.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -description: How to forward Analytics data to Splunk. -nd-docs: DOCS-533 -title: Forward Analytics Data to Splunk -toc: true -weight: 200 -type: -- tutorial ---- - -## Overview - -Follow the steps in this guide to set up an F5 NGINX Controller Integration that forwards data to [Splunk](https://www.splunk.com/). - -## Before You Begin - -This guide assumes that you are already an active Splunk user. If you haven't already done so, you will need to [install and configure Splunk](https://docs.splunk.com/Documentation) before you proceed. - -You will also need to [Create an Integration]({{< ref "/controller/platform/integrations/splunk-integration.md" >}}) for your Splunk forwarder. - -## Create a Forwarder - -Take the following steps to create a Forwarder for Splunk: - -1. Open the NGINX Controller user interface and log in. -1. Select the NGINX Controller menu icon, then select **Platform**. -1. On the **Platform** menu, select **Data Forwarders**. -1. On the **Data Forwarders** menu, select the **Create Data Forwarder** quick action. -1. Add a name. -1. (Optional) Add a display name. -1. (Optional) Add a description. -1. Select your **Integration Reference** from the dropdown menu or select **Create New** to create a new Integration. -1. In the **Collector Type** list, select `SPLUNK`. -1. In the **Source** list, select the type of data to forward: `metrics` or `events`. -1. In the **Output Format** list, select `SPLUNK`. -1. The **Selector** field consists of the following query parameters (optional): - - - `names` (inapplicable for `EVENTS`): The list of metrics names that you want to forward. - - `excluded_names` (inapplicable for `EVENTS`): The list of metric names that you don't want to forward. - - `filter`: The conditions to use to refine the metrics or events data. - - Example usage when selecting metrics: `"names=nginx.*&excluded_names=nginx.upstream.*filter=app='myapp'"` - - Example usage when selecting events: `"filter=type='security violation' AND app='my-app'"` - -1. (Optional) Add additional **Streams** as required using the **Add Stream** button. - -{{< call-out "important" >}} - -Each metric will be prefixed with a common namespace -- such as `nginx-controller` -- before it is sent to Splunk. This prefix is used by Splunk only and is not applied to any of the internal NGINX Controller metrics. Refer to the [metrics catalog]({{< ref "/controller/analytics/catalogs/metrics.md" >}}) for the full list of valid metric names. - -In case of events, the "nginx-controller" namespace will be placed in the ["source" key](https://docs.splunk.com/Documentation/Splunk/8.1.1/Data/FormateventsforHTTPEventCollector#Event_metadata) and sent with each event. - -{{< /call-out >}} - -{{< call-out "note" >}} - -See the [NGINX Controller Metrics]({{< ref "/controller/analytics/metrics/_index.md" >}}) docs for more information. - -{{< /call-out>}} - -## What's Next - -- Refer to [Troubleshooting Forwaders]({{< ref "/controller/support/troubleshooting-forwarders.md" >}}) for tips on resolving common issues. - -{{< versions "3.6" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/analytics/forwarders/forward-analytics-to-syslog.md b/content/controller/analytics/forwarders/forward-analytics-to-syslog.md deleted file mode 100644 index f135c3322..000000000 --- a/content/controller/analytics/forwarders/forward-analytics-to-syslog.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -description: How to forward Analytics Events to Syslog. -nd-docs: DOCS-534 -title: Forward Analytics Events to Syslog -toc: true -weight: 201 -type: -- tutorial ---- - -## Overview - -Follow the steps in this guide to set up a F5 NGINX Controller Integration that forwards events to a syslog server. - -## Before You Begin - -This guide assumes that you already have a working instance of any syslog server. - -If you haven't already done so, you can use an open-source version of [Syslog-NG](https://www.syslog-ng.com/products/open-source-log-management/). - -You will also need to [Create an Integration]({{< ref "/controller/platform/integrations/syslog-integration.md" >}}) for your Syslog forwarder. - -## Create a Forwarder - -Take the following steps to create a Forwarder for Splunk: - -1. Open the NGINX Controller user interface and log in. -1. Select the NGINX Controller menu icon, then select **Platform**. -1. On the **Platform** menu, select **Data Forwarders**. -1. On the **Data Forwarders** menu, select the **Create Data Forwarder** quick action. -1. Add a name. -1. (Optional) Add a display name. -1. (Optional) Add a description. -1. Select your **Integration Reference** from the dropdown menu or select **Create New** to create a new Integration. -1. In the **Collector Type** list, select `SYSLOG`. -1. In the **Source** list, select the type of data to forward: `events`. NGINX Controller can forward only `EVENTS` data to syslog. -1. In the **Output Format** list, select `SYSLOG`. -1. The **Selector** field consists of the following query parameters (optional): - - - `filter`: The conditions to use to refine the metrics or events data. - - Example usage: `"filter=type='security violation' AND app='my-app'"` - -1. (Optional) Add additional **Streams** as required using the **Add Stream** button. - -## What's Next - -- Refer to [Troubleshooting Forwaders]({{< ref "/controller/support/troubleshooting-forwarders.md" >}}) for tips on resolving common issues. - -{{< versions "3.16" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/analytics/metrics/_index.md b/content/controller/analytics/metrics/_index.md deleted file mode 100644 index 841c2b5b5..000000000 --- a/content/controller/analytics/metrics/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -description: Learn about F5 NGINX Controller Metrics. -title: Metrics -weight: 150 -url: /nginx-controller/analytics/metrics/ ---- - diff --git a/content/controller/analytics/metrics/metrics-api.md b/content/controller/analytics/metrics/metrics-api.md deleted file mode 100644 index 900da4362..000000000 --- a/content/controller/analytics/metrics/metrics-api.md +++ /dev/null @@ -1,479 +0,0 @@ ---- -description: Tips and tricks for using the Metrics API query parameters to refine - your data. -nd-docs: DOCS-535 -title: Using the Metrics API -toc: true -weight: 50 -type: -- tutorial ---- - -## Overview - -You can use the F5 NGINX Controller Analytics module to monitor your NGINX instances and evaluate your applications' performance. The [Metrics API]({{< ref "/controller/api/_index.md" >}}) query parameters let you fine-tune your system data based on parameters such as time window, aggregation, time resolution, and filter. - -By using different combinations of these query parameters, you can gather information that lets you: - -- Identify which of your Apps receives the most traffic -- query for the highest number of requests among all apps. -- Understand the behavior of your back-end server(s) -- query for upstream latency by instance or location. -- Monitor your application performance -- filter on HTTP response codes to track the number of successful or failed requests by app and environment. -- Understand how your App behavior and/or usage changes across version releases -- compare data like the examples above across different versions of your application. - -## Usage - -You can use the NGINX Controller [Metrics API]({{< ref "/controller/api/_index.md" >}}) to query for desired metric names and fine-tune the data returned based on the following parameters: - -- time window (`startTime` and `endTime`) -- `filter` -- `resolution` -- `groupBy` -- `seriesLimit` -- `orderSeriesBy` -- `dimensions` - -{{< call-out "note" >}} -Because NGINX Controller is constantly evolving, these example metrics and dimensions may differ from what you see with your NGINX Controller instance. Some metrics may require pre-configured applications to be visible in the API. -{{< /call-out >}} - -### Understanding the Metrics API Response - -The [Metrics API]({{< ref "/controller/api/_index.md" >}}) response consists of query metadata and an array of `metrics` -- one array element for each queried metric. - -- The **metric** object includes the queried metric name and an array of data series associated with the metric. -- The **series** object groups metrics data according to dimension values. The series consists of dimensions (key-value map), timestamps, and the timestamps' metric values. - -```json -{ - "metrics":[ - { - "name":"http.request.count", - "series":[ - { - "dimensions":{ - "app":"app-name", - "component":"component-name", - "environment":"environment-name", - "gateway":"gateway-name", - "instance":"instance-name" - }, - "timestamps":[ - "2020-07-01T12:00:00Z" - ], - "values":[ - 1000 - ] - }, - { - "dimensions":{ - "app":"app-name-2", - "component":"component-name", - "environment":"environment-name", - "gateway":"gateway-name", - "instance":"instance-name" - }, - "timestamps":[ - "2020-07-01T12:00:00Z" - ], - "values":[ - 2000 - ] - } - ] - } - ], - "queryMetadata":{ - "endTime":"2020-07-01T12:00:00.970106672Z" - } -} -``` - -In the preceding example, there are two data series for the queried metric. The differentiator between the two series is the "app" name. This name is what makes NGINX metrics app-centric: you can easily distinguish metrics based on their dimensions' values, such as an App, Environment, or Gateway name. - -You can view the full list of the supported metrics and dimensions, with detailed descriptions, by querying the Catalog API: - -```curl -curl -X GET --cookie "session=" --url "{controller-IP}/api/v1/analytics/catalogs/metrics" -``` - -Likewise, you can get a full list of the available dimensions by querying the Catalogs API: - -```curl -curl -X GET --cookie "session=" --url "{controller-IP}/api/v1/analytics/catalogs/dimensions" -``` - -This information is also provided in the [Catalogs Reference]({{< ref "/controller/analytics/catalogs/_index.md" >}})). - -### Querying the Metrics API - -This section provides an overview of each query parameter and examples of using the parameters together to refine your data. - -The examples progress from basic usage to more advanced API queries. - -#### Names - -The `names` parameter is the only required parameter in the [Metrics API]({{< ref "/controller/api/_index.md" >}}). - -The following example query returns a response with the last recorded value for the queried metric: `http.request.count`: - -```curl -curl -X GET --cookie "session=" --url "{controller-IP}/api/v1/analytics/metrics?names=http.request.count" -``` - -If the dimension values differ, the `series` array in the response will contain multiple items. - -It is possible to query the API for several metrics simultaneously. To do so, provide the metric names as a comma-separated list: - -```curl -curl -X GET --cookie "session=" --url "{controller-IP}/api/v1/analytics/metrics?names=http.request.count,http.request.bytes_rcvd" -``` - -#### Time Window - -To get more than the last recorded value for the queried metric, use the following time window parameters: - -- `startTime` indicates the start of the time window to include metrics from (inclusive). -- `endTime` means the end of the time window to include metrics from (non-inclusive). - -There are a few rules to remember when working with time window parameters: - -- If you provide an `endTime`, you must also provide a `startTime`; -- `endTime` must be greater than `startTime`; -- If you give a `startTime` but don't give an `endTime`, the `endTime` defaults to the current time. - -You can define time using the `ISO 8601` format or as an offset (for example, `2020-07-14T13:07:11Z`). An offset is a string that starts with `+` or `-`, followed by a number and a unit of time: `y`, `M`, `w`, `d`, `h`, `m`, or `s`. You can also use `now` to indicate the current timestamp. - -The following example request returns all the recorded metric values for the last three hours. - -```curl -curl -X GET --cookie "session=" --url "{controller-IP}/api/v1/analytics/metrics?names=http.request.count&startTime=now-3h" -``` - -The following example query contains a fully defined time window: - -```curl -curl -X GET --cookie "session=" --url "{controller-IP}/api/v1/analytics/metrics?names=http.request.count&startTime=now-5h&endTime=2020-07-01T09:00:00Z" -``` - -In this case, the response contains metrics from 05:00:00 to 09:00:00 on the 1st of July 2020. - -#### Aggregations - -Using only `names` and time window parameters will give you the raw data points of metrics values. - -To get a more organized response, you can provide an aggregate function for each queried metric: `AVG`, `SUM`, `COUNT`, `MAX`, `MIN`, or `RATE`. - -{{< call-out "note" >}} -In the following definitions, `time period` refers to the `resolution` (if provided) or the difference between the `endTime` and `startTime` (when `resolution` is not provided). -{{< /call-out >}} - -- `AVG` - calculates the average value of the metric data samples over the period -- `SUM` - calculates the total value of the metric data samples over the period -- `COUNT` - returns the number of collected data samples of the metric over the period -- `MIN`/`MAX` - returns the minimal/maximal data sample of the metric from the given period -- `RATE` - returns an average value of the metric calculated per second (always *per second*, regardless of the provided `resolution`), based on the data available in the given period - -{{< call-out "note" >}} -You must define a `startTime` when using aggregate functions. -{{< /call-out >}} - -{{< call-out "note" >}} -The list of supported aggregate functions for any particular metric is available in the [Metrics Catalog]({{< ref "/controller/analytics/catalogs/metrics.md" >}})). -{{< /call-out>}} - -For example, the following query returns a single value (per dimension set), which is the sum of the metric values for the last three hours. To get proper values, ensure that the `endTime` is greater than the `startTime`. - -```curl -curl -X GET --cookie "session=" --url "{controller-IP}/api/v1/analytics/metrics?names=SUM(http.request.count)&startTime=now-3h" -``` - -It is possible to use aggregated and non-aggregated metrics in a single query. For this query, the [Metrics API]({{< ref "/controller/api/_index.md" >}}) returns a single value per dimension set. That value is the sum of all of the metric's values for the last three hours. - -For example: - -```curl -curl -X GET --cookie "session=" --url "{controller-IP}/api/v1/analytics/metrics?names=SUM(http.request.count),http.request.bytes_rcvd&startTime=now-3h" -``` - -{{< call-out "important" >}} -Using AVG aggregation with traffic metrics with the `.total` suffix may cause confusion because traffic metrics are already aggregated. To learn more, refer to the [Overview: Traffic Metrics]({{< ref "/controller/analytics/metrics/overview-traffic-metrics.md" >}})) topics. -{{< /call-out >}} - -#### Resolution - -If you want to change the returned data's granularity, you can use `resolution` parameter. This parameter must be used in conjunction with an aggregation function and a time window (at least `startTime` must be provided). - -The `resolution` parameter must be a valid duration. The duration is a string that starts with a number, followed by a unit of time: `y`, `M`, `w`, `d`, `h`, `m`, or `s`. - -The following example query returns three aggregated metric values. Here, we're asking for the data from last three hours with one-hour granularity: - -```curl -curl -X GET --cookie "session=" --url "{controller-IP}/api/v1/analytics/metrics?names=SUM(http.request.count),&startTime=now-3h&resolution=1h" -``` - -There may be situations when the returned resolution is lower than that requested in the query. This has to do with metrics retention periods—the older the metric, the lower the resolution. - -If the time window contains metrics with a lower resolution than was queried for, the API downsizes the granularity to the lowest possible value. You will see a warning in the `responseMetadata`: - -```json -"responseMetadata": { - "warning": "Time window is above 8 days, Resolution is downsized to 300 seconds" -} -``` - -If no `resolution` is provided, the maximum available resolution is returned. This is calculated as `endTime` - `startTime`. - -#### Filter - -This parameter, as the name indicates, filters results based on the value of dimensions. Filtering by dimension value can help to refine the data that's returned into a more specific set. - -The `filter` query consists of one or more predicates in the form of ``, where: - -- `` is the name of the dimension; -- `` is one of the supported operators (`=`, `!=`, `<`, `<=`, `>=` `>`, `in` or `not`); -- `` is value of the dimension(s) that you want to filter on. - -For example, the following query includes a simple filter on the app name. The query returns data for the application named `app1` for the last three hours. - -```curl -curl -X GET --cookie "session=" --url "{controller-IP}/api/v1/analytics/metrics?names=http.request.count&filter=app='app1'&startTime=now-3h" -``` - -{{< call-out "tip" >}} - -- Predicates can be combined into logical expressions using `OR`, `AND`, and `(` `)`. -- For matching values, wildcard (`*`) use is supported. -- We recommend wrapping predicates in single quotes to ensure that the full query string is processed correctly. - -{{< /call-out >}} - -The following example request uses `filter` with logical expressions: - -```curl -curl -X GET --cookie "session=" --url "{controller-IP}/api/v1/analytics/metrics?names=http.request.count&filter=app='ap*' and environment='prod'&startTime=now-3h" -``` - -#### GroupBy - -Using filters and aggregation functions may not be enough to allow you to get comprehensive information about a specific application or environment. - -The `groupBy` parameter helps to gather results according to the specified dimension(s). You can provide multiple dimension names as a comma-separated list. - -{{< call-out "note" >}} - -- When using `groupBy`, you must use an aggregate function and a time window (`startTime` must be defined; `endTime` is optional). -- If a request contains aggregated and non-aggregated metrics, the `groupBy` parameter will apply only to the aggregated metrics. - -{{< /call-out >}} - -For example, the following query returns data for any application with a name that starts with `ap` in the `prod` environment for the last three hours. - -```curl -curl -X GET --cookie "session=" --url "{controller-IP}/api/v1/analytics/metrics?names=SUM(http.request.count)&groupBy=app,alias&startTime=now-3h" -``` - -The API response for the query looks similar to the following: - -```json -{ - "metrics":[ - { - "aggr": "SUM", - "name":"http.request.count", - "series":[ - { - "dimensions":{ - "app":"app-name", - "alias": "alias1" - }, - "timestamps":[ - "2020-07-01T12:00:00Z" - ], - "values":[ - 1000 - ] - }, - { - "dimensions":{ - "app":"app-name-2", - "component":"alias1" - }, - "timestamps":[ - "2020-07-01T12:00:00Z" - ], - "values":[ - 2000 - ] - } - ] - } - ], - "queryMetadata":{ - "endTime":"2020-07-01T12:00:00.970106672Z" - } -} -``` - -The API returns the data for the last three hours grouped by `app` and `alias` dimensions. Unlike other queries, the API only returns those dimensions that have been selected in `groupBy`. However, the series of different dimension values are still distinguished. - -#### SeriesLimit and OrderSeriesBy - -There are cases when you might want to view only a specific data series (for example, "Top-5"). To query the API for a particular series of data, you can define the `seriesLimit` and `orderSeriesBy` query parameters. - -- `seriesLimit` sets an upper limit on the number of series returned. -- `orderSeriesBy` sorts the series values according to the order specified: - - - Must consist of two tokens -- an aggregate function and a sort order. For example, `SUM DESC`, `MIN ASC`, and so on. - - Can be used only in combination with `seriesLimit`. - -When you specify a `seriesLimit`, the response always includes one other series with an `all` metric. This series aggregates the metric values of all the series that are not included in the result. If the total number of series returned is greater than the limit specified in the query parameter, an additional series named `other` is returned. This series aggregates the metrics values of the series outside of the specified limit. - -{{< call-out "note" >}} -When using `seriesLimit`, you can only specify one metric name in the `names` parameter and one `groupBy` parameter. -{{< /call-out >}} - -**Example 1** -The following example request uses `seriesLimit` to restrict the data returned to five series: - -```curl -curl -X GET --cookie "session=" --url "{controller-IP}/api/v1/analytics/metrics?names=SUM(http.request.count)&groupBy=app&seriesLimit=5&startTime=now-3h&resolution=5m -``` - -The response contains data for the last three hours, grouped by the `app` and `alias` dimensions. Unlike the other example queries, in this example, the API returns just those dimensions that have been selected in `groupBy`. Each dimension and its corresponding values are provided as distinct items in a series. - -**Example 2** -The following example query uses both `seriesLimit` and `orderSeriesBy`: - -```curl -curl -X GET --cookie "session=" --url "{controller-IP}/api/v1/analytics/metrics?names=SUM(some.metric.name)&groupBy=someDimension&seriesLimit=5&orderSeriesBy=MAX DESC&startTime=now-1d&endTime=now&resolution=5m -``` - -**Example 3** -Building on the previous examples, here we use `seriesLimit` and `orderSeriesBy` to get the top-5 URIs with the highest number of bytes received for a specific App and Environment: - -```curl -curl -X GET --cookie "session=" --url "{controller-IP}/api/v1/analytics/metrics?names=SUM(http.request.bytes_rcvd)&startTime=now-1h&filter=app='app1' AND environment='qa'&groupBy=http.uri&seriesLimit=5&orderSeriesBy=MAX DESC -``` - -In this case, the API returns five data series for the last hour ordered by MAX value in descending order for bytes received per URL, where the data is related to the application `app1` deployed on the environment `prod`. - -Together, these parameters are particularly useful for refining data. The `seriesLimit` says how many series should be returned, `orderSeriesBy` parameter defines the criteria for ordering series. - -#### Dimensions - -You can use the `dimensions` query parameter to specify which dimension(s) should be included in each metric series' response. - -Dimensions not specified in the query parameter will not be included in the response. This may result in some series having the same dimension set but being returned as separate list items. - -The following example returns results for the specified metric, where `dimensions=environment`: - -```curl -curl -X GET --cookie "session=" --url "{controller-IP}/api/v1/analytics/metrics?names=SUM(http.request.count)&dimensions=environment&startTime=now-3h -``` - -If you have multiple Apps, the response looks similar to the following example: - -```json -{ - "metrics":[ - { - "aggr": "SUM", - "name":"http.request.count", - "series":[ - { - "dimensions":{ - "environment":"prod" - }, - "timestamps":[ - "2020-07-01T12:00:00Z" - ], - "values":[ - 1000 - ] - }, - { - "dimensions":{ - "environment":"prod" - }, - "timestamps":[ - "2020-07-01T12:00:00Z" - ], - "values":[ - 2000 - ] - } - ] - } - ], - "queryMetadata":{ - "endTime":"2020-07-01T12:00:00.970106672Z" - } -} -``` - -If `dimensions` and `groupBy` parameters are both used, the list of provided `dimensions` must be a subset of the list provided in `groupBy`. - -The following example uses `dimensions` with `groupBy`: - -```curl -curl -X GET --cookie "session=" --url "{controller-IP}/api/v1/analytics/metrics?names=SUM(http.request.count)&groupBy=app,location&dimensions=app&startTime=now-3h&resolution=5m -``` - -The `dimensions` parameter also lets you omit the dimensions from the response altogether. To do so, define `dimensions` as an empty list (`dimensions=`). - -This results in several data series for the `http.request.count` metric without any dimensions being visible. That is not useful on its own; however, if you combine the empty `dimensions` parameter with metric aggregation, you will receive a single series with aggregated values. - -For example, the following example query sums all the values in all of the series of the `http.request.count` metric for the past three hours using the default `resolution`. - -```curl -curl -X GET --cookie "session=" --url "{controller-IP}/api/v1/analytics/metrics?names=SUM(http.request.count)&startTime=now-3h&dimensions= -``` - -The response looks similar to the following example: - -```json -{ - "metrics":[ - { - "aggr": "SUM", - "name":"http.request.count", - "series":[ - { - "dimensions":{}, - "timestamps":[ - "2020-07-01T12:00:00Z", - "2020-07-01T12:00:30Z", - "2020-07-01T12:01:00Z", - "2020-07-01T12:01:30Z", - ... - ], - "values":[ - 3000, - 2500, - 2800, - 1900, - ... - ] - } - ] - } - ], - "queryMetadata":{ - "endTime":"2020-07-01T15:00:00Z" - } -} -``` - -{{< call-out "important" >}} -You cannot use `dimensions` with the `seriesLimit` parameter. -{{< /call-out >}} - -## What's Next - -- [Metrics Reference]({{< ref "/controller/analytics/catalogs/metrics.md" >}})) -- [Dimensions Reference]({{< ref "/controller/analytics/catalogs/dimensions.md" >}})) -- [Create Custom Dashboards]({{< ref "/controller/analytics/dashboards/custom-dashboards.md" >}})) - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/analytics/metrics/overview-metrics-metadata.md b/content/controller/analytics/metrics/overview-metrics-metadata.md deleted file mode 100644 index 5f22c4722..000000000 --- a/content/controller/analytics/metrics/overview-metrics-metadata.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -description: Understanding how the F5 NGINX Controller Agent collects and reports - metrics and metadata. -nd-docs: DOCS-536 -title: 'Overview: Metrics and Metadata' -toc: true -weight: 20 -type: -- reference ---- - -## Overview - -The data that F5 NGINX Controller collects can be divided into two categories: - -- **System metrics**: Data collected from the NGINX Plus API, the NGINX log files, and NGINX process state. -- **Traffic metrics**: Data related to processed traffic, with the ability to distinguish the Application, API endpoint, or Environment that traffic is directed through. - -{{< call-out "note" >}} -The key difference between system and traffic metrics is that traffic metrics are pre-aggregated for each time period. -{{< /call-out >}} - -Metrics are published at a regular interval of 60 or 30 seconds for system and traffic metrics, respectively. - -This topic gives an overview of the traffic metrics. Also known as "app-centric" metrics, traffic metrics contain information that lets you easily identify the App to which the data applies. - -{{< call-out "note" >}} -Refer to [View traffic metrics]({{< ref "/controller/analytics/metrics/view-traffic-metrics.md" >}}) for instructions on how to view traffic metrics using the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}). -{{< /call-out>}} -## Metadata and Metrics That Are Reported - -The NGINX Controller Agent collects the following types of data: - -- **NGINX metrics.** The Agent collects NGINX-related metrics using the NGINX Plus API, and by monitoring the NGINX log files and NGINX process state. -- **AVRD metrics.** AVRD sends app-centric data, so each metric has assigned dimensions like "application name" or "gateway". These metrics are related to processed traffic (for example, the number of bytes sent to a particular URL/endpoint). -- **NGINX configuration.** After the initial installation, the NGINX configuration is uploaded to the NGINX Controller server. Configuration updates are also uploaded to the NGINX Controller server. -- **System metrics.** These are key metrics describing the system. For example: CPU usage, memory usage, network traffic, etc. -- **NGINX metadata.** These describe your NGINX instances, and include package data, build information, the path to the binary, build configuration options, and so on. NGINX metadata also includes the NGINX configuration elements. -- **System metadata.** These are the basic information about the OS environment where the Agent runs. For example, the hostname, uptime, OS flavor, and other data. - -For the full list of metrics, see the [Metrics Catalog Reference]({{< ref "/controller/analytics/catalogs/metrics.md" >}}) - -## Metrics Collection and Reporting Process - -The Agent mostly uses Golang's [gopsutil](https://github.com/shirou/gopsutil) to collect OS metrics. - -While the Agent is running on the host, it collects metrics at regular 20-second intervals. Metrics then are downsampled and sent to the Controller server once per minute. The Agent reports metadata to the NGINX Controller server every minute. Changes to the metadata can be examined using the Controller user interface. - -NGINX Controller stores historical metrics data in an analytics database. Metrics are aggregated and rolled-up as follows: - -- Data not older than 8 days are stored with best possible resolution (usually 1 min). -- Data older than 8 days but not older than 30 days are stored with 5 min resolution. -- Data older than 30 days but not older than 15 months are stored with 1 hour resolution. -- Data older than 15 months are stored with 1 day resolution. - -### Parsing and Analyzing NGINX Configuration Files - -NGINX configuration updates are reported only when a configuration change is detected. - -The Agent checks the Controller server every 30 seconds for pending NGINX configuration changes. When changes are pending, the changes are applied and the NGINX is reloaded. Because the configuration is managed in the Controller server, the entire configuration is written to a single `nginx.conf` file. - -If the Agent cannot reach the Controller server to send the accumulated metrics, it continues to collect metrics and sends them to the Controller server as soon as connectivity is re-established. The maximum amount of data that can be buffered by the Agent is about 2 hour's worth of data. - -The Agent is able to automatically find all relevant NGINX configuration files, parse them, extract their logical structure, and send the associated JSON data to the Controller Server for further analysis and reporting. - -To parse SSL certificate metadata, the NGINX Controller Agent uses standard `openssl`(1) functions. SSL certificates are parsed and analyzed only when the corresponding [Agent settings]({{< ref "/controller/admin-guides/config-agent/configure-the-agent.md#default-agent-settings" >}}) are turned on. SSL certificate analysis is `off` by default. - -## Troubleshooting - -Most metrics are collected by the Agent without requiring the user to perform any additional setup. For troubleshooting instructions, see [Troubleshooting NGINX Controller Metrics]({{< ref "/controller/support/troubleshooting-controller.md" >}}). - -## What's Next - -- [Set up Metrics Collection]({{< ref "/controller/admin-guides/config-agent/configure-metrics-collection.md" >}}) -- [Metrics Reference]({{< ref "/controller/analytics/catalogs/metrics.md" >}}) - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/analytics/metrics/overview-traffic-metrics.md b/content/controller/analytics/metrics/overview-traffic-metrics.md deleted file mode 100644 index 4a6aad116..000000000 --- a/content/controller/analytics/metrics/overview-traffic-metrics.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -description: Understanding how traffic metrics are collected, aggregated, and reported. -nd-docs: DOCS-537 -title: 'Overview: Traffic Metrics' -toc: true -weight: 100 -type: -- concept -- reference ---- - -## Overview - -The data that F5 NGINX Controller collects can be divided into two categories: - -- **System metrics**: Data collected from the NGINX Plus API, the NGINX log files, and NGINX process state. -- **Traffic metrics**: Data related to processed traffic, with the ability to distinguish the Application, API endpoint, or Environment that traffic is directed through. - -{{< call-out "note" >}} -The key difference between system and traffic metrics is that traffic metrics are pre-aggregated for each time period. -{{< /call-out >}} - -Metrics are published at a regular interval of 60 or 30 seconds for system and traffic metrics, respectively. - -This topic gives an overview of the traffic metrics. Also known as "app-centric" metrics, traffic metrics contain information that lets you easily identify the App to which the data applies. - -{{< call-out "note" >}} -Refer to [View traffic metrics]({{< ref "/controller/analytics/metrics/view-traffic-metrics.md" >}}) for instructions on how to view traffic metrics using the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}). -{{< /call-out>}} - -## Available traffic metrics - -- `client.latency.{total | max | min | count}` -- `client.network.latency.{total | max | min | count}` -- `client.request.latency.{total | max | min | count}` -- `client.ttfb.latency.{total | max | min | count}` -- `client.response.latency.{total | max | min | count}` -- `upstream.network.latency.{total | max | min | count}` -- `upstream.header.latency.{total | max | min | count}` -- `upstream.response.latency.{total | max | min | count}` -- `http.request.bytes_rcvd` -- `http.request.bytes_sent` -- `http.request.count` - -{{< call-out "note" >}} -Refer to the [NGINX Controller Metrics Catalog]({{< ref "/controller/analytics/catalogs/metrics.md" >}}) for details about these and the other metrics that NGINX Controller reports. -{{< /call-out>}} - -## Calculating traffic metrics - -As traffic flows through a configured application, NGINX Controller collects the traffic-related data. With heavy traffic, the number of single, distinguishable metrics can be challenging to discern. For this reason, the metric values are aggregated. - -The aggregation happens every publish period -- this period is stored in the `aggregation_duration` dimension, and is usually 30 seconds -- and is based on metric dimensions. - -Metrics are aggregated using four aggregation functions: - -- **SUM** for `http.request.bytes_rcvd`, `http.request.bytes_sent` and all metrics with `.total` suffix. -- **MAX** for metrics with `.max` suffix. -- **MIN** for metrics with `.min` suffix. -- **COUNT** for metrics with `.count` suffix. - -### Example - -To better understand how metrics are aggregated, consider the following example: - -Imagine you have one application configured with one URI (recorded in the `http.uri` dimension of each traffic-related metric). In the last 30 seconds, a user queried that URI five times. The `client.request.latency` values for the requests were: 1 ms, 2 ms, 3 ms, 4 ms, and 5 ms. - -The final metric values returned by the Metrics API will be: - -- `http.request.count` = 5 -- `client.request.latency.total` = 15 ms -- `client.request.latency.max` = 5 ms -- `client.request.latency.min` = 1 ms -- `client.request.latency.count` = 5 - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/analytics/metrics/view-traffic-metrics.md b/content/controller/analytics/metrics/view-traffic-metrics.md deleted file mode 100644 index d7f0acbe2..000000000 --- a/content/controller/analytics/metrics/view-traffic-metrics.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -description: How to view the traffic metrics gathered by NGINX Controller Analytics. -nd-docs: DOCS-538 -title: View Traffic Metrics -toc: true -weight: 150 -type: -- how-to -- tutorial ---- - -## Overview - -This topic explains how to use the [NGINX Controller REST API]({{< ref "/controller/api/_index.md" >}}) - to view traffic metrics. - -{{< call-out "note" >}} -Refer to [Overview: Traffic Metrics]({{< ref "/controller/analytics/metrics/overview-traffic-metrics.md" >}}) to learn how NGINX Controller collects, aggregates, and reports traffic metrics. -{{< /call-out>}} - -## Before You Begin - -To view traffic metrics, first confirm that you've correctly configured NGINX Controller. - -The following resources should have the status `Configured`: - -- [Environment]({{< ref "/controller/services/manage-environments.md" >}}) -- [Gateway]({{< ref "/controller/services/manage-gateways.md" >}}) -- [App and Component]({{< ref "/controller/app-delivery/manage-apps.md" >}}) - -Initially, the graphs will display `No data yet`, and querying the Metrics API for traffic metrics will result in an empty response. As soon as the Component starts to receive traffic, the traffic-related data will be displayed in the graphs and the [Dashboards]({{< ref "/controller/analytics/dashboards/overview-dashboard.md" >}}) in the NGINX Controller user interface and will be returned in API responses. - -{{< call-out "note" >}} -If traffic stops flowing to a resource (for example, an Application or Component), then no traffic metrics will be available for the resource. -{{< /call-out >}} - -## View Traffic Metrics Using the REST API - -- To view the full list of metrics and dimensions, send a GET request to the `/analytics/catalogs/metrics` endpoint: - - ```curl - curl -X GET --cookie "session=" --url "{Controller-FQDN}/api/v1/analytics/catalogs/metrics" - ``` - -- To view a detailed description for a metric, send a GET request to the `/analytics/catalogs/metrics/{metricName}` endpoint: - - ```curl - curl -X GET --cookie "session=" --url "{Controller-FQDN}/api/v1/analytics/catalogs/metrics/client.latency.total" - ``` - -- Likewise, to view the full list of available dimensions, send a GET request to the `/analytics/catalogs/dimensions` endpoint: - - ```curl - curl -X GET --cookie "session=" --url "{Controller-FQDN}/api/v1/analytics/catalogs/dimensions" - ``` - -{{< call-out "note" >}} -Refer to the [Catalogs Reference]({{< ref "/controller/analytics/catalogs/_index.md" >}}) for information about all of the dimensions and metrics collected by NGINX Controller. -{{< /call-out>}} - -## Example REST API Queries for Traffic Metrics - -Because traffic metrics are already aggregated, you should be careful about using the Metrics API for aggregations. - -### Example 1 - -Goal: Retrieve the total number of requests for the last 3 hours: - -```curl -curl -X GET --cookie "session=" --url "{Controller-FQDN}/api/v1/analytics/metrics?names=SUM(http.request.count)&startTime=now-3h" -``` - -The Metrics API returns a single value per dimension set. That value is the sum of the aggregated values (in 30s intervals) for the last 3 hours. - -### Example 2 - -Goal: Retrieve an average value of max client latencies for my app -- let's call it `app1` -- for the last day: - -```curl -curl -X GET --cookie "session=" --url "{Controller-FQDN}/api/v1/analytics/metrics?names=AVG(client.latency.max)&startTime=now-24h&filter=app='app1'" -``` - -### Example 3 - -{{< call-out "important" >}} -Because traffic metrics are pre-aggregated, using AVG aggregation with these metrics isn't recommended. -{{< /call-out >}} - -Imagine you have one application configured with one URI (recorded in the `http.uri` dimension of each traffic-related metric). In the last 30 seconds, a user queried that URI 5 times. The `client.request.latency` values for each request were: 1 ms, 2 ms, 3 ms, 4 ms, 5 ms. - -The final metric values returned by the Metrics API will be: - -- `client.request.latency.total` = 15 ms -- `client.request.latency.count` = 5 - -The following query returns the average `client.request.latency.total = 15`, as you have one aggregated sample with value 15. - -```curl -curl -X GET --cookie "session=" --url "{Controller-FQDN}/api/v1/analytics/metrics?names=AVG(client.request.latency.total)&startTime=now-24h" -``` - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/analytics/view-app-security-analytics.md b/content/controller/analytics/view-app-security-analytics.md deleted file mode 100644 index ee33ecfaa..000000000 --- a/content/controller/analytics/view-app-security-analytics.md +++ /dev/null @@ -1,272 +0,0 @@ ---- -description: How to view App Security Analytics. -nd-docs: DOCS-539 -title: View App Security Analytics -toc: true -weight: 500 -type: -- concept -- reference ---- - -## Overview - -When App Security flags or blocks a request made to an App Component as a security violation, it generates an App Security event. -You can use the F5 NGINX Controller web interface or the REST API to view these events or their related statistics (measures). Metrics reflect the number of requests and bytes flagged or blocked. You can use the Security Violation Dimensions to help understand and interpret the analytics data. - -For descriptions of Security Metrics and Events Dimensions, refer to [About App Security]({{< ref "/controller/app-delivery/security/concepts/what-is-waf.md" >}}) page. - -## View App Security Analytics - -You can use the NGINX Controller user interface or the REST API to view App Security Analytics. You can use this data to get a quick, high-level understanding of how the App Security module processes requests to an App. - -1. Open the NGINX Controller user interface and log in. -2. On the Navigation Bar, select **Services**. -3. On the Services Menu, select **Apps**. -4. On the Apps Overview page, select the App name link. -5. Select **Security Analytics** under the Analytics sub-menu. - -## View Security Analytics for Components - -To view Security Analytics for individual Components, take the steps below. - -1. Open the NGINX Controller user interface and log in. -2. On the Navigation Bar, select **Services**. -3. On the Services Menu, select **Apps**. -4. On the Apps Overview page, select the App name link. -5. Select **Components** from the menu. Select the Component name link. -6. Select **Security Analytics** under the Analytics sub-menu. - -### View App Security Events - -To view app security events: - -1. Open the NGINX Controller user interface and log in. -2. On the Navigation Bar, select **Services**. -3. On the Services Menu, select **Apps**. -4. On the Apps Overview page, select the App name link. -5. Select **Security Events** under the Analytics sub-menu. - -### View Security Events for Components - -To view the security events for components, take the following steps: - -1. Open the NGINX Controller user interface and log in. -2. On the Navigation Bar, select **Services**. -3. On the Services Menu, select **Apps**. -4. On the Apps Overview page, select the App name link. -5. Select **Components** from the sub-menu. Select the Component name link. -6. Select **Security Events** under the Analytics sub-menu. - -## Example REST API Queries for App Security Metrics - -Requests which App Security has rejected or allowed: - -```curl -https://{{host}}/api/v1/analytics/metrics? - startTime=0& - endTime=now& - names=sum(http.request.count)& - groupBy=request_outcome& - resolution=30m -``` - -Possible request outcomes are: - -- Passed: WAF allowed the request -- Rejected: WAF blocked the request - -To get request counts based on how App Security processed the traffic: - -```curl -https://{{host}}/api/v1/analytics/metrics? - startTime=0& - endTime=now& - resolution=5m& - names=sum(http.request.count)& - groupBy=request_outcome_reason& - filter=( - app='shopping' and - environment='prod' and - component='app-component') -``` - -| **request_outcome_reason values** | **Description** | -|--------------------------------|-----------------| -| \ | App Security did not process the traffic (in other words, App Security is not enabled). All events with this request_outcome_reason value should have a request_outcome `PASSED`.| -| SECURITY_WAF_OK | App Security processed the traffic and no violations are found. All events with this request_outcome_reason value should have a request_outcome of `PASSED`.| -| SECURITY_WAF_FLAGGED | App Security allowed the request, but it was flagged for review. All events with this request_outcome_reason value should have a request_outcome of `PASSED`.| -| SECURITY_WAF_VIOLATION | App Security identified one or more violations and rejected the request. All events with this request_outcome_reason value should have a request_outcome of `REJECTED`.| - -If you feel App Security is blocking too many requests, you can turn on monitor-only mode. - -### Security Violation Events - -You can use Security Violation Events to investigate violations identified by App Security for requests made to an App Component. Follow the steps below to view the Security Events: - -1. Open the NGINX Controller user interface and log in. -2. Select the NGINX Controller menu icon, then select **Analytics**. -3. On the **Analytics Menu**, select **Component**. - -You can use the following example Events requests to collect App Security Analytics data by using the NGINX Controller REST API: - -- To view ‘security violation’ Events: - - ```curl - GET https://{{host}}/api/v1/analytics/events? - startTime=0& - endTime=now& - filter=( - category='security violation') - ``` - -- To get security violation details based on the Support ID seen on the request blocking page: - - ```curl - GET https://{{host}}/api/v1/analytics/events? - startTime=0& - endTime=now& - filter=( - category='security violation' and - waf.support_id='1880765231147185611') - ``` - -- To get all events where WAF rejected to investigate: - - ```curl - GET https://{{host}}/api/v1/analytics/events? - startTime=0& - endTime=now& - filter=( - category='security violation' and - request_outcome='REJECTED') - ``` - -- To get all events where WAF flagged to investigate: - - ```curl - GET https://{{host}}/api/v1/analytics/events? - startTime=0& - endTime=now& - filter=( - category='security violation' and - request_outcome_reason='SECURITY_WAF_FLAGGED') - ``` - -- To get all events where WAF has rejected or flagged to review: - - ```curl - GET https://{{host}}/api/v1/analytics/events? - startTime=0& - endTime=now& - filter=( - category='security violation' and - request_outcome_reason in ('SECURITY_WAF_VIOLATION','SECURITY_WAF_FLAGGED')) - ``` - -- To get all events where WAF has rejected or flagged for a specific App Component: - - ```curl - GET https://{{host}}/api/v1/analytics/events? - startTime=0& - endTime=now& - filter=( - category='security violation' and - request_outcome_reason in ('SECURITY_WAF_VIOLATION','SECURITY_WAF_FLAGGED') and - app='shopping' and - environment='prod' and - component='app-component') - ``` - - {{< call-out "tip" >}} -To get all Events, remove the Environment, App, and Component filters from the request call. - {{< /call-out >}} - -- To find requests flagged by App Security’s violation rating algorithm as a possible or likely threat: - - ```curl - GET https://{{host}}/api/v1/analytics/events? - startTime=0& - endTime=now& - filter=( - category='security violation' and - request_outcome_reason = 'SECURITY_WAF_FLAGGED' and - waf.violation_rating in ('POSSIBLE_ATTACK','MOST_LIKELY_ATTACK') and - app='shopping' and - environment='prod' and - component='app-component') - ``` - - {{< call-out "important" >}} -This is important if you are using App Security WAF monitoring only mode. You can use it to understand the type of threats WAF believes should be blocked. - {{< /call-out >}} - -- To get Events that have triggered a specific signature-based violation by signature id: - - ```curl - GET https://{{host}}/api/v1/analytics/events? - startTime=0& - endTime=now& - filter=( - category='security violation' and - waf.signature_ids ='*200000098*' and - app='shopping' and - environment='prod' and - component='app-component') - ``` - - The substring search using wildcards or ‘IN’ operand should be used because each signature might be part of various combinations of signatures triggered by App Security per request. - -- To get Events that have triggered a specific a signature-based violation by signature id: - - ```curl - GET https://{{host}}/api/v1/analytics/events? - startTime=0& - endTime=now& - filter=( - category='security violation' and - waf.signature_names IN ('DIRECTORY_TRAVERSAL') and - app='shopping' and - environment='prod' and - component='app-component') - ``` - - The substring search using wildcards or ‘IN’ operand should be used because each signature might be part of various combinations of signatures triggered by App Security per request. - -- To get Events that triggered a particular attack type: - - ```curl - GET https://{{host}}/api/v1/analytics/events? - startTime=0& - endTime=now& - filter=( - category='security violation' and - waf.attack_types='*Non-browser Client, Abuse of Functionality*' and - app='shopping' and - environment='prod' and - component='app-component') - ``` - - The substring search using wildcards or ‘IN’ operand should be used because each signature might be part of various combinations of attack types triggered by App Security per request. - -- To get Events from a remote address (client IP) - - ```curl - GET https://{{host}}/api/v1/analytics/events? - startTime=0& - endTime=now& - filter=( - category='security violation' and - http.remote_addr='172.18.71.147' and - app='shopping' and - environment='prod' and - component='app-component') - ``` - -## Related Pages - -- [About App Security]({{< ref "/controller/app-delivery/security/concepts/what-is-waf.md" >}}) - -{{< versions "3.11" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/api-management/_index.md b/content/controller/api-management/_index.md deleted file mode 100644 index 91312bebd..000000000 --- a/content/controller/api-management/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -description: Tasks for deploying and managing your APIs. -title: API Management -weight: 155 -url: /nginx-controller/api-management/ ---- - diff --git a/content/controller/api-management/manage-apis.md b/content/controller/api-management/manage-apis.md deleted file mode 100644 index 5c7a389aa..000000000 --- a/content/controller/api-management/manage-apis.md +++ /dev/null @@ -1,505 +0,0 @@ ---- -description: Use the F5 NGINX Controller API Manager to add APIs and control how your - APIs are exposed and consumed. -nd-docs: DOCS-569 -title: Manage Your APIs -toc: true -weight: 110 -type: -- tutorial ---- - -## Overview - -The F5 NGINX Controller API Management module provides full life cycle management for your APIs. This document provides a walkthrough of the steps needed to create, version, and publish your API using the NGINX Controller API Management module. When you have completed this guide, you should have the following resources: - -- An **API Definition**, which stores a collection of related API resources. It can be thought of as a folder. -- An **API Version**, which describes a particular API and serves as the data contract. It describes available endpoints and operations on each endpoint and can also include API documentation. -- A **Published API**, which represents an API Version that has been deployed to an NGINX Plus instance serving as an API Gateway. -- (Optional) API documentation available via the Developer Portal. - -{{< call-out "note" >}} - -- You must have an API Management module license installed to complete the steps in this guide. -- The API Management module is available to users with the predefined [Admin or User Roles]({{< ref "/controller/platform/access-management/manage-roles.md#predefined-roles-and-role-groups" >}}). - -{{< /call-out >}} - -## Create an API Definition - -An API Definition functions as a collection of related API resources. - -1. Open the NGINX Controller user interface and log in. - -2. Select the NGINX Controller menu icon, then select **Services**. - -3. On the **Services** menu, select **APIs**. - -4. On the **All APIs** page, select **Create** and choose **API Definition**. Alternatively, you can also select **Create API Definition** from the Quick Actions list. - -## Create an API Version - -An API Version describes a particular API. It can be thought of as an API specification. - -1. Open the NGINX Controller user interface and log in. - -2. Select the NGINX Controller menu icon, then select **Services**. - -3. On the **Services** menu, select **APIs**. - -4. On the **All APIs** page, select **Create** and choose **API Version**. Alternatively, you can also select **Create API Version** from the Quick Actions list. - -5. Select an existing **API Definition** under which to group the API Version or select **Create New** to add a new **API Definition**. - -6. Choose how you would like to describe the API: - - 1. [OpenAPI specification](#import-an-openapi-specification) - - 2. [Configure manually](#define-api-resources-manually) - - 3. [WSDL file](#import-a-web-services-description-language-wsdl-file) (Currently only supports unauthenticated, unencrypted traffic) - -7. Provide a version. If a version isn't provided, the default version `unspecified` is used. - -8. (Optional) Provide a display name. - -9. (Optional) Provide a description. - - {{< call-out "note" >}} - - If your API specification includes a description, that text populates this field automatically when you [add your OpenAPI spec](#import-an-openapi-specification). - - {{< /call-out >}} - -10. (Optional) Add tags. - -### Import an OpenAPI Specification - -The APIM module supports import of a valid OpenAPI v3 specification formatted as valid JSON or YAML. - -{{< call-out "note" >}} - -If your API spec includes documentation elements, the "Enable documentation" option is selected automatically. You do not need to take any additional steps to document your API. - -{{< /call-out >}} - -**To import your spec by uploading a file:** - -1. Select **OpenAPI Specification**. - -2. Select **Import file**. - -3. Drag and drop your file into the upload box, or select **Browse** to find and upload a file. - -**To import your spec by copying and pasting:** - -1. Select **OpenAPI Specification**. - -2. Select **Copy and paste specification text**. - -3. Paste or type your API in the space provided. - -Once you have imported your API spec, select **Next** to continue to the **Resources** page. - -### Define API Resources Manually - -Take the steps below to manually add your API resources. - -1. Select **Configure Manually**. - -2. Select **Next** to continue to the **Resources** page. - -3. Select **Add API Resource**. - -4. Select the **Match Type** to use for the API resource path. - -5. Specify the **Path** for the API resource. -**Tip**: Path should start with `/`, for example, `/userlookup/{userid}/attributes/{surname}`. - -6. Select the HTTP method(s). - -7. (Optional) [Document Your API](#document-your-api). - -8. Review the API spec that will be submitted to create the **API Version**. - -9. Select **Submit** to save the **API Version**. - -### Document Your API - -Follow the steps below to document your API. - -{{< call-out "note" >}} - -API documentation must follow the OpenAPI 2.0/3.0 Specification. - -If you uploaded an API spec that contains documentation, you don't need take any further steps to document your API. - -{{< /call-out >}} - -{{< call-out "tip" >}} - -Skip to step 6 if you're continuing from the [Define API Resources Manually](#define-api-resources-manually) section. - -{{< /call-out >}} - -1. Open the NGINX Controller user interface and log in. - -2. Select the NGINX Controller menu icon, then select **Services**. - -3. On the **Services** menu, select **APIs**. - -4. On the **All APIs** page, select the **API Version** for which you want to create documentation. Click the pencil (edit) button to edit the API Version. - -5. Select **Resources**. - -6. Select the pencil (edit) icon next to the method or methods that you want to document. - -7. Select **Enable Documentation**. - -8. Add a summary. - -9. (Optional) Add a description. - -10. (Optional) Add a request body description. - -11. (Optional) Add a sample request. - -12. Specify whether the request body is required. - -13. To add a parameter, select **Add Parameter**. - -14. Provide the parameter name. - -15. (Optional) Provide a parameter description. - -16. Select the parameter type. - -17. Select the parameter value. - -18. (Optional) Specify whether the parameter is required. - -19. To add a response, select **Add Response**. - -20. Provide the HTTP Response status code. - -21. Provide a description. - -22. (Optional) Provide a sample response in JSON format. - -23. Select **Next** to review the API spec that will be submitted to update the **API Version**. - -24. Select **Submit** to save the **API Version**. - -### Import a Web Services Description Language (WSDL) file - - {{< call-out "caution" >}} - -Currently, only HTTP is supported for SOAP-REST proxy traffic. Traffic will be unauthenticated and unencrypted, and as a result will be vulnerable to several security risks. It should be treated as a beta/preview feature. - - {{< /call-out >}} - -The APIM module supports importing a WSDL file that describes a SOAP service. - -**To import your spec by uploading a file:** - -1. Select **WSDL File**. - -2. Select **Import file**. - -3. Drag and drop your file into the upload box, or select **Browse** to find and upload a file. - -**To import your spec by copying and pasting:** - -1. Select **WSDL file**. - -2. Select **Copy and paste WSDL text**. - -3. Paste or type your API in the space provided. - -Once you've imported your API spec, select **Next** to continue to the **Resources** page. Note that you need to submit the API spec before you can modify the **Resources** and **Schema**. Select **Submit** to save the **API Version.** - -### Modify Schema and Resources for an API Version created from a WSDL file - -Take the following steps to **Edit** add your API Version: - -1. On the **All APIs** page, select the **API Version** that was created from a WSDL - -2. Select **Next** to continue to the **Resources** page. - -3. For each **SOAP operation**, choose the appropriate equivalent **REST Method**. - -4. (optional) Modify the **Path** for the API resource as desired. - - {{< call-out "tip" >}} - - Path should start with `/`, for example, `/userlookup/{userid}/attributes/{surname}`. - - {{< /call-out >}} - -5. Select **Next** to continue to the **Schema** page - -6. (Optional) For each JSON schema, modify the **Property** as desired - -7. Review the API spec that will be submitted to create the **API Version**. - -8. Select **Submit** to save the **API Version**. - -## Publish an API - -You need at least one of each of the resources listed below to complete this section. If you haven't already created the required resources, you can do so while configuring the Published API. - -- [Environment]({{< ref "/controller/services/manage-environments.md" >}}) - -- [Gateway]({{< ref "/controller/services/manage-gateways.md" >}}) - -- [App]({{< ref "/controller/app-delivery/manage-apps.md" >}}) - -- [Identity Provider]({{< ref "/controller/services/manage-identity-providers.md" >}}) - - (required to add Authentication to the Published API Component). - -{{< call-out "tip" >}} -You can connect one or more [Developer Portals]({{< ref "/controller/api-management/manage-dev-portals.md" >}}) to your Published API to host your API documentation. This can be done either when creating or editing your Published API, or independently via the API Quick Actions menu. -{{< /call-out >}} - -### Add a Published API - -1. Open the NGINX Controller user interface and log in. - -2. Select the NGINX Controller menu icon, then select **Services**. - -3. On the **Services** menu, select **APIs**. - -4. On the **All APIs** page, select the **API Version** that you want to publish. - -5. Select **Add Published API**. - -#### Configure the Published API - -On the **Create Published API** *Configuration* page: - -1. Select the **API Definition Version** that you want to publish. - -2. (Optional) Provide a **Base Path** for the Published API. - -3. Specify whether the **Strip Base Path** parameter is required. - - {{< call-out "note" >}} - - The `Strip Base Path` option modifies the path that is passed from the Gateway to the upstream host. When the option is selected, the base path will be removed from the original request when the request is passed to the upstream host. If the option is not selected, the original request -- including the base path -- is passed from the Gateway to the upstream host. - - {{< /call-out >}} - -4. Provide a Name and/or Display Name for the Published API. - -5. (Optional) Provide a description for the Published API. - -6. (Optional) Add tags. - -7. Select **Next**. - -#### Define the Published API Deployment - -For each of the steps below, you can create a new resource for the Published API by selecting the **Create New** link. - -On the **Create Published API** *Deployment* page: - -1. Select the **Environment** that the Published API belongs to. - -2. Select the **App** that the Published API represents. - -3. Select the **Gateway(s)** that will expose the Published API. - -4. Select the **Dev Portal(s)** that will host documentation for the Published API. - -5. Select **Next**. - -#### Define the Routing Rules - -On the **Create Published API** *Routing* page: - -1. Select the **Add New** link to create a new App Component resource for the Published API. The **Create App Component** page has multiple sections. - -2. On the **Create App Component** *Configuration* page: - - 1. Provide the name for your Component. - - 2. (Optional) Provide a Display Name. - - 3. (Optional) Provide a Description. - - 4. (Optional) Add any desired tags. - - 5. (Optional) Select the error response format. - - 6. Select **Next**. - -3. On the **Create App Component** *Workload Groups* page: - - 1. Provide a Workload Group Name. - - 2. (Optional) Select a Location. The default Location is 'Unspecified'. This value is applied automatically to "bring your own" (BYO) NGINX Plus instances that were not deployed by NGINX Controller. - - 3. Define the backend workload URIs. - - 4. (Optional) Define the DNS Server. - - 5. (Optional) Select the Load Balancing Method. The default value is `Round Robin`. - - 6. (Optional) Select the Session Persistence Type (applicable only to Web Components). - - 7. (Optional) Select the Desired Proxy Settings (applicable only to Web Components). - - 8. Select **Next**. - {{< call-out "note" >}} - - - Refer to the [Manage Locations]({{< ref "/controller/infrastructure/locations/manage-locations.md" >}}) topic for more information. - - - Refer to the [NGINX Plus Admin Guide](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/) for more information about the available options. - - {{< /call-out>}} - {{< call-out "tip" >}} - Hover your pointer over the info icon for each setting to learn about the expected values and requirements. - {{< /call-out >}} - - -4. On the **Create App Component** *Rate Limiting* page: - - 1. Enable Rate Limiting and select a **Key**. - - 2. Select options for Rate and Units. - - 3. (Optional) Select options for Excess Request Processing and Ignore Initial N Requests. - - 4. Select options for Reject Status Code. - - 5. Select **Next**. - -5. On the **Create App Component** *Authentication* page: - - 1. Select **Add Authentication**. - - 2. Select an [**Identity Provider**]({{< ref "/controller/services/manage-identity-providers.md" >}}). - - 3. Select a **Credential Location**. - - 1. (Optional) Enable [**Conditional Access**]({{< ref "/controller/services/available-policies.md#conditional-access" >}}). - - 4. Select **Next**. - -{{< call-out "important" >}} - -The **Advanced Security** features require an *NGINX Controller API Management Advanced Security* license. - -{{< /call-out >}} - -6. On the **Create App Components** *Advanced Security* page: - - 1. (Optional) Select **Enable Web Application Firewall (WAF)** to monitor and block suspicious requests or attacks. - - 2. (Optional) Select **Monitor Only** to allow traffic to pass without being rejected. Security events are still generated and metrics are still collected. Refer to [About App Security Analytics]({{< ref "/controller/analytics/view-app-security-analytics.md" >}}) for more information. - - 3. (Optional) Add the signature(s) that you want WAF to ignore. You can specify multiple signatures as a comma-separated list. - - 4. Select **Next** - - {{< call-out "note" >}} Refer to the [Default WAF Policy]({{< ref "/controller/app-delivery/security/concepts/app-sec-default-policy-original.md" >}}) topics to learn more about the default protection provided by NGINX App Protect. {{< /call-out>}} - - -7. On the **Create App Component** *Ingress* page: - - 1. (Optional) Set the desired **Client Max Body Size**. - 2. Select **Next**. - - {{< call-out "note" >}} - - Refer to the [NGINX module docs](http://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size) for more information about this option. - - {{< /call-out>}} - - -8. On the **Create App Component** *Monitoring* page: - - 1. (Optional) Enable **Health Monitoring** and define the desired Monitoring Request and Response. Health Monitoring is disabled by default. - - 2. (Optional) Specify the URI to use in health check requests (applicable only to Web Components). The default is `/`. For TCP/UDP Components, specify the Send string. - - 3. (Optional) Specify the port to use when connecting to a server to perform a health check. The server port is used by default. - - 4. (Optional) Set the interval to wait between two consecutive health checks. The default is 5 seconds. - - 5. (Optional) Specify the number of consecutive passed health checks that must occur for a server to be considered healthy. The default is `1`. - - 6. (Optional) Specify the number of consecutive failed health checks that must occur for a server to be considered unhealthy. The default is `1`. - - 7. (Optional) Specify the default state for the server. The default state is `HEALTHY`. - - 8. (Optional) Specify the starting HTTP status code to match against (applicable only to Web components). - - 9. (Optional) Specify the ending HTTP status code to match against (applicable only to Web components). - - 10. (Optional) Select whether a response should pass in order for the health check to pass (applicable only to Web components). By default, the response should have status code `2xx` or `3xx`. - - 11. Select **Next**. - - {{< call-out "note" >}} - - Refer to the [NGINX module docs](http://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html#health_check) for more information about these options. - - {{< /call-out>}} - -9. On the **Create App Component** *Logs* page: - - 1. (Optional) Select the logs to enable: - - § Error Log - - § Access Log - - 2. (Optional) Specify the log format to use. - - 3. Select **Next**. - - {{< call-out "note" >}} - - Refer to the [NGINX docs](http://nginx.org/en/docs/http/ngx_http_log_module.html) for more information about these options. - - {{< /call-out>}} - -9. On the **Create App Component** *Programmability* page: - - The following settings are applicable **only to Web components**. - - 1. (Optional) Select **Add URI Redirects** and define the desired redirect condition(s). - - 2. (Optional) Select **Add URI Rewrite** and define the desired rewrite pattern(s). - - 3. (Optional) Select **Add Request Header Modification** and define how to modify the request header. - - 4. (Optional) Select **Add Response Header Modification** and define how to modify the response header. - - 5. Select **Next**. - - {{< call-out "note" >}} - - Refer to the [NGINX module docs](http://nginx.org/en/docs/http/ngx_http_rewrite_module.html) for more information about these options. - - {{< /call-out>}} - - 6. Select **Next** to review the API spec that will be sent to create the App Component. - - 7. Drag and drop resources one at a time, or move multiple resources by selecting the checkboxes next to the desired resources, from the **Unrouted** column to the desired Component in the **Components** list. You can use the search bar to narrow down the list. - **Note:** Resources can be dragged between **Components** and back to the **Unrouted** section either one at a time or by multi-select. - - 8. Select **Next** to review the API spec that will be sent to create the Published API. - - 9. Select **Submit** to create the Published API. - -## Create a Developer Portal - -Once you have created an API Definition and a Published API, you can host your API in a Developer Portal. - -From the **API Definitions** page, select **Create Dev Portal** from the Quick Actions menu. Then, follow the steps in [Create a Developer Portal]({{< ref "/controller/api-management/manage-dev-portals.md" >}}) to create, customize, and publish your Dev Portal. - -{{< versions "3.0" "3.18" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} diff --git a/content/controller/api-management/manage-dev-portals.md b/content/controller/api-management/manage-dev-portals.md deleted file mode 100644 index 3f3f1aa5d..000000000 --- a/content/controller/api-management/manage-dev-portals.md +++ /dev/null @@ -1,138 +0,0 @@ ---- -description: Learn how to create and manage Developer Portals for your API documentation. -nd-docs: DOCS-570 -title: Manage Developer Portals -toc: true -weight: 120 -type: -- tutorial ---- - -## Overview - -You can use F5 NGINX Controller Developer Portals (also called 'Dev Portals') to create and manage beautiful, easy-to-use API reference documentation to support your [Published APIs]({{< ref "/controller/api-management/manage-apis.md#publish-an-api" >}}). - -## About Developer Portals - -In NGINX Controller, each Dev Portal sits within an Environment. An Environment can contain multiple Dev Portals. You can use the same Dev Portal names across different Environments, which means you can create "test", "dev", and "production" versions of your Dev Portal across the corresponding Environments. - -Each Dev Portal is associated with a Gateway, which defines the URI at which users can access the Dev Portal -- for example, `developer.acme.com`. A Gateway for a Developer Portal can be placed on a dedicated Instance, or share an Instance with other Gateway resources. - -## Before You Begin - -You must complete the steps below before you can create a Developer Portal. - -1. [Create an Environment]({{< ref "/controller/services/manage-environments.md" >}}). -1. [Create a Gateway]({{< ref "/controller/services/manage-gateways.md" >}}) for the Dev Portal. - - {{< call-out "tip" >}} -You can create multiple Dev Portal Gateways on the same Instance. If you do so, be sure to use a unique hostname and port for each. For example: - -- Gateway 1's ingress URI is `https://dev-developer.acme.com`. -- Gateway 2's ingress URI is `https://test-developer.acme.com`. These resources might both have IP addresses and ports that are accessible only from within your private network. -- Gateway 3's ingress URI is `https://developer.acme.com`. This resource would have a public IP address and be accessible via the internet. - -If you create multiple Dev Portal Gateways on the same Instance using the same hostname and port, the Dev Portal configuration will fail. - {{< /call-out >}} - -1. [Create an API Definition]({{< ref "/controller/api-management/manage-apis.md#create-an-api-definition" >}}). - - {{< call-out "tip" >}} -If you choose to [define your API manually]({{< ref "/controller/api-management/manage-apis.md#define-resources-manually" >}}), be sure to [document your API]({{< ref "/controller/api-management/manage-apis.md#document-your-api" >}}). - {{< /call-out >}} - -1. [Create a Published API]({{< ref "/controller/api-management/manage-apis.md#publish-an-api" >}}). - - {{< call-out "important" >}} -You must create an App Component when creating a Published API. You'll [assign routes]({{< ref "/controller/api-management/manage-apis.md#define-the-routing-rules" >}}) from the API Definition to this Component. - -Both the Published API and the associated App Component must be successfully created before you can create a Dev Portal. - -See [Manage Your APIs]({{< ref "/controller/api-management/manage-apis.md" >}}) and the [troubleshooting](#troubleshoot-dev-portal-publication) section below for more information. - -You also have the option to associate Dev Portal(s) in the *Deployment* page when you [Add a Published API]({{< ref "/controller/api-management/manage-apis.md#add-a-published-api" >}}). If you already have a Published API and you want to create a new Dev Portal to host it, complete the tasks described in this guide. - - {{< /call-out >}} - -## Create a Developer Portal - -To create a Dev Portal, take the steps below: - -1. Open the NGINX Controller user interface and log in. -2. Select the NGINX Controller menu icon, then select Services. -3. On the **Services** menu, select APIs. -4. On the APIs page, select **Create Dev Portal** from the Quick Actions menu. - - {{< call-out "tip" >}} -If you want to connect one or more Dev Portals to an existing Published API, you should select the **Edit Published API** option. The API Documentation will be published to the selected Dev Portal(s). Refer to the [Define the Published API Deployment]({{< ref "/controller/api-management/manage-apis.md#define-the-published-api-deployment" >}}) section for more information and instructions. - {{< /call-out >}} - -### Configure the Developer Portal - -On the **Create Dev Portal** *Configuration* page: - -1. Provide a resource name for the Dev Portal. -2. (Optional) Provide a display name, description, and tags. -3. Select the desired Environment, or select Create to create a new resource. -4. Select a Gateway, or select Create to create a new resource. -5. Select the Published API(s) that you want to host in the Dev Portal. -6. Select **Next** to move to the **Themes** page. - -### Define the Dev Portal Theme - -On the **Create Dev Portal** *Themes* page: - -1. Select **Brand** to define the following elements: - - - **Brand Name**, - - **Logo**, and - - **Favicon** - -2. Select **Next**. -3. Set the **Colors** for theme elements. Then, select **Next**. -4. Set the **Fonts** for the theme. Then, select **Next**. -5. Review the **API Spec**, then select **Submit**. - -> You should now be able to access the Dev Portal via the hostname and port that you assigned to the Dev Portal Gateway. - -## View, Edit, or Delete a Developer Portal - -To view, edit, or delete a Dev Portal, take the steps below: - -1. Open the NGINX Controller user interface and log in. -2. Select the NGINX Controller menu icon, then select Services. -3. On the **Services** menu, select APIs. -4. On the APIs menu, select **Dev Portals**. - -To **edit** a Dev Portal: - -1. Select the **Edit** icon for the Dev Portal. -2. Edit the Dev Portal as desired. - - - Select **Configure** to update the Dev Portal configurations, including the Environment, Gateway, and Published API. - - Select **Brand** to customize the **Brand Name** and to upload a **Logo** and **Favicon**. - - Select **Color** to customize the Dev Portal theme colors. - - Select **Fonts** to customize the Dev Portal theme fonts. - -3. Select **Submit** to save your changes. - -To **delete** a Dev Portal, select the **Delete** icon. Then, select **Delete** in the confirmation prompt window. - -## Troubleshoot Dev Portal Publication - -If the Gateway that the Dev Portal is associated with is in an error state, publishing your Dev Portal will fail. You won't necessarily see an error in the Dev Portals section of the user interface when this happens, but configuration errors in these resources will impact Dev Portal functionality. - -- App Component configuration errors are displayed only in the App Component section of the user interface. -- Published API configuration errors are displayed in the Published APIs section of the user interface, as well as in the Dev Portal. -- Dev Portal configuration errors are not displayed in the NGINX Controller user interface. - -If your Dev Portal failed to publish, check the status of the Gateway first; resolve any issues with the Gateway, then try publishing the Dev Portal again. -If the issue persists, check the other resources for configuration errors. - -## What's Next - -- [Learn about Policies]({{< ref "/controller/services/available-policies.md" >}}) -- [Manage Your APIs]({{< relref "./manage-apis.md" >}}) - -{{< versions "3.7" "3.18" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} diff --git a/content/controller/api/_index.md b/content/controller/api/_index.md deleted file mode 100644 index 100d0ce46..000000000 --- a/content/controller/api/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -description: Learn how to use the F5 NGINX Controller REST API. -title: API Reference -weight: 210 -url: /nginx-controller/api/reference/ ---- - diff --git a/content/controller/api/overview.md b/content/controller/api/overview.md deleted file mode 100644 index d37acb406..000000000 --- a/content/controller/api/overview.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -description: Provides information about the F5 NGINX Controller API. -nd-docs: DOCS-343 -layout: docs -title: API Overview -toc: true -weight: 10 -type: -- concept ---- - -## Introduction - -The F5 NGINX Controller API is a [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) API that allows you to programmatically manage your NGINX Plus data planes. - -NGINX Controller follows an "API-first" approach, which means that all NGINX Controller functionality is exclusively exposed through declarative and resource-oriented APIs. Even the user interface (user interface) uses our REST API! You'll find examples of REST request bodies in the user interface. You can rest assured that the example you see is correct, because that is the call that the user interface is going to make to apply your requested configuration. - -## Encoding - -All NGINX Controller API endpoints expect and return JSON-formatted data by default. -When appropriate, the API accepts and returns other media types, such as file uploads or downloads. - -All JSON-formatted data is expected to be encoded using UTF-8 as described by the [IETF JSON Spec](https://tools.ietf.org/html/rfc8259). -If you do not specify a specific media type in an API call, then the API defaults to `"application/json"`. If you specify multiple acceptable media types, the first type that the API supports is chosen for the response. In the event of a request for a media type that the API doesn't support, it returns a "415 Unsupported Media Type" response. - -## Object Model - -The NGINX Controller API -- as well as the user interface and the product documentation -- is organized into four top-level areas: - -- **Analytics**: Enables data visualization for NGINX Controller. -- **Infrastructure**: Lets you manage your NGINX Plus instances and certain aspects of the host machines on which NGINX Controller and NGINX Plus instances run. -- **Platform**: Lets you manage NGINX Controller options and configurations, including Users, Roles, Licenses, and Global Settings. -- **Services**: Lets you manage your applications and APIs. - -The diagrams below demonstrate how the different objects at the Service level relate to each other: - -1. All Service objects are part of an Environment. -1. Gateways and Certs can be defined at the Environment level --or-- at the Component Level. The diagram below shows an example of how traffic flows through a Gateway to an App. -1. Components are child objects that represent the back-end server(s) that host your App or API. - {{< call-out "note" >}}A Component can represent an application **or** an API. The same Component cannot be used for both App Delivery and API Management.{{< /call-out >}} -1. Certs can be added to a Gateway or to an individual Component. - -{{< img src="/ctlr/img/services-object-model-example.png" alt="Diagram showing the relationship of objects in an Environment within the Services area." >}} -{{< img src="/ctlr/img/traffic-flow-example-1.png" alt="Example traffic flow through a gateway to app components that represent a back-end application. Certs can be configured at the gateway or at the app component level." >}} - -### Permissions - -Access to each of these areas is determined by your User Role. Roles grant Users access to specific Environments; Role permission levels define what content you can see ("Read" access) and interact with ("Write" access). Users with Roles that contain "Full" access can interact with all areas. - -The diagram below shows a sample System Administrator (or, "SysAdmin") workflow. The SysAdmin user has full administrator permissions, which allows creation of objects in all areas. In this workflow, the SysAdmin user creates an Environment; then creates a Role that has permission to interact with objects in that Environment; and, finally, creates a User. The Role grants the User access to objects in the Environment. - -{{< img src="/ctlr/img/netops-workflow.png" alt="Example System Admin workflow" >}} - -The diagram below shows a sample deployment workflow. In this workflow, the user - a Deployment Manager - has read and write access to objects in one specific Environment, but no access to other Environments. Within the allowed Environment, the user can create objects or select from objects that were added by a system administrator. In this workflow, the Deployment Manager creates an App and an App Component. Associated objects like Certs and Gateways can be added -- or selected from a list -- when adding the App Component. The configs for load balancing, monitoring, and URI redirects are defined as part of the App Component as well. - -{{< img src="/ctlr/img/devops-workflow-simple.png" alt="Example deployment workflow" >}} - -{{< call-out "note" >}} - -- [Managing Roles & Users]({{< ref "/controller/platform/access-management/manage-users.md" >}}) - -{{< /call-out>}} - -## Authentication - -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]({{< ref "/controller/api/_index.md" >}}) documentation for information about session cookie timeouts and invalidation. - -{{< call-out "tip" >}} -You can send a GET request to the login endpoint to find the status of the session token. -{{< /call-out >}} - -For example: - -- Login and capture the session cookie: - - ```curl - 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@example.net","password": ""}}' - ``` - -- Use the session cookie to authenticate and get the session status: - - ```curl - curl -b cookie.txt -c cookie.txt -X GET --url 'https://198.51.100.10/api/v1/platform/login' - ``` - - -## Resource Types - -The NGINX Controller API contains two types of resources: immediately consistent and eventually consistent. - -Immediately consistent resources are synchronous. For these resources, any changes you make will be applied at the time the request is received. Requests to modify state using an API write operation (POST, PUT, PATCH or DELETE) result in the transmitted data being stored by the server as state. There is no need to check for progress, success, or failure using an API read operation (GET) for these resources. The original response should communicate if the request was successful. - -Eventually consistent resources are asynchronous. For these resources, any changes you request will be applied over time. Requests to modify state using an API write operation (POST, PUT, PATCH or DELETE) result in the transmitted data being stored by the server and messages or events being generated to eventually apply this state. You may check for progress, success, or failure using an API read operation (GET). The original response communicates that the data resulting in instructions was understood by the system. - -## Resource Properties - -All NGINX Controller API resources contain the following properties: - -```json -{ - "metadata": { - }, - "desiredState": { - }, - "currentStatus": { - } -} -``` - -The `desiredState` property is a representation of the state that you want to apply to the system. The properties within `desiredState` are the API representation of data. While changes to `desiredState` may trigger eventually consistent operations, the object itself is "immediately consistent". Consumers of the API can "read their own writes" and should always be able to retrieve the current desired state, no matter where the system is in the process of applying the state change. - -The `currentStatus` property represents the current state of the system. Its purpose is to communicate the progress of achieving eventual consistency to the API consumer. As such, `currentStatus` is a read-only property. - -## Versioning - -The introduction of backwards-incompatible changes to the NGINX Controller API constitutes a major version change. This will be represented in the NGINX Controller API version string. For example, to use a `v2` API, you would use `https:///api/v2`. - -When any NGINX Controller component requires a version change, we will release a new version of the entire API. In other words, you won't see a mix of `v1` and `v2` objects in the same API. - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.18" "latest" "apimvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/api/reference/ctlr-adc-api.md b/content/controller/api/reference/ctlr-adc-api.md deleted file mode 100644 index 04ead674a..000000000 --- a/content/controller/api/reference/ctlr-adc-api.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -description: Represents the state of the F5 NGINX Controller Application Delivery - REST API. -nd-docs: DOCS-1280 -type: -- reference -doctypes: - - reference -type: redoc -tags: - - api -title: ADC API -toc: false -weight: 300 -nd-api-reference: "./nginx-controller/api/reference/ctlr-adc-openapi.json" ---- diff --git a/content/controller/api/reference/ctlr-analytics-api.md b/content/controller/api/reference/ctlr-analytics-api.md deleted file mode 100644 index 70e1214f6..000000000 --- a/content/controller/api/reference/ctlr-analytics-api.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -description: Represents the state of the F5 NGINX Controller Analytics REST API. -nd-docs: DOCS-1279 -type: -- reference -doctypes: - - reference -type: redoc -tags: - - api -title: Analytics API -toc: false -weight: 200 -nd-api-reference: "./nginx-controller/api/reference/ctlr-analytics-openapi.json" ---- diff --git a/content/controller/api/reference/ctlr-apim-api.md b/content/controller/api/reference/ctlr-apim-api.md deleted file mode 100644 index 5add27db2..000000000 --- a/content/controller/api/reference/ctlr-apim-api.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -description: Represents the state of the F5 NGINX Controller API Management REST API. -nd-docs: DOCS-1281 -type: -- reference -doctypes: - - reference -type: redoc -tags: - - api -title: APIM API -toc: false -weight: 400 -nd-api-reference: "./nginx-controller/api/reference/ctlr-apim-openapi.json" ---- diff --git a/content/controller/api/reference/ctlr-platform-api.md b/content/controller/api/reference/ctlr-platform-api.md deleted file mode 100644 index 562a3db72..000000000 --- a/content/controller/api/reference/ctlr-platform-api.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -description: Represents the state of the F5 NGINX Controller Platform REST API. -nd-docs: DOCS-1278 -doctypes: - - reference -type: redoc -tags: - - api -title: Platform API -toc: false -nd-api-reference: "./nginx-controller/api/reference/ctlr-platform-openapi.json" ---- diff --git a/content/controller/app-delivery/_index.md b/content/controller/app-delivery/_index.md deleted file mode 100644 index 021e9ba97..000000000 --- a/content/controller/app-delivery/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -description: Tasks for deploying and managing your applications. -title: Application Delivery -weight: 152 -url: /nginx-controller/app-delivery/ ---- - diff --git a/content/controller/app-delivery/about-app-delivery.md b/content/controller/app-delivery/about-app-delivery.md deleted file mode 100644 index 544e54607..000000000 --- a/content/controller/app-delivery/about-app-delivery.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -description: Learn about F5 NGINX Controller Application Delivery concepts. -nd-docs: DOCS-474 -title: About Application Delivery -toc: true -weight: 100 ---- - -## Apps - -In F5 NGINX Controller, an App serves as a container for one or more Components. Components represent the backend services that comprise your application. Together, an App and its Components represent the logical partitioning of your application into its composite parts. For example, a Component might correspond to a particular microservice within your application. Each Component you add to an App represents one or more paths via which traffic can reach that microservice. - -All Apps and Components live within an [Environment]({{< ref "/controller/services/manage-environments.md" >}}). This means that in order to have access to a particular App, a User needs to have permission to access its Environment. If you need access to an Environment or App, contact your administrator. - -## Components - -A Component is a child object of an App. Components let you partition an App into smaller, self-contained pieces that are each responsible for a particular function of the overall application. For example, a Component could correspond to a microservice that, together with several other microservices, comprises a complete application. - -Each Component contains an ingress definition that includes the fully-qualified domain names (FQDNs) and URIs from clients. These ingress definitions associate incoming requests with a particular path; the certificates that are used for decryption/encryption of HTTPS requests and responses that traverse that path; the backend servers that host the App to which the path delivers the requests; and the rewrites, redirects, and modifications on the requests/responses that occur along the path. - -Components can be instantiated on multiple paths corresponding to the placements associated with the Component; these placements are defined within the [Gateway(s)]({{< ref "/controller/services/manage-gateways.md" >}}) referenced in the Component. - -## Inherited or Independent Resources - -When you configure a Component, you can choose to: - -- inherit resources and configurations from the Gateway; -- create and define new resources and configurations specific to the Component; or -- use a combination of inherited and Component-specific configurations. - -For example, a Gateway's ingress definition might include the URIs for a Service's FQDN(s) and the associated TLS [certificates]({{< ref "/controller/services/manage-certs.md" >}}), while the Component's ingress definition would contain relative URIs for the FQDN defined in the Gateway: - -- Gateway Ingress URIs: `www.example.com` -- Component Ingress URIs: `/about/`, `/docs/`, `/contact/` - -Together, the Component's relative paths and the Gateway's FQDN results form the absolute URI for each path (`www.example.com/about/`, `www.example.com/docs/`, and `www.example.com/contact/`). - -Likewise, you can configure a Component with its own FQDN and paths, but inherit the TLS certificates from the Gateway. Or, you can configure a Component that doesn't inherit any resources or configurations from the Gateway and uses its own set of definitions. - -{{< call-out "note" >}}The ability to add resources, like Certificates, is determined by your account permissions. If you don't have the ability to add new Certs, contact your administrator. {{< /call-out >}} - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/app-delivery/about-caching.md b/content/controller/app-delivery/about-caching.md deleted file mode 100644 index 6e5f9c005..000000000 --- a/content/controller/app-delivery/about-caching.md +++ /dev/null @@ -1,387 +0,0 @@ ---- -description: Learn how F5 NGINX Controller handles caching configurations and what - NGINX cache directives are supported. -nd-docs: DOCS-339 -title: About Caching -toc: true -weight: 200 -type: -- concept ---- - -## Overview - -The F5 NGINX Controller Application Delivery (AD) module lets you configure content caching by using either the user interface (UI) or the [Components REST API](https://docs.nginx.com/nginx-controller/api/ctlr-adc-api/#tag/Components). - -## Basic Caching - -NGINX Controller Caching supports [basic caching](https://www.nginx.com/blog/nginx-caching-guide/#How-to-Set-Up-and-Configure-Basic-Caching) via the *disk store* resource. - -When you add a disk store to a component, you define the location of the cache on the hard disk. The path you specify for the disk store is the base path under which you want to store the cache files for the component. - -{{< call-out "important" >}} -The directory that you want to use as the cache must already exist and the NGINX process must have read and write permissions to it. Otherwise, NGINX Controller can't create the cached folders and files. - -If NGINX Controller can't create the desired cache directory and/or write files to it, the user interface will display an error for the component. -{{< /call-out >}} - -When you use the UI or the REST API to create a single disk store, NGINX Controller adds the following directives to the auto-generated `nginx.conf` file: - -- [`proxy_cache_path`](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_path), in the top-level `http` context; -- [`proxy_cache`](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache), added to the component's `location` block. - -You can include NGINX Controller Caching data when creating [custom dashboards]({{< ref "/controller/analytics/dashboards/custom-dashboards" >}}) and [alerts]({{< ref "/controller/analytics/alerts/manage-alerts" >}}) for your applications. - -## Cache Splitting - -NGINX Controller Caching also supports splitting the cache across multiple directories, which can reside on different hard drives. To split the cache, you need to create a disk store for each desired cache location. The Caching *split config* settings let you determine how NGINX Controller should split the data between the disk stores -- either by percentage or by pattern matching. - -The percentage option lets you set the percentage of the cache to store in each location. Pattern matching lets you define where to store cache contents -- like certain file types -- and which cache location should send a response based on the request. - -{{< call-out "note" >}} -Read the [NGINX Caching Guide](https://www.nginx.com/blog/nginx-caching-guide/#Splitting-the-Cache-Across-Multiple-Hard-Drives) to learn more about splitting the cache across multiple hard drives. -{{< /call-out>}} - -When you define a split cache, NGINX Controller adds a `split_clients` configuration block with percentage split or a `map` configuration block with string split to the `http` context of the generated `nginx.conf` file. - -## Advanced Caching - -As noted earlier in this topic, you can use Caching to manage basic caching use cases. -To add any of the [`ngx_http_proxy_module`](http://nginx.org/en/docs/http/ngx_http_proxy_module.html) cache directives listed below, use NGINX Controller **Snippets**. - -- [`proxy_cache_background_update`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_background_update) -- [`proxy_cache_bypass`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_bypass) -- [`proxy_cache_convert_head`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_convert_head) -- [`proxy_cache_key`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_key) -- [`proxy_cache_lock`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_lock) -- [`proxy_cache_lock_age`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_lock_age) -- [`proxy_cache_lock_timeout`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_lock_timeout) -- [`proxy_cache_max_range_offset`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_max_range_offset) -- [`proxy_cache_methods`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_methods) -- [`proxy_cache_min_uses`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_min_uses) -- [`proxy_cache_purge`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_purge) -- [`proxy_cache_revalidate`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_revalidate) -- [`proxy_cache_use_stale`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_use_stale) -- [`proxy_cache_valid`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_valid) -- [`proxy_no_cache`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_no_cache) -- [`proxy_temp_path`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_temp_path) - -In order to enable the collection of app centric caching metrics, NGINX Controller has added a minimal set of APIs to enable and control caching. For more advanced caching features, you can make use of `configSnippets` to configure the directives above. - -{{< call-out "note" >}} -When you enable the temporary path for disk store with `tempPath:ENABLED`, you need to set the temporary path `proxy_temp_path` using the snippets API. -{{< /call-out >}} - - -{{< call-out "note" >}} -NGINX Controller does not collect or report metrics for directives configured using Snippets. -{{< /call-out >}} - -## Usage Examples - -Each of the examples provided here shows a sample API request and the resulting NGINX config file. These examples are for learning purposes only and are not intended for use in production settings. - -### Basic Caching {#basic-caching-example} - -The example below shows an excerpt of a REST API request that sets up basic caching. This example defines one server as the cache location. - -```json -"desiredState": { - "caching": { - "diskStores": [ - { - "path": "/tmp/cache-1", - "maxSize": "5G", - "minFree": "10k", - "inMemoryStoreSize": "500M", - "inactiveTime": "2s" - } - ] - } -} -``` - -The above request modifies the NGINX Controller-generated `nginx.conf` file as follows: - -- Adds a `proxy_cache_path` directive for the disk store to the `http` context; -- Adds a new `proxy_cache` directive to the `location` block for the component. - -```Nginx configuration file {hl_lines=[1,14]} -proxy_cache_path /tmp/cache-1/app_centric_example-env|example-app-1|example-app-component| max_size=5G min_free=10k keys_zone=app_centric_example-env|example-app-1|example-app-component|/tmp/cache-1:500M purger=off; - -server { - server_name test.example.com; - listen 80; - status_zone server_5ae404e8-005d-38e8-b355-6d54cb219730; - set $f5_gateway example-gw; - f5_metrics_marker gateway $f5_gateway; - set $f5_environment example-env; - f5_metrics_marker environment $f5_environment; - location / { - error_log /dev/null; - access_log off; - proxy_cache app_centric_example-env|example-app-1|example-app-component|/tmp/cache-1; - set $f5_app example-app-1; - f5_metrics_marker app $f5_app; - set $f5_component example-app-component; - f5_metrics_marker component $f5_component; - proxy_set_header X-Forwarded-For $remote_addr; - proxy_set_header Host $host; - proxy_set_header Connection ''; - proxy_http_version 1.1; - proxy_pass http://wg-example_http_b4859463-b3bd-4ccb-8442-e21253a50da7; - } -} -``` - -### Cache Splitting using Percentage and Snippets {#split-percentage-example} - -You can set up cache splitting using the Percentage criteria to define the percent of the cache to store in each location. - -The example request excerpt below does the following: - -- splits the cache across three different storage paths; -- sets one of the stores -- `/tmp/default` -- as the default; -- uses the Component `configSnippets.uriSnippets` API to configure the [`add_header`](https://nginx.org/en/docs/http/ngx_http_headers_module.html#add_header) directive, to include `Cache` header with "HIT/MISS/EXPIRED/BYPASS" in the response; -- uses the Component `configSnippets.uriSnippets` API to set a cache duration time of 1m for all requests using [`proxy_cache_valid`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_valid). - -```json -{ - "desiredState": { - "configSnippets": { - "uriSnippets": [ - { - "directives": [ - { - "directive": "proxy_cache_valid", - "args": [ - "any", - "1m" - ] - } - ] - } - ] - }, - "programmability": { - "responseHeaderModifications": [ - { - "action": "ADD", - "headerName": "X-Cache-Status", - "headerValue": "$upstream_cache_status" - } - ] - }, - "caching": { - "splitConfig": { - "criteriaType": "PERCENTAGE", - "key": "$request_uri" - }, - "diskStores": [ - { - "inMemoryStoreSize": "100m", - "inactiveTime": "1m", - "isDefault": false, - "maxSize": "5G", - "minFree": "10k", - "path": "/tmp/hdd1", - "percentCriteria": "20%" - }, - { - "inMemoryStoreSize": "100m", - "inactiveTime": "10s", - "isDefault": false, - "maxSize": "5g", - "minFree": "10k", - "path": "/tmp/hdd2", - "percentCriteria": "50%" - }, - { - "inMemoryStoreSize": "100m", - "inactiveTime": "15s", - "isDefault": true, - "maxSize": "2g", - "minFree": "10k", - "path": "/tmp/default" - } - ] - } - } -} -``` - -The above request modifies the `nginx.conf` file as follows: - -- Adds the `split_clients` directive to the `http` context, reflecting the criteria defined for `diskStores`; -- Adds a `proxy_cache_path` directive for each disk store to the `http` context; -- Adds a new `proxy_cache` variable -- `$cache_` -- to the `location` block for the component; -- Adds the `proxy_cache_valid` and `add_header` directives to the `location` block for the component. - -```Nginx configuration file {hl_lines=["1-8",27,36,37]} -split_clients $request_uri $cache_bdfa5d91f97d37dbb97a42dde6a5f4ff { - 20% app_centric_env|app|split_cache_percentage|/tmp/hdd1; - 50% app_centric_env|app|split_cache_percentage|/tmp/hdd2; - * app_centric_env|app|split_cache_percentage|/tmp/default; -} -proxy_cache_path /tmp/hdd1/app_centric_env|app|split_cache_percentage| max_size=5G min_free=10k keys_zone=app_centric_env|app|split_cache_percentage|/tmp/hdd1: 100m purger=off inactive=1m; -proxy_cache_path /tmp/hdd2/app_centric_env|app|split_cache_percentage| max_size=5g min_free=10k keys_zone=app_centric_env|app|split_cache_percentage|/tmp/hdd2: 100m purger=off inactive=10s; -proxy_cache_path /tmp/default/app_centric_env|app|split_cache_percentage| max_size=2g min_free=10k keys_zone=app_centric_env|app|split_cache_percentage|/tmp/default: 100m purger=off inactive=15s; -upstream split_p_http_7ec84d9e-373e-4d90-bcaa-0e33dcc4b906 { - zone split_p_http_7ec84d9e-373e-4d90-bcaa-0e33dcc4b906 160k; - server 10.146.187.154: 80; - keepalive 64; - keepalive_requests 100; - keepalive_timeout 60s; -} -server { - server_name test.example.com; - listen 80 reuseport; - status_zone server_4d1ee345-cf08-354e-93dc-1c3a844a04e3; - set $f5_gateway gw; - f5_metrics_marker gateway $f5_gateway; - set $f5_environment env; - f5_metrics_marker environment $f5_environment; - location /aaa { - error_log /dev/null; - access_log off; - proxy_cache $cache_bdfa5d91f97d37dbb97a42dde6a5f4ff; - set $f5_app app; - f5_metrics_marker app $f5_app; - set $f5_component split_cache_percentage; - f5_metrics_marker component $f5_component; - proxy_set_header X-Forwarded-For $remote_addr; - proxy_set_header Host $host; - proxy_set_header Connection ''; - proxy_http_version 1.1; - add_header Cache $upstream_cache_status; - proxy_cache_valid any 1m; - proxy_pass http: //split_p_http_7ec84d9e-373e-4d90-bcaa-0e33dcc4b906; -} -``` - -### Cache Splitting using Pattern Matching and Snippets {#split-string-example} - -You can also use pattern matching to cache based on a certain string (`stringCriteria`) for each store. For example, you can define the string criteria as a list of file formats, as shown in the request excerpt below. As in the [percentage example](#split-percentage-example), we're also using the Components `configSnippets` API here to set the `add_header` and `proxy_cache_valid` directives. - -The request below splits the cache into three different stores. - -- One store is the default location and has no string criteria defined. -- One store is the location for all `.html`files. -- Ones store is the location for all `.mp4` files. - -```json -"desiredState": { - "configSnippets": { - "uriSnippets": [ - { - "directives": [ - { - "directive": "proxy_cache_valid", - "args": [ - "any", - "1m" - ] - } - ] - } - ] - }, - "programmability": { - "responseHeaderModifications": [ - { - "action": "ADD", - "headerName": "X-Cache-Status", - "headerValue": "$upstream_cache_status" - } - ] - }, - "caching": { - "splitConfig": { - "criteriaType": "STRING", - "key": "$request_uri" - }, - "diskStores": [ - { - "inMemoryStoreSize": "10m", - "inactiveTime": "1m", - "isDefault": false, - "maxSize": "2G", - "minFree": "1m", - "path": "/tmp/hdd1", - "stringCriteria": ["~.html$"] - }, - { - "inMemoryStoreSize": "50m", - "inactiveTime": "1m", - "isDefault": false, - "maxSize": "1g", - "minFree": "10k", - "path": "/tmp/hdd2", - "stringCriteria": ["~.mp4$"] - }, - { - "inMemoryStoreSize": "30m", - "inactiveTime": "1m", - "isDefault": true, - "maxSize": "2g", - "minFree": "10k", - "path": "/tmp/default" - } - ] - } -} -``` - -The above request modifies the `nginx.conf` file as follows: - -- Adds a `map` directive to the `http` context, reflecting the string criteria defined for the disk stores. -- Adds a `proxy_cache_path` directive to the `http` context for each disk store. -- Adds a new variable `$cache_` to the `location` block for the component. - -```Nginx configuration file {hl_lines=["1-8",30,39,40]} -map $request_uri $cache_8de5273e13f731e283acbc999760c3e3 { - ~.html$ app_centric_env|app|split_string|/tmp/hdd1; - ~.mp4$ app_centric_env|app|split_string|/tmp/hdd2; - default app_centric_env|app|split_string|/tmp/default; -} -proxy_cache_path /tmp/hdd1/app_centric_env|app|split_string| max_size=2G min_free=1m keys_zone=app_centric_env|app|split_string|/tmp/hdd1:10m purger=off inactive=1m; -proxy_cache_path /tmp/hdd2/app_centric_env|app|split_string| max_size=1g min_free=10k keys_zone=app_centric_env|app|split_string|/tmp/hdd2:50m purger=off inactive=1m; -proxy_cache_path /tmp/default/app_centric_env|app|split_string| max_size=2g min_free=10k keys_zone=app_centric_env|app|split_string|/tmp/default:30m purger=off inactive=1m; -upstream wg_http_0ace772a-0c68-4d01-a443-6e377d4f6133 { - zone wg_http_0ace772a-0c68-4d01-a443-6e377d4f6133 160k; - server 10.146.187.154:80; - keepalive 64; - keepalive_requests 100; - keepalive_timeout 60s; -} -map $host $f5_published_api { - default -; -} -server { - server_name test.example.com; - listen 80 reuseport; - status_zone server_4d1ee345-cf08-354e-93dc-1c3a844a04e3; - set $f5_gateway gw; - f5_metrics_marker gateway $f5_gateway; - set $f5_environment env; - f5_metrics_marker environment $f5_environment; - location / { - error_log /dev/null; - access_log off; - proxy_cache $cache_8de5273e13f731e283acbc999760c3e3; - set $f5_app app; - f5_metrics_marker app $f5_app; - set $f5_component split_string; - f5_metrics_marker component $f5_component; - proxy_set_header X-Forwarded-For $remote_addr; - proxy_set_header Host $host; - proxy_set_header Connection ''; - proxy_http_version 1.1; - add_header Cache $upstream_cache_status; - proxy_cache_valid any 1m; - proxy_pass - } -} -``` - -{{< versions "3.22" "latest" "adcvers" >}} diff --git a/content/controller/app-delivery/about-snippets.md b/content/controller/app-delivery/about-snippets.md deleted file mode 100644 index 83c3c063f..000000000 --- a/content/controller/app-delivery/about-snippets.md +++ /dev/null @@ -1,564 +0,0 @@ ---- -nd-docs: DOCS-340 -title: About Snippets -toc: true -weight: 300 -type: -- concept ---- - -## Overview - -The F5 NGINX Controller Application Delivery (AD) module lets you configure NGINX directives that aren't represented in the NGINX Controller API via "config snippets", or "Snippets". You can do so by using either the user interface (UI) or the [Application Delivery REST API](https://docs.nginx.com/nginx-controller/api/ctlr-adc-api/). - -{{< call-out "caution" >}} -When you use Snippets to customize your NGINX configuration, your changes are applied to the `nginx.conf` file *as is*. NGINX Controller does not verify that your configuration is valid before applying the snippet. - -We strongly recommend verifying Snippets in a lab environment before making any changes in production. -{{< /call-out >}} - -## Types of Snippets - -There are five types of Snippets, which you can configure for gateways or components. This lets you add custom directives into the corresponding NGINX configuration blocks generated by the gateways and components for the associated URIs. - -{{< call-out "note" >}}The `uriSnippets` can't be used for TCP/UDP components.{{< /call-out >}} - -{{}} - -| Snippet | Description | Corresponding API Endpoint | -| ----------------------- | ------------------------------------------------------------------ | -------------------------- | -| `httpSnippet` | Adds directives to the `http` block. | Gateway | -| `mainSnippet` | Adds directives to the `main` block. | Gateway | -| `streamSnippet` | Adds directives to the `stream` block. | Gateway | -| `uriSnippets` | Adds directives to the component's `server` and `location` blocks. | Component | -| `uriSnippets` | Adds directives to the gateway's `server` blocks. | Gateway | -| `workloadGroupSnippets` | Adds directives to the `upstream` blocks. | Component | - -{{}} - -## Best Practices - -### Gateway Partitions - -It's important to avoid adding conflicting snippets to the same [context](https://docs.nginx.com/nginx/admin-guide/basic-functionality/managing-configuration-files/#contexts) in your NGINX configuration file. We recommend that you create one stand-alone Gateway to hold the `main`, `http`, and `stream` snippets. Doing so lets you share the configuration for these contexts across Gateways that define the URIs (`server` blocks) for particular instances while reducing the risk of duplicate or conflicting settings. - -### NGINX Variables - -NGINX configurations commonly use [NGINX variables](https://nginx.org/en/docs/varindex.html) or custom variables. If you prefer to configure NGINX Controller by using the REST API, you may run into problems with variable expansion when sending JSON as part of a `curl` request using th `-d` flag. The recommended best practice for this is to reference the JSON in a data file instead of sending the string as part of the request. An alternative is to redefine the variable to itself, which allows the variable to pass through to the NGINX configuration. If you're using the NGINX `$host` variable in your JSON data -- represented by the `` placeholder in the example below -- you would define the variable before the curl request as follows: - -```none -host='$host' curl -s -k -H "Content-Type: application/json" -X PUT -d "" https://192.168.100.10:80/ -``` - -## Usage Examples - -{{< call-out "caution" >}} -The examples provided here are intended for demonstration purposes only. -We strongly recommend verifying Snippets in a lab environment before making any changes in production. -{{< /call-out >}} - -### Add HTTP Strict Transport Security Headers - -If you want to implement a [HTTP Strict Transport Security](https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx/) (HSTS) policy, you can add a snippet to your gateway. -For example: - -```json -{ - "metadata": { - "name": "" - }, - "desiredState": { - "configSnippets": { - "uriSnippets": [ - { - "applicableUris": [ - { - "uri": "http://172.16.0.238:81" - } - ], - "directives": [ - { - "directive": "add_header", - "args": ["Strict-Transport-Security", "max-age=31536000; includeSubDomains", "always"] - } - ] - } - ] - }, - "ingress": { - "uris": { - "http://example.com:8020": {} - }, - "placement": { - "instanceRefs": [ - { - "ref": "/infrastructure/locations/unspecified/instances/" - } - ] - } - } - } -} -``` - -### Allow or Deny IP Addresses - -You can add IP addresses to your allow- or deny-list by using the `allow` or `deny` directives in a gateway snippet. For example: - -```json -{ - "metadata": { - "name": "" - }, - "desiredState": { - "configSnippets": { - "uriSnippets": [ - { - "applicableUris": [ - { - "uri": "" - } - ], - "directives": [ - { - "directive": "deny", - "args": ["192.0.2.2"] - }, - { - "directive": "allow", - "args": ["192.0.2.1/24"] - }, - { - "directive": "allow", - "args": ["2001:0db8::/32"] - }, - { - "directive": "deny", - "args": ["all"] - } - ] - } - ] - }, - "ingress": { - "uris": { - "http://example.com:8020": {} - }, - "placement": { - "instanceRefs": [ - { - "ref": "/infrastructure/locations/unspecified/instances/" - } - ] - } - } - } -} -``` - - -### Load the NGINX Prometheus Module - -In order to use the [NGINX Prometheus-njs](https://docs.nginx.com/nginx/admin-guide/dynamic-modules/prometheus-njs/) module with NGINX Controller, you need to use`load_module` in the `main` context, `js_import` in the `http` context, and `js_content` in the `location`. NGINX Controller automatically enables the location api `location /api`, which is also required for metrics reporting. - -After installing the module, add the following Snippets to your gateway. This will add `load_module` and `js_import`: - -```json -{ - "metadata": { - "name": "" - }, - "desiredState": { - "configSnippets": { - "mainSnippet": { - "directives": [ - { - "directive": "load_module", - "args": ["modules/ngx_http_js_module.so"] - } - ] - }, - "httpSnippet":{ - "directives": [ - { - "directive": "js_import", - "args": ["/usr/share/nginx-plus-module-prometheus/prometheus.js"] - } - ] - } - }, - "ingress": { - "uris": { - "http://example.com:8020": {} - }, - "placement": { - "instanceRefs": [ - { - "ref": "/infrastructure/locations/unspecified/instances/" - } - ] - } - } - } -} - -``` - -Then, you'd add a config snippet similar to the example below to your component. - -```json -{ - "metadata": { - "name": "" - }, - "desiredState": { - "configSnippets": { - "uriSnippets": [ - { - "applicableUris": [ - { - "uri": "/metrics" - } - ], - "directives": [ - { - "directive":"js_content", - "args": ["prometheus.metrics"] - } - ] - } - ] - }, - "ingress": { - "uris": { - "http://example.com:8020": {} - }, - "placement": { - "instanceRefs": [ - { - "ref": "/infrastructure/locations/unspecified/instances/" - } - ] - } - } - } -} -``` - - -### NGINX as a WebSocket Proxy - -If you want to use NGINX Controller to configure [NGINX as a WebSocket Proxy](https://www.nginx.com/blog/websocket-nginx/), you can customize your `nginx.conf` by using Snippets and header programmability. - -In the gateway, provide an `http` snippet that defines the `map` directive and the `server` configuration: - -```json -{ - "metadata": { - "name": "" - }, - "desiredState": { - "configSnippets": { - "httpSnippet": { - "directives": [ - { - "directive": "map", - "args": ["$http_upgrade", "$connection_upgrade"], - "block": [ - { - "directive": "default", - "args": ["upgrade"] - }, - { - "directive": "''", - "args": ["close"] - } - ] - } - ] - } - }, - "ingress": { - "uris": { - "http://example.com:8020": {} - }, - "placement": { - "instanceRefs": [ - { - "ref": "/infrastructure/locations/unspecified/instances/" - } - ] - } - } - } -} -``` - -Then, add the two required headers to the component using `requestHeaderModifications`. For example: - -```json -{ - "metadata": { - "name": "", - }, - "desiredState": { - "ingress": { - "uris": { - "/": {} - }, - "gatewayRefs": [ - {"ref": "/services/environments/${env}/gateways/"} - ] - }, - "programmability": { - "requestHeaderModifications": [ - { - "action": "ADD", - "headerName": "Upgrade", - "headerValue": "$http_upgrade" - }, - { - "action": "ADD", - "headerName": "Connection", - "headerValue": "$connection_upgrade" - } - ] - }, - "backend": { - "workloadGroups": { - "websocket": { - "uris": { - "http://:8010": {} - } - } - } - } - } -} -``` - -### Forward Errors Logs to Remote Syslog - -If you want to forward HTML error logs to [syslog](https://nginx.org/en/docs/syslog.html), you can add the `error_log` directive snippet to your gateway. -For example: - -```json -{ - "metadata": { - "name": "" - }, - "desiredState": { - "configSnippets": { - "httpSnippet": { - "directives": [ - { - "directive": "error_log", - "args": ["syslog:server=", "debug"] - } - ] - } - }, - "ingress": { - "uris": { - "http://example.com:8000": {} - }, - "placement": { - "instanceRefs": [ - { - "ref": "/infrastructure/locations/unspecified/instances/" - } - ] - } - } - } -} -``` - -{{< call-out "note" >}} -The `error_log` and `accesslog` directives can appear at various block levels (`main`, `http`, `stream`, `server`, `location`, etc.). -NGINX Controller adds these directives to control logging to the local file. When using Snippets to add additional logging capabilities, the inner blocks override the outer block definitions. -For example, if you enable remote logging for errors at the `main` level, and you add an `error_log` directive to a `server` or `location` block that uses local logging, the local logging configuration overrides the remote logging configured at the `main` level. -{{< /call-out >}} - -### Manage IPv6 Addresses - -You can use Snippets to manage IPv6 addresses for HTTP and TCP/UDP use cases. IPv6 address management is supported in both Gateway and Component Snippets. - -- Be sure to set the `reuseport` option for all IPv6 listen directives. Failure to do so can cause bind errors. -- NGINX Controller's post-processing logic removes the `reuseport` option in certain cases. This is a [known issue]({{< ref "/controller/releases/adc/adc-release-notes-3.22.md" >}}) when the IPv6 port matches an IPv4 port and the IPv4 listen directive does not specify an IP address (in other words, a wildcard IP). To change the IPv6 listen directive's IP address, remove the Snippet, then re-add the Snippet with a new IPv6 address. - -If you need to support IPv6 addresses for the NGINX listen directive, you can use a snippet similar to the ones shown below to achieve it. - -#### HTTP Gateway with IPv6 - -For HTTP, use the Gateway URI Snippets block to add an IPv6 [`listen`](https://nginx.org/en/docs/http/ngx_http_core_module.html#listen) directive to the `server` blocks. - -```json -{ - "metadata": { - "name": "" - }, - "desiredState": { - "configSnippets": { - "uriSnippets": [ - { - "directives": [ - { - "directive": "listen", - "args": [ - "[::]:80", - "reuseport" - ] - }, - { - "directive": "listen", - "args": [ - "[]:80", - "reuseport" - ] - } - ] - } - ] - }, - "ingress": { - "placement": { - "instanceRefs": [ - { - "ref": "/infrastructure/locations/unspecified/instances/" - } - ] - }, - "uris": { - "http://example.com:80": {} - } - } - } -} -``` - -{{< call-out "note" >}}You cannot add IPv6 `listen` directives to a server block when the FQDN is defined in the Component URI (for example, `http://{FQDN}/{PATH}`). {{< /call-out >}} - -#### TCP/UDP Component with IPv6 - -For TCP/UDP, use the Component URI Snippets block to add an IPv6 [`listen`](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#listen) directive to the `server` blocks. - -##### TCP Component - -```json -{ - "metadata": { - "name": "" - }, - "desiredState": { - "configSnippets": { - "uriSnippets": [ - { - "directives": [ - { - "directive": "listen", - "args": [ - "[::]:9090", - "reuseport" - ] - } - ] - } - ] - }, - "backend": { - "workloadGroups": { - "wg": { - "uris": { - "tcp://:9090": {} - }, - } - } - }, - "componentType": "TCPUDP", - "ingress": { - "gatewayRefs": [ - { - "ref": "/services/environments//gateways/" - } - ], - "uris": { - "tcp://*:9090": {} - } - } - } -} -``` - -##### UDP Component - -```json -{ - "metadata": { - "name": "" - }, - "desiredState": { - "configSnippets": { - "uriSnippets": [ - { - "directives": [ - { - "directive": "listen", - "args": [ - "[]:9053", - "udp", - "reuseport" - ] - } - ] - } - ] - }, - "backend": { - "workloadGroups": { - "wg": { - "uris": { - "udp://:9053": {} - } - } - } - }, - "componentType": "TCPUDP", - "ingress": { - "gatewayRefs": [ - { - "ref": "/services/environments//gateways/" - } - ], - "uris": { - "udp://*:9053": {} - } - } - } -} -``` - -#### IPv6-only Server Block - -To add an IPv6-only `server` block, define the entire block in the Gateway HTTP or the Stream Snippets block. - -#### UI Config - -Add `listen` directives with parameters in URI Snippets. To learn more about what the `listen` directive does and what parameters it accepts, refer to the following topics: - -- [`stream` listen options](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#listen) -- [`http` listen options](https://nginx.org/en/docs/http/ngx_http_core_module.html#listen) - -{{< call-out "note" >}} - -The `reuseport` parameter creates an individual listening socket for each worker process. See [`reuseport` option](https://nginx.org/en/docs/http/ngx_http_core_module.html#reuseport). - -{{< /call-out >}} - -## Extend App Security with Snippets - -When adding [NGINX Controller App Security]({{< ref "add-app-security-with-waf" >}}) to your components, you can use Snippets to add NGINX App Protect directives that aren't represented in the NGINX Controller API. You can also use Snippets to [tune your F5 WAF for NGINX performance]({{< ref "/controller/app-delivery/security/tutorials/tune-waf-for-app" >}}). - -Refer to [Extend App Security with Snippets]({{< ref "extend-app-security-snippets" >}}) for more information and examples. - -{{< versions "3.22" "latest" "adcvers" >}} diff --git a/content/controller/app-delivery/deploy-simple-app.md b/content/controller/app-delivery/deploy-simple-app.md deleted file mode 100644 index 78a9dc3eb..000000000 --- a/content/controller/app-delivery/deploy-simple-app.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -description: Overview of the steps required to deploy a simple App. -nd-docs: DOCS-477 -title: Deploy a Simple Application -toc: true -weight: 400 -type: -- tutorial ---- - -## Overview - -This topic provides an overview of the steps required to create a simple application by using F5 NGINX Controller's user interface. Use the links provided to learn more about each step. - -## Create an Environment - -First, you'll need to create an Environment. - -- [About Environments]({{< ref "/controller/services/manage-environments.md#about-environments" >}}) -- [Create an Environment]({{< ref "/controller/services/manage-environments.md#create-an-environment" >}}) - -## Create a Certificate - -If you want to secure your application traffic, you'll need to add Certificates. - -If you just want to deploy a simple HTTP application, skip ahead to [Gateways](#create-a-gateway). - -{{< call-out "tip" >}} Make sure that you add the new Cert to the Environment that you created in the previous step.{{< /call-out >}} - -- [About Certificates]({{< ref "/controller/services/manage-certs.md#about-certificates" >}}) -- [Create a certificate]({{< ref "/controller/services/manage-certs.md#create-a-cert" >}}) - -## Create a Gateway - -Next, you'll need to create a Gateway. Be sure to add the Gateway to your Environment. - -- [About Gateways]({{< ref "/controller/services/manage-gateways.md#about-gateways" >}}) -- [Create a Gateway]({{< ref "/controller/services/manage-gateways.md#create-a-gateway" >}}) - -## Create an Identity Provider - -If you require authentication for any Component, you need to define an Identity Provider. The provider should be in the same environment as your component. -to be in the same environment as your components. - -- [Identity Provider]({{< ref "/controller/services/manage-identity-providers.md" >}}) - -## Create an App - -Create an App. The App needs to be in your Environment and needs to connect to your Gateway. If you created a Cert by following the instructions above and added the Cert to the Gateway, the App will access the Cert via the Gateway. If you didn't add the Cert to the Gateway, you can reference the Cert in the App's definition by choosing the Cert from the Certs list. - -- [About Apps]({{< ref "/controller/app-delivery/about-app-delivery.md#apps" >}}) -- [Create an App]({{< ref "/controller/app-delivery/manage-apps.md#create-an-app" >}}) - -## Create Components for your App - -Finally, create Components for your App. Components let you partition an App into smaller, self-contained pieces that are each responsible for a particular function of the overall application. For example, a Component could correspond to a microservice that, together with several other microservices, comprises a complete application. - -- [About Components]({{< ref "/controller/app-delivery/about-app-delivery.md#components" >}}) -- [Create a Component]({{< ref "/controller/app-delivery/manage-apps.md#create-a-component" >}}) - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/app-delivery/manage-apps.md b/content/controller/app-delivery/manage-apps.md deleted file mode 100644 index 8dbb4ecb6..000000000 --- a/content/controller/app-delivery/manage-apps.md +++ /dev/null @@ -1,373 +0,0 @@ ---- -description: Create, view, and edit Apps and Components. -nd-docs: DOCS-478 -title: Manage Apps & Components -toc: true -weight: 300 -type: -- how-to ---- - -## Overview - -Follow the steps in this topic to learn how to create and manage Apps and App Components. - -{{< call-out "tip" >}}You can also use the F5 NGINX Controller API to create Apps and Components. See the [NGINX Controller API Reference]({{< ref "/controller/api/_index.md" >}}) for details.{{< /call-out >}} -  - -## Before You Begin - -You will need to select an [Environment]({{< ref "/controller/services/manage-environments.md#create-an-environment" >}}) and [Gateway]({{< ref "/controller/services/manage-gateways.md#create-a-gateway" >}}) -- or create new Environment and Gateway resources -- when adding a new App. - -{{< call-out "note" >}}If you do not have permission to create these resources and none are available to select, contact your system administrator.{{< /call-out >}} -  - -## Create an App - -To create an App: - -1. Open the NGINX Controller user interface and log in. -1. Select the NGINX Controller menu icon, then select **Services**. -1. On the **Services** menu, select **Apps**. -1. On the **Apps** menu, select **Create App**. -1. On the **Create App** page, provide the following information: - - Name - - Environment - - Description (Optional) - - Display Name (Optional) - - Tags (Optional) -1. Select **Submit**. - -## Create a Component - -To create a Component: - -1. Open the NGINX Controller user interface and log in. -1. Select the NGINX Controller menu icon, then select **Services**. -1. On the **Services** menu, select **Apps**. -1. On the **Apps** menu, in the **Recent Apps** section, select the name of the App that you want to add the Component to. -1. On the Overview page for your App, select **Create Component**. -1. Then, complete each of the configuration sections as needed: - - - [General Configuration](#general-configuration) - - [URIs](#uris) - - [Workload Groups](#workload-groups) - - [Ingress](#ingress) - - [Backend](#backend) - - [Monitoring](#monitoring) - - [Errors and Logs](#errors-and-logs) - - [Programmability](#programmability) - - [Caching](#caching) - - [Snippets](#snippets) - - [Rate Limiting](#rate-limiting) - - [Authentication](#authentication) - - [Security](#security) - -1. When ready, review the API Spec and then select **Submit** to create the Component. - -## Configuration Options - -### General Configuration - -On the **Create App Component** *Configuration* page: - -1. Select the App Component Type: - - - Web - - TCP/UDP - -1. Provide the name for your Component. -1. (Optional) Provide a Display Name. -1. (Optional) Provide a Description. -1. (Optional) Add any desired tags. -1. (Optional) Select a **Gateway Ref** or select **Create Gateway Ref** to create a new Gateway. -1. Select **Next**. - -### URIs - -A Component definition must contain one or more URIs. - -**Web Component URIs** can be either of the following: - -- a complete URI that follows the format `[:port][/path]`, or -- a relative path that follows the format `[/...]`. - -Relative paths inherit the host URI configured for the Gateway associated with the Component. -The host and relative path(s) defined for a Component take precedence over the host defined in the associated Gateway. - -Example Web URI definitions: - -- `http://www.f5.com:8080/sales` -- `http://*.f5.com:5050/test` -- `/images` -- `/*.jpg` -- `/locations/us/wa*` - -**TCP/UDP URIs** must be a complete URI that follows the format ``. -TCP+TLS URIs can include TLS information. - -Example TCP/UDP URI definitions: - -- `tcp://192.168.1.1:12345` -- `tcp+tls://192.168.1.1:12346` -- `tcp://192.168.1.1:12345-12350` -- `tcp://*:12345` -- `udp://192.168.1.1:12345` -- `udp://*:12345` - -On the **Create App Component** *URIs* page: - -1. Define the **URIs**: - - - Select **Add URI**. - - In the **URI** box, type the URI for the Component. - - (Optional) Select a **Match Method** (applicable only to Web Components). - - (Optional) Select **Customize for this URI** to add custom **TLS Settings**. - - {{< call-out "note" >}} -TLS Settings can be inherited from the Gateway, or customized at the Component level. Enable this option if you want the Component to use a different cert than that used by the Gateway. - {{< /call-out >}} - -1. (Optional) Define the **Shared TLS Settings**. - - - To use a cert that is already associated with the Gateway, select it from the list. - - To add a new shared cert, select **Create New**. - -1. Select **Next**. - -### Workload Groups - -On the **Create App Component** *Workload Groups* page: - -1. Provide a Workload Group Name. -1. (Optional) Select a Location. - - The location determines which instances or instance groups the workload group is applied to. If any workload group specifies a location, they all must specify a location. Note: If the associated gateway uses instance groups, the location should refer to the instance group location, not the location(s) of the individual instances that make up that group. - - {{< call-out "note" >}}Refer to the [Manage Locations]({{< ref "/controller/infrastructure/locations/manage-locations.md" >}}) topic for more information.{{< /call-out>}} -1. Define the backend workload URIs. -1. (Optional) Define the DNS Server. -1. (Optional) Select the Load Balancing Method. The default value is "Round Robin". - - {{< call-out "note" >}}Refer to the [NGINX Plus Admin Guide](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/) for more information about the available options.{{< /call-out>}} - -1. (Optional) Select the Session Persistence Type (applicable only to Web Components). -1. (Optional) Select the Desired Proxy Settings (applicable only to Web Components). - - {{< call-out "tip" >}}Hover your pointer over the info icon for each setting to learn about the expected values and requirements.{{< /call-out >}} -1. Select **Next**. - -### Ingress - -On the **Create App Component** *Ingress* page: - -{{< call-out "note" >}} The following settings are applicable only to Web components. {{< /call-out >}} - -1. (Optional) Select the supported HTTP methods. -1. (Optional) Set the desired **Client Max Body Size**. - - {{< call-out "note" >}} -Refer to the [`ngx_http_core_module` docs](http://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size) for more information about these options. - {{< /call-out>}} - -1. Select **Next**. - -### Backend - -On the **Create App Component** *Backend* page: - -{{< call-out "note" >}} The following settings are applicable only to Web components. {{< /call-out >}} - -1. (Optional) Enable [NTLM authentication](https://en.wikipedia.org/wiki/Integrated_Windows_Authentication) to allow proxying requests with NT LAN Manager (NTLM) Authentication. -1. (Optional) Specify the persistent state. -1. (Optional) Set the HTTP protocol version for proxying. -1. (Optional) Specify the Keep Alive settings: - - - **Connections**: Set the maximum number of idle keepalive connections to upstream servers that are preserved in the cache of each worker process. When this number is exceeded, the least recently used connections are closed. - - **Requests per Connection**: Set the maximum number of requests that can be served through one keepalive connection. After the maximum number of requests is made, the connection is closed. - - **Idle Timeout box**: Set a timeout during which an idle keepalive connection to an upstream server will stay open. -1. Select **Next**. - -### Monitoring - -On the **Create App Component** *Monitoring* page: - -1. (Optional) Enable **Health Monitoring** and define the desired Monitoring Request and Response. Health Monitoring is disabled by default. -1. (Optional) Enable **Workload Health Events**. Workload Health Events are disabled by default. -1. (Optional) Specify the URI to use in health check requests (applicable only to Web Components). The default is `/`. For TCP/UDP Components, specify the Send string. -1. (Optional) Specify the port to use when connecting to a server to perform a health check. The server port is used by default. -1. (Optional) Set the interval to wait between two consecutive health checks. The default is 5 seconds. -1. (Optional) Specify the number of consecutive passed health checks that must occur for a server to be considered healthy. The default is 1. -1. (Optional) Specify the number of consecutive failed health checks that must occur for a server to be considered unhealthy. The default is 1. -1. (Optional) Specify the default state for the server. The default state is `HEALTHY`. -1. (Optional) Specify the starting HTTP status code to match against (applicable only to Web components). -1. (Optional) Specify the ending HTTP status code to match against (applicable only to Web components). -1. (Optional) Select whether a response should pass in order for the health check to pass (applicable only to Web components). By default, the response should have status code `2xx` or `3xx`. -1. Select **Next**. - - {{< call-out "note" >}} -Refer to the [`ngx_http_upstream_hc_module` docs](http://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html#health_check) for more information about these options. - {{< /call-out>}} - -### Errors and Logs - -On the **Create App Component** *Logs* page: - -1. (Optional) Select the logs to enable: - - - Error Log - - Access Log - -1. (Optional) Specify the log format to use. -1. Select **Next**. - - {{< call-out "note" >}} -Refer to the [`ngx_http_log_module` docs](http://nginx.org/en/docs/http/ngx_http_log_module.html) for more information about these options. - {{< /call-out>}} - -### Programmability - -On the **Create App Component** *Programmability* page: - -{{< call-out "note" >}} The following settings are applicable only to Web components. {{< /call-out >}} - -1. (Optional) Select **Add URI Redirects** and define the desired redirect condition(s). -1. (Optional) Select **Add URI Rewrite** and define the desired rewrite pattern(s). -1. (Optional) Select **Add Request Header Modification** and define how to modify the request header. -1. (Optional) Select **Add Response Header Modification** and define how to modify the response header. -1. Select **Next**. - - {{< call-out "note" >}} -Refer to the [`ngx_http_rewrite_module` docs](http://nginx.org/en/docs/http/ngx_http_rewrite_module.html) for more information about these options. - {{< /call-out>}} - -### Caching - -{{< call-out "note" >}} -Introduced in NGINX Controller App Delivery module v3.22. -{{< /call-out >}} - -On the **Create App Component** *Caching* page: - -1. Select the *Enable Caching* toggle to turn on caching. -1. Define the *Split Config* settings as appropriate for your component. - - - **PERCENTAGE** -- Select if you want to split the cache across two or more disk stores and assign a percentage of the store to each location. The *key* field is not required for this option if users set only one disk. - - **STRING** -- Select if you want to split the cache across two or more disk stores using pattern matching. The *key* field is required for this option. - - {{< call-out "note" >}}The *key* string must contain at least one valid [NGINX variable](https://nginx.org/en/docs/varindex.html). Example: `${request_uri}`{{< /call-out >}} - -1. Define the desired settings for the Disk Store: - - - **Path**: This is the location where the cache will be stored; this path must already exist on the data plane. - - **Max Size** - - **Min Free** - - **In Memory Store Size** - - **Is Default** - - **Temp Path** (Optional) - - **Inactive Time** (Optional) - - **Directory Level** (Optional) - - **Trim Policy** (Optional) - - **Loader Policy** (Optional) - - **Purger Policy** (Optional) - - {{< call-out "note" >}}Refer to the [`proxy_cache_path` docs](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_path) for more information about these options.{{< /call-out>}} - -1. Select *Add Disk Store* to add another disk store (Optional). - This will split the cache across multiple storage locations according to the *Split Config* criteria you selected. - - The following *Split Config* options will display depending on the criteria you selected: - - **Percent Criteria** - Required when using "PERCENTAGE" criteria type; must be an integer followed by the `%` symbol; decimals are supported; for example, `75%` or `50.5%`. - - **String Criteria** - Required when using "STRING" criteria type; Depending upon the `SplitConfig`-> `Key` it could be a string like `~/html`, `~*.html$'` or IP based string like `10.1.1.2` - -1. Select **Next** to go to the next page, or **Submit** to save and submit your changes. - -### Snippets - -{{< call-out "note" >}} -Introduced in NGINX Controller App Delivery module v3.22. -{{< /call-out >}} - -Refer to the [About Snippets]({{< ref "/controller/app-delivery/about-snippets.md" >}}) topic to learn more about Snippets and how they impact the NGINX Controller-generated `nginx.conf` file. - -On the **Create App Component** *Snippets* page: - -1. Select the appropriate snippet type: - - - *Add URI Snippet*: Adds NGINX directives to the component's `server` and `location` blocks. - - *Add Workload Group Snippet*: Adds NGINX directives to the component's `upstream` block(s). - -1. Paste or type the desired snippet into the text field. - - Snippets should follow the standard `nginx.conf` format. - For example, the below URI snippet adds the `proxy_set_header` directive to the component's `server` block. - - ```Nginx configuration file - proxy_set_header Host $proxy_host; - ``` - - {{< call-out "caution" >}}When you use Snippets to customize your NGINX configuration, your changes are applied to the `nginx.conf` file *as is*. NGINX Controller does not verify that your configuration is valid before applying the snippet. We strongly recommend verifying Snippets in a lab environment before making any changes in production.{{< /call-out >}} - -1. Select **Next** to preview the REST API call for your component, or **Submit** to save and submit your changes. - -### Rate Limiting - -On the **Create App Component** *Rate Limiting* page: - -{{< call-out "note" >}} The following Rate Limiting settings are applicable only to Web components. {{< /call-out >}} - -1. Enable Rate Limiting and select a **Key**. -1. Select options for Rate and Units. -1. (Optional) Select options for Excess Request Processing and Ignore Initial N Requests. -1. Select options for Reject Status Code. -1. Select **Next**. - -### Authentication - -On the **Create App Component** *Authentication* page: - -1. Select **Add Authentication**. -1. Select an [**Identity Provider**]({{< ref "/controller/services/manage-identity-providers.md" >}}). -1. Select a **Credential Location**. -1. (Optional) Enable [**Conditional Access**]({{< ref "/controller/services/available-policies.md#conditional-access" >}}). -1. Select **Next**. - -### Security - -On the **Create App Component** *Security* page: - -{{< call-out "note" >}} The following Security settings are applicable only to Web components. {{< /call-out >}} - -1. (Optional) Select **Enable Web Application Firewall (WAF)** to watch for or block suspicious requests or attacks. -1. (Optional) Select **Monitor Only** to allow traffic to pass without being rejected. Security events are still generated and metrics are still collected. Refer to [About App Security Analytics]({{< ref "/controller/analytics/view-app-security-analytics.md#overview" >}}) for more information. -1. (Optional) the signature(s) that you want the WAF to ignore. You can specify multiple signatures as a comma-separated list. -1. Select **Next**. - -{{< call-out "note" >}} -Refer to the [Secure Your Apps]({{< ref "/controller/app-delivery/security/_index.md" >}}) topics to learn more about WAF and the default protections provided by NGINX App Protect. -{{< /call-out>}} - -## Edit or Delete Apps and Components - -To view, edit, and delete Apps: - -1. Open the NGINX Controller user interface and log in. -1. Select the **NGINX Controller menu icon** > **Services** > **Apps**. -1. On the **Apps** menu, select **Overview**. The **Apps Overview** page is displayed and shows a list of your Apps. -1. To view the details for an App, including metrics data and components, select the App name in the list of Apps. -1. To edit the App, select **Edit Config** on the **Quick Actions** menu. -1. To delete the App, select **Delete Config** on the **Quick Action**s menu. - -To edit or delete a Component: - -1. Open the NGINX Controller user interface and log in. -1. Select the **NGINX Controller menu icon** > **Services** > **Apps**. -1. On the **Apps** menu, select **Overview**. The **Apps Overview** page is displayed and shows a list of your Apps. -1. Select the App that contains the Component that you want to modify. The App's **Overview** page is displayed. -1. In the details panel for your App, select **Components**. -1. On the **Components** page, select the Component that you want to modify. -1. To edit the Component, select **Edit Config** on the **Quick Actions** menu. -1. To delete the Component, select **Delete Config** on the **Quick Actions** menu. - -{{< versions "3.0" "latest" "ctrlvers" >}} -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/app-delivery/security/_index.md b/content/controller/app-delivery/security/_index.md deleted file mode 100644 index 54d5419bf..000000000 --- a/content/controller/app-delivery/security/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -description: Secure your applications using F5 NGINX Controller App Security -title: App Security -weight: 100 -url: /nginx-controller/app-delivery/security/ ---- - diff --git a/content/controller/app-delivery/security/concepts/_index.md b/content/controller/app-delivery/security/concepts/_index.md deleted file mode 100644 index 097169f5b..000000000 --- a/content/controller/app-delivery/security/concepts/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -description: Overview of the App Security module and default policy -title: Learn About App Security -weight: 100 -url: /nginx-controller/app-delivery/security/concepts/ ---- - diff --git a/content/controller/app-delivery/security/concepts/app-sec-default-policy-original.md b/content/controller/app-delivery/security/concepts/app-sec-default-policy-original.md deleted file mode 100644 index 342bc0cb4..000000000 --- a/content/controller/app-delivery/security/concepts/app-sec-default-policy-original.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -description: Learn about the default protections provided by F5 NGINX Controller App - Security. -nd-docs: DOCS-479 -title: Default WAF Policy -toc: true -weight: 200 -type: -- concept -- reference ---- - -## Overview - -You can use the F5 NGINX Controller App Security module to configure and manage a web application firewall (WAF). The App Security WAF protects your applications from HTTP and web-based threats, including the [OWASP Top 10](https://owasp.org/www-project-top-ten/). - -NGINX Controller App Security provides out-of-the-box analytics events and metrics, which are reported through the NGINX Controller API and user interface. App Security works with [NGINX App Protect](https://www.nginx.com/products/nginx-app-protect), running NGINX Plus as the WAF in the data path. - -## Default Policy - -The default policy for App Security WAF in NGINX Controller focuses on [OWASP Top 10](https://owasp.org/www-project-top-ten/) protection. This policy is the same default policy that is used by NGINX App Protect. - -The default policy for NGINX Controller App Security WAF includes these security checks: - - - - - -| **Security Checks** | **Description** | -|---------------------------|-----------------| -| HTTP RFC compliance enforcement | Validation of HTTP requests to prevent the use of the HTTP protocol as an entry point for malicious requests to applications. | -| URL normalization | Decoding of requests for encoded request that contain different types of encoded escapes | -| Evasion techniques | Protection for techniques commonly used by hackers to access resources or evade what would otherwise be identified as an attack. The checks performed are:
  • Bad unescape (bad escaping)
  • Directory traversal
  • Bare byte decoding
  • Apache whitespace
  • Multiple % decoding
  • IIS Unicode codepoint
  • IIS backslashes
  • %u decoding
| -| Malformed cookie | Validates that the cookie format is RFC compliant. | -| Illegal status code | Responses in the 400–500 range -- except for `400`, `401`, `404`, `407`, `417`, `503` -- are rejected. | -| Request size exceeds the buffer | Requests that exceed the buffer size | -| Maximum length for URL, header, query string, cookie, and POST data | URL length: 2048
Header length: 4096
Query string length: 2048
Cookie length: 4096
Post data length: 4096

{{< call-out "note" >}} The whole request length is not checked. The entire request cannot exceed the maximum buffer size of 10 MB.{{< /call-out >}} | -| Disallowed file type extension | These file types are disallowed:
  • bak, bat, bck, bkp, cfg, conf, config, ini, log, old, sav, save, temp, tmp
  • bin, cgi, cmd, com, dll, exe, msi, sys, shtm, shtml, stm
  • cer, crt, der, key, p12, p7b, p7c, pem, pfx
  • dat, eml, hta, htr, htw, ida, idc, idq, nws, pol, printer, reg, wmz
| -| Allowed methods | Only these HTTP methods are allowed:
  • GET
  • HEAD
  • POST
  • PUT
  • PATCH
  • DELETE
  • OPTIONS
| -| Character/Metacharacter validation in URL and header | Metacharacters are checked in the URL and header. | -| Parameter parsing | NGINX Controller App Security auto-detects the payload type for JSON and XML. App Security then applies the signature that matches the correct format.| -| JSON format | If the content is JSON, then App Security checks that the JSON payload body is well-formed. The max structure depth and max array length may not exceed 25. The max structure depth and max array length may not exceed 25.

No JSON schema enforcement. | -| DTD XML format | If the content is XML, then App Security checks that an XML payload body is well-formed.

No XML schema enforcement. No SOAP and Web Services Security format enforcement. | - -## Attack Types Used In Default Policy - -The following signature attack types are included with the default NGINX Controller App Security WAF policy. These attack types protect against [OWASP Top 10](https://owasp.org/www-project-top-ten/) vulnerabilities and [CVEs](https://cve.mitre.org/). Low, medium, and high accuracy signatures generate events as part of assessing the [Violation Rating](#use-of-violation-ratings-in-default-policy). - -- Command Execution Signatures -- Cross-Site Scripting Signatures -- Directory Indexing Signatures -- Information Leakage Signatures -- OS Command Injection Signatures -- Path Traversal Signatures -- Predictable Resource Location Signatures -- Remote File Include Signatures -- SQL Injection Signatures -- Authentication/Authorization Attacks Signatures -- XML External Entity (XXE) Signatures -- XPath Injection Signatures -- Buffer Overflow Signatures -- Denial of Service Signatures -- Vulnerability Scanner Signatures - -## Use of Violation Ratings in Default Policy - -The default policy for App Security assesses violations and provides a Violation Rating. This rating is an NGINX App Protect computed assessment of the risk of the request and its likelihood of an attack based on the triggered violations. - -NGINX App Protect violations are rated to distinguish between attacks and potential false-positive alerts. A rating is assigned to requests based on the presence of one or more violations. Each violation type and severity contribute to the calculation of the Violation Rating assigned to a request. - -The possible Violation Ratings are: - -- 0: No violation (no event available) -- 1: Possible False Positive (no event available) -- 2: Most Likely False positive (no event available) -- 3: Needs examination -- 4: Possible Attack -- 5: Most Likely Attack - -The Violation Rating is a dimension in Security Violation Events. NGINX App Protect rejects requests that have a Violation Rating of `4 (Possible Attack)` or `5 (Most Likely an Attack)`. However, the following violations and signature sets have a low chance of being false positives and are, therefore, configured by default to reject the request regardless of its Violation Rating: - -- High accuracy attack signatures -- Threat campaigns -- Malformed request: unparsable header, malformed cookie, and malformed body (JSON or XML). - -{{< call-out "note" >}} - -With the default policy, all requests rejected by NGINX App Protect generate a Security Event in NGINX Controller. Requests with Violation Rating of `3 (Needs examination)` also generate a Security Event in NGINX Controller. All other requests do not generate a Security Event in NGINX Controller. - -{{< /call-out >}} - -## Additional Information - -### HTTP RFC Compliance Already Rejected By NGINX - -Note the following events are blocked by NGINX Plus and not by the NGINX Controller App Security policy. These events are not reported in NGINX Controller as security violation events. - -| **HTTP RFC Compliance Checks** | **Description** | -|--------------------------------|-----------------| -| Unparsable request content | This violation is triggered when the system's parser cannot parse the message. | -| Several Content-Length headers | More than one content-length header is a non-RFC violation. Indicates an HTTP response splitting attack. | -| NULL in header | The system issues a violation for requests with a NULL character in the header. | -| No Host header in HTTP/1.1 request | Check to see if HTTP/1/1 requests contain a "Host" header. | -| High ASCII characters in headers| Check for high ASCII characters (greater than 127) in headers. | -| Content length should be a positive number | The Content-Length header value should be greater than zero; only a numeric positive number value is accepted. | -| Bad HTTP version | Enforces legal HTTP version number (only 0.9 or higher allowed). | - -{{< versions "3.12" "latest" "ctrlvers" >}} diff --git a/content/controller/app-delivery/security/concepts/app-sec-metrics.md b/content/controller/app-delivery/security/concepts/app-sec-metrics.md deleted file mode 100644 index a07aa2fd8..000000000 --- a/content/controller/app-delivery/security/concepts/app-sec-metrics.md +++ /dev/null @@ -1,184 +0,0 @@ ---- -description: Learn about the F5 NGINX Controller Application Security metrics and - events. -nd-docs: DOCS-480 -title: App Security Metrics -toc: true -weight: 400 -type: -- reference ---- - -## Overview - -This topic provides reference information for the metrics and events that F5 NGINX Controller reports for Application Security. - -## Security Metrics and Event Dimensions - -The following table shows the attributes and dimensions you can view and filter by for WAF violation events. - -{{}} - -| **Attribute** | **Possible Values** | **Description and Additional Information** | -|-------------|-----------|------| -| category | security violation | | -| timestamp | Timestamp of the request | UTC | -| message | | Provides summary info about if a request was rejected or flagged, from what source, and due to what attack types.| -| level | `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` | Security violation events are only `INFO` for now| -| hostname | |Hostname used in the request| -| environment | | | -| app | | | -| component | | | -| gateway | | | -| corelationId | | | -| http.request_endpoint | | Request URI | -| http.request_method | | Method used for the request| -| request_outcome |`REJECTED`, `PASSED`| The outcome of the request after Controller App Security processed the request.| -| request_outcome_reason | `SECURITY_WAF_OK`, `SECURITY_WAF_VIOLATION`, `SECURITY_WAF_FLAGGED`, `SECURITY_WAF_BYPASS`, `SECURITY_NGINX_VIOLATION`, `SECURITY_WAF_FLAGGED` | request_outcome_reason provides the reason why App Security rejected or flagged a request to be reviewed. Outcome reasons for `SECURITY_WAF_BYPASSED` and `SECURITY_NGINX_VIOLATION` have not been implemented.
{{< call-out "note" >}} App Security Events are not created for requests that don't trigger any violations. This means you should not see Events with `outcome_reason = SECURITY_WAF_OK`.{{< /call-out >}}| -| http.response_code | | Response code returned to App Security. A `0` code is returned if App Security did not block the request.| -| http.hostname | | Hostname of request| -| http.remote_addr | | Client IP of the request| -| http.remote_port | | Port of the client initiating the request| -| http.server_addr | | Server IP address that NGINX is listening on| -| http.server_port | | Server IP port that NGINX is listening on| -| waf.http_request | | Request including header, body, etc.| -| waf.support_id | | ID seen on the App Security rejection page| -| waf.signature_ids | | ID list of signatures triggered with the request. It usually does not go above three signature IDs.| -| waf.signature_names | | Names of signatures triggered with the request. It usually does not go above three signature names.| -|waf.attack_types | | Attack types triggered by the request. It can be based on any of the above signature or other protection mechanisms used in the WAF policy. It usually does not go above three attack types.| -| violations ||Comma-separated list of logical violation names| -| sub_violation ||More specific violations within ‘HTTP protocol compliance failed’ (violation = `VIOL_HTTP_PROTOCOL`) and/or ‘Evasion technique detected’ violations (violation = `VIOL_EVASION`) | -| sig_cves||Signature CVEs value of the matched signatures.| -| is_truncated||A flag that returns true if a request is truncated in the security events, or false if it is not. | -| x_forwarded_for_header_value||X-Forwarded-For header information. This option is commonly used when proxies are involved to track the originator of the request.| - -{{< /bootstrap-table >}} - -### Attack Types and Description - -Each signature and violation has an Attack Type which is the attack vector WAF protects from. The list of Attack Types and descriptions are listed here. You may see these attack types and violations in Security Events and Metrics. - -{{}} - -| **Attack Type** | **Description** | -|-----------------|-----------------| -| Server-Side Template Injection | Some applications use server-side templates for better modularity. This attack occurs when a non-sanitized input containing template directives is embedded into a server-side template which then leads to the execution of the injected code when rendered. | -|Insecure File Upload | Many applications allow uploading files to the server, such as images or documents. An application that does not correctly restrict the type of the uploaded files or the upload folder path can be exploited by attackers to upload files, called ‘WebShells’, containing malicious code that later will be executed or override the server configuration.| -|NoSQL Injection|NoSQL databases are non-relational databases, and even though they do not use the SQL syntax, non-sanitized input might let attackers control the original query via a database-specific programming language.| -|Insecure Deserialization | This is an attack against an application that receives serialized objects. An application which does not restrict which objects might be deserialized could be exploited by attackers sending specific object called ‘gadgets’, that could trigger arbitrary code execution when deserialized.| -|XML External Entities (XXE)| This is a type of attack against an application that parses XML input. This attack occurs when XML input containing a reference to an external entity is processed by a weakly configured XML parser.| -|Server-Side Request Forgery (SSRF) | Some applications receive a URL as an input and use it to exchange data with another service. An attacker could provide special URLs to read or update internal resources such as localhost services, cloud metadata servers, internal network web applications or HTTP enabled databases.| -|Cache Poisoning| Cache poisoning is an attack against the integrity of an intermediate Web cache repository, in which genuine content cached for an arbitrary URL is replaced with spoofed content.| -|WebSocket Parser Attack | WebSocket parser attack targets the functionality of the WebSocket parser to crash it or force the parser to work abnormally.| -|GWT Parser Attack | This attack targets the functionality of the GWT parser to crash it or force the parser to work abnormally.| -|Cross-site Request Forgery | An attacker exploits the web application’s assumption and trust that the authenticated user is purposely sending requests to perform actions or commands, while the attacker is causing the user to send the commands without the user’s knowledge or consent.| -|JSON Parser Attack |This attack targets the functionality of the JSON parser to crash it or force the parser to work abnormally.| -|Malicious File Upload|Malicious file upload occurs when a user tries to upload a malicious file to the web application. This could allow remote attackers to cause Server Infection, Network Infection, Buffer Overflow, and Remote Comma Execution.| -|HTTP Response Splitting|Specially crafted HTTP messages can manipulate the webserver or cache’s standard behavior. This can lead to XSS, and cache poisoning.| -|Session Hijacking|An attacker can steal a valid web session from legitimate users to gain unauthorized access.| -|XML Parser Attack|This attack targets the functionality of the XML parser to crash it or force the parser to work abnormally.| -|Parameter Tampering|By changing certain parameters in a URL or web page form, attackers can successfully attack the web application business logic.| -|Injection Attempt|This is an attack where an attacker injects OS commands, active script commands (in JavaScript or any other scripting language), or SQL commands into various parts of an HTTP request, for the injected content to run on remote systems. The two most common injection attacks are SQL injection and Cross-Site Scripting.| -|Brute Force Attack|Brute-force attacks are mainly used for guessing passwords and bypassing access control of an application by executing many different attempts.| -|Forceful Browsing|This attack occurs when an attacker is directly accessing a URL, which could grant access to a restricted part of the web site.| -|HTTP Request Smuggling Attack|Specially crafted HTTP messages can manipulate the webserver or cache’s standard behavior. This can lead to XSS, and cache poisoning.| -|HTTP Parser Attack|HTTP parser attack targets the functionality of the HTTP parser to crash it or force the parser to work abnormally.| -|Other Application Activity|This attack does not belong to any specific attack category, however, it is a violation of the user-defined security policy.| -|Denial of Service|A denial-of-service (DoS) attack represents a family of attacks aimed to exhaust the application server resources up to a point that the application cannot respond to legitimate traffic, either because it has crashed, or because its slow response renders it effectively unavailable.| -|Cross-Site Scripting (XSS)|Cross-Site Scripting (XSS) occurs when a web application does not sanitize user-supplied input and places it directly into the page returned to the user. Usually, the attacker will submit malicious JavaScript, VBScript, ActiveX, HTML, or Flash code to the vulnerable website.| -|SQL-Injection|SQL-Injection occurs when a web application does not sanitize user-supplied input and places it directly into the SQL statement. This attack allows remote attackers to run SQL statements on the internal database.| -|Command Execution|Web applications can be tricked to execute operating system commands, injected from a remote machine if user-supplied input is not properly checked by the web application.| -|Server Side Code Injection|An attacker can submit server-side code by invalidated input. The webserver, when parsing malicious input, may execute operating system commands or access restricted files.| -|LDAP Injection|If user-supplied input is not correctly sanitized, the attacker could change the construction of LDAP statements. Successful exploitation results in information gathering, system integrity compromise, and possible modification of the LDAP tree.| -|XPath Injection|XPath-Injection occurs when a web application does not sanitize user-supplied input but places it directly into the XML document query. Successful exploitation results in information gathering and system integrity compromise.| -|Path Traversal|Path traversal can be used to bypass the webserver root and request various files, including system files or private directories and resources. This attack can lead to information disclosure and possible exposure of sensitive system information.| -|Directory Indexing|This is a directory listing attempt which can lead to information disclosure and possible exposure of sensitive system information. Directory Indexing attacks usually target webservers that are not correctly configured, or which have a vulnerable component that allows Directory Indexing.| -|Information Leakage|Sensitive information may be present within HTML comments, error messages, source code, or simply left in files that are accessible by remote clients. Besides, attackers can manipulate the application to reveal classified information like credit card numbers. This can lead to the disclosure of sensitive system information which may be used by an attacker to further compromise the system.| -|Predictable Resource Location|By making educated guesses, the attacker could discover hidden web site content and functionality, such as configuration, temporary, backup, or sample files. This can lead to the disclosure of sensitive system information which may be used by an attacker to compromise the system.| -|Buffer Overflow|Buffer Overflow could be triggered when data written to memory exceeds the allocated size of the buffer for that data. This could lead to the Denial of Service or arbitrary code execution.| -|Authentication/Authorization Attacks|Authentication/Authorization Attacks occur when a web site permits an attacker to access sensitive content or functionality without having to properly authenticate, or authorize, that resource.| -|Abuse of Functionality|Abuse of Functionality is an attack technique that uses a website’s features and functionality to consume, defraud, or circumvent access control mechanisms.| -|Vulnerability Scan|An attempt is made using an automatic tool to scan a webserver, or an application running on a webserver, for a possible vulnerability.| -|Detection Evasion|An attempt is made to evade detection of the attack on a webserver, by obfuscating the attack using various methods such as encodings and path manipulation.| -|Trojan/Backdoor/Spyware|This is an attack initiated by some form of malicious code.| -|Other Application Attacks|This is an attack which targets the web application and does not fall in any predefined category| -|Non-browser Client|An attempt is made by a non-browser client to explore the site.| -|Remote File Include|Remote File Inclusion attacks allow attackers to run arbitrary code on a vulnerable website.| - -{{< /bootstrap-table >}} - -### Violations and Descriptions - -Each violation consists of one or more security checks (for example, attack signatures, HTTP RFC compliance, and evasion techniques). Each security check could be a specific attack signature, a specific HTTP Compliance check, or a specific evasion technique that is triggered within WAF. - -{{}} - -| **Violation Value** | **Name** | **Description** | -|-----------------|-----------------|--------------------| -|`VIOL_ASM_COOKIE_MODIFIED` | Modified ASM cookie |The system checks that the request contains an ASM cookie that has not been modified or tampered with. Blocks modified requests.| -|`VIOL_ATTACK_SIGNATURE`|Attack signature detected|The system examines the HTTP message for known attacks by matching it against known attack patterns. See signature_ids and signature_names attributes for specific signatures matched.| -|`VIOL_COOKIE_EXPIRED`|Expired timestamp|The system checks that the timestamp in the HTTP cookie is not old. An old timestamp indicates that a client session has expired. Blocks expired requests. The timestamp is extracted and validated against the current time. If the timestamp is expired and it is not an entry point, the system issues the Expired Timestamp violation.| -|`VIOL_COOKIE_LENGTH`|Illegal cookie length|The system checks that the request does not include a cookie header that exceeds the acceptable length specified in the security policy.| -|`VIOL_COOKIE_MALFORMED`|Cookie not RFC-compliant|This violation occurs when HTTP cookies contain at least one of the following components:
  • Quotation marks in the cookie name
  • A space in the cookie name.
  • An equal sign (=) in the cookie name. Note: A space between the cookie name and the equal sign (=), and between the equal sign (=) and cookie value is allowed.
  • An equal sign (=) before the cookie name.
  • A carriage return (hexadecimal value of 0xd) in the cookie name.
    • | -|`VIOL_ENCODING`|Failed to convert character|The system detects that one of the characters does not comply with the configured language encoding of the web application’s security policy.| -|`VIOL_EVASION`|Evasion technique detected|This category contains a list of evasion techniques that attackers use to bypass detection.| -|`VIOL_FILETYPE`|Illegal file type|The system checks that the requested file type is configured as a valid file type, or not configured as an invalid file type, within the security policy. Only for disallowed file types.| -|`VIOL_HEADER_LENGTH`|Illegal header length|The system checks that the request includes a total HTTP header length that does not exceed the length specified in the security policy. The actual size in the default policy is 4 KB.| -|`VIOL_HEADER_METACHAR`|Illegal meta character in header|The system checks that the values of all headers within the request only contain meta characters defined as allowed in the security policy.| -|`VIOL_HTTP_PROTOCOL`|HTTP protocol compliance failed|This category contains a list of validation checks that the system performs on HTTP requests to ensure that the requests are formatted properly.| -|`VIOL_HTTP_RESPONSE_STATUS`|Illegal HTTP response status|The server response contains an HTTP status code that is not defined as valid in the security policy.| -|`VIOL_JSON_MALFORMED`|Malformed JSON data|The system checks that the request contains JSON content that is well-formed. Enforces parsable JSON requests.| -|`VIOL_METHOD`|Illegal method|The system checks that the request references an HTTP request method that is found in the security policy. Enforces desired HTTP methods; GET and POST are always allowed. These HTTP methods are supported: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS.| -|`VIOL_QUERY_STRING_LENGTH`|Illegal query string length|The system checks that the request contains a query string whose length does not exceed the acceptable length specified in the security policy. In * file type entity. The actual size is 2 KB.| -|`VIOL_REQUEST_MAX_LENGTH`|Request length exceeds defined buffer size|The system checks that the request length is not larger than the maximum memory buffer size of the ASM. Note that this is a BIG-IP unit parameter that protects the ASM from consuming too much memory across all security policies which are active on the device. Default is 10MB.| -|`VIOL_URL_LENGTH`|Illegal URL length|The system checks that the request is for a URL whose length does not exceed the acceptable length specified in the security policy. In * file type entity. The actual size is 2 KB.| -|`VIOL_URL_METACHAR`|Illegal meta character in URL|The system checks that the incoming request includes a URL that contains only meta characters defined as allowed in the security policy. Enforces the desired set of acceptable characters.| -|`VIOL_XML_FORMAT`|XML data does not comply with format settings|The system checks that the request contains XML data that complies with the various document limits within the defense configuration in the security policy’s XML profile. Enforces proper XML requests and the data failed format/defense settings such as the maximum document length. This violation is generated when a problem in an XML document is detected (for example, an XML bomb), generally checking the message according to boundaries such as the message’s size, maximum depth, and the maximum number of children.| -|`VIOL_XML_MALFORMED`|Malformed XML data|The system checks that the request contains XML data that is well-formed, according to W3C standards. Enforces proper XML requests.| -|`VIOL_RATING_THREAT`|Request is likely a threat|The combination of violations in this request determined that the request is likely to be a threat.| -|`VIOL_PARAMETER_NAME_METACHAR`|Illegal meta character in parameter name|The system checks that all parameter names within the incoming request only contain meta characters defined as allowed in the security policy.| -|`VIOL_PARAMETER_VALUE_METACHAR`|Illegal meta character in value|The system checks that all parameter values, XML element/attribute values, or JSON values within the request only contain meta characters defined as allowed in the security policy. Enforces proper input values.| - -{{< /bootstrap-table >}} - -### HTTP RFC Sub-violations and Descriptions - -The following table specifies the HTTP Compliance sub-violation settings. All are supported in NGINX, but not all are enabled in the default App Protect security template. The table specifies which. Some of the checks are enforced by NGINX Plus and App Protect only gets a notification. Note: In this case, the request is always blocked regardless of the App Protect policy. - -{{}} - -| **Sub-violation** | **Description** | -|-----------------|-----------------| -|Null in request (null in body, null in the header is done by NGINX Plus)|The system issues a violation for requests with a NULL character anywhere in the request (except for a NULL in the binary part of a multipart request).| -|Multiple host headers|Examines requests to ensure that they contain only a single “Host” header.| -|The host header contains IP address|The system verifies that the request’s host header value is not an IP address to prevent non-standard requests.| -|CRLF characters before request start|Examines whether there is a CRLF character before the request method. If there is, the system issues a violation.| -|Chunked request with Content-Length header|The system checks for a Content-Length header within chunked requests.| -|Check the maximum number of parameters|The system compares the number of parameters in the request to the maximum configured number of parameters. Maximum is set to 500.| -|Check the maximum number of headers|The system compares the request headers to the maximal configured number of headers. Maximum is set to 50.| -|Unescaped space in URL|The system checks that there is no unescaped space within the URL in the request line. Such spaces split URLs introducing ambiguity on picking the actual one.| -|Bad multipart/form-data request parsing|When the content type of a request header contains the substring “Multipart/form-data”, the system checks whether each multipart request chunk contains the strings “Content-Disposition” and “Name”. If they do not, the system issues a violation.| -|Bad multipart parameters parsing|The system checks the following:
    • A boundary follows immediately after request headers.
    • The parameter value matches the format: ‘name=”param_key”;rn.
    • A chunked body contains at least one CRLF.
    • A chunked body ends with CRLF.
    • Final boundary was found on multipart request.
    • There is no payload after final boundary.
    • If one of these is false, the system issues a violation.
      • | - -{{< /bootstrap-table >}} - -### Evasion Techniques and Description - -The following table specifies the Evasion Techniques sub-violation values and descriptions. - -{{}} - -| **Sub-violation** | **Description** | -|-----------------|-----------------| -|%u decoding|The system performs Microsoft %u Unicode decoding (%UXXXX where X is a hexadecimal digit). For example, the system turns a%u002fb to a/b. The system performs this action on URI and parameter input to evaluate if the request contains an attack.| -|Apache whitespace|The system detects the following characters in the URI: 9 (0x09), 11 (0x0B), 12 (0x0C), and 13 (0x0D).| -|Bad unescape|The system detects illegal HEX encoding. Reports unescaping errors (such as %RR).| -|Bare byte decoding|The system detects higher ASCII bytes (greater than 127).| -|Directory traversals|The system ensures that directory traversal commands like ../ are not part of the URL. While requests generated by a browser should not contain directory traversal instructions, sometimes requests generated by JavaScript have them.| -|IIS backslashes|The system normalizes backslashes (`\`) to slashes (`/`) for further processing.| -|IIS Unicode codepoints|The system handles the mapping of IIS specific non-ASCII codepoints. Indicates that, when a character is greater than ‘0x00FF’, the system decodes %u according to an ANSI Latin 1 (Windows 1252) code page mapping. For example, the system turns a%u2044b to a/b. The system performs this action on URI and parameter input.| -|Multiple decoding|The system decodes URI and parameter values multiple times according to the number specified before the request is considered an evasion. The maximum decoding is 3.| - -{{< /bootstrap-table >}} - -{{< versions "3.12" "latest" "ctrlvers" >}} diff --git a/content/controller/app-delivery/security/concepts/bring-your-own-policy.md b/content/controller/app-delivery/security/concepts/bring-your-own-policy.md deleted file mode 100644 index b9a72634e..000000000 --- a/content/controller/app-delivery/security/concepts/bring-your-own-policy.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -description: Learn how to use your own F5 WAF for NGINX policies with NGINX - Controller. -nd-docs: DOCS-481 -title: Bring Your Own WAF Policy -toc: true -weight: 300 -type: -- concept ---- - -## Overview - -You can use the App Security Add-on for F5 NGINX Controller ADC to bring your own ("BYO") NGINX App Protect policies into NGINX Controller. This lets you use your existing declarative JSON policies from NGINX App Protect to protect your ADC app components. - -A BYO NGINX App Protect policy lets you maintain consistent Security Policies across your F5 WAF and NGINX WAF deployments. For example, say you already use F5 BIG-IP Application Security Manager (ASM) or F5 Advanced WAF and are now adopting NGINX Controller App Security. You can convert your XML Security Policies to an NGINX App Protect policy by using the [NGINX App Protect Policy Converter tool](https://docs.nginx.com/nginx-app-protect/configuration/#policy-converter). - -To export a policy from F5 Advanced WAF or ASM, take the following steps: - -1. Convert your F5 XML security policy to an F5 WAF for NGINX declarative JSON policy using the [NGINX App Protect Policy Converter tool](https://docs.nginx.com/nginx-app-protect/configuration/#policy-converter). - {{< call-out "note" >}}We recommend using the Converter tool that corresponds with the most recent NGINX App Protect version.{{< /call-out >}} - -2. Use the NGINX App Protect declarative JSON policy as the WAF policy in NGINX Controller for your app component(s). - -  - -With a BYO NGINX App Protect policy, you can also provide customized security by crafting an F5 WAF for NGINX policy that specifies the security controls appropriate for your apps. For more information on how to configure an F5 WAF for NGINX policy, refer to the [NGINX App Protect Configuration Guide](https://docs.nginx.com/nginx-app-protect/configuration/). - -## Security Strategy for BYO NGINX App Protect Policy - -The BYO NGINX App Protect policy uses the concept of a [Security Strategy]({{< ref "/controller/app-delivery/security/concepts/what-is-waf.md#security-policy-and-security-strategy" >}}) - -With the BYO NGINX App Protect policy feature, you can specify the exact NGINX App Protect policy for the Security Strategy. Then, the Security Strategy can be shared across -- and referenced by -- multiple app components. -A Security Strategy can be comprised of various app-security-related Security Policies. NGINX Controller includes a custom F5 WAF for NGINX policy, which can be assigned to a Security Strategy. - -You can also add a BYO F5 WAF for NGINX policy in JSON format to NGINX Controller "as-is" for use in a Security Strategy. - - -An **App Component** contains a reference to a **Security Strategy**, which, in turn, references a Security Policy. This Security Policy contains the **F5 WAF for NGINX policy**. - -Refer to the topic [Enable WAF for a Component Using Your Own NGINX App Protect Policy]({{< ref "/controller/app-delivery/security/tutorials/add-app-security-with-waf.md#enable-waf-for-a-component-using-your-own-nap-policy-beta" >}}) to get started. - -## Limitations - -BYO NAP WAF policy currently has the following limitations: - -- The size of the BYO F5 WAF for NGINX policy that's referenced by app components may affect application performance. -- References to external files, such as the following, in the F5 WAF for NGINX JSON declarative policy are not supported: - - User Defined Signatures - - Security controls in external references - - Referenced OpenAPI spec files -- Cookie modification (`VIOL_COOKIE_MODIFIED`) is not supported. -- gRPC protection is not supported. -- Protection with partial security visibility: - - Not all security metrics dimensions are available for the following: - - Bot violations - - CSRF origin validation violations - - User-defined browser violations - -{{< versions "3.20" "latest" "adcvers" >}} diff --git a/content/controller/app-delivery/security/concepts/extend-app-security-snippets.md b/content/controller/app-delivery/security/concepts/extend-app-security-snippets.md deleted file mode 100644 index c2bc242b2..000000000 --- a/content/controller/app-delivery/security/concepts/extend-app-security-snippets.md +++ /dev/null @@ -1,240 +0,0 @@ ---- -description: Learn how to extend your App Security configurations using F5 NGINX Controller - Snippets. -nd-docs: DOCS-338 -title: Extend App Security with Snippets -toc: true -weight: 400 -type: -- concept -- reference ---- - -## Overview - -F5 NGINX Controller [Snippets]({{< ref "/controller/app-delivery/about-snippets.md" >}}) let you customize your NGINX configuration by adding NGINX directives that aren't represented by the NGINX Controller API. - -Snippets also let you customize App Security for your Components by adding NGINX App Protect directives that aren't present in the NGINX Controller API. You can use Snippets when [tuning your F5 WAF for NGINX performance]({{< ref "/controller/app-delivery/security/tutorials/tune-waf-for-app" >}}) as well. - -{{< call-out "caution" >}} -When you use Snippets to customize your NGINX configuration, your changes are applied to the `nginx.conf` file *as is*. NGINX Controller does not verify that your configuration is valid before applying the Snippet. - -We strongly recommend verifying Snippets in a lab environment before making any changes in production. -{{< /call-out >}} - -## App Security Usage Examples - -{{< call-out "caution" >}} -The examples provided here are intended for demonstration purposes only. -We strongly recommend verifying Snippets in a lab environment before making any changes in production. -{{< /call-out >}} - -### Define a Backup Location for Security Event Logs - -When you [enable WAF on a Component]({{< ref "/controller/app-delivery/security/tutorials/add-app-security-with-waf" >}}), all Security Events are sent to NGINX Controller logs via syslog. The following example uses the `app_protect_security_log` directive in a URI Snippet to define a local backup location for Security Event logs. You can also send Security Events to another syslog server or to `stderr` by inserting an additional URI Snippet with the `app_protect_security_log` directive. - -{{< call-out "caution" >}} -Using local files as a backup for Security Events may use up disk space and affect your system performance. In production environments, setting up a remote file or a remote syslog server for backup purposes are good alternatives to using a local backup. -{{< /call-out >}} - -```json -{ - "metadata": { - "name": "" - }, - "desiredState": { - "ingress": { - "uris": { - "/": { - } - }, - "gatewayRefs": [ - { - "ref": "/services/environments/environment-name/gateways/" - } - ] - }, - "security": { - "strategyRef": { - "ref": "/security/strategies/balanced_default" - }, - "waf": { - "isEnabled": true - } - }, - "backend": { - "workloadGroups": { - "servers": { - "uris": { - "https://test-01.example.com": { - }, - "https://test-02.example.com": { - } - } - } - } - }, - "configSnippets": { - "uriSnippets": [ - { - "directives": [ - { - "directive":"app_protect_security_log", - "args": ["/etc/controller-agent/configurator/auxfiles/log-default.json", "/var/log/app_protect/security.log"] - } - ] - } - ] - } - } -} -``` - -### Add Location of User-Defined Signature Definition File - -When using [Bring Your Own WAF Policy]({{< ref "/controller/app-delivery/security/concepts/bring-your-own-policy" >}}) in NGINX Controller, you can define a URI Snippet for a Gateway API to define the location for your User-Defined Signature Definition file. The User-Defined Signature can then be referenced in the custom F5 WAF for NGINX policy that you use for your Components. - -{{< call-out "note" >}} -The file that contains the signature definition must already exist on your F5 WAF for NGINX instances. For more information regarding User-Defined Signatures, refer to the [F5 WAF for NGINX Configuration Guide](https://docs.nginx.com/nginx-app-protect/configuration-guide/configuration/#user-defined-signatures). -{{< /call-out >}} - -The following example adds a URI snippet to the Gateway API definition that provides the location of the User-Defined Signature Definition file. - -```json -{ - "metadata": { - "name": "" - }, - "desiredState": { - "configSnippets": { - "httpSnippet": { - "directives": [ - { - "directive": "app_protect_user_defined_signatures", - "args": ["app_protect_user_defined_signature_def_01"] - } - ] - } - }, - "ingress": { - "uris": { - "": {} - }, - "placement": { - "instanceRefs": [ - { - "ref": "/infrastructure/locations/unspecified/instances/" - } - ] - } - } - } -} - -``` - -### Harden Security using Fail-Closed - -Setting NGINX App Protect to "fail-closed" drops application traffic when certain conditions exist. This setting lets you err on the side of greater security as opposed to convenience, providing better protection for your applications when NGINX App Protect is not available. - -The example below adds HTTP Snippets to the Gateway that set the following NGINX App Protect directives to `drop`, or "fail-closed": - -- `app_protect_failure_mode_action` -- `app_protect_compressed_requests_action` -- `app_protect_request_buffer_overflow_action` - -Refer to the [NGINX App Protect Configuration Guide](https://docs.nginx.com/nginx-app-protect/configuration-guide/configuration/#global-directives) for more information about these directives and the conditions to which each applies. - -```json -{ - "metadata": { - "name": "gateway-name" - }, - "desiredState": { - "configSnippets": { - "httpSnippet": { - "directives": [ - { - "directive": "app_protect_failure_mode_action", - "args": ["drop"] - }, - { - "directive": "app_protect_compressed_requests_action", - "args": ["drop"] - }, - { - "directive": "app_protect_request_buffer_overflow_action", - "args": ["drop"] - } - ] - } - }, - "ingress": { - "uris": { - "http://example.com:8000": {} - }, - "placement": { - "instanceRefs": [ - { - "ref": "/infrastructure/locations/unspecified/instances/" - } - ] - } - } - } -} - -``` - -## Tuning WAF Performance Usage Examples - -{{< call-out "caution" >}} -The examples provided here are intended for demonstration purposes only. -We strongly recommend verifying Snippets in a lab environment before making any changes in production. -{{< /call-out >}} - -## Set the Memory and CPU Threshold Values - -This example adds an HTTP Snippet to a Gateway to control the memory and CPU threshold values which determine when NGINX App Protect enters and exits failure mode. - -In *failure mode*, F5 WAF for NGINX stops processing app traffic. Traffic is either dropped or passed through, as determined by the `app_protect_failure_mode_action` directive. - -The example below directs F5 WAF for NGINX to enter failure mode when memory utilization or CPU utilization reaches 85% and to exit failure mode when memory or CPU utilization drops to 60%. - -```json -{ - "metadata": { - "name": "" - }, - "desiredState": { - "configSnippets": { - "httpSnippet": { - "directives": [ - { - "directive": "app_protect_physical_memory_util_thresholds", - "args": ["high=85 low=60"] - }, - { - "directive": "app_protect_cpu_thresholds", - "args": ["high=85 low=60"] - } - ] - } - }, - "ingress": { - "uris": { - "http://example.com:8000": {} - }, - "placement": { - "instanceRefs": [ - { - "ref": "/infrastructure/locations/unspecified/instances/" - } - ] - } - } - } -} -``` - -{{< versions "3.22" "latest" "adcvers" >}} diff --git a/content/controller/app-delivery/security/concepts/what-is-waf.md b/content/controller/app-delivery/security/concepts/what-is-waf.md deleted file mode 100644 index c03264384..000000000 --- a/content/controller/app-delivery/security/concepts/what-is-waf.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -description: Overview of the App Security module's WAF feature. -nd-docs: DOCS-483 -title: About App Security -toc: true -weight: 100 -type: -- concept -- reference ---- - -## Overview - -The App Security Add-on for F5 NGINX Controller ADC lets you protect your applications with a web applications firewall (WAF). The WAF protects your apps from a variety of application layer attacks such as [cross-site scripting (XSS)](https://www.f5.com/services/resources/glossary/cross-site-scripting-xss-or-css), [SQL injection](https://www.f5.com/services/resources/glossary/sql-injection), and [cookie poisoning](https://www.f5.com/services/resources/glossary/cookie-poisoning), among others. - -A WAF protects your web apps by filtering, monitoring, and blocking any malicious HTTP/S traffic traveling to the web application, and prevents any unauthorized data from leaving the app. It does this by adhering to a set of policies that help determine what traffic is malicious and what traffic is safe. Just as a proxy server acts as an intermediary to protect the identity of a client, a WAF operates in similar fashion but in the reverse—called a reverse proxy—acting as an intermediary that protects the web app server from a potentially malicious client. - -{{< call-out "note" >}} To learn more about what a WAF is and how it works, check out the F5 DevCentral video: [What is a Web Application Firewall?](https://www.youtube.com/watch?v=p8CQcF_9280){{< /call-out>}} - -  - -## How it works - -App Security on NGINX Controller provides an app‑centric self‑service model to address the security needs of modern apps. - -The App Security add-on uses the NGINX App Protect Web Application Firewall (F5 WAF for NGINX) enforcement engine on the data path (data plane). -When you enable WAF on an app component using NGINX Controller, a security policy (sets of security controls and enforcement logic) is deployed and applied to configured NGINX App Protect instances that process traffic for the app component. - -F5 WAF for NGINX inspects incoming traffic as specified in the Security Policy to identify potential threats. When malicious traffic is suspected or blocked, the NGINX Controller Analytics module logs security events and metrics. These are then included in the NGINX Controller Threat Visibility and Analytics reporting. - -{{< call-out "note" >}}To learn more, read the [Threat Visibility and Analytics](https://www.nginx.com/blog/threat-visibility-analytics-nginx-controller-app-security/) blog post on [nginx.com](https://nginx.com).{{< /call-out>}} - -{{< img src="/ctlr/img/cas-overview.png" title="" alt="Controller App Security Overview Image" width="75%">}} - -## Security Policy - -In NGINX Controller, the Security Policy contains an F5 WAF for NGINX policy. The F5 WAF for NGINX policy has security controls and settings in a declarative JSON format. The Security Policy defines the rules and settings for application traffic inspection, detection of malicious traffic, and handling violations when they occur. For more about creating, updating, or deleting Security Policies, see the [Policies API Reference](https://docs.nginx.com/nginx-controller/api/ctlr-adc-api/#operation/listPolicies). - -When enabling WAF to protect your Apps, you can either add your own custom Security Policy or use the default Security Policy. - -## Security Strategy - -A Security Strategy is a logical container for multiple Security Policies. In a Security Strategy, you can reference a Security Policy that represents a security risk profile. For example, you can map low- or high-risk security profiles to different Security Strategies as you deem fit for your Apps' specific use case or organizational needs. - -When you enable security on the App Component, you can specify the Security Strategy to protect it. You can use the same Security Strategy across multiple app components. The Security Policy referenced in the Security Strategy detects and protects against malicious traffic to the App Component. - -- **App Component** references **Security Strategy**; -- **Security Strategy** references **Security Policy**. - -For more about creating, updating, or deleting Security Policies, see the [Strategies API Reference](https://docs.nginx.com/nginx-controller/api/ctlr-adc-api/#tag/Strategies). - -You can use a custom Security Strategy to protect your Apps, or you can use NGINX Controller's default Security Strategy, which contains a pre-defined WAF policy. - -{{< call-out "note" >}} - -The `/services/strategies/balanced_default` endpoint was replaced by `/security/strategies/balanced_default` in NGINX Controller ADC v3.18. - -- Specify the `StrategyRef` setting with `/security/strategies/balanced_default` instead of `/services/strategies/balanced_default`. - -Refer to the AskF5 knowledge base article [K02089505](https://support.f5.com/csp/article/K02089505) for more information. - -{{< /call-out >}} - diff --git a/content/controller/app-delivery/security/tutorials/_index.md b/content/controller/app-delivery/security/tutorials/_index.md deleted file mode 100644 index 838458c47..000000000 --- a/content/controller/app-delivery/security/tutorials/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -description: How to deploy and configure the App Security module -title: Manage App Security -weight: 200 -url: /nginx-controller/app-delivery/security/tutorials/ ---- - diff --git a/content/controller/app-delivery/security/tutorials/add-app-security-with-waf.md b/content/controller/app-delivery/security/tutorials/add-app-security-with-waf.md deleted file mode 100644 index 74c0e66d3..000000000 --- a/content/controller/app-delivery/security/tutorials/add-app-security-with-waf.md +++ /dev/null @@ -1,271 +0,0 @@ ---- -description: How to add F5 NGINX Controller App Security to your applications. -nd-docs: DOCS-484 -title: Manage App Security -toc: true -weight: 100 -type: -- concept -- reference ---- - -## Overview - -You can use the App Security add-on for F5 NGINX Controller ADC to enable Web Application Firewall (WAF) capabilities to protect your applications. WAF lets you flag or block suspicious requests or attacks. WAF can be added to individual app components. - - -## Before You Begin - -Before proceeding with this guide, complete the following tasks. -{{< call-out "note" >}}These steps may need to be completed by a user with admin permissions.{{< /call-out >}} - -1. [Add an NGINX App Protect instance]({{< ref "/controller/infrastructure/instances/add-nap-instance.md" >}}) to NGINX Controller. - -In addition, the following resources must exist in order to complete the steps in this topic: - -- [Environment]({{< ref "/controller/services/manage-environments.md" >}}) -- [Gateway]({{< ref "/controller/services/manage-gateways.md" >}}) -- [Certs]({{< ref "/controller/services/manage-gateways.md" >}}) (required if your Components use HTTPS) -- [App and Component(s)]({{< ref "/controller/app-delivery/manage-apps.md" >}}) - -## Enable WAF for a Component using the Default Security Strategy - -To enable WAF functionality for Application Security using the default security strategy, send a POST or PUT request to the Components endpoint, with a JSON object similar to the following: - -```json - "security": { - "waf": { - "isEnabled": true - } - } -``` - -{{< call-out "note" >}}You need READ access to the `/security/strategies/` API path to enable WAF on a component. By default, only users with an admin role have full access to all API endpoint resources.{{< /call-out >}} - -This JSON object should be added to the Component endpoint similar to the following example: - -```json -{ - "metadata": { - "name": "secure", - "displayName": "protected web server", - "description": "ProtectedWeb Server", - "tags": [ - "dev", - "protected" - ] - }, - "desiredState": { - "ingress": { - "gatewayRefs": [ - { - "ref": "/services/environments/dev/gateways/dev-gw" - } - ], - "uris": { - "/secure": { - "matchMethod": "PREFIX" - } - } - }, - "security": { - "strategyRef": { - "ref": "/security/strategies/balanced_default" - }, - "waf": { - "isEnabled": true - } - }, - "backend": { - "ntlmAuthentication": "DISABLED", - "preserveHostHeader": "DISABLED", - "workloadGroups": { - "farm": { - "locationRefs": [ - { - "ref": "/infrastructure/locations/unspecified" - } - ], - "loadBalancingMethod": { - "type": "ROUND_ROBIN" - }, - "uris": { - "http://{{workload-1}}:8080": { - "isBackup": false, - "isDown": false, - "isDrain": false, - "resolve": "DISABLED" - }, - "http://{{workload-2}}:8080": { - "isBackup": false, - "isDown": false, - "isDrain": false, - "resolve": "DISABLED" - }, - "http://{{workload-3}}:8080": { - "isBackup": false, - "isDown": false, - "isDrain": false, - "resolve": "DISABLED" - }, - "http://{{workload-4}}:8080": { - "isBackup": false, - "isDown": false, - "isDrain": false, - "resolve": "DISABLED" - } - } - } - } - }, - "logging": { - "errorLog": "ENABLED", - "accessLog": { - "state": "DISABLED", - "format": "" - } - } - } -} -``` - -## Enable WAF for a Component Using Your Own F5 WAF for NGINX Policy - -Instead of using NGINX Controller's default policy for WAF, you can [bring your own NGINX App Protect Policy]({{< ref "/controller/app-delivery/security/concepts/bring-your-own-policy.md" >}}) for use in a Security Strategy to protect your app components. - -To do so, you first need to upload your F5 WAF for NGINX declarative JSON policy to the Security Policy endpoint and reference it in a Security Strategy. Then, you can reference the Security Strategy in the Component where you are enabling WAF. - -### Upload your F5 WAF for NGINX Policy - -To upload your NGINX App Protect declarative JSON Policy to NGINX Controller, use an HTTP client like cURL and send a `PUT` request to the [Security Policy REST API}(https://docs.nginx.com/nginx-controller/api/ctlr-adc-api/) -The JSON object should be similar to the example below: - -```json -{ - "metadata": { - "name": "yourPolicyName", - "displayName": "App Protect Policy", - "description": "my special NAP policy", - "tags": ["test1", "test2"] - }, - "desiredState": { - "content": {"policy": {"name": "/Common/yourPolicyName", "template": {"name": "POLICY_TEMPLATE_NGINX_BASE"}, "applicationLanguage": "utf-8", "enforcementMode": "blocking", "signatures": [{"signatureId": 123458888, "enabled": false}, {"signatureId": 200000098, "enabled": false}, {"signatureId": 200001475, "enabled": false}, {"signatureId": 200002595, "enabled": false}], "bot-defense": {"settings": {"isEnabled": false}}, "headers": [{"name": "*", "type": "wildcard", "decodeValueAsBase64": "disabled"}, {"name": "*-bin", "type": "wildcard", "decodeValueAsBase64": "required"}, {"name": "Referer", "type": "explicit", "decodeValueAsBase64": "disabled"}, {"name": "Authorization", "type": "explicit", "decodeValueAsBase64": "disabled"}, {"name": "Transfer-Encoding", "type": "explicit", "decodeValueAsBase64": "disabled"}], "cookies": [{"name": "*", "type": "wildcard", "decodeValueAsBase64": "disabled"}], "parameters": [{"name": "*", "type": "wildcard", "decodeValueAsBase64": "disabled"}]}} - } -} -``` - -### Create or Update a Security Strategy with a BYO F5 WAF for NGINX Policy - -You can create or update a Security Strategy that references a BYO F5 WAF for NGINX policy by sending a `PUT` request to the [Strategies REST API](https://docs.nginx.com/nginx-controller/api/ctlr-adc-api/) endpoint. - -The JSON object should be similar to the example below: - -```json - -{ - "metadata": { - "name": "yourSecStrategyName", - "displayName": "Security Strategy", - "description": "my special security strategy", - "tags": [ - "tag1", - "tag2" - ] - }, - "desiredState": { - "content": { - "securityPolicyRef": "/security/policies/yourPolicyName" - } - } -} - -``` - -### Add a BYO F5 WAF for NGINX policy to an App Component - -To add your BYO NGINX App Protect Policy to your App(s), you need to add a reference to the Security Strategy that contains the policy to your App Component. - -To do so, send a `PUT` request to the [Components REST API](https://docs.nginx.com/nginx-controller/api/ctlr-adc-api/#tag/Components) endpoint. - -The JSON object should be similar to the example below: - -```json - - "security": { - "strategyRef": { - "ref": "/security/strategies/" - }, - "waf": { - "isEnabled": true, - } - } - -``` - -{{< call-out "note" >}} - -The following WAF security parameters are not supported in App Components that reference a custom Security Strategy: - -- `isMonitorOnly` -- `signatureOverrides` - -These preceding parameters are supported by NGINX Controller's default policy for WAF. - -{{< /call-out >}} - -  - -## Verify that WAF is Enabled - -Complete the tasks in this section to verify that the Web Application Firewall is active and processing traffic. - -To verify that WAF has been enabled by NGINX Controller App Security to protect your app component, send an HTTP GET request to the app component. - -**Example using NGINX Controller's default policy**: GET: `https://[gateway FQDN]/?a=