-
Notifications
You must be signed in to change notification settings - Fork 100
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
base: main
Are you sure you want to change the base?
Conversation
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.
✅ Deploy Preview will be available once build job completes!
|
- 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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- 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 . |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. |
There was a problem hiding this comment.
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`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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). |
There was a problem hiding this comment.
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.
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). |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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) |
There was a problem hiding this comment.
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
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. |
There was a problem hiding this comment.
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 >}}` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 >}}` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Navigate to `/kubernetes-ingress/charts/nginx-ingress`. | |
Go to `/kubernetes-ingress/charts/nginx-ingress`. |
--set controller.name="" | ||
``` | ||
|
||
It could look as follows: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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" >}}). |
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 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.
README.md
Footnotes
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. ↩