/nginx-plus-ingress
+```
---
@@ -160,6 +161,8 @@ Key targets include:
| _ubi-image-nap-dos-plus_ | Builds a UBI-based image with NGINX Plus, [NGINX App Protect WAF](/nginx-app-protect/) and the [NGINX App Protect DoS](/nginx-app-protect-dos/) module for [OpenShift](https://www.openshift.com/) clusters.
**Important**: Save your RHEL organization and activation keys in a file named _rhel_license_ at the project root.
For instance:
RHEL_ORGANIZATION=1111111
RHEL_ACTIVATION_KEY=your-key
|
{{}}
+---
+
### Additional useful targets {#other-makefile-targets}
A few other useful targets:
diff --git a/site/content/installation/installing-nic/create-license-secret.md b/site/content/installation/create-license-secret.md
similarity index 92%
rename from site/content/installation/installing-nic/create-license-secret.md
rename to site/content/installation/create-license-secret.md
index 2a71f2218..e4a4124cf 100644
--- a/site/content/installation/installing-nic/create-license-secret.md
+++ b/site/content/installation/create-license-secret.md
@@ -1,11 +1,13 @@
---
-title: Create a License Secret
+title: Create a license Secret
toc: true
-weight: 100
+weight: 300
+type: how-to
+product: NIC
docs: DOCS-000
---
-This document explains how to create and use a license secret for NGINX Ingress Controller.
+This document explains how to create and use a license secret for F5 NGINX Ingress Controller.
# Overview
@@ -17,9 +19,17 @@ The JWT is required for validating your subscription and reporting telemetry dat
{{< note >}} Read the [subscription licenses topic](https://docs.nginx.com/solutions/about-subscription-licenses/#for-internet-connected-environments) for a list of IPs associated with F5's licensing endpoint (`product.connect.nginx.com`). {{ note >}}
-## Set up the JWT
+---
+
+## Set up your NGINX Plus license
-{{< include "installation/download-jwt.md" >}}
+### Download the JWT
+
+{{< include "/installation/download-jwt.md" >}}
+
+---
+
+### Create the Secret
The JWT needs to be configured before deploying NGINX Ingress Controller. The JWT will be stored in a Kubernetes Secret of type `nginx.com/license`, and can be created with the following command.
@@ -34,6 +44,8 @@ The Secret needs to be in the same Namespace as the NGINX Ingress Controller Pod
{{< include "installation/jwt-password-note.md" >}}
+---
+
### Use the NGINX Plus license Secret
If using a name other than the default `license-token`, provide the name of this Secret when installing NGINX Ingress Controller:
@@ -42,7 +54,7 @@ If using a name other than the default `license-token`, provide the name of this
{{%tab name="Helm"%}}
-Specify the Secret name using the `controller.mgmt.licenseTokenSecretName` helm value.
+Specify the Secret name using the `controller.mgmt.licenseTokenSecretName` Helm value.
For detailed guidance on creating the Management block via Helm, refer to the [Helm configuration documentation]({{< relref "installation/installing-nic/installation-with-helm/#configuration" >}}).
@@ -60,12 +72,13 @@ For detailed guidance on creating the Management ConfigMap, refer to the [Manage
**If you are reporting to the default licensing endpoint, then you can now proceed with [installing NGINX Ingress Controller]({{< relref "installation/installing-nic/" >}}). Otherwise, follow the steps below to configure reporting to NGINX Instance Manager.**
+---
-### Reports for NGINX Instance Manager {#nim}
+### Create report for NGINX Instance Manager {#nim}
-If you are deploying NGINX Ingress Controller in an "air-gapped" environment you will need to report to NGINX Instance Manager (NIM) instead of the default licensing endpoint.
+If you are deploying NGINX Ingress Controller in an "air-gapped" environment you will need to report to [NGINX Instance Manager](https://docs.nginx.com/nginx-instance-manager/) instead of the default licensing endpoint.
-First, you must specify the endpoint of your NGINX Instance Manager:
+First, you must specify the endpoint of your NGINX Instance Manager.
{{}}
@@ -83,6 +96,8 @@ Specify the endpoint in the `usage-report-endpoint` Management ConfigMap key.
{{}}
+---
+
#### Configure SSL certificates and SSL trusted certificates {#nim-cert}
To configure SSL certificates or SSL trusted certificates, extra steps are necessary.
@@ -128,6 +143,8 @@ Specify the SSL trusted certificate Secret name in the `ssl-trusted-certificate-
**Once these Secrets are created and configured, you can now [install NGINX Ingress Controller ]({{< relref "installation/installing-nic" >}}).**
+---
+
## What’s reported and how it’s protected {#telemetry}
NGINX Plus reports the following data every hour by default:
diff --git a/site/content/installation/installing-nic/installation-with-helm.md b/site/content/installation/installing-nic/installation-with-helm.md
index b416838fb..4134bc6d8 100644
--- a/site/content/installation/installing-nic/installation-with-helm.md
+++ b/site/content/installation/installing-nic/installation-with-helm.md
@@ -1,8 +1,10 @@
---
-docs: DOCS-602
title: Installation with Helm
toc: true
weight: 100
+type: how-to
+product: NIC
+docs: DOCS-602
---
This document explains how to install F5 NGINX Ingress Controller using [Helm](https://helm.sh/).
@@ -14,7 +16,7 @@ This document explains how to install F5 NGINX Ingress Controller using [Helm](h
- A [Kubernetes Version Supported by NGINX Ingress Controller](https://docs.nginx.com/nginx-ingress-controller/technical-specifications/#supported-kubernetes-versions)
- Helm 3.0+.
- If you’d like to use NGINX Plus:
- - Get the NGINX Ingress Controller JWT and [create a license secret]({{< relref "installation/installing-nic/create-license-secret/" >}}).
+ - Get the NGINX Ingress Controller JWT and [create a license secret]({{< relref "/installation/create-license-secret.md" >}}).
- Download the image using your NGINX Ingress Controller subscription certificate and key. View the [Get NGINX Ingress Controller from the F5 Registry]({{< relref "installation/nic-images/get-registry-image.md" >}}) topic.
- The [Get the NGINX Ingress Controller image with JWT]({{< relref "installation/nic-images/get-image-using-jwt.md" >}}) topic describes how to use your subscription JWT token to get the image.
- The [Build NGINX Ingress Controller]({{< relref "installation/build-nginx-ingress-controller.md" >}}) topic explains how to push an image to a private Docker registry.
diff --git a/site/content/installation/installing-nic/installation-with-manifests.md b/site/content/installation/installing-nic/installation-with-manifests.md
index 178f46771..0d132489a 100644
--- a/site/content/installation/installing-nic/installation-with-manifests.md
+++ b/site/content/installation/installing-nic/installation-with-manifests.md
@@ -1,17 +1,17 @@
---
-docs: DOCS-603
-doctypes:
-- ''
title: Installation with Manifests
toc: true
weight: 200
+type: how-to
+product: NIC
+docs: DOCS-603
---
This guide explains how to use Manifests to install F5 NGINX Ingress Controller, then create both common and custom resources and set up role-based access control.
## Before you start
-If you are using NGINX Plus, get the NGINX Ingress Controller JWT and [create a license secret]({{< relref "installation/installing-nic/create-license-secret/" >}}).
+If you are using NGINX Plus, get the NGINX Ingress Controller JWT and [create a license secret]({{< relref "/installation/create-license-secret.md" >}}).
### Get the NGINX Controller Image
diff --git a/site/content/installation/installing-nic/installation-with-operator.md b/site/content/installation/installing-nic/installation-with-operator.md
index 3896ad21e..830f61e81 100644
--- a/site/content/installation/installing-nic/installation-with-operator.md
+++ b/site/content/installation/installing-nic/installation-with-operator.md
@@ -1,17 +1,17 @@
---
-docs: DOCS-604
-doctypes:
-- ''
title: Installation with NGINX Ingress Operator
toc: true
weight: 300
+type: how-to
+product: NIC
+docs: DOCS-604
---
-This document explains how to use NGINX Ingress Operator to install NGINX Ingress Controller.
+This document explains how to install F5 NGINX Ingress Controller using NGINX Ingress Operator.
## Before you start
-If you're using NGINX Plus, get the NGINX Ingress Controller JWT and [create a license secret]({{< relref "installation/installing-nic/create-license-secret/" >}}).
+If you're using NGINX Plus, get the NGINX Ingress Controller JWT and [create a license secret]({{< relref "/installation/create-license-secret.md" >}}).
{{< note >}} We recommend the most recent stable version of NGINX Ingress Controller, available on the GitHub repository's [releases page]({{< relref "releases.md" >}}). {{< /note >}}
diff --git a/site/content/installation/installing-nic/upgrade-to-v4.md b/site/content/installation/installing-nic/upgrade-to-v4.md
new file mode 100644
index 000000000..7880c17a9
--- /dev/null
+++ b/site/content/installation/installing-nic/upgrade-to-v4.md
@@ -0,0 +1,119 @@
+---
+title: Upgrade to NGINX Ingress Controller 4.0.0
+toc: true
+weight: 400
+type: how-to
+product: NIC
+docs: DOCS-000
+---
+
+This document explains how to upgrade F5 NGINX Ingress Controller to 4.0.0.
+
+There are two necessary steps required: updating the `apiVersion` value of custom resources and configuring structured logging.
+
+For NGINX Plus users, there is a third step to create a Secret for your license.
+
+---
+
+## Update custom resource apiVersion
+
+If the Helm chart you have been using is `v2.x`, before upgrading to NGINX Ingress Controller 4.0.0 you must update your GlobalConfiguration, Policy and TransportServer resources from `apiVersion: k8s.nginx.org/v1alpha1` to `apiVersion: k8s.nginx.org/v1`.
+
+If the Helm chart you have been using is `v1.0.2` or earlier (NGINX Ingress Controller `v3.2.2`), upgrade to Helm chart `v1.4.2` (NGINX Ingress Controller `v3.7.2`) before updating your GlobalConfiguration, Policy and TransportServer resources.
+
+The example below shows the change for a Policy resource: you must do the same for all GlobalConfiguration and TransportServer resources.
+
+{{}}
+
+{{% comment %}} Keep this left aligned. {{% /comment %}}
+{{%tab name="Before"%}}
+
+```yaml
+apiVersion: k8s.nginx.org/v1alpha1
+kind: Policy
+metadata:
+ name: rate-limit-policy
+spec:
+ rateLimit:
+ rate: 1r/s
+ key: ${binary_remote_addr}
+ zoneSize: 10M
+```
+{{% /tab %}}
+
+{{%tab name="After"%}}
+```yaml
+apiVersion: k8s.nginx.org/v1
+kind: Policy
+metadata:
+ name: rate-limit-policy
+spec:
+ rateLimit:
+ rate: 1r/s
+ key: ${binary_remote_addr}
+ zoneSize: 10M
+```
+{{% /tab %}}
+
+{{}}
+
+{{< warning >}}
+If a *GlobalConfiguration*, *Policy* or *TransportServer* resource is deployed with `apiVersion: k8s.nginx.org/v1alpha1`, it will be **deleted** during the upgrade process.
+{{ warning >}}
+
+---
+
+## Configure structured logging
+
+To configure structured logging, you must update your log deployment arguments from an integer to a string. The logs themselves can also be rendered in different formats.
+
+{{< note >}} These options apply to NGINX Ingress Controller logs, and do not affect NGINX logs. {{< /note >}}
+
+| **Level arguments** | **Format arguments** |
+|---------------------|----------------------|
+| `trace` | `json` |
+| `debug` | `text` |
+| `info` | `glog` |
+| `warning` | |
+| `error` | |
+| `fatal` | |
+
+{{}}
+
+{{%tab name="Helm"%}}
+
+The Helm value of `controller.logLevel` has been changed from an integer to a string.
+
+To change the rendering of the log format, use the `controller.logFormat` key.
+
+```yaml
+controller:
+ logLevel: info
+ logFormat: json
+```
+{{% /tab %}}
+
+{{%tab name="Manifests"%}}
+
+The command line argument `-v` has been replaced with `-log-level`, and takes a string instead of an integer. The argument `-logtostderr` has also been deprecated.
+
+To change the rendering of the log format, use the `-log-format` argument.
+
+```yaml
+args:
+ - -log-level=info
+ - -log-format=json
+```
+{{% /tab %}}
+
+{{}}
+
+---
+
+## Create License secret
+
+If you're using [NGINX Plus]({{< ref "/overview/nginx-plus.md" >}}) with NGINX Ingress Controller, you should read the [Create License Secret]({{< ref "/installation/create-license-secret.md" >}}) topic to set up your NGINX Plus license.
+
+The topic also contains guidance for [sending reports to NGINX Instance Manager]({{< ref "/installation/create-license-secret.md#nim">}}), which is necessary for air-gapped environments.
+
+In prior versions, usage reporting with the cluster connector was required: it is no longer necessary, as it is built into NGINX Plus.
diff --git a/site/content/installation/nic-images/_index.md b/site/content/installation/nic-images/_index.md
index 41ac35081..bcf9d1557 100644
--- a/site/content/installation/nic-images/_index.md
+++ b/site/content/installation/nic-images/_index.md
@@ -1,5 +1,4 @@
---
title: NGINX Ingress Controller images
-description:
-weight: 300
+weight: 200
---
diff --git a/site/content/usage-reporting.md b/site/content/usage-reporting.md
index a5594f27d..469e12deb 100644
--- a/site/content/usage-reporting.md
+++ b/site/content/usage-reporting.md
@@ -1,14 +1,19 @@
---
-docs: DOCS-1445
-doctypes:
-- concept
title: Enable Usage Reporting
toc: true
weight: 1800
+noindex: true
+headless: true
+type: how-to
+product: NIC
+docs: DOCS-1445
---
{{< important >}}
-This page is only applicable to NGINX Ingress Controller versions 3.2.0 - 3.7.2
+This page is only applicable to NGINX Ingress Controller versions 3.2.0 - 3.7.2.
+
+For more recent versions of NGINX Ingress Controller, view the [Upgrade to NGINX Ingress Controller 4.0.0]({{< ref "/installation/install-nic/upgrade-to-v4.md" >}}) topic.
+
{{< /important >}}
This page describes how to enable Usage Reporting for F5 NGINX Ingress Controller and how to view usage data through the API.