feat: Clarify NGINX Ingress Controller install & upgrade documentation (#816)

This commit makes a number of changes to clarify what the precise steps
are to install, upgrade and uninstall NGINX Ingress Controller

- The Install document clarifies necessary steps
- Uninstall steps have been moved to the bottom of the document
- Upgrade instructions have been moved into their own document

The changes made focused on clarifying the critical path for one single
user story, as lots of unnecessary contextual information was being
provided, which was causing confusion.

With this commit, the general reading and execution flow for these
deployment steps become more coherent. Similar changes may be made for
Manifests documentation, if common steps are identified.

As part of the work, a number of include files have been updated or created 
that are shared with NGINX Plus, to ensure the documentation around 
obtaining an NGINX Ingress Controller image with Docker are consistent.

Subsequently, process documentation for managing includes was split from 
the style guide and made into its own file due to the anticipated length 
as reference information.

---------

Co-authored-by: Travis Martin <[email protected]>

Author: ADubhlaoich

content/includes/licensing-and-reporting/download-certificates-from-myf5.md

@@ -0,0 +1,9 @@
+---
+files:
+- content/includes/use-cases/credential-download-instructions.md
+---
+
+1. Log in to [MyF5](https://my.f5.com/manage/s/).
+1. Go to **My Products & Plans > Subscriptions** to see your active subscriptions.
+1. Find your NGINX subscription, and select the **Subscription ID** for details.
+1. Download the **SSL Certificate** and **Private Key** files from the subscription page.

content/includes/licensing-and-reporting/download-jwt-from-myf5.md

@@ -1,8 +1,19 @@
 ---
 docs:
+files:
+- content/includes/nim/docker/docker-registry-login.md
+- content/includes/use-cases/credential-download-instructions.md
+- content/nap-waf/v5/admin-guide/install.md
+- content/nginx/admin-guide/installing-nginx/installing-nginx-plus.md
+- content/nginx-one/connect-instances/connect-nginx-plus-container-images-to-nginx-one.md
+- content/nim/admin-guide/add-license.md
+- content/nim/deploy/docker/deploy-nginx-plus-and-agent-docker.md
+- content/nim/disconnected/add-license-disconnected-deployment.md
+- content/solutions/about-subscription-licenses.md
+- content/solutions/r33-pre-release-guidance-for-automatic-upgrades.md
 ---
 
 1. Log in to [MyF5](https://my.f5.com/manage/s/).
-2. Go to **My Products & Plans > Subscriptions** to see your active subscriptions.
-3. Find your NGINX products or services subscription, and select the **Subscription ID** for details.
-4. Download the **JSON Web Token** from the subscription page.
+1. Go to **My Products & Plans > Subscriptions** to see your active subscriptions.
+1. Find your NGINX subscription, and select the **Subscription ID** for details.
+1. Download the **JSON Web Token** file from the subscription page.

content/includes/use-cases/credential-download-instructions.md

@@ -0,0 +1,25 @@
+---
+files:
+- content/nginx/admin-guide/installing-nginx/installing-nginx-docker.md
+- content/nic/installation/nic-images/registry-download.md
+---
+
+In order to obtain a container image, you will need the JSON Web Token file or SSL certificate and private key files provided with your NGINX Plus subscription. 
+
+These files grant access to the package repository from which the script will download the NGINX Plus package:
+
+{{< tabs name="product_keys" >}}
+
+{{% tab name="JSON Web Token" %}}
+
+{{< include "licensing-and-reporting/download-jwt-from-myf5.md" >}}
+
+{{% /tab %}}
+
+{{% tab name="SSL" %}}
+
+{{< include "licensing-and-reporting/download-certificates-from-myf5.md" >}}
+
+{{% /tab %}}
+
+{{< /tabs >}}

content/includes/use-cases/docker-registry-instructions.md

@@ -0,0 +1,49 @@
+---
+files:
+- content/nginx/admin-guide/installing-nginx/installing-nginx-docker.md
+- content/nic/installation/nic-images/registry-download.md
+---
+
+This step describes how to use Docker to communicate with the F5 Container Registry located at `private-registry.nginx.com`.
+
+{{< call-out "note" >}}
+
+The steps provided are for Linux. For Mac or Windows, see the [Docker for Mac](https://docs.docker.com/docker-for-mac/#add-client-certificates) or [Docker for Windows](https://docs.docker.com/docker-for-windows/#how-do-i-add-client-certificates) documentation. 
+
+For more details on Docker Engine security, you can refer to the [Docker Engine Security documentation](https://docs.docker.com/engine/security/).
+
+{{< /call-out >}}
+
+{{< tabs name="docker_login" >}}
+
+{{% tab name="JSON Web Token"%}}
+
+Open the JSON Web Token file previously downloaded from [MyF5](https://my.f5.com) customer portal (for example, `nginx-repo-12345abc.jwt`) and copy its contents.
+
+Log in to the Docker registry using the contents of the JSON Web Token file:
+
+```shell
+docker login private-registry.nginx.com --username=<output_of_jwt_token> --password=none
+```
+
+{{% /tab %}}
+
+{{% tab name="SSL" %}}
+
+Create a directory and copy your certificate and key to this directory:
+
+```shell
+mkdir -p /etc/docker/certs.d/private-registry.nginx.com
+cp <path-to-your-nginx-repo.crt> /etc/docker/certs.d/private-registry.nginx.com/client.cert
+cp <path-to-your-nginx-repo.key> /etc/docker/certs.d/private-registry.nginx.com/client.key
+```
+
+Log in to the Docker registry:
+
+```shell
+docker login private-registry.nginx.com
+```
+
+{{% /tab %}}
+
+{{< /tabs >}}

content/nginx/admin-guide/installing-nginx/installing-nginx-docker.md

@@ -88,61 +88,13 @@ where:
 
 - the `jq` command is used to format the JSON output for easier reading and requires the [jq](https://jqlang.github.io/jq/) JSON processor to be installed.
 
+### Download your subscription credential files
 
+{{< include "use-cases/credential-download-instructions.md" >}}
 
-### Download the JSON Web Token or NGINX Plus certificate and key {#myf5-download}
+### Set up Docker for the F5 Container Registry
 
-Before you get a container image, you should provide the JSON Web Token file or SSL certificate and private key files provided with your NGINX Plus subscription. These files grant access to the package repository from which the script will download the NGINX Plus package:
-
-{{<tabs name="product_keys">}}
-
-{{%tab name="JSON Web Token"%}}
-{{< include "licensing-and-reporting/download-jwt-from-myf5.md" >}}
-{{% /tab %}}
-
-{{%tab name="SSL"%}}
-1. Log in to the [MyF5](https://my.f5.com) customer portal.
-2. Go to **My Products and Plans** > **Subscriptions**.
-3. Select the product subscription.
-4. Download the **SSL Certificate** and **Private Key** files.
-{{% /tab %}}
-
-{{% /tabs %}}
-
-### Set up Docker for NGINX Plus container registry
-
-Set up Docker to communicate with the NGINX Container Registry located at `private-registry.nginx.com`.
-
-{{<tabs name="docker_login">}}
-
-{{%tab name="JSON Web Token"%}}
-Open the JSON Web Token file previously downloaded from [MyF5](https://my.f5.com) customer portal (for example, `nginx-repo-12345abc.jwt`) and copy its contents.
-
-Log in to the docker registry using the contents of the JSON Web Token file:
-
-```shell
-docker login private-registry.nginx.com --username=<output_of_jwt_token> --password=none
-```
-{{% /tab %}}
-
-{{%tab name="SSL"%}}
-Create a directory and copy your certificate and key to this directory:
-
-```shell
-mkdir -p /etc/docker/certs.d/private-registry.nginx.com
-cp <path-to-your-nginx-repo.crt> /etc/docker/certs.d/private-registry.nginx.com/client.cert
-cp <path-to-your-nginx-repo.key> /etc/docker/certs.d/private-registry.nginx.com/client.key
-```
-The steps provided are for Linux. For Mac or Windows, see the [Docker for Mac](https://docs.docker.com/docker-for-mac/#add-client-certificates) or [Docker for Windows](https://docs.docker.com/docker-for-windows/#how-do-i-add-client-certificates) documentation. For more details on Docker Engine security, you can refer to the [Docker Engine Security documentation](https://docs.docker.com/engine/security/).
-
-Log in to the docker registry:
-
-```shell
-docker login private-registry.nginx.com
-```
-{{% /tab %}}
-
-{{% /tabs %}}
+{{< include "use-cases/docker-registry-instructions.md" >}}
 
 ### Pull the image
 
@@ -192,7 +144,6 @@ For NGINX modules, run:<!-- Is this enough info?-->
 docker pull private-registry.nginx.com/nginx-plus/modules:<version-tag>
 ```
 
-
 {{< include "security/jwt-password-note.md" >}}
 
 ### Push the image to your private registry

content/nic/installation/build-nginx-ingress-controller.md

@@ -199,5 +199,5 @@ If you prefer not to build your own NGINX Ingress Controller image, you can use
 
 **NGINX Plus Ingress Controller**: You have two options for this:
 
-- Download the image using your NGINX Ingress Controller subscription certificate and key. View the [Get NGINX Ingress Controller from the F5 Registry]({{< ref "/nic/installation/nic-images/get-registry-image" >}}) topic.
-- Use your NGINX Ingress Controller subscription JWT token to get the image. View the [Get the NGINX Ingress Controller image with JWT]({{< ref "/nic/installation/nic-images/get-image-using-jwt.md" >}}) topic.
+- Download the image using your NGINX Ingress Controller subscription certificate and key. View the [Download NGINX Ingress Controller from the F5 Registry]({{< ref "/nic/installation/nic-images/registry-download.md" >}}) topic.
+- Use your NGINX Ingress Controller subscription JWT token to get the image. View the [Add an NGINX Ingress Controller image to your cluster]({{< ref "/nic/installation/nic-images/add-image-to-cluster.md" >}}) topic.

content/nic/installation/create-license-secret.md

@@ -27,20 +27,21 @@ The JWT is required for validating your subscription and reporting telemetry dat
 
 ### 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.
+The JWT needs to be configured before deploying NGINX Ingress Controller. 
+
+It must be stored in a Kubernetes Secret of type `nginx.com/license` in the same namespace as your NGINX Ingress Controller pod(s).
+
+Create the Secret with the following command:
 
 ```shell
-kubectl create secret generic license-token --from-file=license.jwt=<path-to-your-jwt> --type=nginx.com/license -n <Your Namespace>
+kubectl create secret generic license-token --from-file=license.jwt=<path-to-your-jwt> --type=nginx.com/license -n <your-namespace>
 ```
-You can now delete the downloaded `.jwt` file.
 
-{{< note >}}
-The Secret needs to be in the same Namespace as the NGINX Ingress Controller Pod(s).
-{{</ note >}}
+Once created, you can download the `.jwt` file.
 
 {{< include "/nic/installation/jwt-password-note.md" >}}
 
-### Use the NGINX Plus license Secret
+### Add the license Secret to your deployment
 
 If using a name other than the default `license-token`, provide the name of this Secret when installing NGINX Ingress Controller:
 
@@ -50,7 +51,7 @@ If using a name other than the default `license-token`, provide the name of this
 
 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]({{< ref "/nic/installation/installing-nic/installation-with-helm/#configuration" >}}).
+For detailed guidance on creating the Management block with Helm, refer to the [Helm configuration documentation]({{< ref "/nic/installation/installing-nic/installation-with-helm/#configuration" >}}).
 
 {{% /tab %}}
 
@@ -129,11 +130,8 @@ Specify the SSL trusted certificate Secret name in the `ssl-trusted-certificate-
 
 {{</tabs>}}
 
-<br>
-
 Once these Secrets are created and configured, you can now [install NGINX Ingress Controller ]({{< ref "/nic/installation/installing-nic/" >}}).
 
-
 ## What’s reported and how it’s protected {#telemetry}
 
 NGINX Plus reports the following data every hour by default:

content/nic/installation/ingress-nginx.md

@@ -1,12 +1,10 @@
 ---
-nd-docs: DOCS-1469
-doctypes:
-- tutorial
-tags:
-- docs
 title: Migrate from Ingress-NGINX Controller to NGINX Ingress Controller
 toc: true
-weight: 500
+weight: 700
+nd-content-type: how-to
+nd-product: NIC
+nd-docs: DOCS-1469
 ---
 
 This document describes how to migrate from the community-maintained Ingress-NGINX Controller to F5 NGINX Ingress Controller.