feat: Rework Manifest installation cases #1551
Conversation
feat: Add OIDC Timeout to NIC ConfigMap
…s, Configmap, VirtualServer (#1468) * feat: Add client-body-buffer-size directive to NIC Ingress Annotations, Configmap, VirtualServer * update descriptions based off pr changes
This commit reworks the manifest installation document to instead become a folder, with each individual page within covering exactly one use case. The new structure guides a user completely from end to end on the process necessary for installing NGINX Gateway Fabric NGINX Open Source or NGINX Plus without using multiple documents. It also includes general improvements to specification discoverability, allowing readers to more easily find what parts of the Gateway API specification are supported and what to expect from future releases.
github-actions
bot
added
documentation
✅ Deploy Preview will be available once build job completes!
|
ADubhlaoich
changed the title
|
Pushed my latest changes. Running into issues testing the NGINX Plus deployment: there's no problems in the actual installation process, but the pod never becomes ready due to a crash loop. The nature of the deployment makes me assume it could be related to the license for the pod. |
|
The Plus deployment case now works as expected: I'd been trying to create consistency with Gateway Fabric and Ingress Controller processes. The latter installs everything (including secrets) to the default namespace, whereas NGINX Gateway Fabric confines it all to its own namespace. |
Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com>
|
@sjberman I have resolved a few bits of feedback and responded to everything else. This is a pattern that is being applied to all onboarding documentation: a user can follow each document in full vertical sequence to deploy in less than 10 minutes. The only nuance is if they want to install experimental, which is not presumed as a default use case - for which they have a separate document explaining and providing replacement URLs for installation steps. Outside of the existing Manifest installation document, none of the other onboarding documentation has been changed yet as I opted to replicate steps in-place as a proof of concept: this same pattern has already been applied to NGINX Ingress Controller's Helm documentation: https://docs.nginx.com/nginx-ingress-controller/install/helm/ My intent is to rewrite all onboarding documentation to reduce each page to covering exactly one use case, delineating between OSS and Plus. Users have an idea of what kind of deployment they're going to use off the bat, so giving them extra optional dials on an individual document (Choosing between OSS and Plus and whether or not to use experimental) adds extra friction to each journey, and may also be a reason some people think NGINX Gateway Fabric cannot be used without a Plus license. If there are technical nuances that need to be addressed that detail is incredibly important (Such as the note about cert-manager - I successfully deployed OSS and Plus with these procedures 5 times without issue), but otherwise I don't think we should be prioritizing maintainer time over user time or clarity. If examples risk being outdated, we can periodically update them - the docs team is even working on procedures to schedule investigating and testing product documentation regularly, so that we can trust they are still accurate. We should not avoid maintaining reference information like Technical specifications on the basis that they might become outdated or will have to be updated with each release, because that information is critically important for end users. |
|
@ADubhlaoich I agree the value of including the Tech specs, and also don't want to avoid including them. However, saying that they "might get outdated" is optimistic. They will get outdated. We have problems updating it in our own repo where those dependency updates actually happen. It's a manual chore that I wish we could automate in our own README because we often forget to do it. We can leave it in and update our release process doc to mention updating this at release time, which might be the best option for us. But in between that cadence, it will probably lag behind. |
|
After conferring with the rest of the documentation team, I will be preparing whole documents for the experimental use case, which will be applied to other deployments as part of a design pattern. I have yet to test the nuances of the cert-manager installation, and will do so after the content work. |
|
Discovered a missing parameter from the old Manifest documentation when installing the API resources: adding it to the new use case resolves as expected. Finished testing the open source experimental deployment: tearing down my test deployment and trying the plus experimental deployment use case now. |
|
Found an incorrect URL for the NGINX Plus experimental deployment: works as expected! All that's left is testing the Let's Encrypt certificate documentation to see if it works with a "default" contemporary cert-manager installation, though one of the requirements for testing is... challenging. |
|
|
||
| {{% /tab %}} | ||
|
|
||
| {{% tab name="AWS NLB" %}} |
There was a problem hiding this comment.
I believe this was the only existing non-default example that currently existed for OSS with experimental.
This PR has been open for so long I have lost context.
| ```text | ||
| NAME TYPE DATA AGE | ||
| nplus-license Opaque 1 31s | ||
| regcred kubernetes.io/dockerconfigjson 1 22s |
There was a problem hiding this comment.
This should be nginx-plus-registry-secret
There was a problem hiding this comment.
This output is from running the actual commands in the documents: please provide an edit suggestion to whatever section of YAML is creating this inaccuracy.
| ```text | ||
| NAME TYPE DATA AGE | ||
| nplus-license Opaque 1 31s | ||
| regcred kubernetes.io/dockerconfigjson 1 22s |
There was a problem hiding this comment.
This should be nginx-plus-registry-secret
There was a problem hiding this comment.
This output is from running the actual commands in the documents: please provide an edit suggestion to whatever section of YAML is creating this inaccuracy.
|
|
||
| ## Install the Gateway API resources | ||
|
|
||
| {{< call-out "note" >}} If you have already installed Gateway API resources in your cluster, ensure they are a version [supported by NGINX Gateway Fabric]({{< ref "/ngf/overview/technical-specifications.md" >}}) {{< /call-out >}} |
There was a problem hiding this comment.
This section is in an include now, right?
There was a problem hiding this comment.
It appears to be, but I will need to review if the contents are identical, or if I realized there was differences that meant the include was non-functional.
This PR has been open for so long I have lost context.
| nd-product: FABRIC | ||
| --- | ||
|
|
||
| This page describes how to use Manifests to uninstall NGINX Gateway Fabric, its custom resource definitions, and its Gateway API resources. |
There was a problem hiding this comment.
We're technically not using manifests to uninstall, we're just using a few manual kubectl commands.
Proposed changes
This commit reworks the manifest installation document to instead become
a folder, with each individual page within covering exactly one use
case. The new structure guides a user completely from end to end on the
process necessary for installing NGINX Gateway Fabric NGINX Open Source
or NGINX Plus without using multiple documents.
It also includes general improvements to specification discoverability,
allowing readers to more easily find what parts of the Gateway API
specification are supported and what to expect from future releases.
Checklist
Before sharing this pull request, I completed the following checklist:
Footnotes
Potentially sensitive information includes personally identify information (PII), authentication credentials, and live URLs. Refer to the style guide for guidance about placeholder content. ↩