Skip to content

feat: Clarify NIC install & upgrade steps #816

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 12 commits into
base: main
Choose a base branch
from

Conversation

ADubhlaoich
Copy link
Contributor

Proposed changes

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.

Checklist

Before merging a pull request, run through this checklist and mark each as complete.

  • I have read the contributing guidelines
  • I have signed the F5 Contributor License Agreement (CLA)
  • I have rebased my branch onto main
  • I have ensured my PR is targeting the main branch and pulling from my branch from my own fork
  • I have ensured that the commit messages adhere to Conventional Commits
  • I have ensured that documentation content adheres to the style guide
  • If the change involves potentially sensitive changes1, I have assessed the possible impact
  • If applicable, I have added tests that prove my fix is effective or that my feature works
  • I have ensured that existing tests pass after adding my changes
  • If applicable, I have updated README.md

Footnotes

  1. Potentially sensitive changes include anything involving code, personally identify information (PII), live URLs or significant amounts of new or revised documentation. Please refer to our style guide for guidance about placeholder content.

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.
@ADubhlaoich ADubhlaoich requested review from a team as code owners July 15, 2025 16:32
@github-actions github-actions bot added documentation Improvements or additions to documentation product/nic NGINX Ingress Controller related issues labels Jul 15, 2025
Copy link

Deploy Preview will be available once build job completes!

Name Link
😎 Deploy Preview https://frontdoor-test-docs.nginx.com/previews/docs/816/

@ADubhlaoich ADubhlaoich requested a review from a team July 17, 2025 08:54
@ADubhlaoich ADubhlaoich linked an issue Jul 17, 2025 that may be closed by this pull request
@ADubhlaoich ADubhlaoich requested a review from vepatel July 18, 2025 14:46
Comment on lines +21 to +22
- 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.md" >}}) topic.
- The [Get the NGINX Ingress Controller image with JWT]({{< ref "/nic/installation/nic-images/get-image-using-jwt.md" >}}) topic describes how to use your subscription JWT token to get the image.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Only one of these is required, one or the other.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, this read like a mess to me.

I was trying to make the minimum amount of changes to pull the upgrade instructions out, but there's a larger series of things to fix here.

I'm pretty confident every document involving NGINX Plus includes the step to create the license secret, so even listing it here as a requisite might be redundant if you're following the instructions and the prerequisites linearly.

