diff --git a/site/content/installation/build-nginx-ingress-controller.md b/site/content/installation/build-nginx-ingress-controller.md index 7ede18229..15ff02cb3 100644 --- a/site/content/installation/build-nginx-ingress-controller.md +++ b/site/content/installation/build-nginx-ingress-controller.md @@ -1,11 +1,10 @@ --- -description: -docs: DOCS-1453 -doctypes: -- installation title: Build NGINX Ingress Controller toc: true -weight: 200 +weight: 400 +type: how-to +product: NIC +docs: DOCS-1453 --- This document describes how to build an F5 NGINX Ingress Controller image from source code and upload it to a private Docker registry. @@ -14,7 +13,7 @@ It also includes information on the Makefile targets and variables. {{}} If you do not need to build a custom image, see the [pre-built image options](#pre-built-images) at the end of this guide. {{}} -## Before you start +## Before you begin To get started, you need the following software installed on your machine: @@ -24,7 +23,9 @@ To get started, you need the following software installed on your machine: - [OpenSSL](https://www.openssl.org/), optionally, if you would like to generate a self-signed certificate and a key for the default server. - For NGINX Plus users, download the certificate (_nginx-repo.crt_) and key (_nginx-repo.key_) from [MyF5](https://my.f5.com). -Although NGINX Ingress Controller is written in Golang, you don't need to have Golang installed. You can download the precompiled binary file or build NGINX Ingress Controller in a Docker container. +Although NGINX Ingress Controller is written in Golang, you don't need to have Golang installed. + +You can download the precompiled binary file or build NGINX Ingress Controller in a Docker container. --- @@ -62,45 +63,45 @@ After setting up your environment, follow these steps to build the NGINX Ingress ### For NGINX -1. Build the image. Replace `` with your private registry's path. +Build the image. Replace `` with your private registry's path. - - For a Debian-based image: +- For a Debian-based image: - ```shell - make debian-image PREFIX=/nginx-ingress TARGET=download - ``` + ```shell + make debian-image PREFIX=/nginx-ingress TARGET=download + ``` - - For an Alpine-based image: +- For an Alpine-based image: - ```shell - make alpine-image PREFIX=/nginx-ingress TARGET=download - ``` + ```shell + make alpine-image PREFIX=/nginx-ingress TARGET=download + ``` - **What to expect**: The image is built and tagged with a version number, which is derived from the `VERSION` variable in the [_Makefile_](#makefile-details). This version number is used for tracking and deployment purposes. +**What to expect**: The image is built and tagged with a version number, which is derived from the `VERSION` variable in the [_Makefile_](#makefile-details). This version number is used for tracking and deployment purposes. ### For NGINX Plus -1. Place your NGINX Plus license files (_nginx-repo.crt_ and _nginx-repo.key_) in the project's root folder. To verify they're in place, run: +Place your NGINX Plus license files (_nginx-repo.crt_ and _nginx-repo.key_) in the project's root folder. To verify they're in place, run: - ```shell - ls nginx-repo.* - ``` +```shell +ls nginx-repo.* +``` - You should see: +You should see: - ```shell - nginx-repo.crt nginx-repo.key - ``` +```text +nginx-repo.crt nginx-repo.key +``` -2. Build the image. Replace `` with your private registry's path. +Build the image. Replace `` with your private registry's path. - ```shell - make debian-image-plus PREFIX=/nginx-plus-ingress TARGET=download - ``` +```shell +make debian-image-plus PREFIX=/nginx-plus-ingress TARGET=download +``` -
+
- **What to expect**: The image is built and tagged with a version number, which is derived from the `VERSION` variable in the [_Makefile_](#makefile-details). This version number is used for tracking and deployment purposes. +**What to expect**: The image is built and tagged with a version number, which is derived from the `VERSION` variable in the [_Makefile_](#makefile-details). This version number is used for tracking and deployment purposes. {{}} If a patch for NGINX Plus is released, make sure to rebuild your image to get the latest version. If your system is caching the Docker layers and not updating the packages, add `DOCKER_BUILD_OPTIONS="--pull --no-cache"` to the make command. {{}} @@ -112,19 +113,19 @@ Once you've successfully built the NGINX or NGINX Plus Ingress Controller image, ### For NGINX -1. Upload the NGINX image. If you're using a custom tag, append `TAG=your-tag` to the command. Replace `` with your private registry's path. +Upload the NGINX image. If you're using a custom tag, append `TAG=your-tag` to the command. Replace `` with your private registry's path. - ```shell - make push PREFIX=/nginx-ingress - ``` +```shell +make push PREFIX=/nginx-ingress +``` ### For NGINX Plus -1. Upload the NGINX Plus image. Like with the NGINX image, if you're using a custom tag, add `TAG=your-tag` to the end of the command. Replace `` with your private registry's path. +Upload the NGINX Plus image. Like with the NGINX image, if you're using a custom tag, add `TAG=your-tag` to the end of the command. Replace `` with your private registry's path. - ```shell - make push PREFIX=/nginx-plus-ingress - ``` +```shell +make push PREFIX=/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`). {{}} -## 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. +{{}} + +--- + +## 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.