Add upgrading to 4.x docs (#6930)

* add upgrading to 4.x page

* Update upgrading docs

* Delete upgrading-to-4.x.x.md

* Apply suggestions from code review

Co-authored-by: Alan Dooley <[email protected]>
Signed-off-by: Jim Ryan <[email protected]>

* Apply suggestions from code review

Co-authored-by: Venktesh Shivam Patel <[email protected]>
Signed-off-by: Jim Ryan <[email protected]>

* feat: Update IA, metadata and content related to v4 upgrades

This commit updates the information architecture and metadata
for documentation related to NGINX Ingress Controller 4.0.0.

It clarifies the relationship between certain documents, moves or hides
pages and delineates sections of the upgrade documentation while
making the text instruction more concise and precise.

---------

Signed-off-by: Jim Ryan <[email protected]>
Co-authored-by: Jakub Jarosz <[email protected]>
Co-authored-by: Alan Dooley <[email protected]>
Co-authored-by: Venktesh Shivam Patel <[email protected]>

Author: 4 people

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.
 
 {{<call-out "tip" "Pre-built image alternatives" >}} 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. {{</call-out>}}
 
-## 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 `<my-docker-registry>` with your private registry's path.
+Build the image. Replace `<my-docker-registry>` with your private registry's path.
 
-    - For a Debian-based image:
+- For a Debian-based image:
 
-        ```shell
-        make debian-image PREFIX=<my-docker-registry>/nginx-ingress TARGET=download
-        ```
+    ```shell
+    make debian-image PREFIX=<my-docker-registry>/nginx-ingress TARGET=download
+    ```
 
-    - For an Alpine-based image:
+- For an Alpine-based image:
 
-        ```shell
-        make alpine-image PREFIX=<my-docker-registry>/nginx-ingress TARGET=download
-        ```
+    ```shell
+    make alpine-image PREFIX=<my-docker-registry>/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 `<my-docker-registry>` with your private registry's path.
+Build the image. Replace `<my-docker-registry>` with your private registry's path.
 
-    ```shell
-    make debian-image-plus PREFIX=<my-docker-registry>/nginx-plus-ingress TARGET=download
-    ```
+```shell
+make debian-image-plus PREFIX=<my-docker-registry>/nginx-plus-ingress TARGET=download
+```
 
-    <br>
+<br>
 
-     **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.
 
 {{<note>}} 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. {{</note>}}
 
@@ -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 `<my-docker-registry>` 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 `<my-docker-registry>` with your private registry's path.
 
-    ```shell
-    make push PREFIX=<my-docker-registry>/nginx-ingress
-    ```
+```shell
+make push PREFIX=<my-docker-registry>/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 `<my-docker-registry>` 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 `<my-docker-registry>` with your private registry's path.
 
-    ```shell
-    make push PREFIX=<my-docker-registry>/nginx-plus-ingress
-    ```
+```shell
+make push PREFIX=<my-docker-registry>/nginx-plus-ingress
+```
 
 ---
 
@@ -160,6 +161,8 @@ Key targets include:
 | _ubi-image-nap-dos-plus_      | <p>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.</p> <p> **Important**: Save your RHEL organization and activation keys in a file named _rhel_license_ at the project root.</p> <p> For instance:</p> <pre>RHEL_ORGANIZATION=1111111<br />RHEL_ACTIVATION_KEY=your-key</pre>|
 {{</bootstrap-table>}}
 
+---
+
 ### Additional useful targets {#other-makefile-targets}
 
 A few other useful targets:

site/content/installation/installing-nic/create-license-secret.md renamed to 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.
 
 {{<tabs name="nim-endpoint">}}
 
@@ -83,6 +96,8 @@ Specify the endpoint in the `usage-report-endpoint` Management ConfigMap key.
 
 {{</tabs>}}
 
+---
+
 #### 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:

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.

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
 

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