- [Create a license Secret]({{< ref "/nic/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]({{< ref "/nic/installation/nic-images/get-registry-image.md" >}}) topic.
- The [Get the NGINX Ingress Controller image with JWT]({{< ref "/nic/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]({{< ref "/nic/installation/build-nginx-ingress-controller.md" >}}) topic explains how to push an image to a private Docker registry.
Copy link
Contributor

@pdabelf5 pdabelf5 Jul 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- The [Build NGINX Ingress Controller]({{< ref "/nic/installation/build-nginx-ingress-controller.md" >}}) topic explains how to push an image to a private Docker registry.
- The [Push the image to your private registry]({{< ref "/nic/installation/build-nginx-ingress-controller.md#push-image)" >}}) topic explains how to push an image to a private Docker registry.

--set controller.name=""
```
```shell
helm install my-release -f values-plus.yaml .
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The OCI example above uses --set arguments to pass the correct values to the helm command. We should be consistent. Also, the command does not describe what configuration should be included in the values file.


6. Once the upgrade process has finished, use `kubectl describe` on the deployment to verify the change by reviewing its events:
The command deploys NGINX Ingress Controller in your Kubernetes cluster in the default configuration. The [Helm chart parameters](#helm-chart-parameters) lists the parameters that can be configured during installation.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This comment should also be included for OCI installations

kubectl apply -f https://raw.githubusercontent.com/nginx/kubernetes-ingress/v{{< nic-version >}}/deploy/crds.yaml
```

In the above command, `v{{< nic-version >}}` represents the version of NGINX Ingress Controller release rather than the Helm chart version.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
In the above command, `v{{< nic-version >}}` represents the version of NGINX Ingress Controller release rather than the Helm chart version.
In the above command, `v{{< nic-version >}}` represents the version of the NGINX Ingress Controller release rather than the Helm chart version.


This section provides step-by-step instructions for upgrading NGINX Ingress Controller from version v3.x to v4.0.0.

There are two necessary steps required: updating the `apiVersion` value of custom resources and configuring structured logging.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This might catch attention better as a bulleted list.


### 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`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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 you're using Helm chart version `v2.x`, update your `GlobalConfiguration`, `Policy`, and `TransportServer` resources from `apiVersion: k8s.nginx.org/v1alpha1` to `apiVersion: k8s.nginx.org/v1` before upgrading to NGINX Ingress Controller 4.0.0.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

serial comma


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.3.2`), upgrade to Helm chart `v1.4.2` (NGINX Ingress Controller `v3.7.2`) before updating your GlobalConfiguration, Policy and TransportServer resources.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If the Helm chart you have been using is `v1.0.2` or earlier (NGINX Ingress Controller `v3.3.2`), upgrade to Helm chart `v1.4.2` (NGINX Ingress Controller `v3.7.2`) before updating your GlobalConfiguration, Policy and TransportServer resources.
If the Helm chart you have been using is `v1.0.2` or earlier (NGINX Ingress Controller `v3.3.2`), upgrade to Helm chart `v1.4.2` (NGINX Ingress Controller `v3.7.2`) before updating your GlobalConfiguration, Policy, and TransportServer resources.

If a *GlobalConfiguration*, *Policy* or *TransportServer* resource is deployed with `apiVersion: k8s.nginx.org/v1alpha1`, it will be **deleted** during the upgrade process.
{{</ warning >}}

Once above specified custom resources are moved to `v1` ,please run below `kubectl` commands before upgrading to v4.0.0 Custom Resource Definitions (CRDs) to avoid [this issue](https://github.com/nginx/kubernetes-ingress/issues/7010).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thought it might be helpful to describe the issue that's linked to.

Suggested change
Once above specified custom resources are moved to `v1` ,please run below `kubectl` commands before upgrading to v4.0.0 Custom Resource Definitions (CRDs) to avoid [this issue](https://github.com/nginx/kubernetes-ingress/issues/7010).
After you move the custom resources to `v1`, run the following `kubectl` commands before upgrading to v4.0.0 Custom Resource Definitions (CRDs) to avoid webhook errors caused by leftover `v1alpha1` resources. For details, see [GitHub issue #7010](https://github.com/nginx/kubernetes-ingress/issues/7010).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

active voice


### 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
To configure structured logging, you must update your log deployment arguments from an integer to a string. You can also choose different formats for the log output.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

active voice


{{%tab name="Helm"%}}

The Helm value of `controller.logLevel` has been changed from an integer to a string.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The Helm value of `controller.logLevel` has been changed from an integer to a string.
The Helm value `controller.logLevel` is now a string instead of an integer.


The topic also contains guidance for [sending reports to NGINX Instance Manager]({{< ref "/nic/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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
In prior versions, usage reporting with the cluster connector was required: it is no longer necessary, as it is built into NGINX Plus.
Earlier versions required usage reporting through the cluster connector. This is no longer needed because it's now built into NGINX Plus.


## Upgrade a version older than v3.1.0

For NGINX Ingress Controller version v3.1.0, [changes were introduced](https://github.com/nginx/kubernetes-ingress/pull/3606) to Helm resource names, labels and annotations to fit with Helm best practices.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
For NGINX Ingress Controller version v3.1.0, [changes were introduced](https://github.com/nginx/kubernetes-ingress/pull/3606) to Helm resource names, labels and annotations to fit with Helm best practices.
Starting in version 3.1.0, NGINX Ingress Controller uses updated Helm resource names, labels, and annotations to follow Helm best practices. [See the changes.](https://github.com/nginx/kubernetes-ingress/pull/3606)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

style guide says to use serial commas

Comment on lines +202 to +204
When using Helm to upgrade from a version prior to 3.1.0, certain resources like Deployment, DaemonSet and Service will be recreated during the process, which will result in downtime.

We advise updating all resources to match the new naming convention: the following steps will minimize the aforementioned downtime.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When using Helm to upgrade from a version prior to 3.1.0, certain resources like Deployment, DaemonSet and Service will be recreated during the process, which will result in downtime.
We advise updating all resources to match the new naming convention: the following steps will minimize the aforementioned downtime.
When you upgrade with Helm from a version earlier than 3.1.0, some resources such as `Deployment`, `DaemonSet`, and `Service` are recreated. This causes downtime.
To reduce downtime, update all resources to use the new naming convention. The following steps help you do that.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"aforementioned" might be difficult for a global audience at an 8th grade reading level.

Selector: app=nginx-ingress-nginx-ingress
```

Checkout the latest available tag using `git checkout v{{< nic-version >}}`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Checkout the latest available tag using `git checkout v{{< nic-version >}}`
Check out the latest available tag using `git checkout v{{< nic-version >}}`

check out (v) -- two words


Checkout the latest available tag using `git checkout v{{< nic-version >}}`

Navigate to `/kubernetes-ingress/charts/nginx-ingress`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Navigate to `/kubernetes-ingress/charts/nginx-ingress`
Go to `/kubernetes-ingress/charts/nginx-ingress`

Style guide says to use "go" instead of "navigate"

--set fullnameOverride="nginx-ingress-nginx-ingress"
```

It could look as follows:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
It could look as follows:
It might look like this:

Selector: app=<helm_release_name>-nginx-ingress
```

Checkout the latest available tag using `git checkout v{{< nic-version >}}`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Checkout the latest available tag using `git checkout v{{< nic-version >}}`
Check out the latest available tag using `git checkout v{{< nic-version >}}`


Checkout the latest available tag using `git checkout v{{< nic-version >}}`

Navigate to `/kubernetes-ingress/charts/nginx-ingress`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Navigate to `/kubernetes-ingress/charts/nginx-ingress`.
Go to `/kubernetes-ingress/charts/nginx-ingress`.

--set controller.name=""
```

It could look as follows:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
It could look as follows:
It might look like this:

@@ -158,10 +158,10 @@ versions: 1.25-1.32.
16 Dec 2024

With added support for [NGINX R33]({{< ref "/nginx/releases.md#nginxplusrelease-33-r33" >}}), deployments of F5 NGINX Ingress Controller using NGINX Plus now require a valid JSON Web Token to run.
Please see the [Upgrading to v4]({{< ref "/nic/installation/installing-nic/upgrade-to-v4.md#create-license-secret" >}}) for full details on setting up your license `Secret`.
Please see the [Upgrading to v4]({{< ref "/nic/installation/upgrade-version.md#upgrade-from-3x-to-4x" >}}) for full details on setting up your license `Secret`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Please see the [Upgrading to v4]({{< ref "/nic/installation/upgrade-version.md#upgrade-from-3x-to-4x" >}}) for full details on setting up your license `Secret`.
For full details on setting up your license `Secret`, see [Upgrading to v4]({{< ref "/nic/installation/upgrade-version.md#upgrade-from-3x-to-4x" >}}).

We shoudl avoid please: https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please


API Version `v1alpha1` of `GlobalConfiguration`, `Policy` and `TransportServer` resources are now deprecated.
Please see [Update custom resource apiVersion]({{< ref "/nic/installation/installing-nic/upgrade-to-v4.md#update-custom-resource-apiversion" >}}) for full details on updating your resources.
Please see [Update custom resource apiVersion]({{< ref "/nic/installation/upgrade-version.md#upgrade-from-3x-to-4x" >}}) for full details on updating your resources.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Please see [Update custom resource apiVersion]({{< ref "/nic/installation/upgrade-version.md#upgrade-from-3x-to-4x" >}}) for full details on updating your resources.
For full details on updating your resources, see [Update custom resource apiVersion]({{< ref "/nic/installation/upgrade-version.md#upgrade-from-3x-to-4x" >}}).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation product/nic NGINX Ingress Controller related issues
Projects
None yet
Development

Successfully merging this pull request may close these issues.

NIC Upgrades to current version (5.1)
4 participants