- Notifications
You must be signed in to change notification settings - Fork100
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 ourterms of service andprivacy 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 stepsare 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 documentThe changes made focused on clarifying the critical path for one singleuser story, as lots of unnecessary contextual information was beingprovided, which was causing confusion.With this commit, the general reading and execution flow for thesedeployment steps become more coherent. Similar changes may be made forManifests documentation, if common steps are identified.
✅ Deploy Preview will be available once build job completes!
|
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
| - 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 thedeployment to verifythechange by reviewing its events: | ||
| The command deploys NGINX Ingress Controller in your Kubernetes cluster in thedefault configuration. The[Helm chart parameters](#helm-chart-parameters) liststheparameters 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 oftheNGINX 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.
| IftheHelm chartyou have been using is`v2.x`,before upgrading to NGINX Ingress Controller 4.0.0 you mustupdate your GlobalConfiguration,Policy and TransportServer resources from`apiVersion: k8s.nginx.org/v1alpha1` to`apiVersion: k8s.nginx.org/v1`. | |
| Ifyou're usingHelm chartversion`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 specifiedcustom resourcesare movedto`v1` ,please runbelow`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 thecustom resources to`v1`, runthe following`kubectl` commands before upgrading to v4.0.0 Custom Resource Definitions (CRDs) to avoidwebhook 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 themselvescan alsobe rendered indifferent formats. | |
| To configure structured logging, you must update your log deployment arguments from an integer to a string.Youcan alsochoosedifferent 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 valueof`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 priorversions,usage reportingwith the cluster connector was required: itis no longernecessary, as it is built into NGINX Plus. | |
| Earlierversions requiredusage reportingthrough the cluster connector. Thisis no longerneeded 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 Controllerversionv3.1.0,[changes were introduced](https://github.com/nginx/kubernetes-ingress/pull/3606) toHelm resource names, labels and annotations tofit withHelm best practices. | |
| Starting inversion3.1.0,NGINX Ingress Controller uses updatedHelm resource names, labels, and annotations tofollowHelm 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.
| Whenusing Helm to upgrade from a versionprior to 3.1.0,certain resourceslikeDeployment,DaemonSet and Service will berecreated during the process, which will result in downtime. | |
| We advise updatingall resources tomatch the new naming convention: the following stepswill minimize the aforementioned downtime. | |
| Whenyou upgrade with Helm from a versionearlier than 3.1.0,some resourcessuch as`Deployment`,`DaemonSet`, and`Service` arerecreated. This causes downtime. | |
| To reduce downtime, updateall resources touse the new naming convention. The following stepshelp 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.
| Itcould lookas follows: | |
| Itmight looklike 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.
| Itcould lookas follows: | |
| Itmight looklike 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 avoidplease: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.
| Pleasesee[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.mdFootnotes
Potentially sensitive changes include anything involving code, personally identify information (PII), live URLs or significant amounts of new or revised documentation. Please refer toour style guide for guidance about placeholder content.↩