NGINX Gateway Fabric Docs Not Very Easy To Follow

[conradwt]

When attempting to install the Nginx implementation K8s Gateway API (i.e. Nginx Gateway Fabric), I found the documentation hard to follow because I had to jump from one page of the site to another. Thus, it wasn't clear as to what I was installing here. In the documentation, there should be a quick start that provides an end-to-end example of how to install and use Nginx's K8s Gateway API features. For example, here's a possible Getting Started outline for local development:

1. create the cluster
2. install MetalLB
3. install the Gateway CRDs
4. create the Gateway and Gateway resources
5. install Nginx Gateway Fabric
6. deploy a sample service
7. create HTTPRoute for our deployed service
8. test the routing rule
9. and so on

BTW, the steps were inspired by both the Kong and Traefik K8s Gateway API implementations. Furthermore, I put together a document for using the Kong implementation that can be found here:

• https://github.com/conradwt/k8s-gateway-api-using-kong

[sjberman]

@conradwt Thanks for the feedback. We're always looking to improve the flow of our documentation, and will have some improvements in our upcoming release.

For now, the simplest path I can see to meet your requirements of local development would be to follow:

• https://docs.nginx.com/nginx-gateway-fabric/installation/running-on-kind/
  • this will link to the installation guide for NGF itself
• https://docs.nginx.com/nginx-gateway-fabric/how-to/traffic-management/routing-traffic-to-your-app/

We also have a developer guide in our Github repo: https://github.com/nginxinc/nginx-gateway-fabric/blob/main/docs/developer/quickstart.md#deploy-on-kind that helps with a basic setup and links to some example apps/routes.

[mpstefan]

Modifying the original ask by a bit, we should definitely produce a complete on-boarding journey. Here's the resulting story:

As a new user to NGF
I want a guide that gets me started using the project as quickly as possible
So that I do not get stuck on my path to install NGF
And so that trying out NGF does not take an excessive amount of time.

Acceptance

• A Quickstart guide is created which guides the user from installation to sending traffic through an HTTPRoute.
• The Quickstart guide replaces the Deploy NGINX Gateway Fabric on a kind Cluster guide
• The guide should contain the following:
  • An introduction to the goals of the Quickstart guide and why users may want to use KIND
  • Setup for the KIND cluster, NodePort, and Port Forwarding
  • Install the Gateway API resources
  • One method to install NGF using NGINX or NGINX Plus OR multiple methods split by combo box
  • Link or short description on how to enable experimental features and the required experimental CRDs
  • Create a simple HTTPRoute to a example application
  • Testing the installation with traffic
  • A link or links to guides for other NGF features
• Upgrade and uninstall information are moved to their own pages

[ADubhlaoich]

I've started work on this! I will link a draft PR once it's gotten to an appropriate state.

[ADubhlaoich]

I have what I anticipate is most of the finer details on initial set-up finished: I've condensed the existing kind set-up guide down to its essential information. There's a lot of noise around conditional configuration in the Helm installation page, so I've taken the minimum steps necessary with the one "peripheral" path being the changes needed for experimental features.

The remaining sections are for setting up an example application, configuring a HTTPRoute and testing everything works. I have not accounted for if the reader wants to use NGINX Plus in this particular guide: I think there's improvements to existing documents that could facilitate that instead, and it isn't a core use case for someone trying to see how NGINX Gateway Fabric works.

[ADubhlaoich]

I will be putting up a draft PR to resolve this issue tomorrow.

With a lot of help from @sjberman I managed to combine the existing kind tutorial, Helm installation and the cafe example into a single document.

It has been (thoroughly) tested, so I need to clean up the explanatory text and add some contextual notes.