Skip to content

Commit 87b16a3

Browse files
ADubhlaoichtravisamartin
ADubhlaoich
and
travisamartin
authored
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]>
1 parent 30dd70e commit 87b16a3

26 files changed

+843
-793
lines changed

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

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
files:
3+
- content/includes/use-cases/credential-download-instructions.md
4+
---
5+
6+
1. Log in to [MyF5](https://my.f5.com/manage/s/).
7+
1. Go to **My Products & Plans > Subscriptions** to see your active subscriptions.
8+
1. Find your NGINX subscription, and select the **Subscription ID** for details.
9+
1. Download the **SSL Certificate** and **Private Key** files from the subscription page.

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

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,19 @@
11
---
22
docs:
3+
files:
4+
- content/includes/nim/docker/docker-registry-login.md
5+
- content/includes/use-cases/credential-download-instructions.md
6+
- content/nap-waf/v5/admin-guide/install.md
7+
- content/nginx/admin-guide/installing-nginx/installing-nginx-plus.md
8+
- content/nginx-one/connect-instances/connect-nginx-plus-container-images-to-nginx-one.md
9+
- content/nim/admin-guide/add-license.md
10+
- content/nim/deploy/docker/deploy-nginx-plus-and-agent-docker.md
11+
- content/nim/disconnected/add-license-disconnected-deployment.md
12+
- content/solutions/about-subscription-licenses.md
13+
- content/solutions/r33-pre-release-guidance-for-automatic-upgrades.md
314
---
415

516
1. Log in to [MyF5](https://my.f5.com/manage/s/).
6-
2. Go to **My Products & Plans > Subscriptions** to see your active subscriptions.
7-
3. Find your NGINX products or services subscription, and select the **Subscription ID** for details.
8-
4. Download the **JSON Web Token** from the subscription page.
17+
1. Go to **My Products & Plans > Subscriptions** to see your active subscriptions.
18+
1. Find your NGINX subscription, and select the **Subscription ID** for details.
19+
1. Download the **JSON Web Token** file from the subscription page.

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

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
files:
3+
- content/nginx/admin-guide/installing-nginx/installing-nginx-docker.md
4+
- content/nic/installation/nic-images/registry-download.md
5+
---
6+
7+
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.
8+
9+
These files grant access to the package repository from which the script will download the NGINX Plus package:
10+
11+
{{< tabs name="product_keys" >}}
12+
13+
{{% tab name="JSON Web Token" %}}
14+
15+
{{< include "licensing-and-reporting/download-jwt-from-myf5.md" >}}
16+
17+
{{% /tab %}}
18+
19+
{{% tab name="SSL" %}}
20+
21+
{{< include "licensing-and-reporting/download-certificates-from-myf5.md" >}}
22+
23+
{{% /tab %}}
24+
25+
{{< /tabs >}}

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

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
files:
3+
- content/nginx/admin-guide/installing-nginx/installing-nginx-docker.md
4+
- content/nic/installation/nic-images/registry-download.md
5+
---
6+
7+
This step describes how to use Docker to communicate with the F5 Container Registry located at `private-registry.nginx.com`.
8+
9+
{{< call-out "note" >}}
10+
11+
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.
12+
13+
For more details on Docker Engine security, you can refer to the [Docker Engine Security documentation](https://docs.docker.com/engine/security/).
14+
15+
{{< /call-out >}}
16+
17+
{{< tabs name="docker_login" >}}
18+
19+
{{% tab name="JSON Web Token"%}}
20+
21+
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.
22+
23+
Log in to the Docker registry using the contents of the JSON Web Token file:
24+
25+
```shell
26+
docker login private-registry.nginx.com --username=<output_of_jwt_token> --password=none
27+
```
28+
29+
{{% /tab %}}
30+
31+
{{% tab name="SSL" %}}
32+
33+
Create a directory and copy your certificate and key to this directory:
34+
35+
```shell
36+
mkdir -p /etc/docker/certs.d/private-registry.nginx.com
37+
cp <path-to-your-nginx-repo.crt> /etc/docker/certs.d/private-registry.nginx.com/client.cert
38+
cp <path-to-your-nginx-repo.key> /etc/docker/certs.d/private-registry.nginx.com/client.key
39+
```
40+
41+
Log in to the Docker registry:
42+
43+
```shell
44+
docker login private-registry.nginx.com
45+
```
46+
47+
{{% /tab %}}
48+
49+
{{< /tabs >}}

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

Lines changed: 4 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -88,61 +88,13 @@ where:
8888

8989
- 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.
9090

91+
### Download your subscription credential files
9192

93+
{{< include "use-cases/credential-download-instructions.md" >}}
9294

93-
### Download the JSON Web Token or NGINX Plus certificate and key {#myf5-download}
95+
### Set up Docker for the F5 Container Registry
9496

95-
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:
96-
97-
{{<tabs name="product_keys">}}
98-
99-
{{%tab name="JSON Web Token"%}}
100-
{{< include "licensing-and-reporting/download-jwt-from-myf5.md" >}}
101-
{{% /tab %}}
102-
103-
{{%tab name="SSL"%}}
104-
1. Log in to the [MyF5](https://my.f5.com) customer portal.
105-
2. Go to **My Products and Plans** > **Subscriptions**.
106-
3. Select the product subscription.
107-
4. Download the **SSL Certificate** and **Private Key** files.
108-
{{% /tab %}}
109-
110-
{{% /tabs %}}
111-
112-
### Set up Docker for NGINX Plus container registry
113-
114-
Set up Docker to communicate with the NGINX Container Registry located at `private-registry.nginx.com`.
115-
116-
{{<tabs name="docker_login">}}
117-
118-
{{%tab name="JSON Web Token"%}}
119-
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.
120-
121-
Log in to the docker registry using the contents of the JSON Web Token file:
122-
123-
```shell
124-
docker login private-registry.nginx.com --username=<output_of_jwt_token> --password=none
125-
```
126-
{{% /tab %}}
127-
128-
{{%tab name="SSL"%}}
129-
Create a directory and copy your certificate and key to this directory:
130-
131-
```shell
132-
mkdir -p /etc/docker/certs.d/private-registry.nginx.com
133-
cp <path-to-your-nginx-repo.crt> /etc/docker/certs.d/private-registry.nginx.com/client.cert
134-
cp <path-to-your-nginx-repo.key> /etc/docker/certs.d/private-registry.nginx.com/client.key
135-
```
136-
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/).
137-
138-
Log in to the docker registry:
139-
140-
```shell
141-
docker login private-registry.nginx.com
142-
```
143-
{{% /tab %}}
144-
145-
{{% /tabs %}}
97+
{{< include "use-cases/docker-registry-instructions.md" >}}
14698

14799
### Pull the image
148100

@@ -192,7 +144,6 @@ For NGINX modules, run:<!-- Is this enough info?-->
192144
docker pull private-registry.nginx.com/nginx-plus/modules:<version-tag>
193145
```
194146

195-
196147
{{< include "security/jwt-password-note.md" >}}
197148

198149
### Push the image to your private registry

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -199,5 +199,5 @@ If you prefer not to build your own NGINX Ingress Controller image, you can use
199199
200200
**NGINX Plus Ingress Controller**: You have two options for this:
201201
202-
- 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.
203-
- 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.
202+
- 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.
203+
- 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

Lines changed: 9 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -27,20 +27,21 @@ The JWT is required for validating your subscription and reporting telemetry dat
2727

2828
### Create the Secret
2929

30-
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.
30+
The JWT needs to be configured before deploying NGINX Ingress Controller.
31+
32+
It must be stored in a Kubernetes Secret of type `nginx.com/license` in the same namespace as your NGINX Ingress Controller pod(s).
33+
34+
Create the Secret with the following command:
3135

3236
```shell
33-
kubectl create secret generic license-token --from-file=license.jwt=<path-to-your-jwt> --type=nginx.com/license -n <Your Namespace>
37+
kubectl create secret generic license-token --from-file=license.jwt=<path-to-your-jwt> --type=nginx.com/license -n <your-namespace>
3438
```
35-
You can now delete the downloaded `.jwt` file.
3639

37-
{{< note >}}
38-
The Secret needs to be in the same Namespace as the NGINX Ingress Controller Pod(s).
39-
{{</ note >}}
40+
Once created, you can download the `.jwt` file.
4041

4142
{{< include "/nic/installation/jwt-password-note.md" >}}
4243

43-
### Use the NGINX Plus license Secret
44+
### Add the license Secret to your deployment
4445

4546
If using a name other than the default `license-token`, provide the name of this Secret when installing NGINX Ingress Controller:
4647

@@ -50,7 +51,7 @@ If using a name other than the default `license-token`, provide the name of this
5051

5152
Specify the Secret name using the `controller.mgmt.licenseTokenSecretName` Helm value.
5253

53-
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" >}}).
54+
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" >}}).
5455

5556
{{% /tab %}}
5657

@@ -129,11 +130,8 @@ Specify the SSL trusted certificate Secret name in the `ssl-trusted-certificate-
129130

130131
{{</tabs>}}
131132

132-
<br>
133-
134133
Once these Secrets are created and configured, you can now [install NGINX Ingress Controller ]({{< ref "/nic/installation/installing-nic/" >}}).
135134

136-
137135
## What’s reported and how it’s protected {#telemetry}
138136

139137
NGINX Plus reports the following data every hour by default:

‎content/nic/installation/ingress-nginx.md

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,10 @@
11
---
2-
nd-docs: DOCS-1469
3-
doctypes:
4-
- tutorial
5-
tags:
6-
- docs
72
title: Migrate from Ingress-NGINX Controller to NGINX Ingress Controller
83
toc: true
9-
weight: 500
4+
weight: 700
5+
nd-content-type: how-to
6+
nd-product: NIC
7+
nd-docs: DOCS-1469
108
---
119

1210
This document describes how to migrate from the community-maintained Ingress-NGINX Controller to F5 NGINX Ingress Controller.

0 commit comments

Comments
 (0)